Honeypot Webhooks : envoyez les détections d'attaques vers n'importe quelle API

Le Honeypot Server ReportedIP peut désormais transmettre chaque attaque qu’il détecte vers les outils que vous utilisez déjà. La version 1.3.0 transforme ses Webhooks en un routeur configurable : choisissez la méthode HTTP, les en-têtes et le corps du message, puis envoyez les détections directement vers votre SIEM, Slack, Discord ou AbuseIPDB.

Si vous exploitez déjà un nœud Honeypot, effectuez la mise à jour vers la version 1.3.0 et configurez un Endpoint dans le panneau d’administration. La procédure complète de configuration est décrite dans la documentation du Honeypot Server.

À quoi servent les Honeypot Webhooks ?

A Webhook est un endpoint HTTP(S) qui reçoit une requête chaque fois que le Honeypot signale une attaque. Cette fonctionnalité a été introduite pour la première fois dans la version 1.2.0 afin de transmettre les détections à l’API de la communauté ReportedIP et à des collecteurs externes. À partir de la version 1.3.0, ces mêmes détections peuvent être transmises à n’importe quelle API HTTP : Splunk, Elastic, un canal Slack ou Discord, ou encore une deuxième base de données de menaces.

La transmission a lieu après l’envoi de la réponse piège à l’attaquant ; l’ajout d’un Webhook ne ralentit donc jamais le Honeypot. Chacun des 36 analyseurs intégrés — SQL Injection, XSS, traversée de chemin, Brute Force et autres — peut en déclencher un. Lorsqu’une seule requête déclenche plusieurs analyseurs, les détections sont regroupées en une seule notification avec des catégories fusionnées et le niveau de gravité le plus élevé.

Acheminer les détections vers n’importe quelle API, et pas seulement vers ReportedIP

Il s’agit de la principale nouveauté de la version 1.3.0. Un Webhook n’est désormais plus contraint à un format JSON fixe. Chaque Endpoint définit désormais sa propre requête, ce qui lui permet de s’adapter au format attendu par l’API cible :

Méthode HTTP — POST, PUT, PATCH, ou GET.
En-têtes personnalisés — un par ligne, pour les API Keys et l’authentification ; ils remplacent les valeurs par défaut.
Format du corps — structuré json, encodé en URL formou un modèle personnalisé au format libre.
Espaces réservés — {{ip}}, {{categories}}, {{severity}}, {{timestamp}} ainsi que les autres champs de requête et de détection, chacun comportant une {{..._url}} variante (encodée en URL) et {{..._json}} (avec échappement JSON).

Mappage AbuseIPDB intégré

Auparavant, la transmission de données vers une deuxième base de données impliquait la création d’une couche de traduction, car chaque service numérote ses Threat Categories différemment. La version 1.3.0 intègre un {{abuseipdb_categories}} qui mappe les catégories ReportedIP (ID 24 à 58) vers les ID AbuseIPDB les plus proches. Un rapport direct vers l’API AbuseIPDB v2 se résume désormais à un modèle de corps de message d’une seule ligne :

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

Des préréglages pour AbuseIPDB, Slack, Discord et une cible JSON générique préremplissent la méthode, les en-têtes et le corps du message : choisissez-en un, insérez votre clé ou votre URL, puis envoyez un test. Les envois de test utilisent l’adresse IP de bouclage 127.0.0.1; ainsi, la vérification d’un Webhook AbuseIPDB n’entraîne jamais l’envoi d’un véritable signalement à une adresse active.

Comment configurer un Webhook

Les Webhooks sont gérés dans le panneau d’administration, sous la rubrique « Webhooks », et stockés dans une honeypot_webhooks table que la migration de schéma étend automatiquement. Trois paramètres déterminent ce que chaque Endpoint reçoit :

Filtres par catégorie — limitent la diffusion aux identifiants de Threat Categories spécifiques, mis en correspondance avec les mêmes Threat Categories que celles utilisées sur ReportedIP.
Filtres de l’analyseur — limitent la transmission à des moteurs de détection spécifiques, par exemple SqlInjection.
Clé secrète — facultative ; active la signature HMAC-SHA256 de la Payload.

Si les filtres sont vides, toutes les détections sont transmises. Lorsque les deux filtres sont définis, le Webhook se déclenche dès que l’un d’entre eux est satisfait. Le panneau d’administration enregistre le dernier résultat, l’horodatage et un compteur d’échecs consécutifs par Endpoint, ce qui permet de repérer d’un seul coup d’œil une cible défaillante.

