IPScanner

Integraties

Caddy-module

De directive ipscanner checkt elke bezoeker in Caddy zelf, vóór reverse_proxy of file_server.

Installatie

  1. 1Bouw Caddy met de module via xcaddy, of kies github.com/ipscanner/ipscanner-caddy op caddyserver.com/download.
  2. 2Voeg een Caddy-site toe in het dashboard en kopieer de Site-ID.
  3. 3Zet IPSCANNER_API_KEY in de omgeving van Caddy.
  4. 4Zet de directive ipscanner met de Site-ID in je site-blok.

Vereist Caddy 2.8 of nieuwer. Controleer met caddy list-modules | grep ipscanner.

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 Caddy-module, broncode op GitHub.

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

Caddyfile

  • ipscanner

    De module zet hem vóór basic_auth, dus een globale order-regel is niet nodig. Hij draait na header, redir en rewrites, vóór authenticatie, reverse_proxy en file_server.

  • ipscanner /app/* { ... }

    Een matcher beperkt de check tot bepaalde paden.

  • mode, block_classes

    Zonder site_id stelt de Caddyfile de modus en de geblokkeerde klassen in.

  • "handler": "ipscanner"

    In JSON-config een handler met dezelfde velden.

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

Configuratie

  • api_keystandaard {env.IPSCANNER_API_KEY}

    API-sleutel. Placeholders werken, dus de sleutel kan uit de omgeving of een bestand komen.

  • site_id

    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.

  • block_classesstandaard malicious_automation

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

  • timeoutstandaard 1.5s

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

  • cache_ttlstandaard 10m

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

  • cache_sizestandaard 10000

    Oordelen in het geheugen.

  • policy_ttlstandaard 30s

    Hoe lang het beleid van de site hergebruikt wordt.

  • skip_pathsstandaard statische bestanden

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

  • block_messagestandaard Blocked by IPScanner edge guard.

    Tekst van de 403-pagina.

  • debugstandaard uit

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

  • api_urlstandaard https://ipscanner.io

    Basis-URL van de API.

De standaard skip_paths dekt robots.txt, sitemap.xml, favicon.ico, scripts, stylesheets, source maps, afbeeldingen, fonts en video.

Client-IP

De module gebruikt het client-IP dat Caddy bepaald heeft en leest X-Forwarded-For nooit zelf. Zonder trusted_proxies is dat het peer-adres.

  • trusted_proxies

    Vertrouw je load balancer of CDN in de globale serveropties.

  • trusted_proxies_strict

    Neemt het meest rechtse onvertrouwde adres, zodat een bezoeker geen nep-hop vooraan kan zetten. Aanbevolen.

  • client_ip_headers CF-Connecting-IP

    Achter Cloudflare: vertrouw de Cloudflare-bereiken en lees CF-Connecting-IP.

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

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.

Placeholders

  • {http.vars.ipscanner.status}

    Status van de check, voor logs en matchers na de directive.

  • {http.vars.ipscanner.class}

    Verkeersklasse, gezet als de status ok is.

  • {http.vars.ipscanner.action}

    allow, flag, block, would_flag of 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 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 items. Na het herladen van de config begint de cache leeg.

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

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

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