IPScanner

整合

Traefik 外掛

來自 Traefik Plugin Catalog 的中介軟件，在路由器轉發請求之前檢查每位訪客。

安裝

  1. 1在 Traefik 的靜態設定中宣告外掛，然後重新啟動 Traefik。
  2. 2在控制台中加入 Traefik 網站並複製其 Site ID。
  3. 3在 Traefik 容器上設定 IPSCANNER_API_KEY。
  4. 4加入附 Site ID 的 ipscanner 中介軟件，並套用到路由器上。

新網站預設以 Monitor 模式運行：只加入標頭，在切換到 Enforce 之前不會封鎖任何請求。

概覽見 Traefik 外掛頁面，原始碼及完整範例見 GitHub。

experimental:
  plugins:
    ipscanner:
      moduleName: github.com/ipscanner/ipscanner-traefik
      version: v0.1.0

Coolify、Compose、Kubernetes

  • Coolify

    外掛參數寫入代理的 command 清單，金鑰寫入其 environment。然後在應用程式的容器標籤中定義中介軟件，附加到 Coolify 產生的每個路由器上。每個應用程式使用獨立的中介軟件名稱。

  • Docker Compose

    參數寫在 Traefik 服務上，中介軟件寫在應用程式的標籤中。其他路由器可透過 ipscanner@docker 重用。

  • Kubernetes

    一個 Middleware 資源，金鑰來自 Secret。在 IngressRoute 中參照，或在 Ingress 上以 router.middlewares 註解參照。

  • File provider

    中介軟件寫在動態設定檔中，金鑰來自掛載的 secret。

沒有金鑰時，所有請求附 X-IPScanner-Status: skipped 放行。

- '--experimental.plugins.ipscanner.modulename=github.com/ipscanner/ipscanner-traefik'
- '--experimental.plugins.ipscanner.version=v0.1.0'

environment:
  - IPSCANNER_API_KEY=pk_live_...

設定

  • apiKey

    API 金鑰。外掛選項會顯示在 Traefik 控制台中，建議改用 IPSCANNER_API_KEY、apiKeyFile 或 urn:k8s:secret 參照。

  • apiKeyFile

    存放 API 金鑰的檔案，例如掛載的 Docker 或 Kubernetes secret。

  • siteId

    控制台中的 Site ID。設定後，模式及策略由控制台決定。

  • mode預設 monitor

    monitor 或 enforce。設定網站後只有 monitor 生效：令網站保持 Monitor 模式。

  • blockClasses預設 malicious_automation

    未設定網站時 Enforce 模式封鎖的類別：malicious_automation、ai_agent、tor、vpn、proxy、hosting、relay 或 none。

  • trustedProxies

    信任其 IP 標頭的位址及 CIDR 範圍。private 加入私人範圍，cloudflare 加入 Cloudflare 範圍。

  • ipHeaders預設 X-Forwarded-For

    按次序從可信代理讀取的標頭。位於 Cloudflare 之後時使用 CF-Connecting-IP。

  • timeout預設 1500ms

    單次檢查的時間預算。逾時後請求放行。

  • cacheTTL預設 10m

    按網站、IP 及 User-Agent 重用一次結果的時長。

  • cacheSize預設 10000

    記憶體中保存的結果數目。

  • policyTTL預設 30s

    網站策略的重用時長。

  • skipPaths預設 靜態檔案

    對路徑比對的正規表示式，不分大小寫。符合的請求不作檢查；none 表示檢查所有路徑。

  • blockMessage預設 Blocked by IPScanner edge guard.

    403 頁面的文字。

  • debug預設 false

    在回應中加入 X-IPScanner-Status、-Class 及 -Action，並為每項決定記錄一行日誌。

  • apiUrl預設 https://ipscanner.io

    API 基本 URL。

清單可用 YAML 清單或以逗號分隔的值（標籤中寫 blockClasses=tor,vpn）。時長採用 Go 語法：1500ms、30s、10m。無效選項會停用該路由器，並在 Traefik 日誌中報錯。

用戶端 IP

