Honeypot Webhooks: envía las detecciones de ataques a cualquier API

El Honeypot Server ReportedIP ahora puede enviar cada ataque que detecte a cualquier herramienta que ya utilices. La versión 1.3.0 convierte sus Webhooks en un enrutador configurable: elige el método HTTP, los encabezados y el cuerpo del mensaje, y envía las detecciones directamente a tu SIEM, Slack, Discord o AbuseIPDB.

Si ya tienes en funcionamiento un nodo Honeypot, actualízalo a la versión 1.3.0 y configura un Endpoint en el panel de administración. La configuración completa se describe en la documentación del Honeypot Server.

Qué hacen los Honeypot Webhooks

A webhook es un endpoint HTTP(S) que recibe una solicitud cada vez que el Honeypot detecta un ataque. Esta función se introdujo por primera vez en la versión 1.2.0 para reenviar las detecciones a la ReportedIP API y a recopiladores externos. A partir de la versión 1.3.0, esas mismas detecciones pueden enviarse a cualquier API HTTP: Splunk, Elastic, un canal de Slack o Discord, o una segunda base de datos de amenazas.

La entrega se produce después de que la respuesta de la trampa ya se haya enviado al atacante, por lo que añadir un Webhook nunca ralentiza el Honeypot. Cada uno de los 36 analizadores integrados —SQL Injection, XSS, recorrido de rutas, Brute Force y el resto— puede activar uno. Cuando una sola solicitud activa varios analizadores, las detecciones se agrupan en un único envío con categorías fusionadas y el nivel de gravedad más alto.

Dirige las detecciones a cualquier API, no solo a ReportedIP

Este es el cambio más destacado de la versión 1.3.0. Los Webhooks ya no están limitados a un formato JSON fijo. Ahora, cada Endpoint define su propia solicitud, por lo que puede comunicarse en el formato que espere la API de destino:

Método HTTP — POST, PUT, PATCH, o GET.
Encabezados personalizados: uno por línea, para API Keys y autenticación; sustituyen a los valores predeterminados.
Formato del cuerpo: estructurado json, codificado como URL formo una plantilla personalizada de formato libre.
Marcadores de posición — {{ip}}, {{categories}}, {{severity}}, {{timestamp}} y los demás campos de solicitud y detección, cada uno con una {{..._url}} variante (codificada como URL) y {{..._json}} (con escape JSON).

Asignación integrada de AbuseIPDB

Anteriormente, enviar informes a una segunda base de datos implicaba crear una capa de traducción, ya que cada servicio numera sus Threat Categories de forma diferente. La versión 1.3.0 incluye un {{abuseipdb_categories}} marcador de posición específico que asigna las categorías de ReportedIP (ID 24–58) a los ID de AbuseIPDB más cercanos. Un informe directo a la API de AbuseIPDB v2 se convierte en una plantilla de cuerpo de una sola línea:

POST https://api.abuseipdb.com/api/v2/report
Header:  Key: <your-abuseipdb-api-key>
Body (form):  ip={{ip}}&categories={{abuseipdb_categories}}&comment={{comment_url}}

Las configuraciones predefinidas para AbuseIPDB, Slack, Discord y un destino JSON genérico rellenan automáticamente el método, los encabezados y el cuerpo del mensaje: elige una, introduce tu clave o URL y envía una prueba. Las pruebas de envío utilizan la IP de bucle cerrado 127.0.0.1, por lo que al verificar un Webhook de AbuseIPDB nunca se envía un informe real contra una dirección activa.

Cómo configurar un Webhook

Los Webhooks se gestionan en el panel de administración, en la sección «Webhooks», y se almacenan en una honeypot_webhooks tabla que la migración de esquema amplía automáticamente. Hay tres controles que determinan lo que recibe cada Endpoint:

Filtros de categoría: restringen el envío a los identificadores de Threat Categories específicos, asociados a las mismas Threat Categories que se utilizan en ReportedIP.
Filtros del analizador: restringen el envío a motores de detección específicos, por ejemplo SqlInjection.
Clave secreta: opcional; activa la firma HMAC-SHA256 de la Payload.

Si los filtros están vacíos, se envían todas las detecciones. Cuando ambos filtros están configurados, el Webhook se activa cuando cualquiera de ellos coincide. El panel de administración registra el último resultado, la marca de tiempo y un contador de fallos consecutivos por cada Endpoint, de modo que se puede detectar a simple vista si un objetivo está averiado.

La carga útil JSON predeterminada

Si mantienes el formato JSON del cuerpo de la solicitud, cada solicitud incluye Content-Type: application/jsonun X-ReportedIP-Event encabezado (detection o test), y —cuando se ha establecido un secreto— un X-ReportedIP-Signature encabezado. El cuerpo agrupa el Honeypot, la solicitud y una o más detecciones:

{
  "event": "detection",
  "generated_at": "2026-06-12T14:00:00+00:00",
  "honeypot": {
    "name": "reportedip-honeypot-server",
    "version": "1.3.0",
    "host": "your-honeypot.example.com",
    "profile": "wordpress"
  },
  "request": {
    "ip": "203.0.113.50",
    "method": "POST",
    "uri": "/wp-login.php",
    "user_agent": "sqlmap/1.7"
  },
  "detections": [
    {
      "analyzer": "SqlInjection",
      "categories": [16, 45],
      "category_names": ["SQL Injection", "Code Injection"],
      "comment": "SQL injection attempt detected: ...",
      "severity": 85
    }
  ]
}

Verificación de la firma

Cuando se configura un secreto, la firma es un HMAC-SHA256 sobre el cuerpo de la solicitud sin procesar, enviado como sha256=. Calcula el mismo valor por tu parte y compáralo en tiempo constante:

$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
$valid = hash_equals($expected, $_SERVER['HTTP_X_REPORTEDIP_SIGNATURE'] ?? '');

Este es el mismo patrón que utilizan GitHub y Stripe para sus Webhooks, por lo que el código receptor existente se puede adaptar fácilmente. Genera siempre un hash de los bytes sin procesar antes de realizar cualquier análisis de JSON; de lo contrario, la reserialización modificará la firma.

Por qué es importante para los operadores de SOC y de laboratorios domésticos

Un Honeypot solo vale la pena si alguien ve lo que captura. Obligar a los operadores a iniciar sesión en un Dashboard independiente hacía que las detecciones del Honeypot quedaran aisladas del resto de señales de seguridad. Los Webhooks flexibles cierran esa brecha: los ataques aparecen en el mismo panel que tu cortafuegos, tu WAF y los registros de las aplicaciones, con campos estructurados que puedes correlacionar, sobre los que puedes generar alertas o reenviar a una Blocklist —y ahora también a una segunda base de datos de reputación en el mismo paso—.

Además, se adapta a la forma en que la gente ya gestiona estos nodos. Si proteges un conjunto de servidores —el tipo de configuración que se describe en «Cómo proteger un clúster de servidores con ReportedIP»—, un Webhook permite que un único Honeypot envíe datos a un colector central del que se nutre el resto del clúster.

Notas de la actualización: de la versión 1.2.0 a la 1.3.0

Las tres versiones se lanzaron el 12 de junio de 2026. La versión 1.2.0 introdujo los Webhooks y corrigió la detección de IPv6 de Cloudflare, un False Positive de «HeaderAnomaly» en direcciones IPv6 legítimas y la gestión de la cola de informes en caso de rechazos permanentes de la API.

1.2.1 se aplicó como corrección urgente: la falta de una entrada en el autocargador provocaba un error HTTP 500 en la página de administración de Webhooks justo después de la actualización. Posteriormente, la versión 1.3.0 reestructuró la capa de Webhooks para convertirla en el enrutador flexible descrito anteriormente, añadió la asignación y los ajustes preestablecidos de AbuseIPDB, fusionó múltiples detecciones por solicitud y amplió el conjunto de pruebas a 363 pruebas. Si utilizas una versión anterior, actualízate directamente a la 1.3.0.

FAQ

¿Puede el honeypot enviar informes a AbuseIPDB?

Sí. Utiliza la configuración predefinida «AbuseIPDB» o crea un Webhook con el form formato «body» y el {{abuseipdb_categories}} marcador de posición, que asigna las categorías de ReportedIP a los ID de AbuseIPDB. Añade tu clave de AbuseIPDB como encabezado personalizado y el Honeypot enviará la información directamente al Endpoint de informes v2.

¿Los Webhooks ralentizan el Honeypot?

No. La solicitud se envía una vez que la respuesta de la trampa ya se ha devuelto al atacante, por lo que lo que ve el atacante nunca se ve retrasado por el envío del Webhook.

¿Cómo puedo saber si una Payload procede realmente de mi Honeypot?

Establece un secreto en el Webhook. De este modo, cada solicitud incluirá un X-ReportedIP-Signature encabezado que contiene un HMAC-SHA256 del cuerpo sin procesar. Vuelve a calcularlo con tu clave secreta y compáralo en tiempo constante antes de dar por válida la Payload.

Descarga el Honeypot Server

El Honeypot Server es de código abierto (BSL 1.1, se migrará a Apache 2.0 en 2030) y no incluye ninguna dependencia externa: PHP 8.2, SQLite, y ya está.

Lee la documentación del Honeypot Server: instalación, configuración y la referencia completa sobre Webhooks.
Consulta la versión 1.3.0 en GitHub: Changelog y código fuente.
Convierte las detecciones en una Blocklist: incorpora la Community Blacklist a tu sistema periférico.