Comment mettre en place un WAF avec HAProxy

HAProxy open source ne fournit aucun module WAF. Il existe trois véritables options pour en ajouter un, et il vaut la peine de choisir délibérément avant d'installer quoi que ce soit :

• coraza-spoa (open source, recommandé ici) : exécute le moteur OWASP Coraza et l'OWASP Core Rule Set sous la forme d'un Stream Processing Offload Agent. HAProxy transmet chaque requête à l'agent via SPOP et applique le verdict rendu. Mêmes règles SecLang que ModSecurity.
• SPOA ModSecurity (open source) : un SPOA plus ancien qui embarque le moteur ModSecurity. Il fonctionne, mais il est moins activement maintenu que Coraza et se trouve de fait supplanté par coraza-spoa pour les nouveaux déploiements.
• WAF HAProxy Enterprise (commercial) : un WAF intégré, propulsé par du machine learning, qui s'exécute dans le même processus que le load balancer, avec un mode de compatibilité OWASP CRS optionnel. Aucun agent distinct, une latence ajoutée quasi nulle, mais il nécessite une licence Enterprise.

Quel que soit le WAF retenu, les ACL et les stick-tables natives de HAProxy assurent la limitation de débit et un filtrage grossier. Ce guide utilise coraza-spoa parce qu'il est gratuit, open source et exécute les mêmes règles CRS que ModSecurity.

Avant d'ajouter un moteur WAF, servez-vous des fonctionnalités natives de HAProxy pour la limitation de débit et le filtrage de requêtes de base. Les stick-tables suivent l'état par client ; les ACL permettent de bloquer ou de brider en fonction de cet état. Ajoutez ceci à votre frontend dans /etc/haproxy/haproxy.cfg :

frontend web
    mode http
    bind :80

    # Bufferiser le corps de la requête pour que le WAF puisse inspecter les charges utiles POST et JSON par la suite
    option http-buffer-request

    # Suivre le débit de requêtes par IP source sur une fenêtre de 10 s
    stick-table type ip size 100k expire 30s store http_req_rate(10s)
    http-request track-sc0 src

    # Refuser les clients dépassant 100 requêtes par tranche de 10 secondes
    http-request deny deny_status 429 if { sc_http_req_rate(0) gt 100 }

    # Exemple de filtrage de base fondé sur le chemin
    acl block_path path_beg /.git /.env /wp-login.php
    http-request deny deny_status 403 if block_path

    default_backend web-backend

Rechargez et vérifiez que la configuration est valide :

sudo haproxy -c -f /etc/haproxy/haproxy.cfg
sudo systemctl reload haproxy

coraza-spoa est un programme Go qui exécute le moteur WAF Coraza et l'expose à HAProxy via SPOP. Compilez-le depuis les sources :

# Cloner le SPOA
cd /opt
sudo git clone https://github.com/corazawaf/coraza-spoa.git
cd coraza-spoa

# Compiler le binaire avec Mage (il n'y a pas de Makefile ; nécessite Go 1.25+ selon go.mod)
sudo go run mage.go build

# Installer le binaire compilé dans votre PATH (il est écrit dans build/)
sudo cp build/coraza-spoa /usr/local/bin/

Créez un répertoire pour héberger la configuration et les règles de l'agent :

sudo mkdir -p /etc/coraza-spoa/rules

Coraza exécute les règles OWASP CRS standard, les mêmes règles SecLang que celles utilisées par ModSecurity. Récupérez le CRS et sa configuration de base :

cd /etc/coraza-spoa/rules
sudo git clone https://github.com/coreruleset/coreruleset.git
cd coreruleset

# Créer le fichier de configuration du CRS à partir de l'exemple
sudo cp crs-setup.conf.example crs-setup.conf

Vous avez également besoin d'une configuration de base Coraza, qui définit le mode du moteur de règles et la gestion du corps des requêtes. Créez /etc/coraza-spoa/rules/coraza.conf avec les directives essentielles :

# Démarrer en mode détection jusqu'à ce que vous ayez réglé les faux positifs
SecRuleEngine DetectionOnly

SecRequestBodyAccess On
SecRequestBodyLimit 13107200
SecRequestBodyLimitAction Reject