訪客即 Traefik 看到的位址，除非該位址是可信代理。

  • trustedProxies

    只會從這些位址讀取 X-Forwarded-For 或 ipHeaders 清單中的標頭。

  • forwardedHeaders.trustedIPs

    對於不在入口點可信 IP 之內的對端，Traefik 會捨棄 X-Forwarded-For，因此兩處都要設定，或改為讀取 CF-Connecting-IP。

  • trustedProxies=cloudflare, ipHeaders=CF-Connecting-IP

    位於已啟用代理（橙色雲朵）的 Cloudflare 之後時，在中介軟件上同時設定這兩項。

加入的標頭

加入至應用程式收到的請求。會先移除傳入的 X-IPScanner-* 標頭，用戶端無法自行附上判定結果。

  • X-IPScanner-Statusok, error, timeout, backoff, skipped

    檢查是否已執行，未執行時說明原因。

  • X-IPScanner-Classhuman, verified_bot, ai_agent, …

    訪客的流量類別。

  • X-IPScanner-Actionallow, flag, block, would_flag, would_block

    請求的處理結果。Monitor 模式下為 would_flag 及 would_block。

  • X-IPScanner-Network-Classresidential_clean, hosting, vpn, tor, …

    位址的網絡類別。

  • X-IPScanner-Anonymizedtrue, false

    該網絡隱藏了訪客的實際位置。

  • X-IPScanner-Risk0-100

    位址的風險分數。

  • X-IPScanner-CountryDE

    位址所屬國家或地區。

  • X-IPScanner-Sitesite_...

    已設定時為 Site ID。

檢查失敗或被略過時，只會設定 X-IPScanner-Status。

傳往應用程式的請求
X-IPScanner-Status: ok
X-IPScanner-Class: ai_agent
X-IPScanner-Action: would_block
X-IPScanner-Network-Class: hosting
X-IPScanner-Anonymized: true
X-IPScanner-Risk: 60
X-IPScanner-Country: US
X-IPScanner-Site: site_4fQ8nZ2kLm7xR1vT9cBw

快取與故障放行

  • 網站策略GET /v1/sites/{id}/policy

    模式及按類別的策略，快取 30 秒。更新失敗時，最近一次有效的策略最多沿用 24 小時。修改無需重新載入即可生效。

  • 結果快取

    每位訪客（網站、IP、User-Agent）每 10 分鐘檢查一次，保存在記憶體中，最多 10,000 位訪客。重新載入設定後仍會保留。

  • 故障放行

    結果與策略合共 1.5 秒。逾時或 API 出錯時請求放行，檢查暫停 30 秒；遇到 401、402、403 或 429 時暫停 5 分鐘。

  • 一律放行

    已驗證的爬蟲、OPTIONS 請求、私人及回送位址，以及略過清單中的路徑。

  • 封鎖

    傳回附請求 ID 的 403 頁面。Monitor 模式從不封鎖。

  • Free 方案

    Free 方案的網站會保持 Monitor 模式。

  • 費用

    每位未命中快取的訪客計 2 個請求單位。快取期內的重複請求不收費。

發送的內容

  • POST /v1/edge/check計為 2 次請求

    每位未命中快取的訪客一次呼叫。

  • GET /v1/sites/{id}/policy不計入用量

    網站策略，已設定 Site ID 時才會請求。

  • X-IPScanner-Source: traefik

    在流量及用量中將呼叫標記為此整合發出。

  • User-Agent: ipscanner-traefik/<version>

    版本號，顯示在控制台的網站頁面上。

請求主體

  • sitestring

    已設定時為 Site ID。

  • ipstring

    訪客位址。

  • user_agentstring

    訪客的 User-Agent。

  • headersobject

    Accept、Accept-Language、Accept-Encoding、Sec-CH-UA* 及 Sec-Fetch-*，各自截短至 512 位元組。

  • request_idstring

    請求的 X-Request-Id 或新產生的 ID，亦會顯示在封鎖頁面上。

它發出的邊緣偵測請求
curl https://ipscanner.io/v1/edge/check \
  -H "Authorization: Bearer $IPSCANNER_API_KEY" \
  -H "X-IPScanner-Source: traefik" \
  -H "User-Agent: ipscanner-traefik/0.1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "site": "site_4fQ8nZ2kLm7xR1vT9cBw",
    "ip": "203.0.113.7",
    "user_agent": "Mozilla/5.0",
    "headers": {
      "accept-language": "en-US"
    },
    "request_id": "9f2c41b7d03e77f2"
  }'