IPScanner

Intégrations

Module Caddy

La directive ipscanner vérifie chaque visiteur dans Caddy, avant reverse_proxy ou file_server.

Installation

  1. 1Compilez Caddy avec le module via xcaddy, ou choisissez github.com/ipscanner/ipscanner-caddy sur caddyserver.com/download.
  2. 2Ajoutez un site Caddy dans le tableau de bord et copiez son Site ID.
  3. 3Définissez IPSCANNER_API_KEY dans l'environnement de Caddy.
  4. 4Ajoutez la directive ipscanner avec le Site ID dans votre bloc de site.

Nécessite Caddy 2.8 ou plus récent. Vérifiez avec caddy list-modules | grep ipscanner.

Un nouveau site démarre en mode monitor : il ajoute les en-têtes et ne bloque rien tant que vous ne passez pas en enforce.

Présentation sur la page du module Caddy, code source sur GitHub.

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

Caddyfile

  • ipscanner

    Le module la place avant basic_auth, aucune ligne order globale n'est donc nécessaire. Elle s'exécute après header, redir et les réécritures, avant l'authentification, reverse_proxy et file_server.

  • ipscanner /app/* { ... }

    Un matcher limite la vérification à certains chemins.

  • mode, block_classes

    Sans site_id, le Caddyfile définit le mode et les classes bloquées.

  • "handler": "ipscanner"

    En configuration JSON, un handler avec les mêmes champs.

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

Configuration

  • api_keypar défaut {env.IPSCANNER_API_KEY}

    Clé d'API. Les placeholders fonctionnent : la clé peut venir de l'environnement ou d'un fichier.

  • site_id

    Site ID du tableau de bord. Le mode et la politique viennent alors du tableau de bord.

  • modepar défaut monitor

    monitor ou enforce. Avec un site, seul monitor a un effet : il maintient le site en mode monitor.

  • block_classespar défaut malicious_automation

    Classes bloquées en mode enforce sans site : malicious_automation, ai_agent, tor, vpn, proxy, hosting, relay ou none.

  • timeoutpar défaut 1.5s

    Budget d'une vérification. En cas de dépassement, la requête passe.

  • cache_ttlpar défaut 10m

    Durée de réutilisation d'un verdict par site, IP et user agent.

  • cache_sizepar défaut 10000

    Verdicts gardés en mémoire.

  • policy_ttlpar défaut 30s

    Durée de réutilisation de la politique du site.

  • skip_pathspar défaut fichiers statiques

    Regex sur le chemin, sans distinction de casse. Les requêtes correspondantes ne sont pas vérifiées ; none vérifie tous les chemins.

  • block_messagepar défaut Blocked by IPScanner edge guard.

    Texte de la page 403.

  • debugpar défaut désactivé

    Ajoute X-IPScanner-Status, -Class et -Action aux réponses et journalise chaque décision sur une ligne.

  • api_urlpar défaut https://ipscanner.io

    URL de base de l'API.

Le skip_paths par défaut couvre robots.txt, sitemap.xml, favicon.ico, scripts, feuilles de style, source maps, images, polices et vidéos.

IP du client

Le module utilise l'IP client résolue par Caddy et ne lit jamais X-Forwarded-For lui-même. Sans trusted_proxies, c'est l'adresse du pair.

  • trusted_proxies

    Déclarez votre load balancer ou CDN de confiance dans les options globales du serveur.

  • trusted_proxies_strict

    Prend l'adresse non fiable la plus à droite, un visiteur ne peut donc pas ajouter un faux saut en tête. Recommandé.

  • client_ip_headers CF-Connecting-IP

    Derrière Cloudflare : faites confiance aux plages Cloudflare et lisez CF-Connecting-IP.

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

En-têtes ajoutés

Ajoutés à la requête que reçoit votre app. Les en-têtes X-IPScanner-* entrants sont d'abord supprimés, un client ne peut donc pas envoyer son propre verdict.

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

    Si la vérification a eu lieu, et sinon pourquoi.

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

    Classe de trafic du visiteur.

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

    Ce qui est arrivé à la requête. En mode monitor : would_flag et would_block.

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

    Classe de réseau de l'adresse.

  • X-IPScanner-Anonymizedtrue, false

    Le réseau masque où se trouve le visiteur.

  • X-IPScanner-Risk0-100

    Score de risque de l'adresse.

  • X-IPScanner-CountryDE

    Pays de l'adresse.

  • X-IPScanner-Sitesite_...

    Le Site ID, s'il est défini.

Si une vérification échoue ou est ignorée, seul X-IPScanner-Status est défini.

Placeholders

  • {http.vars.ipscanner.status}

    Statut de la vérification, pour les logs et les matchers après la directive.

  • {http.vars.ipscanner.class}

    Classe de trafic, définie quand le statut est ok.

  • {http.vars.ipscanner.action}

    allow, flag, block, would_flag ou 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 et fail open

  • Politique du siteGET /v1/sites/{id}/policy

    Mode et politique par classe, en cache 30 s. Si une mise à jour échoue, la dernière politique valide reste en place 24 heures. Les changements s'appliquent sans rechargement.

  • Cache des verdicts

    Une vérification par visiteur (site, IP, user agent) toutes les 10 minutes, en mémoire, jusqu'à 10 000 entrées. Un rechargement de configuration repart d'un cache vide.

  • Fail open

    1,5 s pour le verdict et la politique ensemble. En cas de dépassement ou d'erreur d'API, la requête passe et les vérifications s'arrêtent 30 s, ou 5 minutes après un 401, 402, 403 ou 429.

  • Toujours autorisés

    Crawlers vérifiés, requêtes OPTIONS, adresses privées et de loopback, et chemins de la liste d'exclusion.

  • Bloqué

    Une page 403 avec l'identifiant de requête. Le mode monitor ne bloque jamais.

  • Offre Free

    Les sites de l'offre Free restent en mode monitor.

  • Coût

    2 unités de requête par visiteur hors cache. Les requêtes répétées dans la fenêtre du cache sont gratuites.

Ce qui est envoyé

  • POST /v1/edge/checkCompte pour 2 requêtes

    Un appel par visiteur hors cache.

  • GET /v1/sites/{id}/policyNon décompté

    La politique du site, si un Site ID est défini.

  • X-IPScanner-Source: caddy

    Attribue les appels à cette intégration dans votre trafic et votre consommation.

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

    La version, affichée sur la page du site dans le tableau de bord.

Corps de la requête

  • sitestring

    Le Site ID, s'il est défini.

  • ipstring

    L'adresse du visiteur.

  • user_agentstring

    Le User-Agent du visiteur.

  • headersobject

    Accept, Accept-Language, Accept-Encoding, Sec-CH-UA* et Sec-Fetch-*, chacun coupé à 512 octets.

  • request_idstring

    Le X-Request-Id de la requête ou un nouvel identifiant, affiché aussi sur la page de blocage.

La vérification edge envoyée
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"
  }'