BunkerWeb : protéger une application web avec un WAF open source

BunkerWeb est un WAF (Web Application Firewall) open source qui se place en reverse proxy devant vos applications web. Il bloque les injections SQL, le XSS, les scans automatisés et le brute force dès la première requête, sans toucher au code de votre application. Basé sur NGINX, il embarque ModSecurity avec les règles OWASP CRS 4, un rate limiter, un système de ban automatique et une Web UI d’administration. Le tout se déploie en quelques minutes avec Docker Compose.

Ce que vous allez apprendre

• Comprendre l’architecture BunkerWeb : instance, Scheduler, API, base de données
• Déployer un WAF fonctionnel devant une application avec Docker Compose
• Observer les protections actives par défaut et lire les logs de blocage
• Configurer la vraie IP client quand BunkerWeb est derrière un proxy ou un load balancer
• Activer la Web UI pour administrer les services, plugins et bans via le navigateur
• Choisir entre les offres Free (AGPLv3) et PRO selon votre besoin

Dans quel contexte ?

Dès qu’une application web est exposée sur Internet, elle subit un trafic hostile permanent :

• Injections SQL automatisées sur chaque paramètre de formulaire ou d’URL
• XSS dans les champs de recherche, les commentaires, les headers
• Scans de vulnérabilités par Nikto, Nuclei, sqlmap et des centaines de bots
• Brute force sur les pages de login
• Path traversal pour accéder à /etc/passwd ou aux fichiers de configuration

BunkerWeb se place entre Internet et votre application. Toute requête passe d’abord par ses filtres avant d’atteindre votre backend. L’intérêt : bloquer ces attaques sans modifier votre code et sans infrastructure lourde.

Architecture : comprendre les composants

BunkerWeb n’est pas un simple conteneur. En production, il repose sur plusieurs composants qui communiquent entre eux.

Les composants principaux

Composant	Rôle	Image Docker
BunkerWeb	Reverse proxy NGINX qui filtre le trafic	bunkerity/bunkerweb
Scheduler	Pousse la configuration vers BunkerWeb, exécute les jobs planifiés (blacklists, certificats)	bunkerity/bunkerweb-scheduler
API	Plan de contrôle interne (FastAPI). Reçoit la config du Scheduler et la transmet à BunkerWeb	Intégré à BunkerWeb
Base de données	Stocke la configuration, les bans, les sessions. SQLite par défaut, MariaDB/PostgreSQL en production	Intégré au Scheduler
Web UI	Interface d’administration, disponible en service dédié (bunkerweb-ui) ou via l’image AIO	bunkerity/bunkerweb-ui ou intégrée AIO
Redis	Cache des sessions et persistance des bans entre redémarrages (optionnel)	Standard redis ou intégré AIO

Glissez pour voir

L’image All-In-One (AIO)

Pour simplifier le démarrage, BunkerWeb propose une image All-In-One (bunkerity/bunkerweb-all-in-one) qui embarque tous les composants dans un seul conteneur : BunkerWeb, Scheduler, Web UI, Redis et la base de données.

API interne : ne jamais l'exposer

L’API de BunkerWeb est un plan de contrôle interne. Elle ne doit jamais être accessible depuis Internet. La variable API_WHITELIST_IP restreint les réseaux autorisés à la contacter. Par défaut, seul 127.0.0.0/8 est autorisé.

Comment les composants communiquent

Depuis la version 1.6.0, le Scheduler porte la configuration métier (variables d’environnement) et la pousse vers BunkerWeb via l’API interne. En revanche, les paramètres liés à l’API (API_WHITELIST_IP, API_HTTP_PORT, API_LISTEN_IP, API_SERVER_NAME) doivent être déclarés de façon cohérente sur le Scheduler et sur l’instance BunkerWeb, sinon cette dernière refusera les ordres du Scheduler.

API_WHITELIST_IP vs API_WHITELIST_IPS

Dans ce guide, API_WHITELIST_IP concerne l’API interne utilisée par le Scheduler pour piloter l’instance. La documentation de l’API standalone emploie aussi API_WHITELIST_IPS pour son propre plan de contrôle. Ne confondez pas les deux.

