Webhooks du honeypot : envoyer les détections d’attaques vers toute API
La version 1.3.0 du ReportedIP Honeypot Server, publiée le 12 juin 2026, transforme ses webhooks en routeur configurable qui envoie chaque détection d’attaque vers n’importe quelle API HTTP. Chaque point de terminaison définit sa propre méthode, ses en-têtes et son corps, si bien que les détections arrivent dans un SIEM, sur Slack, Discord ou chez AbuseIPDB sans code d’adaptation.
La version actuelle est la 1.4.1 du 15 septembre 2026, et tout ce qui est décrit ici y fonctionne à l’identique. L’installation et la liste complète des champs figurent dans la documentation du Honeypot Server.
À quoi servent les webhooks du honeypot ?
Un webhook est un point de terminaison HTTP ou HTTPS qui reçoit une requête chaque fois que le honeypot détecte une attaque correspondant à ses filtres. La fonction est arrivée avec la version 1.2.0, avec un format JSON fixe pour les systèmes de journalisation et les SIEM. La version 1.3.0 l’a ouverte à toutes les API : Splunk, Elastic, un canal Slack ou Discord, ou une seconde base de données d’abus.
Le honeypot envoie les webhooks une fois la réponse du piège transmise à l’attaquant. Un point de terminaison lent ou en panne ne retarde donc jamais ce que voit l’attaquant. À la sortie de la 1.3.0, la chaîne de détection comptait 36 analyseurs, de l’injection SQL et du cross-site scripting jusqu’au path traversal et à la force brute. Depuis la version 1.3.10, elle en compte 40, et chacun peut déclencher un webhook.
Comment envoyer les détections du honeypot vers n’importe quelle API ?
Jusqu’à la version 1.2.1, chaque envoi était un POST JSON. Depuis la 1.3.0, chaque webhook définit sa propre requête :
- Méthode HTTP :
POST,PUT,PATCHouGET. Une requête GET n’a pas de corps, les données passent alors dans l’URL. - En-têtes personnalisés : un par ligne, pour les clés d’API et l’authentification. Ils remplacent les en-têtes par défaut.
- Format du corps :
jsonstructuré,formencodé pour URL ou modèle librecustom. - Variables : 13 champs comme
{{ip}},{{categories}},{{severity}}et{{timestamp}}, utilisables dans le corps et dans l’URL. Chaque champ existe aussi en variante{{..._url}}(encodée pour URL) et{{..._json}}(échappée pour JSON).
Quand une requête déclenche plusieurs analyseurs, chaque webhook ne reçoit qu’un seul envoi. Les variables regroupent les catégories, retiennent la gravité la plus élevée et joignent les commentaires. Le format JSON liste chaque détection séparément.
La correspondance avec AbuseIPDB est intégrée
Chaque base de menaces numérote ses catégories à sa façon, et signaler à une seconde base demandait jusqu’ici un code de conversion. La variable {{abuseipdb_categories}} se charge de cette correspondance : les ID 1 à 23 sont identiques sur les deux plateformes, et les catégories ReportedIP à partir de 24 sont converties vers leur équivalent AbuseIPDB le plus proche. Dans la 1.3.0, la correspondance couvrait les ID 24 à 58. Depuis la version 1.3.7, elle couvre aussi les catégories honeypot 59 à 63. Un signalement vers le point de signalement AbuseIPDB ressemble à ceci :
POST https://api.abuseipdb.com/api/v2/report
Key: <your-abuseipdb-api-key>
Accept: application/json
ip={{ip_url}}&categories={{abuseipdb_categories}}&comment={{comment_url}}Quatre modèles préremplissent la requête
Le formulaire des webhooks propose quatre modèles rapides (Quick Presets). Chacun remplit l’URL, la méthode, les en-têtes et le modèle de corps. Il vous reste à ajouter votre propre clé d’API ou URL de webhook.
| Modèle | Méthode | Format du corps |
|---|---|---|
| Generic JSON | POST | json |
| AbuseIPDB | POST | custom |
| Slack | POST | custom |
| Discord | POST | custom |
Le bouton de test envoie une requête avec l’adresse de bouclage 127.0.0.1. Les bases d’abus refusent cette adresse, si bien que tester un webhook AbuseIPDB ne crée jamais de signalement contre un hôte réel.
Comment configurer un webhook ?
Les webhooks se gèrent dans le panneau d’administration du honeypot, sous Webhooks. La mise à jour vers la 1.3.0 étend d’elle-même les réglages de webhook enregistrés, aucune migration manuelle n’est nécessaire. Trois réglages déterminent ce que reçoit un point de terminaison :
- Filtre de catégories : des ID tirés de la liste des catégories de menaces utilisée partout chez ReportedIP.
- Filtre d’analyseurs : noms de moteurs de détection, par exemple
SqlInjection. - Secret : facultatif. Il ajoute une signature HMAC-SHA256 à chaque requête.
Si les deux filtres sont vides, chaque détection est envoyée. Si les deux sont renseignés, une détection qui correspond à l’un ou à l’autre déclenche le webhook. Le panneau affiche pour chaque point de terminaison le dernier statut, son horodatage et le nombre d’échecs consécutifs, qu’un envoi réussi remet à zéro. La référence des webhooks décrit chaque champ.
À quoi ressemble le payload JSON par défaut ?
Avec le format json, chaque requête porte Content-Type: application/json, un en-tête X-ReportedIP-Event de valeur detection ou test et, si un secret est défini, un en-tête X-ReportedIP-Signature. 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", "WP Database Injection"],
"comment": "SQL injection attempt detected: ...",
"severity": 85
}
]
}Vérifier la signature côté récepteur
La signature est un HMAC-SHA256 calculé sur le corps brut de la requête avec votre secret comme clé (RFC 2104), transmis sous la forme sha256=<hex>. Calculez la même valeur de votre côté et comparez les deux en temps constant :
$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
$valid = hash_equals($expected, $_SERVER['HTTP_X_REPORTEDIP_SIGNATURE'] ?? '');Hachez les octets bruts avant tout parsing JSON. Un corps analysé puis réencodé peut différer par les espaces ou l’ordre des clés, et la signature ne correspond plus. GitHub signe ses webhooks dans le même format sha256=, un code récepteur existant n’a donc besoin que d’un autre nom d’en-tête.
Pourquoi envoyer les détections du honeypot vers un SIEM ?
Un honeypot n’est utile que si quelqu’un voit ce qu’il capture. Sans webhooks, ses détections restaient dans un panneau d’administration à part, loin de tous les autres signaux de sécurité. Avec les webhooks, elles arrivent à côté des journaux du pare-feu, du WAF et des applications, sous forme de champs structurés que vous pouvez corréler, utiliser pour des alertes ou verser dans une liste de blocage. La même détection peut partir en même temps vers ReportedIP et vers AbuseIPDB.
Les webhooks conviennent aussi aux parcs de serveurs. Si vous exploitez plusieurs serveurs, comme dans le guide sur la sécurisation d’un cluster, un seul honeypot peut alimenter un collecteur central que le reste du cluster consulte.
Qu’est-ce qui a changé entre les versions 1.2.0 et 1.3.0 ?
Les versions 1.2.0, 1.2.1 et 1.3.0 sont toutes sorties le 12 juin 2026. La 1.2.0 a introduit les webhooks et corrigé trois problèmes : les plages IPv6 de Cloudflare manquaient dans la détection de l’IP client, l’analyseur d’en-têtes prenait des adresses IPv6 légitimes pour du loopback, et les signalements refusés définitivement par l’API bloquaient la file d’envoi.
La 1.2.1 était un correctif pour une erreur HTTP 500 sur la page Webhooks juste après la mise à jour, causée par un autoloader obsolète. La 1.3.0 a transformé l’envoi en routeur décrit plus haut, ajouté la correspondance AbuseIPDB et les modèles, regroupé plusieurs détections par requête et porté la suite de tests à 363 tests.
Depuis, la 1.3.1 a corrigé le jour même le texte d’aide et les modèles de la page Webhooks, la 1.3.3 a ajouté les catégories honeypot 59 à 63, et la 1.3.7 a aligné la correspondance AbuseIPDB sur les noms de catégories corrigés. Si vous utilisez encore une version plus ancienne, passez directement à la 1.4.1.
Questions fréquentes sur les webhooks du honeypot
Le honeypot peut-il signaler à AbuseIPDB ?
Le honeypot signale à AbuseIPDB grâce à son modèle intégré. Ce modèle définit le point de signalement, un modèle de corps personnalisé et la variable {{abuseipdb_categories}}, qui convertit les catégories ReportedIP en ID AbuseIPDB. Placez votre propre clé d’API AbuseIPDB dans l’en-tête Key, envoyez un test, et chaque détection correspondante part vers les deux bases.
Les webhooks ralentissent-ils le honeypot ?
L’envoi ne retarde jamais la réponse que voit l’attaquant, car le honeypot n’envoie les webhooks qu’une fois la réponse du piège partie. Un point de terminaison lent ne peut donc pas trahir le piège par son temps de réponse. Un envoi échoué augmente seulement le compteur d’échecs du panneau, la détection et le signalement à ReportedIP continuent normalement.
Comment savoir qu’un payload vient bien de mon honeypot ?
Un secret sur le webhook prouve l’origine d’une requête. Avec un secret défini, chaque requête porte un en-tête X-ReportedIP-Signature contenant un HMAC-SHA256 du corps brut. Votre récepteur calcule la même valeur avec le même secret et compare les deux en temps constant. Rejetez toute requête dont la signature ne correspond pas.
Obtenir le Honeypot Server
Le code du Honeypot Server est consultable librement (source-available) sous Business Source License 1.1 et passera sous Apache 2.0 le 1er mars 2030. Vous pouvez l’utiliser en production pour votre propre infrastructure, sans le proposer à des tiers comme service hébergé. Il lui faut PHP 8.2 avec SQLite et cURL, sans paquet externe.
- Documentation du Honeypot Server : installation, configuration et référence des webhooks.
- Produits ReportedIP : le plugin Hive, l’API, le flux de blacklist et les outils gratuits, dont le honeypot.
- Blacklist communautaire : transformer les attaquants signalés en liste de blocage pour votre pare-feu.