Honeypot Fail2ban 2.6.1 : la documentation complète
Cette documentation décrit Honeypot Fail2ban 2.6.1, extension WordPress qui relie les journaux d’accès de votre serveur web à fail2ban. Les essais ont été faits avec WordPress 7.1, PHP 8.3 et 8.4, fail2ban 1.0.2 et 1.1.0 sous Debian 13, ufw et OpenLiteSpeed. Sur une autre distribution ou une autre version de fail2ban, les chemins et les noms d’actions peuvent différer : l’extension les détecte et vous le dit.
À quoi sert l’extension
Les scanners automatiques parcourent internet en demandant à chaque serveur les mêmes adresses : /.env, /.git/config, des copies de wp-config.php, phpMyAdmin, des outils de développement oubliés. Ces adresses n’existent pas sur un site bien tenu, et aucun visiteur ne les demande. Chaque demande désigne donc un robot.
Honeypot Fail2ban en fait des pièges. Un moteur lit vos journaux d’accès, repère les adresses qui tombent dedans et les écrit dans un journal des pièges. Une prison fail2ban lit ce journal et bannit ces adresses sur tous les ports du serveur, pas seulement sur le web : un robot repéré ne peut plus non plus tenter SSH ou la messagerie.
Prérequis
| Élément | Requis |
|---|---|
| WordPress | 6.0 ou plus |
| PHP | 8.0 ou plus |
| Serveur | Linux, avec un accès root pour coller deux commandes |
| fail2ban | installé et en service |
| Python | Python 3, pour l’agent |
| Journaux d’accès | format combined : Apache, nginx, OpenLiteSpeed |
| Pare-feu | celui que pilote fail2ban : ufw, nftables, iptables, firewalld… |
Un hébergement mutualisé, où vous n’avez pas la main sur le serveur, ne convient pas : l’agent doit tourner en root.
Comment ça marche
L’extension se partage en deux morceaux, pour que WordPress n’ait jamais de droits sur le système.
- L’agent, un petit programme Python, tourne en root sur le serveur. Une tâche cron le lance chaque minute. À chaque passage, il lit les journaux d’accès depuis là où il s’était arrêté, en suivant leur rotation, fait tourner le moteur des pots de miel, écrit les adresses prises dans le journal des pièges, interroge fail2ban et exécute les demandes faites depuis WordPress.
- L’extension, dans WordPress, est le tableau de bord. Elle dépose ses réglages et ses demandes, comme un débannissement ou une simulation, dans un dossier d’échange, et lit l’état que l’agent y laisse.
Le dossier d’échange appartient à root. WordPress n’y écrit que dans deux sous-dossiers, demandes et reglages, et l’agent vérifie tout ce qu’il y lit : une demande de bannissement d’une adresse privée, par exemple, est refusée.
- La prison fail2ban
pot-de-miel-autolit le journal des pièges. Une ligne suffit à bannir l’adresse, par l’action de votre choix.
Installation
- Téléchargez l’extension depuis sa page sur www.1et2.com, puis dans WordPress : « Extensions » › « Ajouter » › « Téléverser une extension ». Choisissez le zip, installez, activez. Le menu « Honeypot » apparaît.
- Ouvrez l’onglet « fail2ban et agent ». Vérifiez le nom de la prison, la durée du bannissement, l’action et la liste blanche, puis cliquez sur « Enregistrer et régénérer les commandes ».
- Copiez le bloc 1. Agent et moteur et collez-le dans un terminal root. Il crée le dossier d’échange, installe l’agent et sa tâche cron, puis lance un premier passage.
- Copiez le bloc 2. Prison fail2ban et collez-le à son tour. Il crée le journal des pièges et sa rotation, le filtre et la prison, valide la configuration par
fail2ban-client -t, puis recharge fail2ban. - Revenez au tableau de bord : l’agent doit être « vivant », la prison « active ».
- Dans « Analyse des journaux », vérifiez que vos journaux d’accès sont bien trouvés et que vos domaines sont listés, puis lancez une simulation.

Si une ancienne déclaration de la même prison existe déjà dans /etc/fail2ban, l’onglet le signale et propose une commande 0 qui déplace l’ancien fichier dans /root : deux déclarations d’une même prison se mêlent.
Le tableau de bord

