IPScanner

Integrationen

Traefik-Plugin

Eine Middleware aus dem Traefik Plugin Catalog, die jeden Besucher prüft, bevor der Router die Anfrage weitergibt.

Installation

  1. 1Deklarieren Sie das Plugin in der statischen Konfiguration von Traefik und starten Sie Traefik neu.
  2. 2Legen Sie eine Traefik-Website im Dashboard an und kopieren Sie ihre Site-ID.
  3. 3Setzen Sie IPSCANNER_API_KEY im Traefik-Container.
  4. 4Legen Sie eine ipscanner-Middleware mit der Site-ID an und hängen Sie sie an einen Router.

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

Überblick auf der Seite zum Traefik-Plugin, Quellcode und vollständige Beispiele auf GitHub.

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

Coolify, Compose, Kubernetes

  • Coolify

    Plugin-Flags in die command-Liste des Proxys, den Schlüssel in seine environment. Dann die Middleware in die Container-Labels Ihrer App, angehängt an jeden von Coolify erzeugten Router. Pro App ein eigener Middleware-Name.

  • Docker Compose

    Flags am Traefik-Service, die Middleware in den Labels Ihrer App. Andere Router nutzen sie als ipscanner@docker.

  • Kubernetes

    Eine Middleware-Ressource mit dem Schlüssel aus einem Secret. Verweisen Sie darauf aus einer IngressRoute oder aus einem Ingress mit der Annotation router.middlewares.

  • File Provider

    Die Middleware in einer dynamischen Konfigurationsdatei, mit dem Schlüssel aus einem eingebundenen Secret.

Ohne Schlüssel passiert jede Anfrage mit 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_...

Konfiguration

  • apiKey

    API-Schlüssel. Plugin-Optionen erscheinen im Traefik-Dashboard, nutzen Sie daher besser IPSCANNER_API_KEY, apiKeyFile oder einen urn:k8s:secret-Verweis.

  • apiKeyFile

    Datei mit dem API-Schlüssel, etwa ein eingebundenes Docker- oder Kubernetes-Secret.

  • siteId

    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.

  • blockClassesStandard malicious_automation

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

  • trustedProxies

    Adressen und CIDR-Bereiche, deren IP-Header vertraut wird. private ergänzt die privaten Bereiche, cloudflare die Cloudflare-Bereiche.

  • ipHeadersStandard X-Forwarded-For

    Header, die der Reihe nach von einem vertrauenswürdigen Proxy gelesen werden. Hinter Cloudflare: CF-Connecting-IP.

  • timeoutStandard 1500ms

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

  • cacheTTLStandard 10m

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

  • cacheSizeStandard 10000

    Ergebnisse im Speicher.

  • policyTTLStandard 30s

    Wie lange die Richtlinie der Website wiederverwendet wird.

  • skipPathsStandard statische Dateien

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

  • blockMessageStandard Blocked by IPScanner edge guard.

    Text der 403-Seite.

  • debugStandard false

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

  • apiUrlStandard https://ipscanner.io

    Basis-URL der API.

Listen nehmen YAML-Listen oder kommagetrennte Werte (blockClasses=tor,vpn in Labels). Zeitangaben in Go-Syntax: 1500ms, 30s, 10m. Eine ungültige Option deaktiviert den Router mit einem Fehler im Traefik-Log.

Client-IP

Der Besucher ist die Adresse, die Traefik sieht, außer diese Adresse ist ein vertrauenswürdiger Proxy.

  • trustedProxies

    X-Forwarded-For oder die Liste ipHeaders wird nur von diesen Adressen gelesen.

  • forwardedHeaders.trustedIPs

    Traefik verwirft X-Forwarded-For von Peers außerhalb der vertrauenswürdigen IPs des Entry Points. Setzen Sie also beides oder lesen Sie CF-Connecting-IP.

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

    Hinter Cloudflare mit aktivem Proxy (orange Wolke): beides an der Middleware setzen.

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.

Anfrage an Ihre App
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 Besucher. Bleibt bei Konfigurationsänderungen erhalten.

  • 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: traefik

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

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