Cómo configurar un WAF con HAProxy

El HAProxy de código abierto no incluye un módulo WAF. Existen tres opciones reales para añadir uno, y conviene elegir con criterio antes de instalar nada:

• coraza-spoa (código abierto, la opción recomendada aquí): Ejecuta el motor OWASP Coraza y el OWASP Core Rule Set como un Stream Processing Offload Agent. HAProxy envía cada petición al agente por SPOP y actúa según el veredicto. Usa las mismas reglas SecLang que ModSecurity.
• SPOA de ModSecurity (código abierto): Un SPOA más antiguo que integra el motor de ModSecurity. Funciona, pero recibe menos mantenimiento activo que Coraza y, en la práctica, queda desplazado por coraza-spoa en los despliegues nuevos.
• WAF de HAProxy Enterprise (comercial): Un WAF integrado y potenciado con ML que se ejecuta en el mismo proceso que el balanceador, con un modo opcional de compatibilidad con el OWASP CRS. No hay agente aparte y la latencia añadida es casi nula, pero requiere una licencia Enterprise.

Sea cual sea el WAF que elijas, las ACLs y stick-tables nativas de HAProxy se encargan del límite de tasa y del filtrado grueso. Esta guía usa coraza-spoa porque es gratuito, de código abierto y ejecuta las mismas reglas del CRS que ModSecurity.

Antes de añadir un motor WAF, usa las funciones nativas de HAProxy para el límite de tasa y el filtrado básico de peticiones. Las stick-tables registran el estado por cliente; las ACLs te permiten bloquear o limitar en función de ese estado. Añade esto a tu frontend en /etc/haproxy/haproxy.cfg:

frontend web
    mode http
    bind :80

    # Buffer the request body so the WAF can inspect POST and JSON payloads later
    option http-buffer-request

    # Track request rate per source IP over a 10s window
    stick-table type ip size 100k expire 30s store http_req_rate(10s)
    http-request track-sc0 src

    # Deny clients making more than 100 requests per 10 seconds
    http-request deny deny_status 429 if { sc_http_req_rate(0) gt 100 }

    # Basic path-based filtering example
    acl block_path path_beg /.git /.env /wp-login.php
    http-request deny deny_status 403 if block_path

    default_backend web-backend

Recarga y confirma que la configuración es válida:

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

coraza-spoa es un programa en Go que ejecuta el motor WAF Coraza y lo expone a HAProxy mediante SPOP. Compílalo desde el código fuente:

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

# Build the binary with Mage (there is no Makefile; requires Go 1.25+ per go.mod)
sudo go run mage.go build

# Install the compiled binary onto your PATH (it is written to build/)
sudo cp build/coraza-spoa /usr/local/bin/

Crea un directorio para alojar la configuración del agente y las reglas:

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

Coraza ejecuta las reglas estándar del OWASP CRS, las mismas reglas SecLang que usa ModSecurity. Descarga el CRS y su configuración base:

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

# Create the CRS setup file from the example
sudo cp crs-setup.conf.example crs-setup.conf

También necesitas una configuración base de Coraza, que establece el modo del motor de reglas y el tratamiento del cuerpo de la petición. Crea /etc/coraza-spoa/rules/coraza.conf con las directivas principales:

# Start in detection mode until you have tuned false positives
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

El agente necesita su propia configuración que le indique qué reglas cargar y dónde escuchar a HAProxy. Crea /etc/coraza-spoa/config.yaml:

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

# Must match the name of an application defined in the list below
default_application: default

# applications is a YAML list; each entry is an object with a name
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
    # Enable response-phase inspection so the coraza-res message and the
    # http-response deny rule actually run (defaults to false)
    response_check: true
    transaction_ttl_ms: 60000
    log_level: info
    log_file: /var/log/coraza-spoa/coraza.log

Crea el directorio de logs:

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

Comprueba que el agente arranca y carga las reglas sin errores:

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

HAProxy se comunica con el agente a través de un archivo de configuración del Stream Processing Offload Engine (SPOE). Este define qué datos de la petición se envían a Coraza y en qué variables se escribe el veredicto. Crea /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 petición se envía mediante un spoe-group que el frontend dispara con send-spoe-group; el mensaje de respuesta se dispara automáticamente en el evento on-http-response. El orden de los argumentos coincide exactamente con el del ejemplo oficial coraza.cfg, y es obligatorio que estén en ese orden.