Les composants communiquent sur un réseau Docker dédié (bw-universe) avec un sous-réseau statique. L’application protégée est sur un second réseau (bw-services), accessible uniquement par BunkerWeb.

Prérequis

• Docker et Docker Compose installés
• Un terminal avec curl pour les tests
• Optionnel : ajouter www.example.com dans /etc/hosts pour tester via le navigateur

echo "127.0.0.1 www.example.com" | sudo tee -a /etc/hosts

Lab vs production

BunkerWeb se déploie de façons très différentes selon le contexte. Avant de commencer, identifiez votre cible :

Critère	Lab / découverte	Production
Image	AIO (tout-en-un) acceptable	Stack multi-conteneurs (BunkerWeb + Scheduler + DB + Redis)
Web UI	Accès direct sur le port 7000	Derrière BunkerWeb lui-même, avec HTTPS et authentification
Base de données	SQLite intégrée	MariaDB ou PostgreSQL externe
Redis	Intégré à l’AIO ou absent	Service dédié pour la persistance des bans et sessions
HTTPS	Certificat auto-signé (GENERATE_SELF_SIGNED_SSL: "yes")	Let’s Encrypt ou certificat fourni
Real IP	Optionnel (Docker local)	Obligatoire (proxy, load balancer, CDN)
API	Réseau interne Docker	Jamais exposée, API_WHITELIST_IP strict

Glissez pour voir

L'image AIO n'est pas faite pour la production

L’image All-In-One est pratique pour découvrir BunkerWeb en quelques minutes. Pour un vrai déploiement, utilisez la stack multi-conteneurs avec des volumes persistants, une base externe et Redis.

Ce guide commence par un lab minimal (stack BunkerWeb + Scheduler), puis passe à l’AIO avec Web UI pour explorer l’interface d’administration.

Premier déploiement : le stack minimal

Ce premier palier déploie BunkerWeb + Scheduler devant une application de démonstration (whoami). Pas de Web UI, pas de base externe. L’objectif : vérifier que le trafic passe et que les protections fonctionnent.

Le fichier Docker Compose

docker-compose.yml

# BunkerWeb — Stack minimal (BunkerWeb + Scheduler + app démo)
x-bw-api-env: &bw-api-env
  API_WHITELIST_IP: "127.0.0.0/24 10.20.30.0/24"

services:
  bunkerweb:
    image: bunkerity/bunkerweb:1.6.9
    ports:
      - "80:8080/tcp"
      - "443:8443/tcp"
    environment:
      <<: *bw-api-env
    restart: "unless-stopped"
    networks:
      - bw-universe
      - bw-services

  bw-scheduler:
    image: bunkerity/bunkerweb-scheduler:1.6.9
    depends_on:
      - bunkerweb
    environment:
      <<: *bw-api-env
      BUNKERWEB_INSTANCES: "bunkerweb"
      SERVER_NAME: "www.example.com"
      USE_REVERSE_PROXY: "yes"
      REVERSE_PROXY_URL: "/"
      REVERSE_PROXY_HOST: "http://app1:80"
    volumes:
      - bw-storage:/data
    restart: "unless-stopped"
    networks:
      - bw-universe

  app1:
    image: traefik/whoami:v1.10
    restart: "unless-stopped"
    networks:
      - bw-services

volumes:
  bw-storage:

networks:
  bw-universe:
    name: bw-universe
    ipam:
      driver: default
      config:
        - subnet: 10.20.30.0/24
  bw-services:
    name: bw-services

Ce qui se passe dans ce fichier

1. L’ancre YAML x-bw-api-env centralise la variable API_WHITELIST_IP. Elle doit être identique sur BunkerWeb et le Scheduler pour qu’ils puissent communiquer.

2. BunkerWeb écoute sur les ports 8080 (HTTP) et 8443 (HTTPS) à l’intérieur du conteneur. Il est connecté à deux réseaux : bw-universe pour recevoir la config du Scheduler, et bw-services pour atteindre l’application.

