Créer un jail Fail2ban pour protéger une application web

·

·

Mis à jour le

Illustration de la protection d’une application web par un jail Fail2ban, avec analyse des journaux et blocage des adresses IP.

Le jail sshd utilisé dans l’article précédent est fourni directement avec Fail2ban. Pour protéger une application web ou un endpoint particulier, il faut parfois aller un peu plus loin : décider quel événement constitue un échec, écrire un filtre suffisamment précis, puis associer ce filtre à un jail.

Dans ce deuxième article de la série, nous allons prendre un exemple simple : un formulaire d’administration servi derrière Nginx. Après plusieurs réponses HTTP 401 sur /admin/login, Fail2ban bannira temporairement l’adresse source.

Version utilisée dans cet article : Fail2ban 1.1. Les options présentées, comme les durées exprimées en 10m ou le test de configuration avec -t, existent depuis la branche 0.10 et fonctionnent donc avec les versions fournies par les distributions Debian et Ubuntu actuellement supportées.

Principe

Un jail Fail2ban assemble trois choses : une source de logs, un filtre qui extrait l’adresse du client fautif et une action de bannissement. Le plus important est de partir d’un événement de log fiable, horodaté et suffisamment spécifique.

Commencer par le log, pas par la regex

Une erreur classique consiste à écrire une expression régulière avant même d’avoir vérifié ce que l’application renvoie et journalise réellement en cas d’échec.

Le code 401 n’a rien d’universel. L’administration de Django ou wp-login.php renvoient un 200 lorsqu’un mot de passe est faux : elles réaffichent simplement le formulaire avec un message d’erreur. Un 401 vient plutôt d’une API ou d’une authentification HTTP. Si vos 401 proviennent de la directive auth_basic de Nginx, inutile d’écrire un filtre : Fail2ban fournit déjà le jail nginx-http-auth, qu’il suffit d’activer. Et si votre application renvoie 200 en cas d’échec, le log Nginx devient ambigu ; mieux vaut alors que l’application journalise elle-même l’échec, comme nous le verrons plus bas.

Pour notre exemple, nous allons demander à Nginx d’écrire un petit fichier dédié aux tentatives d’authentification. La directive log_format n’est acceptée que dans le bloc http ; sur Debian et Ubuntu, un fichier placé dans /etc/nginx/conf.d/ convient, puisqu’il est inclus dans ce bloc :

sudo vim /etc/nginx/conf.d/fail2ban-auth.conf

Définissons-y un format minimal :

log_format fail2ban_auth '$time_iso8601 $remote_addr $request_method $uri $status';

L’horodatage en tête de ligne n’a rien de décoratif. Sans date valide, Fail2ban ne peut pas savoir si un échec tombe dans la fenêtre findtime, et il l’ignore. J’ai par ailleurs volontairement choisi $uri plutôt que $request_uri : la première variable ne contient pas la query string, si bien que /admin/login?next=/admin/ sera journalisé comme /admin/login, ce qui garde le filtre simple.

Puis, dans le bloc server de l’application concernée, limitez ce journal à l’URL de connexion :

location = /admin/login {
    access_log /var/log/nginx/access.log;
    access_log /var/log/nginx/auth-access.log fail2ban_auth;

    # Reprenez ici les directives de proxy de votre location habituelle
    proxy_pass http://127.0.0.1:8000;
}

Les deux lignes access_log sont nécessaires. Nginx n’hérite des directives access_log du niveau supérieur que si le niveau courant n’en définit aucune : avec une seule ligne, les requêtes vers /admin/login disparaîtraient de votre journal habituel. Placée au niveau server, la même directive aurait même remplacé le journal de tout le site et enregistré toutes ses requêtes, pas seulement les connexions.

Testez la configuration avant de recharger Nginx :

sudo nginx -t
sudo systemctl reload nginx

Le rechargement crée aussi le fichier /var/log/nginx/auth-access.log. C’est important pour la suite : un jail dont le fichier de log n’existe pas refuse de démarrer.

Une tentative refusée produit alors une ligne très simple :

2026-11-03T22:30:12+01:00 203.0.113.42 POST /admin/login 401

Cette simplicité est volontaire : moins le filtre doit interpréter de texte, moins il risque de capturer une mauvaise adresse.

Vérifier que Nginx voit la vraie IP du client

Avant d’aller plus loin, contrôlez le deuxième champ du fichier, juste après la date :

sudo tail -f /var/log/nginx/auth-access.log