Después define un backend que apunte al agente para que HAProxy sepa dónde encontrarlo. Añade esto a /etc/haproxy/haproxy.cfg:

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

Ahora asocia el filtro SPOE a tu frontend y actúa según el veredicto que devuelve Coraza. Actualiza el frontend del Paso 2 en /etc/haproxy/haproxy.cfg:

frontend web
    mode http
    bind :80

    # Buffer the request body so Coraza can inspect POST and JSON payloads
    option http-buffer-request

    # Native rate limiting (from Step 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 }

    # Select which coraza-spoa application this frontend uses
    http-request set-var(txn.coraza.app) str(default)

    # Attach the Coraza WAF filter and send the request to the agent
    filter spoe engine coraza config /etc/haproxy/coraza.cfg
    http-request send-spoe-group coraza coraza-req

    # Deny requests and responses Coraza flags as attacks
    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 línea option http-buffer-request no es opcional si te preocupan los ataques en el cuerpo POST. Sin ella, HAProxy no rellena de forma fiable la muestra req.body antes de enviar la petición al agente, por lo que las cargas de SQLi o XSS transportadas en cuerpos de petición de formularios o JSON nunca se envían a Coraza y quedan sin inspeccionar, aunque SecRequestBodyAccess esté en On. La inspección del cuerpo de la petición está limitada por tune.bufsize (16 KB por defecto): HAProxy solo puede almacenar en búfer alrededor de un bufsize, así que los cuerpos mayores que eso no se envían por completo a Coraza. Si necesitas inspeccionar cuerpos de formulario o JSON más grandes, aumenta tune.bufsize con moderación (por ejemplo a 64 KB) en lugar de igualarlo a un SecRequestBodyLimit de varios megabytes, lo que multiplicaría la memoria por conexión y arriesgaría una condición de falta de memoria.

Valida la configuración completa antes de recargar:

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

Ejecuta el agente bajo systemd para que arranque en el inicio del sistema y se reinicie ante un fallo. Crea /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

Habilita y arranca el agente, y después recarga HAProxy:

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

# Confirm the agent is running and listening
sudo systemctl status coraza-spoa

Establece temporalmente SecRuleEngine On en /etc/coraza-spoa/rules/coraza.conf, reinicia el agente y envía cargas de ataque conocidas. Deberían bloquearse con un 403:

sudo systemctl restart coraza-spoa

# SQL injection attempt (should be blocked)
curl -I 'http://your-server.com/?id=1%20OR%201=1'

# XSS attempt (should be blocked)
curl -I 'http://your-server.com/?q=<script>alert(1)</script>'

# Request-body SQL injection attempt (should be blocked with http-buffer-request enabled)
curl -I -X POST -d 'id=1 OR 1=1' 'http://your-server.com/login'

# A normal request (should pass with 200)
curl -I 'http://your-server.com/'

Confirma que los bloqueos aparecen en el log de auditoría de Coraza:

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

Deberías ver entradas con los IDs de las reglas del CRS coincidentes y la puntuación de anomalía que activó la denegación.

Ejecuta en modo DetectionOnly durante una o dos semanas y revisa el log de auditoría en busca de peticiones legítimas que se habrían bloqueado. Ajusta usando los mecanismos estándar del CRS en un archivo personalizado que se cargue después de las reglas, por ejemplo /etc/coraza-spoa/rules/custom-exclusions.conf:

# Disable a specific rule that misfires
SecRuleRemoveById 942100

# Disable a rule only for a specific path
SecRule REQUEST_URI "@beginsWith /api/upload" \
  "id:1000,phase:1,pass,nolog,ctl:ruleRemoveById=920420"

También puedes bajar el nivel de paranoia del CRS en crs-setup.conf para reducir los falsos positivos (1 = menos falsos positivos, 4 = más estricto):

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

Una vez que el log esté limpio, establece SecRuleEngine On y reinicia el agente para empezar a aplicar el bloqueo.