IPScanner

整合

Caddy 模組

ipscanner 指令在 Caddy 內部檢查每位訪客，先於 reverse_proxy 或 file_server 執行。

安裝

  1. 1以 xcaddy 建置附此模組的 Caddy，或在 caddyserver.com/download 上選取 github.com/ipscanner/ipscanner-caddy。
  2. 2在控制台中加入 Caddy 網站並複製其 Site ID。
  3. 3在 Caddy 的環境變數中設定 IPSCANNER_API_KEY。
  4. 4在網站區塊中加入附 Site ID 的 ipscanner 指令。

需要 Caddy 2.8 或以上版本。以 caddy list-modules | grep ipscanner 確認。

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

概覽見 Caddy 模組頁面，原始碼見 GitHub。

xcaddy build --with github.com/ipscanner/ipscanner-caddy

Caddyfile

  • ipscanner

    模組會將其排在 basic_auth 之前，無需全域 order 行。它在 header、redir 及重寫之後執行，在驗證、reverse_proxy 及 file_server 之前執行。

  • ipscanner /app/* { ... }

    以比對器把檢查限定於部分路徑。

  • mode, block_classes

    未設定 site_id 時，由 Caddyfile 設定模式及封鎖類別。

  • "handler": "ipscanner"

    在 JSON 設定中，是一個欄位相同的 handler。

example.com {
	ipscanner {
		site_id site_...
	}
	reverse_proxy localhost:8080
}

設定

  • api_key預設 {env.IPSCANNER_API_KEY}

    API 金鑰。支援佔位符，金鑰可來自環境變數或檔案。

  • site_id

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

  • mode預設 monitor

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

  • block_classes預設 malicious_automation

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

  • timeout預設 1.5s

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

  • cache_ttl預設 10m

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

  • cache_size預設 10000

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

  • policy_ttl預設 30s

    網站策略的重用時長。

  • skip_paths預設 靜態檔案

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

  • block_message預設 Blocked by IPScanner edge guard.

    403 頁面的文字。

  • debug預設 關閉

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

  • api_url預設 https://ipscanner.io

    API 基本 URL。

預設的 skip_paths 包括 robots.txt、sitemap.xml、favicon.ico、指令碼、樣式表、source map、圖片、字型及影片。

用戶端 IP

模組使用 Caddy 解析出的用戶端 IP，本身從不讀取 X-Forwarded-For。未設定 trusted_proxies 時即為對端位址。

  • trusted_proxies

    在全域 servers 選項中信任您的負載平衡器或 CDN。

  • trusted_proxies_strict

    採用最右邊的不可信位址，訪客無法在前面偽造一跳。建議啟用。

  • client_ip_headers CF-Connecting-IP

    位於 Cloudflare 之後時：信任 Cloudflare 範圍並讀取 CF-Connecting-IP。

Caddyfile
{
	servers {
		trusted_proxies static 10.0.0.0/8
		trusted_proxies_strict
	}
}

加入的標頭

加入至應用程式收到的請求。會先移除傳入的 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。

佔位符

  • {http.vars.ipscanner.status}

    檢查狀態，供指令之後的日誌及比對器使用。

  • {http.vars.ipscanner.class}

    流量類別，狀態為 ok 時設定。

  • {http.vars.ipscanner.action}

    allow、flag、block、would_flag 或 would_block。

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: caddy

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

  • User-Agent: ipscanner-caddy/<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: caddy" \
  -H "User-Agent: ipscanner-caddy/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"
  }'