3. Le Scheduler porte toute la configuration métier : SERVER_NAME, USE_REVERSE_PROXY, REVERSE_PROXY_HOST. Il pousse cette config vers BunkerWeb via BUNKERWEB_INSTANCES.

4. L’application whoami affiche les headers HTTP reçus. Elle est isolée sur le réseau bw-services : seul BunkerWeb peut l’atteindre.

5. Le réseau bw-universe utilise un sous-réseau fixe (10.20.30.0/24). C’est une exigence de BunkerWeb pour que API_WHITELIST_IP fonctionne.

Lancer le stack

docker compose up -d

Attendez que les deux conteneurs soient healthy :

docker compose ps

NAME                       STATUS                  PORTS
lab-bunkerweb-app1-1       Up 2 minutes            80/tcp
lab-bunkerweb-bunkerweb-1  Up 2 minutes (healthy)  0.0.0.0:80->8080/tcp, 0.0.0.0:443->8443/tcp
lab-bunkerweb-bw-scheduler Up 2 minutes (healthy)

Persistance et volumes

Le volume bw-storage monté sur /data dans le Scheduler stocke la base SQLite (configuration, bans, sessions) et les backups. Sans ce volume, toute la configuration et l’historique des bans sont perdus à chaque redémarrage.

UID/GID du Scheduler

Le Scheduler tourne en UID/GID 101. Si vous montez un répertoire hôte au lieu d’un volume Docker, assurez-vous que les permissions sont correctes : chown 101:101 /chemin/vers/data.

Vérifier que le trafic passe

Requête légitime

curl -H "Host: www.example.com" http://localhost

Hostname: 0e7c92246ea1
IP: 127.0.0.1
RemoteAddr: 172.31.0.2:48082
GET / HTTP/1.1
Host: www.example.com
X-Forwarded-For: 172.31.0.1
X-Forwarded-Proto: http
X-Real-Ip: 172.31.0.1

L’application whoami reçoit la requête avec les headers ajoutés par BunkerWeb : X-Forwarded-For, X-Real-Ip et X-Forwarded-Proto.

Headers de sécurité automatiques

BunkerWeb ajoute automatiquement des headers de sécurité à chaque réponse :

curl -sS -D - -H "Host: www.example.com" http://localhost -o /dev/null

HTTP/1.1 200 OK
Referrer-Policy: strict-origin-when-cross-origin
X-Content-Type-Options: nosniff
X-Frame-Options: SAMEORIGIN
X-DNS-Prefetch-Control: off
Content-Security-Policy: object-src 'none'; form-action 'self'; frame-ancestors 'self';
Permissions-Policy: accelerometer=(), camera=(), geolocation=(), microphone=()...

Tous ces headers sont actifs par défaut, sans configuration supplémentaire :

Header	Protection
X-Content-Type-Options: nosniff	Empêche le navigateur de deviner le type MIME
X-Frame-Options: SAMEORIGIN	Bloque l’inclusion dans une iframe tierce (clickjacking)
Content-Security-Policy	Restreint les sources de scripts, images, formulaires
Permissions-Policy	Désactive l’accès à la caméra, au micro, à la géolocalisation
Referrer-Policy	Limite les informations transmises au site de destination
Strict-Transport-Security	Force HTTPS avec HSTS (visible uniquement en HTTPS)

Glissez pour voir

Activer HTTPS

Par défaut, Let’s Encrypt (AUTO_LETS_ENCRYPT=no) et la génération de certificat auto-signé (GENERATE_SELF_SIGNED_SSL=no) sont tous deux désactivés. Pour activer HTTPS, vous avez deux options selon le contexte.

Pour le lab — certificat auto-signé :

GENERATE_SELF_SIGNED_SSL: "yes"

Après redémarrage, testez :

curl -ksS -D - -H "Host: www.example.com" https://localhost -o /dev/null

HTTP/2 200
strict-transport-security: max-age=63072000; includeSubDomains; preload

Le HSTS est activé par défaut en HTTPS avec une durée de 2 ans et preload.

Pour la production — Let’s Encrypt : voir la section HTTPS automatique avec Let’s Encrypt plus bas.

