Integraciones

Plugin de Traefik

Un middleware del Traefik Plugin Catalog que comprueba a cada visitante antes de que el router pase la petición.

Instalación

1Declara el plugin en la configuración estática de Traefik y reinicia Traefik.
2Añade un sitio Traefik en el panel y copia su Site ID.
3Define IPSCANNER_API_KEY en el contenedor de Traefik.
4Añade un middleware ipscanner con el Site ID y ponlo en un router.

Un sitio nuevo empieza en modo monitor: añade cabeceras y no bloquea nada hasta que lo pases a enforce.

Resumen en la página del plugin de Traefik, código y ejemplos completos en GitHub.

Coolify, Compose, Kubernetes

Coolify
Los flags del plugin en la lista command del proxy y la clave en su environment. Después, el middleware en los labels del contenedor de tu app, añadido a cada router que generó Coolify. Un nombre de middleware por app.
Docker Compose
Flags en el servicio de Traefik, el middleware en los labels de tu app. Otros routers lo reutilizan como ipscanner@docker.
Kubernetes
Un recurso Middleware con la clave de un Secret. Referéncialo desde un IngressRoute, o desde un Ingress con la anotación router.middlewares.
File provider
El middleware en un archivo de configuración dinámica, con la clave de un secret montado.

Sin clave, todas las peticiones pasan con 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_...

Configuración

apiKey
Clave de API. Las opciones del plugin se ven en el panel de Traefik, así que mejor usa IPSCANNER_API_KEY, apiKeyFile o una referencia urn:k8s:secret.
apiKeyFile
Archivo con la clave de API, como un secret de Docker o Kubernetes montado.
siteId
Site ID del panel. El modo y la política vienen entonces del panel.
modepor defecto monitor
monitor o enforce. Con un sitio, solo monitor tiene efecto: mantiene el sitio en modo monitor.
blockClassespor defecto malicious_automation
Clases que enforce bloquea sin sitio: malicious_automation, ai_agent, tor, vpn, proxy, hosting, relay o none.
trustedProxies
Direcciones y rangos CIDR cuyas cabeceras de IP se aceptan. private añade los rangos privados, cloudflare los de Cloudflare.
ipHeaderspor defecto X-Forwarded-For
Cabeceras que se leen en orden desde un proxy de confianza. Detrás de Cloudflare: CF-Connecting-IP.
timeoutpor defecto 1500ms
Presupuesto de una comprobación. Si se agota, la petición pasa.
cacheTTLpor defecto 10m
Cuánto se reutiliza un veredicto por sitio, IP y user agent.
cacheSizepor defecto 10000
Veredictos en memoria.
policyTTLpor defecto 30s
Cuánto se reutiliza la política del sitio.
skipPathspor defecto archivos estáticos
Regex sobre la ruta, sin distinguir mayúsculas. Las peticiones que coinciden no se comprueban; none comprueba todas las rutas.
blockMessagepor defecto Blocked by IPScanner edge guard.
Texto de la página 403.
debugpor defecto false
Añade X-IPScanner-Status, -Class y -Action a las respuestas y registra cada decisión en una línea.
apiUrlpor defecto https://ipscanner.io
URL base de la API.

Las listas admiten listas YAML o valores separados por comas (blockClasses=tor,vpn en labels). Las duraciones usan la sintaxis de Go: 1500ms, 30s, 10m. Una opción no válida desactiva el router con un error en el log de Traefik.

IP del cliente

El visitante es la dirección que ve Traefik, salvo que esa dirección sea un proxy de confianza.

trustedProxies
X-Forwarded-For, o la lista ipHeaders, solo se lee de estas direcciones.
forwardedHeaders.trustedIPs
Traefik descarta X-Forwarded-For de pares fuera de las IP de confianza del entry point, así que define ambas cosas o lee CF-Connecting-IP.
trustedProxies=cloudflare, ipHeaders=CF-Connecting-IP
Detrás de Cloudflare con la nube naranja activa, añade las dos al middleware.

Cabeceras que añade

Se añaden a la petición que recibe tu app. Antes se quitan las cabeceras X-IPScanner-* entrantes, así un cliente no puede mandar su propio veredicto.

X-IPScanner-Statusok, error, timeout, backoff, skipped
Si la comprobación se hizo y, si no, por qué.
X-IPScanner-Classhuman, verified_bot, ai_agent, …
Clase de tráfico del visitante.
X-IPScanner-Actionallow, flag, block, would_flag, would_block
Qué pasó con la petición. En modo monitor: would_flag y would_block.
X-IPScanner-Network-Classresidential_clean, hosting, vpn, tor, …
Clase de red de la dirección.
X-IPScanner-Anonymizedtrue, false
La red oculta dónde está el visitante.
X-IPScanner-Risk0-100
Puntuación de riesgo de la dirección.
X-IPScanner-CountryDE
País de la dirección.
X-IPScanner-Sitesite_...
El Site ID, si hay uno.

Si una comprobación falla o se omite, solo se fija X-IPScanner-Status.

Petición a tu 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

Caché y fail open

Política del sitioGET /v1/sites/{id}/policy
Modo y política por clase, en caché 30 s. Si una actualización falla, la última política válida sigue 24 horas. Los cambios se aplican sin recargar.
Caché de veredictos
Una comprobación por visitante (sitio, IP, user agent) cada 10 minutos, en memoria, hasta 10.000 visitantes. Se mantiene al recargar la configuración.
Fail open
1,5 s para veredicto y política juntos. Ante un timeout o un error de la API la petición pasa y las comprobaciones paran 30 s, o 5 minutos tras un 401, 402, 403 o 429.
Siempre pasan
Crawlers verificados, peticiones OPTIONS, direcciones privadas y de loopback, y rutas de la lista de exclusión.
Bloqueado
Una página 403 con el ID de la petición. El modo monitor nunca bloquea.
Plan Free
Los sitios del plan Free se quedan en modo monitor.
Coste
2 unidades de petición por visitante fuera de caché. Las peticiones repetidas dentro de la ventana de caché son gratis.

Qué envía

POST /v1/edge/checkCuenta como 2 solicitudes
Una llamada por visitante fuera de caché.
GET /v1/sites/{id}/policyNo consume cupo
La política del sitio, si hay un Site ID.
X-IPScanner-Source: traefik
Marca las llamadas como de esta integración en tu tráfico y tu uso.
User-Agent: ipscanner-traefik/<version>
La versión, que se muestra en la página del sitio en el panel.

Cuerpo de la petición

sitestring
El Site ID, si hay uno.
ipstring
La dirección del visitante.
user_agentstring
El User-Agent del visitante.
headersobject
Accept, Accept-Language, Accept-Encoding, Sec-CH-UA* y Sec-Fetch-*, cada una recortada a 512 bytes.
request_idstring
El X-Request-Id de la petición o un ID nuevo, que también aparece en la página de bloqueo.

La comprobación en el edge que hace

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"
  }'