IPScanner

Integraties

Traefik-plugin

Een middleware uit de Traefik Plugin Catalog die elke bezoeker checkt voordat de router het verzoek doorgeeft.

Installatie

  1. 1Declareer de plugin in de statische configuratie van Traefik en herstart Traefik.
  2. 2Voeg een Traefik-site toe in het dashboard en kopieer de Site-ID.
  3. 3Zet IPSCANNER_API_KEY op de Traefik-container.
  4. 4Voeg een ipscanner-middleware met de Site-ID toe en hang hem aan een router.

Een nieuwe site start in monitor-modus: hij voegt headers toe en blokkeert niets tot je overschakelt naar enforce.

Overzicht op de pagina van de Traefik-plugin, broncode en volledige voorbeelden op GitHub.

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

Coolify, Compose, Kubernetes

  • Coolify

    Plugin-flags in de command-lijst van de proxy en de sleutel in zijn environment. Daarna de middleware in de container-labels van je app, toegevoegd aan elke router die Coolify aanmaakte. Gebruik per app een eigen middleware-naam.

  • Docker Compose

    Flags op de Traefik-service, de middleware in de labels van je app. Andere routers hergebruiken hem als ipscanner@docker.

  • Kubernetes

    Een Middleware-resource met de sleutel uit een Secret. Verwijs ernaar vanuit een IngressRoute, of vanuit een Ingress met de annotatie router.middlewares.

  • File provider

    De middleware in een dynamisch configuratiebestand, met de sleutel uit een gekoppeld secret.

Zonder sleutel gaat elk verzoek door met 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_...

Configuratie

  • apiKey

    API-sleutel. Plugin-opties zijn zichtbaar in het Traefik-dashboard, dus gebruik liever IPSCANNER_API_KEY, apiKeyFile of een urn:k8s:secret-verwijzing.

  • apiKeyFile

    Bestand met de API-sleutel, zoals een gekoppeld Docker- of Kubernetes-secret.

  • siteId

    Site-ID uit het dashboard. Modus en beleid komen dan uit het dashboard.

  • modestandaard monitor

    monitor of enforce. Met een site heeft alleen monitor effect: de site blijft dan in monitor-modus.

  • blockClassesstandaard malicious_automation

    Klassen die enforce zonder site blokkeert: malicious_automation, ai_agent, tor, vpn, proxy, hosting, relay of none.

  • trustedProxies

    Adressen en CIDR-bereiken waarvan IP-headers vertrouwd worden. private voegt de private bereiken toe, cloudflare die van Cloudflare.

  • ipHeadersstandaard X-Forwarded-For

    Headers die op volgorde gelezen worden van een vertrouwde proxy. Achter Cloudflare: CF-Connecting-IP.

  • timeoutstandaard 1500ms

    Tijdbudget voor één check. Bij een timeout gaat het verzoek door.

  • cacheTTLstandaard 10m

    Hoe lang een oordeel per site, IP en user agent hergebruikt wordt.

  • cacheSizestandaard 10000

    Oordelen in het geheugen.

  • policyTTLstandaard 30s

    Hoe lang het beleid van de site hergebruikt wordt.

  • skipPathsstandaard statische bestanden

    Regex op het pad, hoofdletterongevoelig. Passende verzoeken worden niet gecheckt; none checkt elk pad.

  • blockMessagestandaard Blocked by IPScanner edge guard.

    Tekst van de 403-pagina.

  • debugstandaard false

    Zet X-IPScanner-Status, -Class en -Action op responses en logt elke beslissing op één regel.

  • apiUrlstandaard https://ipscanner.io

    Basis-URL van de API.

Lijsten accepteren YAML-lijsten of waarden met komma's (blockClasses=tor,vpn in labels). Duren in Go-syntax: 1500ms, 30s, 10m. Een ongeldige optie schakelt de router uit met een fout in het Traefik-log.

Client-IP

De bezoeker is het adres dat Traefik ziet, tenzij dat adres een vertrouwde proxy is.

  • trustedProxies

    X-Forwarded-For, of de lijst ipHeaders, wordt alleen van deze adressen gelezen.

  • forwardedHeaders.trustedIPs

    Traefik gooit X-Forwarded-For weg van peers buiten de vertrouwde IP's van het entry point, dus zet beide, of lees CF-Connecting-IP.

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

    Achter Cloudflare met de oranje wolk aan: zet beide op de middleware.

Headers die erbij komen

Toegevoegd aan het verzoek dat je app ontvangt. Inkomende X-IPScanner-*-headers worden eerst verwijderd, zodat een client geen eigen oordeel kan meesturen.

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

    Of de check gedraaid heeft, en zo niet, waarom.

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

    Verkeersklasse van de bezoeker.

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

    Wat er met het verzoek gebeurde. Monitor-modus geeft would_flag en would_block.

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

    Netwerkklasse van het adres.

  • X-IPScanner-Anonymizedtrue, false

    Het netwerk verbergt waar de bezoeker is.

  • X-IPScanner-Risk0-100

    Risicoscore van het adres.

  • X-IPScanner-CountryDE

    Land van het adres.

  • X-IPScanner-Sitesite_...

    De Site-ID, als die gezet is.

Mislukt een check of wordt hij overgeslagen, dan is alleen X-IPScanner-Status gezet.

Verzoek naar je 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 en fail open

  • Beleid van de siteGET /v1/sites/{id}/policy

    Modus en beleid per klasse, 30 s gecachet. Mislukt een verversing, dan blijft het laatste goede beleid 24 uur gelden. Wijzigingen werken zonder herstart.

  • Oordeel-cache

    Eén check per bezoeker (site, IP, user agent) per 10 minuten, in het geheugen, tot 10.000 bezoekers. Blijft bewaard bij het herladen van de configuratie.

  • Fail open

    1,5 s voor oordeel en beleid samen. Bij een timeout of API-fout gaat het verzoek door en pauzeren checks 30 s, of 5 minuten na een 401, 402, 403 of 429.

  • Altijd door

    Geverifieerde crawlers, OPTIONS-verzoeken, private en loopback-adressen, en paden op de uitzonderingslijst.

  • Geblokkeerd

    Een 403-pagina met het request-ID. Monitor-modus blokkeert nooit.

  • Free-abonnement

    Sites op het Free-abonnement blijven in monitor-modus.

  • Kosten

    2 request-eenheden per bezoeker die niet in de cache zit. Herhaalde verzoeken binnen het cachevenster zijn gratis.

Wat er verstuurd wordt

  • POST /v1/edge/checkTelt als 2 verzoeken

    Eén call per bezoeker die niet in de cache zit.

  • GET /v1/sites/{id}/policyTelt niet mee

    Het beleid van de site, als een Site-ID gezet is.

  • X-IPScanner-Source: traefik

    Markeert de calls in je verkeer en verbruik als die van deze integratie.

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

    De versie, zichtbaar op de pagina van de site in het dashboard.

Request-body

  • sitestring

    De Site-ID, als die gezet is.

  • ipstring

    Het adres van de bezoeker.

  • user_agentstring

    De User-Agent van de bezoeker.

  • headersobject

    Accept, Accept-Language, Accept-Encoding, Sec-CH-UA* en Sec-Fetch-*, elk ingekort tot 512 bytes.

  • request_idstring

    De X-Request-Id van het verzoek of een nieuw ID, dat ook op de blokkadepagina staat.

De edge-check die hij doet
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"
  }'