Ne promettez pas HTTPS sans activation explicite

Sans GENERATE_SELF_SIGNED_SSL: "yes" ni AUTO_LETS_ENCRYPT: "yes", BunkerWeb ne sert pas de certificat valide sur le port HTTPS. Testez d’abord en HTTP pour valider le fonctionnement du WAF.

Ce que BunkerWeb active par défaut

Avant de configurer quoi que ce soit, BunkerWeb bloque déjà les attaques les plus courantes. Voici ce qui est activé dans un déploiement standard et comment le vérifier.

ModSecurity + OWASP CRS 4

ModSecurity avec les règles OWASP CRS v4 est activé par défaut (USE_MODSECURITY: yes, USE_MODSECURITY_CRS: yes). Le mode anomaly scoring est utilisé avec un niveau de paranoïa PL1 et un seuil de blocage de 5 sur les requêtes.

Test — injection SQL :

curl -H "Host: www.example.com" "http://localhost/?id=1%20OR%201=1"

Résultat : 403 Forbidden. Dans les logs :

ModSecurity: Warning. detected SQLi using libinjection.
[id "942100"] [msg "SQL Injection Attack Detected via libinjection"]
[ver "OWASP_CRS/4.24.1"] [tag "attack-sqli"]

Test — XSS :

curl -H "Host: www.example.com" "http://localhost/?q=<script>alert(1)</script>"

Résultat : 403 Forbidden.

ModSecurity utilise un système de scoring par anomalies : chaque règle violée ajoute des points. Si le total atteint le seuil (5 par défaut en PL1), la requête est bloquée avec un 403. Le seuil des réponses est à 4 par défaut.

Rate limiting

Le rate limiting est activé par défaut à 2 requêtes par seconde (LIMIT_REQ_RATE: 2r/s) :

