IPScanner

Integraciones

Módulo de Caddy

La directiva ipscanner comprueba a cada visitante dentro de Caddy, antes de reverse_proxy o file_server.

Instalación

  1. 1Compila Caddy con el módulo usando xcaddy, o elige github.com/ipscanner/ipscanner-caddy en caddyserver.com/download.
  2. 2Añade un sitio Caddy en el panel y copia su Site ID.
  3. 3Define IPSCANNER_API_KEY en el entorno de Caddy.
  4. 4Añade la directiva ipscanner con el Site ID a tu bloque de sitio.

Requiere Caddy 2.8 o posterior. Compruébalo con caddy list-modules | grep ipscanner.

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 módulo de Caddy, código en GitHub.

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

Caddyfile

  • ipscanner

    El módulo la coloca antes de basic_auth, así que no hace falta una línea order global. Se ejecuta después de header, redir y las reescrituras, y antes de la autenticación, reverse_proxy y file_server.

  • ipscanner /app/* { ... }

    Un matcher limita la comprobación a algunas rutas.

  • mode, block_classes

    Sin site_id, el Caddyfile fija el modo y las clases bloqueadas.

  • "handler": "ipscanner"

    En configuración JSON, un handler con los mismos campos.

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

Configuración

  • api_keypor defecto {env.IPSCANNER_API_KEY}

    Clave de API. Admite placeholders, así que la clave puede venir del entorno o de un archivo.

  • site_id

    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.

  • block_classespor defecto malicious_automation

    Clases que enforce bloquea sin sitio: malicious_automation, ai_agent, tor, vpn, proxy, hosting, relay o none.

  • timeoutpor defecto 1.5s

    Presupuesto de una comprobación. Si se agota, la petición pasa.

  • cache_ttlpor defecto 10m

    Cuánto se reutiliza un veredicto por sitio, IP y user agent.

  • cache_sizepor defecto 10000

    Veredictos en memoria.

  • policy_ttlpor defecto 30s

    Cuánto se reutiliza la política del sitio.

  • skip_pathspor defecto archivos estáticos

    Regex sobre la ruta, sin distinguir mayúsculas. Las peticiones que coinciden no se comprueban; none comprueba todas las rutas.

  • block_messagepor defecto Blocked by IPScanner edge guard.

    Texto de la página 403.

  • debugpor defecto desactivado

    Añade X-IPScanner-Status, -Class y -Action a las respuestas y registra cada decisión en una línea.

  • api_urlpor defecto https://ipscanner.io

    URL base de la API.

El skip_paths por defecto cubre robots.txt, sitemap.xml, favicon.ico, scripts, hojas de estilo, source maps, imágenes, fuentes y vídeo.

IP del cliente

El módulo usa la IP de cliente que resolvió Caddy y nunca lee X-Forwarded-For por su cuenta. Sin trusted_proxies, es la dirección del par.

  • trusted_proxies

    Confía en tu balanceador o CDN en las opciones globales del servidor.

  • trusted_proxies_strict

    Toma la dirección no confiable más a la derecha, así un visitante no puede anteponer un salto falso. Recomendado.

  • client_ip_headers CF-Connecting-IP

    Detrás de Cloudflare: confía en los rangos de Cloudflare y lee CF-Connecting-IP.

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

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.

Placeholders

  • {http.vars.ipscanner.status}

    Estado de la comprobación, para logs y matchers después de la directiva.

  • {http.vars.ipscanner.class}

    Clase de tráfico, presente cuando el estado es ok.

  • {http.vars.ipscanner.action}

    allow, flag, block, would_flag o 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

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 entradas. Al recargar la configuración la caché empieza vacía.

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

    Marca las llamadas como de esta integración en tu tráfico y tu uso.

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