Si votre Nginx est lui-même derrière un proxy, un load balancer ou un CDN, $remote_addr peut contenir l’adresse de ce proxy plutôt que celle du visiteur. Corrigez d’abord la configuration du module ngx_http_realip_module : set_real_ip_from limité aux seuls proxys de confiance, et real_ip_header pour l’en-tête qu’ils transmettent. Bannir automatiquement une IP de proxy partagé serait évidemment une très mauvaise idée.

Ne faites pas confiance à un en-tête arbitraire

Une adresse envoyée librement dans X-Forwarded-For n’est pas une preuve de l’identité du client. N’utilisez cet en-tête que si Nginx est configuré pour l’accepter depuis des proxys explicitement déclarés comme fiables.

Il faut signaler une limite importante. Derrière un CDN ou un load balancer, une configuration real_ip correcte permet à Nginx de journaliser la bonne adresse, mais les paquets continuent d’arriver depuis le proxy. Un ban posé par Fail2ban dans le pare-feu de l’hôte sur l’adresse du visiteur ne bloquera donc rien. Dans ce cas, le blocage doit se faire en amont, au niveau du CDN ou du load balancer, ou dans Nginx lui-même. Ce sera un bon sujet pour un article séparé : le traiter ici rendrait ce tutoriel inutilement long.

Créer le filtre Fail2ban

Créons un filtre dédié :

sudo vim /etc/fail2ban/filter.d/nginx-admin-login.conf

Son contenu reste volontairement strict :

[Definition]
failregex = ^\s*<HOST>\s+POST\s+/admin/login\s+401$
ignoreregex =

<HOST> est le marqueur Fail2ban prévu pour extraire l’adresse IP ou le nom d’hôte correspondant. Le \s* initial, lui, est indispensable : Fail2ban repère d’abord la date, la retire de la ligne, puis applique la regex à ce qui reste — qui commence ici par une espace. Sans lui, aucune ligne ne correspondrait.

Le reste de l’expression doit décrire aussi précisément que possible l’événement que vous voulez bannir. Les recommandations du projet Fail2ban vont dans ce sens : ancrez les expressions avec ^ et $ et évitez les grands .* lorsque le format du log permet d’être plus précis. Une regex trop large peut bannir des adresses qui n’ont rien fait.

Tester le filtre avant de créer le jail

Fail2ban fournit justement fail2ban-regex pour cette étape :

sudo fail2ban-regex \
    /var/log/nginx/auth-access.log \
    /etc/fail2ban/filter.d/nginx-admin-login.conf

Le résultat indique combien de lignes ont été analysées et combien correspondent au filtre. Testez avec de vrais logs, comprenant à la fois des échecs que vous voulez détecter et des requêtes légitimes qui ne doivent surtout pas correspondre. Regardez aussi la section Date template hits : elle doit indiquer le format de date reconnu, avec un nombre de correspondances non nul.

Un filtre qui correspond n’est pas un jail qui bannit

fail2ban-regex ne vérifie pas la fenêtre findtime. Il peut donc annoncer des correspondances sur des lignes sans date, alors que le serveur Fail2ban les ignorera en se contentant d’écrire « Found a match but no valid date/time found » dans son journal. Si la section Date template hits est vide, corrigez le format du log avant d’aller plus loin. L’option datepattern = {NONE} existe, mais elle reste un dernier recours : au premier démarrage, toutes les lignes déjà présentes dans le fichier seraient considérées comme récentes.

Créer le jail

Ajoutez maintenant :

sudo vim /etc/fail2ban/jail.d/nginx-admin-login.local

Avec par exemple :

[nginx-admin-login]
enabled = true
filter = nginx-admin-login
logpath = /var/log/nginx/auth-access.log
port = http,https
findtime = 10m
maxretry = 5
bantime = 1h

Nous appliquons ici la même logique que pour SSH : cinq échecs dans une fenêtre de dix minutes déclenchent un ban d’une heure. Le paramètre port n’indique pas ce que Fail2ban surveille, mais les ports bloqués lors d’un ban.

Valider puis activer le jail

Testez l’ensemble de la configuration :

sudo fail2ban-client -t

Si tout est correct, la commande se termine par OK: configuration test is successful. Rechargez ensuite Fail2ban ; inutile de redémarrer le service :

sudo fail2ban-client reload

Puis vérifiez le nouveau jail :

sudo fail2ban-client status nginx-admin-login

La ligne File list doit mentionner /var/log/nginx/auth-access.log. Les compteurs Currently failed et Total failed augmentent à chaque échec détecté.

Tester un vrai bannissement

