IPScanner

Integrationen

Caddy-Modul

Die Direktive ipscanner prüft jeden Besucher direkt in Caddy, vor reverse_proxy oder file_server.

Installation

  1. 1Bauen Sie Caddy mit dem Modul per xcaddy oder wählen Sie github.com/ipscanner/ipscanner-caddy auf caddyserver.com/download.
  2. 2Legen Sie eine Caddy-Website im Dashboard an und kopieren Sie ihre Site-ID.
  3. 3Setzen Sie IPSCANNER_API_KEY in der Umgebung von Caddy.
  4. 4Fügen Sie die Direktive ipscanner mit der Site-ID in Ihren Site-Block ein.

Benötigt Caddy 2.8 oder neuer. Prüfen mit caddy list-modules | grep ipscanner.

Eine neue Website startet im Monitor-Modus: Sie erhält Header, blockiert wird nichts, bis Sie auf Enforce umschalten.

Überblick auf der Seite zum Caddy-Modul, Quellcode auf GitHub.

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

Caddyfile

  • ipscanner

    Das Modul ordnet sie vor basic_auth ein, eine globale order-Zeile ist nicht nötig. Sie läuft nach header, redir und Rewrites, vor Authentifizierung, reverse_proxy und file_server.

  • ipscanner /app/* { ... }

    Ein Matcher beschränkt die Prüfung auf bestimmte Pfade.

  • mode, block_classes

    Ohne site_id legt das Caddyfile Modus und blockierte Klassen fest.

  • "handler": "ipscanner"

    In der JSON-Konfiguration ein Handler mit denselben Feldern.

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

Konfiguration

  • api_keyStandard {env.IPSCANNER_API_KEY}

    API-Schlüssel. Platzhalter funktionieren, der Schlüssel kann also aus der Umgebung oder einer Datei kommen.

  • site_id

    Site-ID aus dem Dashboard. Modus und Richtlinie kommen dann aus dem Dashboard.

  • modeStandard monitor

    monitor oder enforce. Mit Website wirkt nur monitor: Die Website bleibt dann im Monitor-Modus.

  • block_classesStandard malicious_automation

    Im Enforce-Modus ohne Website blockierte Klassen: malicious_automation, ai_agent, tor, vpn, proxy, hosting, relay oder none.

  • timeoutStandard 1.5s

    Zeitbudget für eine Prüfung. Bei Zeitüberschreitung passiert die Anfrage.

  • cache_ttlStandard 10m

    Wie lange ein Ergebnis pro Website, IP und User-Agent wiederverwendet wird.

  • cache_sizeStandard 10000

    Ergebnisse im Speicher.

  • policy_ttlStandard 30s

    Wie lange die Richtlinie der Website wiederverwendet wird.

  • skip_pathsStandard statische Dateien

    Regex auf den Pfad, ohne Groß- und Kleinschreibung. Passende Anfragen werden nicht geprüft; none prüft jeden Pfad.

  • block_messageStandard Blocked by IPScanner edge guard.

    Text der 403-Seite.

  • debugStandard aus

    Ergänzt Antworten um X-IPScanner-Status, -Class und -Action und protokolliert jede Entscheidung in einer Zeile.

  • api_urlStandard https://ipscanner.io

    Basis-URL der API.

Das Standard-skip_paths umfasst robots.txt, sitemap.xml, favicon.ico, Skripte, Stylesheets, Source Maps, Bilder, Schriften und Videos.

Client-IP

Das Modul nutzt die Client-IP, die Caddy ermittelt hat, und liest X-Forwarded-For nie selbst. Ohne trusted_proxies ist das die Peer-Adresse.

  • trusted_proxies

    Vertrauen Sie Ihrem Load Balancer oder CDN in den globalen Server-Optionen.

  • trusted_proxies_strict

    Nimmt die am weitesten rechts stehende nicht vertrauenswürdige Adresse, damit ein Besucher keinen gefälschten Hop voranstellen kann. Empfohlen.

  • client_ip_headers CF-Connecting-IP

    Hinter Cloudflare: den Cloudflare-Bereichen vertrauen und CF-Connecting-IP lesen.

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

Gesetzte Header

Werden der Anfrage an Ihre App hinzugefügt. Eingehende X-IPScanner-*-Header werden vorher entfernt, damit kein Client ein eigenes Ergebnis mitschickt.

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

    Ob die Prüfung lief und falls nicht, warum.

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

    Traffic-Klasse des Besuchers.

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

    Was mit der Anfrage geschah. Im Monitor-Modus would_flag und would_block.

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

    Netzwerkklasse der Adresse.

  • X-IPScanner-Anonymizedtrue, false

    Das Netzwerk verbirgt, wo der Besucher ist.

  • X-IPScanner-Risk0-100

    Risikowert der Adresse.

  • X-IPScanner-CountryDE

    Land der Adresse.

  • X-IPScanner-Sitesite_...

    Die Site-ID, wenn eine gesetzt ist.

Schlägt eine Prüfung fehl oder wird sie übersprungen, ist nur X-IPScanner-Status gesetzt.

Platzhalter

  • {http.vars.ipscanner.status}

    Status der Prüfung, für Logs und Matcher nach der Direktive.

  • {http.vars.ipscanner.class}

    Traffic-Klasse, gesetzt wenn der Status ok ist.

  • {http.vars.ipscanner.action}

    allow, flag, block, would_flag oder 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

Cache und Fail-open

  • Richtlinie der WebsiteGET /v1/sites/{id}/policy

    Modus und Richtlinie pro Klasse, 30 s im Cache. Scheitert eine Aktualisierung, gilt die letzte gültige Richtlinie bis zu 24 Stunden. Änderungen greifen ohne Neustart.

  • Ergebnis-Cache

    Eine Prüfung pro Besucher (Website, IP, User-Agent) alle 10 Minuten, im Speicher, bis zu 10.000 Einträge. Ein Neuladen der Konfiguration startet mit leerem Cache.

  • Fail-open

    1,5 s für Ergebnis und Richtlinie zusammen. Bei Zeitüberschreitung oder API-Fehler passiert die Anfrage, und Prüfungen pausieren 30 s, nach 401, 402, 403 oder 429 fünf Minuten.

  • Immer durchgelassen

    Verifizierte Crawler, OPTIONS-Anfragen, private und Loopback-Adressen sowie Pfade auf der Ausnahmeliste.

  • Blockiert

    Eine 403-Seite mit der Request-ID. Der Monitor-Modus blockiert nie.

  • Free-Plan

    Websites im Free-Plan bleiben im Monitor-Modus.

  • Kosten

    2 Request-Einheiten pro Besucher ohne Cache-Treffer. Wiederholte Anfragen im Cache-Fenster sind kostenlos.

Was gesendet wird

  • POST /v1/edge/checkZählt als 2 Anfragen

    Ein Aufruf pro Besucher ohne Cache-Treffer.

  • GET /v1/sites/{id}/policyNicht berechnet

    Die Richtlinie der Website, wenn eine Site-ID gesetzt ist.

  • X-IPScanner-Source: caddy

    Kennzeichnet die Aufrufe in Traffic und Nutzung als Aufrufe dieser Integration.

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

    Die Version, angezeigt auf der Seite der Website im Dashboard.

Request-Body

  • sitestring

    Die Site-ID, wenn eine gesetzt ist.

  • ipstring

    Die Adresse des Besuchers.

  • user_agentstring

    Der User-Agent des Besuchers.

  • headersobject

    Accept, Accept-Language, Accept-Encoding, Sec-CH-UA* und Sec-Fetch-*, jeweils auf 512 Byte gekürzt.

  • request_idstring

    Die X-Request-Id der Anfrage oder eine neue ID, die auch auf der Sperrseite steht.

Die Edge-Prüfung, die gesendet wird
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"
  }'