How to Set Up a WAF with HAProxy

Open source HAProxy does not ship a WAF module. There are three real options for adding one, and it is worth picking deliberately before you install anything:

• coraza-spoa (open source, recommended here): Runs the OWASP Coraza engine and the OWASP Core Rule Set as a Stream Processing Offload Agent. HAProxy sends each request to the agent over SPOP and acts on the verdict. Same SecLang rules as ModSecurity.
• ModSecurity SPOA (open source): An older SPOA that embeds the ModSecurity engine. It works but is less actively maintained than Coraza and is effectively superseded by coraza-spoa for new deployments.
• HAProxy Enterprise WAF (commercial): A built-in, ML-powered WAF that runs in-process with the load balancer, with an optional OWASP CRS compatibility mode. No separate agent, near-zero added latency, but it requires an Enterprise license.

Regardless of which WAF you choose, HAProxy's native ACLs and stick-tables handle rate limiting and coarse filtering. This guide uses coraza-spoa because it is free, open source, and runs the same CRS rules as ModSecurity.

Before adding a WAF engine, use HAProxy's native features for rate limiting and basic request filtering. Stick-tables track per-client state; ACLs let you block or throttle on that state. Add this to your frontend in /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

Reload and confirm the configuration is valid:

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

coraza-spoa is a Go program that runs the Coraza WAF engine and exposes it to HAProxy over SPOP. Build it from source:

# 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/

Create a directory to hold the agent configuration and rules:

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

Coraza runs standard OWASP CRS rules, the same SecLang rules ModSecurity uses. Fetch the CRS and its base configuration:

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

You also need a Coraza base configuration, which sets the rule engine mode and request body handling. Create /etc/coraza-spoa/rules/coraza.conf with the core directives:

# 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

The agent needs its own config that tells it which rules to load and where to listen for HAProxy. Create /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

Create the log directory:

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

Test that the agent starts and loads the rules without error:

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

HAProxy talks to the agent through a Stream Processing Offload Engine (SPOE) configuration file. This defines which request data is sent to Coraza and which variables the verdict is written back to. Create /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

The request is sent via a spoe-group that the frontend triggers with send-spoe-group; the response message fires automatically on the on-http-response event. The argument order matches the official coraza.cfg example exactly, and it is required to be in this order.

Then define a backend pointing at the agent so HAProxy knows where to reach it. Add this to /etc/haproxy/haproxy.cfg:

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

Now attach the SPOE filter to your frontend and act on the verdict Coraza returns. Update the frontend from Step 2 in /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

The option http-buffer-request line is not optional if you care about POST-body attacks. Without it, HAProxy does not reliably populate the req.body sample before the request is sent to the agent, so SQLi or XSS payloads carried in form or JSON request bodies are never sent to Coraza and go uninspected, even though SecRequestBodyAccess is On. Request-body inspection is bounded by tune.bufsize (default 16 KB): HAProxy can only buffer up to about one bufsize, so bodies larger than that are not fully sent to Coraza. If you need to inspect larger form or JSON bodies, raise tune.bufsize modestly (for example to 64 KB) rather than matching a multi-megabyte SecRequestBodyLimit, which would multiply per-connection memory and risk an out-of-memory condition.

Validate the full configuration before reloading:

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

Run the agent under systemd so it starts on boot and restarts on failure. Create /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

Enable and start the agent, then reload 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

Temporarily set SecRuleEngine On in /etc/coraza-spoa/rules/coraza.conf, restart the agent, and send known attack payloads. They should be blocked with a 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/'

Confirm the blocks appear in the Coraza audit log:

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

You should see entries with the matched CRS rule IDs and the anomaly score that triggered the deny.

Run in DetectionOnly mode for one to two weeks and review the audit log for legitimate requests that would have been blocked. Tune using standard CRS mechanisms in a custom file loaded after the rules, for example /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"

You can also lower the CRS paranoia level in crs-setup.conf to reduce false positives (1 = fewest false positives, 4 = strictest):

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

Once the log is clean, set SecRuleEngine On and restart the agent to begin enforcing.