L’en-tête rappelle en permanence l’état de l’agent et le nombre d’adresses bannies.
Les cartes d’état
| Carte | Ce qu’elle montre |
|---|---|
| Prises sur 14 jours | le nombre d’adresses prises et un histogramme par jour, chaque barre partagée par motif. Survolez une barre pour son détail. |
| Moteur des pots de miel | le dernier passage, les appâts appris, les chemins en observation, les journaux lus et les requêtes analysées |
| Prison pot-de-miel-auto | les adresses bannies en ce moment, le total depuis le démarrage de fail2ban et l’action de bannissement |
| Autres prisons | une carte par prison suivie, par exemple sshd |
| fail2ban et agent | la version de fail2ban et l’état de l’agent |
L’agent est « vivant » s’il a donné signe de vie depuis moins de trois minutes, « silencieux » au-delà, « absent » s’il n’a jamais été installé.
Sous les cartes, des alertes signalent ce qui demande votre attention : agent silencieux, prison inactive, journal introuvable, filtre ou prison différents des réglages, agent plus ancien que celui de l’extension.
Prises du moteur liste les prises des quatorze derniers jours : quand, quelle adresse, pour quel motif, sur quel site, quel chemin et quelle réponse du serveur. La pastille « bannie » dit si l’adresse est encore au pare-feu. Survolez un chemin pour voir l’agent utilisateur du robot.
Adresses bannies liste les adresses bannies par les prisons suivies, avec le début et la fin du bannissement. Le bouton « Débannir » envoie la demande à l’agent, qui l’exécute à son passage suivant, dans la minute.
Les deux tableaux ont un champ « Filtrer » et une liste par motif ou par prison. Les filtres sont gardés dans votre navigateur et rappelés à la visite suivante.
L’onglet Analyse des journaux

Journaux d’accès lus
| Réglage | Rôle | Par défaut |
|---|---|---|
| Journaux d’accès lus | Un chemin par ligne, * admis. Le tableau dessous montre les journaux trouvés, leur taille et les lignes lues au dernier passage. | /var/www/*/logs/access.log, OpenLiteSpeed, nginx, Apache |
| Domaines des sites | Une requête venue d’une de vos pages, par exemple une image manquante, n’est jamais une sonde. Sous-domaines compris. | le domaine du site |
| Racines web | Un chemin qui existe sur l’une d’elles n’est jamais appris comme appât. Les sites rangés en /var/www/<site>/html sont trouvés seuls. | la racine de WordPress |
Ce qui est pris
| Réglage | Rôle | Par défaut |
|---|---|---|
| Injections | ../, /etc/passwd, union select, <script, ${jndi:… dans l’adresse | activé |
| Rafales | autant de chemins suspects inexistants en si peu de temps, depuis la même adresse | 3 en 10 minutes |
| Appâts appris | un chemin suspect inexistant demandé par autant d’adresses différentes en autant de jours devient un piège | 3 adresses en 14 jours |
| Statuts comptés comme échec | réponses du serveur qui font un échec, pour les appâts « sur échec » | 400 403 404 405 410 444 |
Jamais pris
Les réseaux privés, les adresses du serveur et la liste blanche de fail2ban sont toujours épargnés.
| Réglage | Rôle | Par défaut |
|---|---|---|
| Administrateurs | une adresse qui a obtenu une page d’administration ou s’est connectée est épargnée pendant ce délai. La page de connexion reconnue est affichée, y compris si vous l’avez renommée. | 24 heures |
| Robots des moteurs de recherche | Google, Bing, Apple, Yandex, Qwant, Baidu, Petal : épargnés seulement si leur adresse pointe vers leur domaine et que ce domaine revient vers la même adresse | activé |
| Chemins protégés | débuts de chemin jamais comptés comme sonde ni appris : administration, API, fichiers des membres, liens stables de vos logiciels | /wp-admin, /wp-json, /.well-known/, /favicon.ico, /robots.txt, /sitemap, /feed, /wp-content/uploads/, /wp-cron.php, /apple-touch-icon |
« Enregistrer et transmettre au moteur » dépose les réglages pour l’agent, qui les applique à son passage suivant.
Simulation
« Lancer une simulation » demande au moteur de relire tous les journaux disponibles avec les réglages enregistrés et de dire qui serait pris, sans rien écrire ni bannir. Une adresse déjà prise depuis moins d’une heure n’est pas recomptée. WordPress ne lit pas lui-même les journaux : l’agent fait la simulation à son passage suivant, et le résultat s’affiche dans l’onglet en moins d’une minute, après un rechargement de la page. Il donne le nombre de requêtes lues, les adresses qui seraient prises avec leur motif, celles qui seraient épargnées, et les appâts qui seraient appris.
L’onglet Appâts
L’onglet se range en cinq sous-onglets, chacun avec son compteur. Le dernier ouvert est rappelé.
Appâts fixes

Vingt appâts commentés : page de connexion d’origine quand elle a été renommée, XML-RPC, wp-config.php et ses copies, installation de WordPress, .env, dépôts .git ou .svn, réglages d’outils (.aws, .ssh, .docker…), fichiers cachés sensibles, identifiants SFTP d’éditeur, PHPUnit, routeurs Boa et D-Link, phpMyAdmin, Adminer, pages d’information PHP, scripts CGI, Spring Boot, statut Apache…
Chaque appât se coche ou se décoche, et se règle :
- toujours : toute demande est prise ;
- sur échec : la demande n’est prise que si le site répond par un des statuts d’échec. Une page qui existe vraiment n’est pas un piège : si vous utilisez phpMyAdmin, il continue de fonctionner.
Décochez XML-RPC si Jetpack ou une application mobile s’en sert. /wp-admin n’est jamais un piège.
Appâts personnels
Une expression régulière par ligne, appliquée au chemin en minuscules, suivie de ; toujours ou ; échec. Par exemple :
^/ancien-admin\.php ; toujours
^/backup/ ; échec
Une expression invalide est refusée à l’enregistrement, avec la raison.
Appâts appris

Chemins devenus des pièges d’eux-mêmes, après avoir été demandés par plusieurs robots : depuis quand, combien de robots l’ont demandé, combien d’adresses ont été prises, la dernière prise. « Oublier » retire l’appât, et le moteur ne l’apprendra plus : utilisez-le si un chemin légitime a été appris.
En observation

Des robots ont déjà demandé ces chemins, qui n’existent pas sur vos sites et ressemblent à une sonde. Le moteur les surveille sans bannir personne. Dès que le nombre d’adresses réglé dans « Analyse des journaux » est atteint dans le délai réglé, le chemin devient un appât appris. La liste montre les chemins les plus demandés. « Écarter » retire de la surveillance un chemin légitime.
Écartés
Les chemins oubliés ou écartés, que le moteur n’apprend plus. « Rendre à l’apprentissage » les remet en surveillance.
L’onglet fail2ban et agent

Prison
| Réglage | Rôle | Par défaut |
|---|---|---|
| Nom | nom de la prison fail2ban | pot-de-miel-auto |
| Journal des pièges | écrit par le moteur, lu par fail2ban, une ligne par adresse prise. Il tourne chaque mois, douze mois gardés. | /var/log/pot-de-miel.log |
| Bannir après | nombre de prises dans le délai choisi | 1 prise en 1 heure |
| Durée du bannissement | de 10 minutes à 1 an | 1 mois |
| À chaque récidive | multiplier la durée à chaque nouveau bannissement de la même adresse, jusqu’à un plafond | désactivé, × 2 jusqu’à 6 mois |
Un mois peut paraître long. Les robots scannent souvent derrière des VPN ou des machines louées à l’heure, dont l’adresse sert surtout à d’autres robots : un long bannissement ne gêne guère qu’eux.
Bannissement et agent
| Réglage | Rôle |
|---|---|
| Action | comment fail2ban bannit : ufw, nftables, iptables, firewalld… ou l’action par défaut du serveur. Une action absente du serveur est signalée. |
| Liste blanche (ignoreip) | adresses jamais bannies. Si votre jail.local a déjà une liste blanche générale, la prison en hérite. |
| Autres prisons suivies | affichées au tableau de bord, avec débannissement possible, par exemple sshd wordpress-auth |
| Dossier de l’agent | dossier d’échange entre WordPress et l’agent, à réserver à l’extension |
Pour la liste blanche, n’indiquez que des adresses qui ne changent pas, par exemple celle d’un autre serveur à vous, depuis lequel vous pourrez vous connecter en SSH pour vous débannir. L’adresse de votre box n’y a sa place que si elle est fixe, ce qui est le cas chez certains fournisseurs (Free par exemple) et avec la plupart des offres professionnelles. Une adresse qui change régulièrement ne protège de rien une fois périmée.
Ce que WordPress voit de fail2ban

« Filtre » et « Prison » comparent les fichiers installés aux réglages : « à jour », « différent » ou « absent ». Après un changement de réglages de la prison, relancez la commande 2.
Commandes
| Bloc | Quand le lancer |
|---|---|
| 0. Retirer l’ancienne déclaration | seulement s’il est proposé : une autre déclaration de la même prison existe |
| 1. Agent et moteur | à l’installation, et quand le tableau de bord signale un agent plus ancien que celui de l’extension |
| 2. Prison fail2ban | à l’installation, et après un changement de réglages de la prison |
| Tester le filtre | pour vérifier que fail2ban lit bien le journal des pièges |
| Tout retirer | voir Tout retirer |
Le lien « Voir le filtre, la prison et la configuration de l’agent » montre les fichiers tels qu’ils seront écrits.
Se débannir
Si votre propre adresse est bannie :
- Depuis une autre connexion, un téléphone sans Wi-Fi par exemple, ouvrez le tableau de bord et cliquez sur « Débannir » en face de l’adresse.
- Ou connectez-vous en SSH depuis une adresse de la liste blanche et tapez :
fail2ban-client set pot-de-miel-auto unbanip <adresse>
- Sinon, passez par la console de secours de votre hébergeur.
Une adresse qui a obtenu une page d’administration est épargnée pendant le délai réglé dans « Analyse des journaux » : en travaillant normalement sur votre site, vous ne vous prenez pas dans vos propres pièges.
Mises à jour
Les nouvelles versions arrivent dans « Tableau de bord » › « Mises à jour » de WordPress, comme pour une extension du répertoire officiel. « Afficher les détails » montre la description et le journal des versions, et les mises à jour automatiques s’activent depuis la liste des extensions. WordPress interroge le serveur de www.1et2.com deux fois par jour.
Quand une version apporte un nouvel agent, le tableau de bord affiche « L’agent installé sur le serveur est plus ancien que celui de l’extension » : relancez alors la commande 1. Les réglages, les appâts appris et l’historique sont gardés.
Dans la liste des extensions, la ligne de Honeypot Fail2ban donne aussi accès aux réglages, à cette documentation, au forum et au signalement d’un bug.
Ce qui est installé sur le serveur
Les noms suivent l’adresse du site, ici notée <site> (par exemple www-exemple-fr).
| Fichier ou dossier | Rôle |
|---|---|
/usr/local/sbin/honeypot-fail2ban-agent | l’agent, commun à tous les sites du serveur |
/etc/honeypot-fail2ban/<site>.conf | la configuration de l’agent pour ce site |
/etc/cron.d/honeypot-fail2ban-<site> | la tâche cron, chaque minute |
/var/lib/honeypot-fail2ban/<site>/ | le dossier d’échange : état du moteur, demandes, réglages |
/var/log/pot-de-miel.log | le journal des pièges |
/etc/logrotate.d/honeypot-fail2ban-<site> | sa rotation mensuelle |
/etc/fail2ban/filter.d/pot-de-miel-auto.conf | le filtre |
/etc/fail2ban/jail.d/pot-de-miel-auto.conf | la prison |
Plusieurs sites WordPress du même serveur peuvent avoir chacun l’extension : chacun a son dossier d’échange et sa configuration, l’agent est partagé.
Dépannage
L’agent est « absent ». La commande 1 n’a pas été lancée, ou le dossier de l’agent indiqué dans les réglages n’est pas celui de la commande. Relancez la commande 1 après avoir enregistré les réglages.
L’agent est « silencieux ». La tâche cron ne tourne plus. Vérifiez que /etc/cron.d/honeypot-fail2ban-<site> existe et que cron est en service, puis lancez l’agent à la main pour voir son message :
/usr/local/sbin/honeypot-fail2ban-agent /etc/honeypot-fail2ban/<site>.conf
La prison est inactive. Lancez fail2ban-client -t : il dit quelle ligne pose problème. Sous Debian, fail2ban lit par défaut le journal système et non des fichiers. La prison générée précise donc backend = auto pour lire le journal des pièges. Une action de bannissement absente du serveur empêche aussi la prison de démarrer : l’onglet le signale.
Aucun journal trouvé. Corrigez les chemins dans « Analyse des journaux ». Le tableau sous le champ montre ce que l’agent trouve vraiment.
Le filtre ne voit rien. Lancez « Tester le filtre » : fail2ban-regex doit compter autant de correspondances que de lignes dans le journal des pièges. S’il n’y a encore eu aucune prise, le journal est vide, et c’est normal.
Un chemin légitime a été appris. Sous-onglet « Appâts appris », « Oublier ». Pour qu’il ne soit plus jamais compté, ajoutez son début aux chemins protégés.
Tout retirer
Commencez par le serveur, tant que l’extension est là pour générer la commande : collez en root le bloc « Tout retirer » de l’onglet fail2ban et agent. Il supprime la prison, le filtre, la tâche cron et la configuration de l’agent, recharge fail2ban, ce qui libère les adresses bannies par cette prison, et retire l’agent si plus aucun site ne s’en sert. Le journal des pièges et le dossier d’échange sont gardés : supprimez-les à la main si vous n’en voulez plus. Désactivez et supprimez ensuite l’extension dans WordPress, qui efface ses réglages.
Données personnelles
Tout reste sur votre serveur : les journaux, les adresses prises, l’état du moteur. Seule la recherche de mises à jour sort, vers www.1et2.com : version de l’extension, version de WordPress et de PHP, langue, et une empreinte tronquée de l’adresse du site, qui ne contient pas l’adresse et sert seulement à compter les installations. Votre serveur n’enregistre pas votre adresse IP en clair, seulement une empreinte salée pour limiter les abus.