SecResponseBodyAccess On
SecResponseBodyMimeType text/plain text/html text/xml application/json

SecAuditEngine RelevantOnly
SecAuditLogParts ABIJDEFHZ
SecAuditLog /var/log/coraza-spoa/audit.log

L'agent a besoin de sa propre configuration, qui lui indique quelles règles charger et sur quelle adresse écouter HAProxy. Créez /etc/coraza-spoa/config.yaml :

# configuration de l'agent coraza-spoa
bind: 127.0.0.1:9000
log_level: info

# Doit correspondre au nom d'une application définie dans la liste ci-dessous
default_application: default

# applications est une liste YAML ; chaque entrée est un objet doté d'un nom
applications:
  - name: default
    directives: |
      Include /etc/coraza-spoa/rules/coraza.conf
      Include /etc/coraza-spoa/rules/coreruleset/crs-setup.conf
      Include /etc/coraza-spoa/rules/coreruleset/rules/*.conf
    # Activer l'inspection en phase de réponse pour que le message coraza-res et
    # la règle http-response deny s'exécutent réellement (false par défaut)
    response_check: true
    transaction_ttl_ms: 60000
    log_level: info
    log_file: /var/log/coraza-spoa/coraza.log

Créez le répertoire de journaux :

sudo mkdir -p /var/log/coraza-spoa

Vérifiez que l'agent démarre et charge les règles sans erreur :

sudo coraza-spoa -config /etc/coraza-spoa/config.yaml

HAProxy communique avec l'agent via un fichier de configuration Stream Processing Offload Engine (SPOE). Celui-ci définit quelles données de requête sont envoyées à Coraza et dans quelles variables le verdict est réécrit. Créez /etc/haproxy/coraza.cfg :

[coraza]
spoe-agent coraza-agent
    messages    coraza-res
    groups      coraza-req
    option      var-prefix      coraza
    option      set-on-error    error
    timeout     hello           2s
    timeout     idle            2m
    timeout     processing      500ms
    use-backend coraza-spoa
    log         global

spoe-message coraza-req
    args app=var(txn.coraza.app) src-ip=src src-port=src_port dst-ip=dst dst-port=dst_port method=method path=path query=query version=req.ver headers=req.hdrs body=req.body exportRuleIDs=bool(false)

spoe-message coraza-res
    args app=var(txn.coraza.app) id=var(txn.coraza.id) version=res.ver status=status headers=res.hdrs body=res.body exportRuleIDs=bool(false) detect-only=bool(false)
    event on-http-response

spoe-group coraza-req
    messages coraza-req

La requête est envoyée via un spoe-group que le frontend déclenche avec send-spoe-group ; le message de réponse se déclenche automatiquement sur l'événement on-http-response. L'ordre des arguments correspond exactement à celui de l'exemple officiel coraza.cfg, et il doit impérativement respecter cet ordre.

Définissez ensuite un backend pointant vers l'agent afin que HAProxy sache où le joindre. Ajoutez ceci à /etc/haproxy/haproxy.cfg :

backend coraza-spoa
    mode tcp
    option spop-check
    server coraza 127.0.0.1:9000 check

Rattachez maintenant le filtre SPOE à votre frontend et agissez sur le verdict renvoyé par Coraza. Mettez à jour le frontend de l'étape 2 dans /etc/haproxy/haproxy.cfg :

frontend web
    mode http
    bind :80

    # Bufferiser le corps de la requête pour que Coraza puisse inspecter les charges utiles POST et JSON
    option http-buffer-request

    # Limitation de débit native (issue de l'étape 2)
    stick-table type ip size 100k expire 30s store http_req_rate(10s)
    http-request track-sc0 src
    http-request deny deny_status 429 if { sc_http_req_rate(0) gt 100 }

    # Sélectionner l'application coraza-spoa utilisée par ce frontend
    http-request set-var(txn.coraza.app) str(default)

    # Rattacher le filtre WAF Coraza et envoyer la requête à l'agent
    filter spoe engine coraza config /etc/haproxy/coraza.cfg
    http-request send-spoe-group coraza coraza-req

    # Refuser les requêtes et réponses que Coraza signale comme des attaques
    http-request deny deny_status 403 if { var(txn.coraza.action) -m str deny }
    http-response deny deny_status 403 if { var(txn.coraza.action) -m str deny }

    default_backend web-backend

La ligne option http-buffer-request n'est pas facultative si les attaques transmises dans le corps des requêtes POST vous préoccupent. Sans elle, HAProxy ne renseigne pas de façon fiable l'échantillon req.body avant l'envoi de la requête à l'agent ; les charges utiles d'injection SQL ou de XSS véhiculées dans les corps de requêtes de formulaire ou JSON ne sont donc jamais envoyées à Coraza et échappent à l'inspection, même si SecRequestBodyAccess vaut On. L'inspection du corps des requêtes est bornée par tune.bufsize (16 Ko par défaut) : HAProxy ne peut bufferiser qu'environ un bufsize, si bien que les corps plus volumineux ne sont pas envoyés intégralement à Coraza. Si vous devez inspecter des corps de formulaire ou JSON plus gros, augmentez tune.bufsize modérément (par exemple à 64 Ko) plutôt que de l'aligner sur un SecRequestBodyLimit de plusieurs mégaoctets, ce qui multiplierait la mémoire par connexion et risquerait de provoquer une saturation mémoire.

Validez l'ensemble de la configuration avant de recharger :

sudo haproxy -c -f /etc/haproxy/haproxy.cfg

Exécutez l'agent sous systemd pour qu'il démarre au boot et redémarre en cas de défaillance. Créez /etc/systemd/system/coraza-spoa.service :

[Unit]
Description=Coraza SPOA WAF agent for HAProxy
After=network.target

[Service]
ExecStart=/usr/local/bin/coraza-spoa -config /etc/coraza-spoa/config.yaml
Restart=on-failure
User=haproxy
Group=haproxy

[Install]
WantedBy=multi-user.target

Activez et démarrez l'agent, puis rechargez HAProxy :

sudo systemctl daemon-reload
sudo systemctl enable --now coraza-spoa
sudo systemctl reload haproxy

# Vérifier que l'agent tourne et écoute
sudo systemctl status coraza-spoa

Passez temporairement SecRuleEngine On dans /etc/coraza-spoa/rules/coraza.conf, redémarrez l'agent et envoyez des charges utiles d'attaque connues. Elles doivent être bloquées avec un code 403 :

sudo systemctl restart coraza-spoa

# Tentative d'injection SQL (doit être bloquée)
curl -I 'http://your-server.com/?id=1%20OR%201=1'

# Tentative de XSS (doit être bloquée)
curl -I 'http://your-server.com/?q=<script>alert(1)</script>'

# Tentative d'injection SQL dans le corps de la requête (doit être bloquée si http-buffer-request est activé)
curl -I -X POST -d 'id=1 OR 1=1' 'http://your-server.com/login'

# Une requête normale (doit passer avec un code 200)
curl -I 'http://your-server.com/'

Vérifiez que les blocages apparaissent dans le journal d'audit de Coraza :

sudo tail -f /var/log/coraza-spoa/audit.log

Vous devriez voir des entrées indiquant les identifiants de règles CRS déclenchées et le score d'anomalie ayant provoqué le refus.

Faites fonctionner le mode DetectionOnly pendant une à deux semaines et passez en revue le journal d'audit à la recherche de requêtes légitimes qui auraient été bloquées. Effectuez le réglage à l'aide des mécanismes CRS standard dans un fichier personnalisé chargé après les règles, par exemple /etc/coraza-spoa/rules/custom-exclusions.conf :

# Désactiver une règle précise qui se déclenche à tort
SecRuleRemoveById 942100

# Désactiver une règle uniquement pour un chemin précis
SecRule REQUEST_URI "@beginsWith /api/upload" \
  "id:1000,phase:1,pass,nolog,ctl:ruleRemoveById=920420"

Vous pouvez également abaisser le niveau de paranoïa du CRS dans crs-setup.conf pour réduire les faux positifs (1 = le moins de faux positifs, 4 = le plus strict) :

SecAction "id:900000,phase:1,pass,t:none,nolog,\
  setvar:tx.blocking_paranoia_level=1"

Une fois le journal propre, positionnez SecRuleEngine On et redémarrez l'agent pour commencer à appliquer les blocages.