# 5 requêtes rapides
for i in $(seq 1 5); do
  code=$(curl -sS -o /dev/null -w "%{http_code}" \
    -H "Host: www.example.com" http://localhost/)
  echo "Requête $i: $code"
done

Requête 1: 200
Requête 2: 200
Requête 3: 429
Requête 4: 429
Requête 5: 429

À partir de la 3e requête, BunkerWeb retourne un 429 Too Many Requests.

Bad Behavior : le ban automatique

Bad Behavior surveille les codes d’erreur retournés à une même IP. Si une IP accumule trop d’erreurs (403, 429, 401, 404, 405) sur une fenêtre de 60 secondes, elle est bannie pour 24 heures.

Paramètre	Valeur par défaut	Description
BAD_BEHAVIOR_THRESHOLD	10	Nombre d’erreurs avant le ban
BAD_BEHAVIOR_COUNT_TIME	60	Fenêtre de comptage (secondes)
BAD_BEHAVIOR_BAN_TIME	86400	Durée du ban (secondes = 24h)
BAD_BEHAVIOR_STATUS_CODES	400 401 403 404 405 429 444	Codes HTTP surveillés

Glissez pour voir

Concrètement, si un attaquant envoie des injections SQL répétées, chaque 403 incrémente le compteur. Au bout de 10 erreurs en 60 secondes, l’IP est bannie :

[BADBEHAVIOR] IP 172.31.0.1 is banned for 86400s (11/10)
on server www.example.com with scope service

Observer le ban dans les logs

docker compose logs bunkerweb | grep "BADBEHAVIOR"

Vous verrez le compteur monter (6/10, 7/10…) puis le ban se déclencher à 11/10.

Détection de scanners

Les requêtes avec un User-Agent de scanner connu (Nikto, sqlmap, Nessus, etc.) sont détectées par la règle CRS 913100 :

curl -A "nikto" -H "Host: www.example.com" http://localhost/

ModSecurity: Warning. Found User-Agent associated with security scanner
[id "913100"] [msg "Found User-Agent associated with security scanner"]
[tag "attack-reputation-scanner"]

Blacklists communautaires

BunkerWeb télécharge et met à jour automatiquement des listes noires :

• danmeuk-tor-exit : nœuds de sortie Tor
• mitchellkrogza-bad-user-agents : User-Agents malveillants
• Shodan, Censys : bloqués par reverse DNS (.shodan.io, .censys.io)

Récapitulatif des protections par défaut

Protection	Activée	Variable	Valeur par défaut
ModSecurity + CRS 4	Oui	USE_MODSECURITY	yes
Rate limiting	Oui	LIMIT_REQ_RATE	2r/s
Bad Behavior (ban auto)	Oui	USE_BAD_BEHAVIOR	yes
Blacklists (Tor, scanners)	Oui	USE_BLACKLIST	yes
BunkerNet (intel communautaire)	Oui	USE_BUNKERNET	yes
Anti-bot	Non	USE_ANTIBOT	no
CrowdSec	Non	USE_CROWDSEC	no
Let’s Encrypt	Non	AUTO_LETS_ENCRYPT	no

Glissez pour voir

Gérer la vraie IP client

Par défaut, BunkerWeb voit l’IP du réseau Docker (172.x.x.x), pas celle du vrai client. C’est un problème : le rate limiting, le ban et les logs utilisent cette IP interne. Tous les clients sont comptés comme un seul.

Activer Real IP

Ajoutez ces variables sur le Scheduler :

environment:
  USE_REAL_IP: "yes"
  REAL_IP_FROM: "192.168.0.0/16 172.16.0.0/12 10.0.0.0/8"
  REAL_IP_HEADER: "X-Forwarded-For"
  REAL_IP_RECURSIVE: "yes"

Variable	Rôle
USE_REAL_IP	Active l’extraction de l’IP depuis un header
REAL_IP_FROM	Réseaux de confiance (vos proxys, load balancers)
REAL_IP_HEADER	Header contenant l’IP réelle (X-Forwarded-For ou X-Real-Ip)
REAL_IP_RECURSIVE	Remonte la chaîne X-Forwarded-For pour trouver la première IP hors REAL_IP_FROM

Glissez pour voir

Vérifier que ça fonctionne

curl -H "Host: www.example.com" \
     -H "X-Forwarded-For: 203.0.113.42" \
     http://localhost

La réponse de whoami affiche X-Real-Ip: 203.0.113.42 et les logs BunkerWeb montrent :

www.example.com 203.0.113.42 - [...] "GET / HTTP/1.1" 200

L’IP 203.0.113.42 (envoyée dans le header) remplace l’IP Docker dans les logs et le rate limiting.

Ne listez que vos proxys de confiance

REAL_IP_FROM définit les IP autorisées à transmettre un X-Forwarded-For fiable. Si vous y mettez 0.0.0.0/0, n’importe quel client peut usurper son IP et contourner le rate limiting et les bans. Ne listez que vos reverse proxys, load balancers et réseaux Docker.

Redémarrez après modification de Real IP

Après modification des paramètres Real IP, redémarrez BunkerWeb (docker compose restart bunkerweb). Un simple reload ne suffit pas pour ces réglages.

Ajuster les protections

Les protections par défaut sont volontairement strictes. Selon votre application, vous devrez peut-être les ajuster.

Rate limiting

LIMIT_REQ_RATE: "10r/s"     # Passer de 2r/s à 10r/s
LIMIT_CONN_MAX_HTTP1: "20"  # Max 20 connexions simultanées par IP

Bad Behavior

BAD_BEHAVIOR_THRESHOLD: "20"   # Tolérer 20 erreurs avant ban
BAD_BEHAVIOR_BAN_TIME: "3600"  # Bannir 1h au lieu de 24h
BAD_BEHAVIOR_COUNT_TIME: "120" # Fenêtre de 2 min au lieu de 1 min

ModSecurity : mode détection et faux positifs

Pour tester sans bloquer (utile au démarrage) :

MODSECURITY_SEC_RULE_ENGINE: "DetectionOnly"

Les attaques apparaissent dans les logs mais ne sont pas bloquées. Repassez à On une fois les faux positifs identifiés et corrigés.

Le CRS est configuré par défaut en PL1 (niveau de paranoïa le plus bas). Si vous montez en PL2 ou PL3, attendez-vous à plus de faux positifs. Ajustez progressivement :

MODSECURITY_CRS_PARANOIA_LEVEL: "2"  # PL2 : plus strict, plus de faux positifs

Environnements contraints en RAM

Si vous hébergez beaucoup de services en multisite, activez USE_MODSECURITY_GLOBAL_CRS: "yes" pour charger le CRS une seule fois en mémoire au lieu d’une instance par service. C’est recommandé par la documentation officielle pour les environnements avec de nombreux SERVER_NAME.

Anti-bot : protéger sans casser l’application

L’anti-bot est désactivé par défaut (USE_ANTIBOT: no). Il ajoute un challenge (captcha, JavaScript, cookie) avant d’autoriser l’accès.

USE_ANTIBOT: "cookie"  # Options : cookie, javascript, captcha, hcaptcha, recaptcha, turnstile

Attention aux API et webhooks

L’anti-bot ne doit pas être activé sur les endpoints techniques : API REST, webhooks, callbacks OAuth, flux M2M. Ces clients ne peuvent pas résoudre un captcha. Utilisez ANTIBOT_IGNORE_URI pour exclure les chemins concernés :

ANTIBOT_IGNORE_URI: "/api/ /webhook/ /oauth/callback"

Administrer via la Web UI

La Web UI est une interface d’administration complète. Elle permet de gérer les services, les plugins, les bans et les logs sans toucher aux fichiers de configuration.

Déployer avec l’image All-In-One

Le moyen le plus simple d’obtenir la Web UI est d’utiliser l’image All-In-One :

docker-compose-aio.yml

services:
  bunkerweb-aio:
    image: bunkerity/bunkerweb-all-in-one:1.6.9
    ports:
      - "80:8080/tcp"
      - "443:8443/tcp"
      - "7000:7000/tcp"
    environment:
      API_WHITELIST_IP: "127.0.0.0/24 10.20.30.0/24 172.16.0.0/12"
      SERVICE_UI: "yes"
      SERVICE_SCHEDULER: "yes"
      USE_REDIS: "yes"
      MULTISITE: "yes"
      SERVER_NAME: "www.example.com"
      USE_REVERSE_PROXY: "yes"
      REVERSE_PROXY_URL: "/"
      REVERSE_PROXY_HOST: "http://app1:80"
      USE_REAL_IP: "yes"
      REAL_IP_FROM: "192.168.0.0/16 172.16.0.0/12 10.0.0.0/8"
      REAL_IP_HEADER: "X-Forwarded-For"
    networks:
      - bw-services

  app1:
    image: traefik/whoami:v1.10
    networks:
      - bw-services

networks:
  bw-services:

La Web UI est accessible sur le port 7000.

MULTISITE est requis

La Web UI impose le mode multisite (MULTISITE: yes). En multisite, chaque SERVER_NAME est un service indépendant avec ses propres paramètres de sécurité.

Le wizard de premier lancement

Au premier accès sur http://localhost:7000, un wizard guide la configuration en 4 étapes :

1. Admin User — Créez le compte administrateur (username, email, mot de passe). Ce sera le seul accès à la Web UI.

2. UI Settings — Configurez le SERVER_NAME, le reverse proxy, Let’s Encrypt (optionnel) et Real IP. Vous pouvez tout laisser par défaut si la configuration est déjà dans le Docker Compose.

3. Upgrade to PRO — Saisissez une clé de licence PRO si vous en avez une, sinon passez cette étape.

4. Overview — Récapitulatif de la configuration. Validez pour terminer.

Newsletter optionnelle

Le wizard propose l’inscription à la newsletter Bunkerity. Décochez si vous ne souhaitez pas la recevoir.

Le dashboard

Après le login, le dashboard affiche une vue d’ensemble de l’état du WAF :

Page Services

La page Services liste tous les SERVER_NAME configurés avec leurs paramètres de reverse proxy et de sécurité :

Page Plugins

Les 42 plugins core sont listés avec leur état (activé/désactivé). Vous pouvez les configurer individuellement :

Logs et Bans

La page Logs affiche le trafic en temps réel avec les détails ModSecurity :

La page Bans montre les IP bannies par Bad Behavior ou manuellement :

HTTPS automatique avec Let’s Encrypt

BunkerWeb gère automatiquement les certificats Let’s Encrypt :

AUTO_LETS_ENCRYPT: "yes"
EMAIL_LETS_ENCRYPT: "admin@example.com"

Prérequis :

• Le domaine dans SERVER_NAME doit pointer vers le serveur (DNS public)
• Le port 80 doit être accessible depuis Internet (challenge HTTP-01)

Pour les domaines wildcard ou les DNS challenge, BunkerWeb supporte plus de 25 fournisseurs DNS (Cloudflare, OVH, Route53, etc.) :

LETS_ENCRYPT_CHALLENGE: "dns"
LETS_ENCRYPT_DNS_PROVIDER: "cloudflare"

BunkerNet et CrowdSec

BunkerNet : l’intelligence communautaire native

BunkerNet est activé par défaut (USE_BUNKERNET: yes). C’est le réseau de threat intelligence propre à BunkerWeb : chaque instance partage les IP malveillantes détectées et reçoit les listes agrégées de la communauté. Aucune configuration nécessaire.

CrowdSec avec l’image AIO

L’image All-In-One embarque une intégration CrowdSec prête à l’emploi. Activez-la avec :

USE_CROWDSEC: "yes"

BunkerWeb initialise automatiquement l’agent local, les collections/parsers par défaut et le bouncer. Aucun déploiement externe nécessaire.

CrowdSec en stack multi-conteneurs

En stack classique (BunkerWeb + Scheduler séparés), CrowdSec est un service externe. BunkerWeb agit comme bouncer face à une LAPI CrowdSec déployée séparément :

USE_CROWDSEC: "yes"
CROWDSEC_API: "http://crowdsec:8080"
CROWDSEC_API_KEY: "votre-bouncer-api-key"

Ce mode nécessite de déployer CrowdSec avec sa propre LAPI, ses collections de scénarios et la collecte des logs BunkerWeb.

BunkerNet ≠ CrowdSec

BunkerNet est natif à BunkerWeb, activé par défaut, sans configuration. CrowdSec est un projet externe, optionnel, qui apporte une visibilité plus large et des scénarios personnalisés. Les deux peuvent coexister.

Multisite : plusieurs applications derrière un seul BunkerWeb

En mode multisite (MULTISITE: yes), chaque SERVER_NAME devient un service indépendant avec ses propres paramètres. Préfixez les variables avec le SERVER_NAME :

environment:
  MULTISITE: "yes"
  SERVER_NAME: "app1.example.com app2.example.com"

  # Paramètres globaux
  USE_MODSECURITY: "yes"

  # Paramètres spécifiques à app1
  app1.example.com_REVERSE_PROXY_HOST: "http://app1:80"
  app1.example.com_REVERSE_PROXY_URL: "/"
  app1.example.com_LIMIT_REQ_RATE: "10r/s"

  # Paramètres spécifiques à app2
  app2.example.com_REVERSE_PROXY_HOST: "http://app2:3000"
  app2.example.com_REVERSE_PROXY_URL: "/"
  app2.example.com_USE_ANTIBOT: "cookie"

Chaque application peut avoir ses propres règles de rate limiting, d’anti-bot et de ModSecurity.

Free vs PRO : que gagne-t-on ?

Capacité	Free (AGPLv3)	PRO (licence payante)
WAF ModSecurity + CRS	Oui	Oui
Rate limiting, Bad Behavior	Oui	Oui
Let’s Encrypt automatique	Oui	Oui
Web UI d’administration	Oui	Oui
BunkerNet (threat intelligence)	Oui	Oui
Anti-bot (cookie, JavaScript)	Oui	Oui
Plugins externes (ClamAV, Coraza, Discord, Slack, VirusTotal, WebHook)	Oui	Oui
SSO (OpenID Connect)	Non	Oui
User Manager (multi-utilisateurs UI)	Non	Oui
Anti-DDoS	Non	Oui
Load balancer	Non	Oui
Prometheus exporter	Non	Oui
OpenAPI Validator	Non	Oui
Backup S3	Non	Oui
Reporting	Non	Oui
Support commercial	Non	Oui

Glissez pour voir

La version Free couvre la majorité des besoins : WAF complet, rate limiting, bans, HTTPS automatique, Web UI et plugins communautaires. La version PRO ajoute des fonctionnalités pour les environnements à fort trafic, multi-utilisateurs ou réglementés.

Dépannage

Symptôme	Cause probable	Solution
BunkerWeb reste en Created	Port déjà utilisé par un autre service	Vérifier avec ss -tlnp | grep :80 et changer le mapping
Scheduler unhealthy	BunkerWeb non joignable sur bw-universe	Vérifier que API_WHITELIST_IP inclut le sous-réseau 10.20.30.0/24
Scheduler refuse de pousser la config	Paramètres API incohérents	Vérifier que API_WHITELIST_IP et les autres paramètres API sont identiques sur BunkerWeb et le Scheduler
403 sur toutes les requêtes	IP bannie par Bad Behavior	Redémarrer BunkerWeb (docker compose restart bunkerweb) pour réinitialiser les bans en mémoire
429 sur des requêtes légitimes	Rate limiting trop strict (2r/s par défaut)	Augmenter LIMIT_REQ_RATE à 10r/s ou plus
whoami ne reçoit pas les requêtes	Application pas sur le réseau bw-services	Vérifier que l’app et BunkerWeb partagent le même réseau
Logs montrent l’IP Docker au lieu du client	Real IP non activé	Ajouter USE_REAL_IP: "yes" avec REAL_IP_FROM et REAL_IP_HEADER
Web UI inaccessible sur le port 7000	Port non exposé ou AIO non utilisé	Vérifier le mapping de port et que SERVICE_UI: "yes"
Wizard demande de reconfigurer à chaque redémarrage	Volume non persisté	Ajouter un volume sur /data pour le conteneur AIO
Let’s Encrypt échoue	Port 80 non accessible ou DNS non configuré	Vérifier que le domaine pointe vers le serveur et que le port 80 est ouvert
Permissions refusées sur /data	UID/GID incorrect	Le Scheduler tourne en UID/GID 101 : chown 101:101 /chemin/vers/data

Glissez pour voir

À retenir

• BunkerWeb est un WAF open source basé sur NGINX qui se déploie en reverse proxy devant vos applications
• Distinguez lab (AIO, auto-signé, port 7000 direct) et production (multi-conteneurs, DB externe, Redis, vrais certificats)
• Le Scheduler porte la configuration métier, mais les paramètres API doivent être cohérents entre Scheduler et BunkerWeb
• ModSecurity + CRS v4, le rate limiting et Bad Behavior sont activés par défaut — votre application est protégée dès le premier docker compose up
• Activez Real IP (avec REAL_IP_RECURSIVE) dès que BunkerWeb est derrière un proxy ou un load balancer
• L’API est un plan de contrôle interne : ne l’exposez jamais sur Internet
• HTTPS n’est pas actif par défaut : activez GENERATE_SELF_SIGNED_SSL pour le lab ou AUTO_LETS_ENCRYPT pour la production
• La Web UI est disponible en service dédié ou via l’image AIO, et nécessite le mode multisite
• BunkerNet (natif) et CrowdSec (externe ou intégré en AIO) sont complémentaires
• Persistez le volume /data du Scheduler pour ne pas perdre la configuration et les bans
• La version Free couvre la majorité des cas — évaluez PRO pour l’anti-DDoS, le SSO, le load balancer ou le support

Prochaines étapes

CrowdSec Protection collaborative contre les attaques : détection, partage communautaire et réponse automatisée.

SysWarden Protéger rapidement un serveur Linux exposé avec nftables, blocklists et Fail2ban.

Introduction aux pare-feux Comprendre les bases du filtrage réseau sous Linux.

Documentation officielle BunkerWeb Référence complète des settings, plugins et intégrations.

×

📖 Voir la documentation →