Comunicados

Webhooks de Honeypot: envía alertas de ataques a cualquier API

12 de junio de 2026 · Patrick Schlesinger

El servidor ReportedIP ahora puede enviar todos los ataques 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 punto de conexión en el panel de administración. La configuración completa se describe en la documentación del servidor honeypot.

Qué hacen los webhooks de Honeypot

Un webhook es un punto final 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 API ReportedIP y a recopiladores externos. A partir de la versión 1.3.0, esas mismas detecciones pueden reenviarse a cualquier API HTTP: Splunk, Elastic, un canal de Slack o Discord, o una segunda base de datos de amenazas.

El envío 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 —inyección SQL, XSS, recorrido de rutas, fuerza bruta y el resto— puede activar uno. Cuando una sola solicitud activa varios analizadores, las detecciones se agrupan en un único envío con las 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 punto final 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 claves API y autenticación; sustituyen a los valores predeterminados.
• Formato del cuerpo — estructurado json, codificado en URL form, o 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 un {{..._url}} (codificado en URL) y {{..._json}} (con codificación JSON).

Asignación integrada de AbuseIPDB

Anteriormente, para integrar datos en una segunda base de datos era necesario crear una capa de traducción, ya que cada servicio numera sus categorías de amenazas de forma diferente. La versión 1.3.0 incluye una {{abuseipdb_categories}} marcador de posición que asigna ReportedIP (ID 24-58) a sus 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}}

Ajustes predefinidos para AbuseIPDB, Slack, Discord, y un JSON genérico Rellena previamente el método, los encabezados y el cuerpo; elige uno, introduce tu clave o URL y envía una prueba. Las pruebas de entrega utilizan la IP de bucle cerrado 127.0.0.1, por lo que la verificación de un webhook de AbuseIPDB nunca genera una denuncia 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, almacenado en un honeypot_webhooks tabla que la migración del esquema amplía automáticamente. Hay tres controles que determinan qué recibe cada punto final:

• Filtros de categoría: restringen la entrega a identificadores de categorías de amenazas específicos, asociados a las mismas categorías de amenazas que se utilizan en ReportedIP.
• Filtros del analizador — limitar la entrega a motores de detección específicos, por ejemplo SqlInjection.
• Clave secreta — opcional; activa la firma HMAC-SHA256 de la carga útil.

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 punto final, por lo que es fácil detectar de un vistazo si un objetivo no funciona correctamente.

La carga útil JSON predeterminada

Si mantienes el formato JSON del cuerpo, cada solicitud incluye Content-Type: application/json, un X-ReportedIP-Event encabezado (detection o test), y —cuando se establece un secreto— un X-ReportedIP-Signature encabezado. El cuerpo agrupa el honeypot, la solicitud y una o varias 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 sin procesar cuerpo de la solicitud, enviado como sha256=<hmac>. Calcula el mismo valor por tu cuenta 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 es fácil de adaptar. Asegúrate siempre de aplicar un hash a los bytes sin procesar antes de analizar el 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 detecta. Al obligar a los operadores a iniciar sesión en un panel de control independiente, las detecciones del honeypot quedaban 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 lista de bloqueo —y ahora 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 falso positivo de HeaderAnomaly en direcciones IPv6 legítimas y la gestión de la cola de informes en caso de rechazos permanentes de la API.

La versión 1.2.1 se lanzó como una corrección de emergencia: la falta de una entrada en el cargador automático provocaba un error HTTP 500 en la página de administración de Webhooks inmediatamente después de la actualización. Posteriormente, la versión 1.3.0 rediseñó 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 tienes una versión anterior, pasa directamente a la 1.3.0.

Preguntas frecuentes

¿Puede el honeypot enviar informes a AbuseIPDB?

Sí. Utiliza la configuración predefinida «AbuseIPDB» o crea un webhook con el form formato del cuerpo y el {{abuseipdb_categories}} marcador de posición, que asigna ReportedIP a los ID de AbuseIPDB. Añade tu clave de AbuseIPDB como encabezado personalizado y el honeypot enviará los datos directamente al punto final 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 la entrega del webhook nunca retrasa lo que ve el atacante.

¿Cómo puedo saber si una carga útil procede realmente de mi honeypot?

Establece una clave secreta en el webhook. A partir de ese momento, cada solicitud incluirá una 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 carga útil.

Descarga el servidor honeypot

El servidor honeypot es de código abierto (licencia BSL 1.1, que pasará a ser Apache 2.0 en 2030) y no requiere ninguna dependencia externa: PHP 8.2, SQLite, y listo.

• Lee la documentación del servidor honeypot: instalación, configuración y la referencia completa de webhooks.
• Consulta la versión 1.3.0 en GitHub: registro de cambios y código fuente.
• Convierte las detecciones en una lista de bloqueados: integra la lista negra de la comunidad en tu sistema periférico.