La charge utile JSON par défaut

Si vous conservez le format JSON pour le corps de la requête, chaque requête contient Content-Type: application/json, un X-ReportedIP-Event en-tête (detection ou test), et — lorsqu’un secret est défini — un X-ReportedIP-Signature en-tête. Le corps regroupe le Honeypot, la requête et une ou plusieurs détections :

{
  "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
    }
  ]
}

Vérification de la signature

Lorsqu’un secret est configuré, la signature est un HMAC-SHA256 calculé sur le corps brut de la requête, envoyé sous la forme sha256=. Calculez la même valeur de votre côté et comparez-la en temps constant :

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

Il s’agit du même modèle que celui utilisé par GitHub et Stripe pour leurs Webhooks ; le code des récepteurs existants est donc facile à adapter. Veillez à toujours calculer le hachage des octets bruts avant toute analyse JSON, sinon la resérialisation modifiera la signature.

Pourquoi cela est-il important pour les opérateurs de SOC et de laboratoires privés ?

Un Honeypot ne vaut la peine que si quelqu’un examine ce qu’il détecte. Le fait d’obliger les opérateurs à se connecter à un Dashboard distinct signifiait que les détections du Honeypot étaient isolées de tous les autres signaux de sécurité. Des Webhooks flexibles comblent cette lacune : les attaques apparaissent dans le même tableau de bord que votre pare-feu, votre WAF et les journaux d’application, avec des champs structurés que vous pouvez corréler, sur lesquels vous pouvez déclencher des alertes ou que vous pouvez transférer vers une Blocklist — et désormais vers une deuxième base de données de réputation en une seule étape.

Cela correspond également à la manière dont ces nœuds sont déjà exploités. Si vous protégez un parc de serveurs — le type de configuration décrit dans l’article « Sécuriser un cluster de serveurs avec ReportedIP » —, un Webhook permet à un seul Honeypot d’alimenter un collecteur central auquel le reste du cluster a accès.

Notes de mise à jour : de la version 1.2.0 à la version 1.3.0

Ces trois versions ont été mises en production le 12 juin 2026. La version 1.2.0 a introduit les Webhooks et corrigé la détection IPv6 de Cloudflare, un False Positive de HeaderAnomaly sur des adresses IPv6 légitimes, ainsi que la gestion dans la file d’attente des rapports des rejets permanents de l’API.

La version 1.2.1 a fait l’objet d’un correctif d’urgence : une entrée manquante dans l’autochargeur provoquait une erreur HTTP 500 sur la page d’administration des Webhooks immédiatement après la mise à jour. La version 1.3.0 a ensuite réorganisé la couche Webhooks pour en faire le routeur flexible décrit ci-dessus, ajouté le mappage AbuseIPDB et des préréglages, fusionné plusieurs détections par requête et étendu la suite de tests à 363 tests. Si vous utilisez une version antérieure, passez directement à la version 1.3.0.

FAQ

Le honeypot peut-il envoyer des rapports à AbuseIPDB ?

Oui. Utilisez le préréglage « AbuseIPDB » ou créez un Webhook au form format « body » et le {{abuseipdb_categories}} placeholder, qui associe les catégories ReportedIP aux identifiants AbuseIPDB. Ajoutez votre clé AbuseIPDB en tant qu’en-tête personnalisé et le Honeypot enverra directement ses données vers l’Endpoint de rapport v2.

Les Webhooks ralentissent-ils le Honeypot ?

Non. La requête est envoyée après que la réponse du piège a déjà été renvoyée à l’attaquant ; par conséquent, ce que voit l’attaquant n’est jamais retardé par la transmission du Webhook.

Comment puis-je savoir si une Payload provient réellement de mon Honeypot ?

Définissez une clé secrète pour le Webhook. Chaque requête comportera alors un X-ReportedIP-Signature en-tête contenant un HMAC-SHA256 du corps brut. Recalculez-le à l’aide de votre clé secrète et comparez-le en temps constant avant de faire confiance à la Payload.

Téléchargez le Honeypot Server

Le Honeypot Server est open source (licence BSL 1.1, qui passera sous licence Apache 2.0 en 2030) et ne nécessite aucune dépendance externe : PHP 8.2, SQLite, c’est tout.

Consultez la documentation du Honeypot Server : installation, configuration et référence complète sur les Webhooks.
Consultez la version 1.3.0 sur GitHub — Changelog et code source.
Transformez les détections en Blocklist — intégrez la Community Blacklist dans votre périphérique.