Comme pour SSH, gardez une session ouverte sur le serveur et provoquez les échecs depuis une autre adresse IP, par exemple une connexion mobile. Si cette adresse figure dans le ignoreip configuré dans l’article précédent, elle ne sera évidemment jamais bannie.

Depuis cette autre machine, envoyez cinq tentatives refusées :

for i in 1 2 3 4 5; do
    curl -s -o /dev/null -w '%{http_code}\n' -X POST https://example.com/admin/login
done

Chaque requête doit afficher 401. Adaptez au besoin la requête à votre application : ce qui compte est qu’elle produise exactement le même code qu’un vrai échec. Si vous obtenez autre chose, revenez à la première étape, car le filtre ne verra rien.

Sur le serveur, l’adresse doit maintenant apparaître dans Banned IP list, et la requête suivante depuis cette adresse doit échouer dès la connexion :

sudo fail2ban-client status nginx-admin-login

Débannissez ensuite l’adresse de test :

sudo fail2ban-client set nginx-admin-login unbanip 203.0.113.42

Adapter le filtre à une application

Le même principe fonctionne avec Django, WordPress, une API ou un autre service : l’application doit produire un événement horodaté qui contient l’adresse réelle du client, puis le filtre Fail2ban doit reconnaître exclusivement cet événement. C’est aussi la bonne solution lorsque l’application renvoie 200 en cas d’échec.

Par exemple, si votre application écrit un fichier dédié contenant :

2026-11-03 22:30:12 login_failed ip=203.0.113.42 user=admin

un filtre peut rester très lisible :

[Definition]
failregex = ^\s*login_failed ip=<HOST> user=\S+$
ignoreregex =

Le jail pointera alors vers le fichier de log de l’application au lieu de celui de Nginx.

Attention à l’adresse journalisée. Derrière Nginx, l’adresse vue par l’application — REMOTE_ADDR pour Django — est souvent celle du proxy. L’application ne doit alors lire X-Forwarded-For que si la requête provient d’un proxy de confiance, selon le même principe que real_ip côté Nginx.

Et si l’application tourne dans Docker ou Podman ?

Si Nginx tourne sur l’hôte et journalise déjà l’événement que vous souhaitez bannir, gardez cette architecture : Fail2ban peut lire le log Nginx sur l’hôte, quelle que soit la technologie utilisée derrière le reverse proxy.

Le cas devient plus intéressant lorsque l’échec n’existe que dans les logs du conteneur. Il faut alors choisir comment rendre ces logs visibles depuis l’hôte : fichier monté, driver de logs Docker ou journal systemd. Avec Podman Quadlets, on peut notamment utiliser LogDriver=journald. Docker sait lui aussi envoyer les logs vers journald.

Si c’est Nginx lui-même qui tourne dans un conteneur avec des ports publiés, une autre difficulté apparaît : le trafic vers ces ports ne traverse pas les règles habituelles de l’hôte. Les bans doivent alors être posés dans une chaîne que Docker consulte, comme DOCKER-USER.

Quand ne pas utiliser Fail2ban

Fail2ban fonctionne bien quand un comportement abusif produit un événement fiable et contient l’adresse du client. Il est beaucoup moins adapté lorsqu’on tente de deviner une attaque à partir d’un log ambigu ou lorsque toutes les requêtes arrivent avec l’adresse d’un proxy non identifié.

Commencez donc toujours par améliorer la qualité des logs et la récupération de l’IP réelle. Le filtre vient ensuite.

Ce que nous avons maintenant

  • un journal Nginx horodaté, limité à l’URL de connexion et contenant l’adresse réelle du client ;
  • un filtre strict, testé avec fail2ban-regex sur de vrais logs ;
  • un jail nginx-admin-login validé avec fail2ban-client -t et vérifié par un vrai bannissement ;
  • une méthode applicable au journal d’une application Django, WordPress ou d’une API.

Et ensuite ?

Lorsque l’échec n’existe que dans les logs d’un conteneur, Fail2ban doit souvent lire le journal systemd plutôt qu’un fichier. Or un jail utilisant le backend systemd ne se configure pas comme un jail basé sur logpath. Dans l’article suivant, nous verrons comment surveiller avec Fail2ban les logs de conteneurs Docker et Podman Quadlets.

Documentation

Fail2ban — recommandations pour écrire des filtres

Manuel jail.conf sur Debian (dates, datepattern, backends)

Manuel fail2ban-regex sur Debian

Nginx — journalisation avec log_format et access_log

Nginx — module realip et adresse réelle du client

Docker — pilote de journalisation journald

Podman — option LogDriver des Quadlets

Commentaires

Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *