IPScanner

Intégrations

Plugin Traefik

Un middleware du Traefik Plugin Catalog qui vérifie chaque visiteur avant que le routeur transmette la requête.

Installation

  1. 1Déclarez le plugin dans la configuration statique de Traefik et redémarrez Traefik.
  2. 2Ajoutez un site Traefik dans le tableau de bord et copiez son Site ID.
  3. 3Définissez IPSCANNER_API_KEY sur le conteneur Traefik.
  4. 4Ajoutez un middleware ipscanner avec le Site ID et placez-le sur un routeur.

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 plugin Traefik, code source et exemples complets sur GitHub.

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

Coolify, Compose, Kubernetes

  • Coolify

    Les options du plugin dans la liste command du proxy et la clé dans son environment. Puis le middleware dans les labels de conteneur de votre app, ajouté à chaque routeur généré par Coolify. Un nom de middleware par app.

  • Docker Compose

    Les options sur le service Traefik, le middleware dans les labels de votre app. Les autres routeurs le réutilisent sous le nom ipscanner@docker.

  • Kubernetes

    Une ressource Middleware avec la clé issue d'un Secret. Référencez-la depuis une IngressRoute, ou depuis un Ingress avec l'annotation router.middlewares.

  • File provider

    Le middleware dans un fichier de configuration dynamique, avec la clé issue d'un secret monté.

Sans clé, chaque requête passe avec 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_...

Configuration

  • apiKey

    Clé d'API. Les options du plugin s'affichent dans le tableau de bord Traefik : préférez IPSCANNER_API_KEY, apiKeyFile ou une référence urn:k8s:secret.

  • apiKeyFile

    Fichier contenant la clé d'API, par exemple un secret Docker ou Kubernetes monté.

  • siteId

    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.

  • blockClassespar défaut malicious_automation

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

  • trustedProxies

    Adresses et plages CIDR dont les en-têtes IP sont acceptés. private ajoute les plages privées, cloudflare celles de Cloudflare.

  • ipHeaderspar défaut X-Forwarded-For

    En-têtes lus dans l'ordre depuis un proxy de confiance. Derrière Cloudflare : CF-Connecting-IP.

  • timeoutpar défaut 1500ms

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

  • cacheTTLpar défaut 10m

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

  • cacheSizepar défaut 10000

    Verdicts gardés en mémoire.

  • policyTTLpar défaut 30s

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

  • skipPathspar 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.

  • blockMessagepar défaut Blocked by IPScanner edge guard.

    Texte de la page 403.

  • debugpar défaut false

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

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

    URL de base de l'API.

Les listes acceptent des listes YAML ou des valeurs séparées par des virgules (blockClasses=tor,vpn dans les labels). Les durées suivent la syntaxe Go : 1500ms, 30s, 10m. Une option invalide désactive le routeur avec une erreur dans le journal Traefik.

IP du client

Le visiteur est l'adresse que voit Traefik, sauf si cette adresse est un proxy de confiance.

  • trustedProxies

    X-Forwarded-For, ou la liste ipHeaders, n'est lu que depuis ces adresses.

  • forwardedHeaders.trustedIPs

    Traefik supprime X-Forwarded-For venant de pairs hors des IP de confiance de l'entry point : définissez les deux, ou lisez CF-Connecting-IP.

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

    Derrière Cloudflare avec le proxy activé (nuage orange), ajoutez les deux au middleware.

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.

Requête vers votre 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 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 visiteurs. Conservé lors des rechargements de configuration.

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

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

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