haproxy

Securing HAProxy with Coraza-SPOA: A Step-by-Step Guide

Patrick de Ruiter

12 Dec 2025 — 3 min read

Coraza-SPOA offers a powerful way to add Web Application Firewall (WAF) capabilities to HAProxy, enhancing security for your web applications. In this guide, I'll take you through the complete process of installing, configuring, and integrating Coraza-SPOA with HAProxy. We'll cover compiling Coraza-SPOA, setting up log rotation, configuring HAProxy, and ensuring everything runs smoothly.

Step 1: Clone and Compile Coraza-SPOA

The first step is to clone the Coraza-SPOA GitHub repository and compile the binary. Make sure you have Go installed before proceeding.

# Clone the Coraza-SPOA repo
git clone https://github.com/corazawaf/coraza-spoa.git

# Change into the directory and compile the binary
cd coraza-spoa
make

Step 2: Install the Binary and Set Permissions

Once compiled, copy the binary to an appropriate location and set the necessary permissions.

# Place the binary in /usr/local/bin
cp -Rp coraza-spoa_amd64 /usr/local/bin/coraza-spoa

# Set ownership and permissions
chown root:root /usr/local/bin/coraza-spoa
chmod 755 /usr/local/bin/coraza-spoa

Step 3: Create Directory Structure for Logs and Configuration

Create the required directories for logs and configuration.

# Create directories
mkdir -p /etc/coraza-spoa
mkdir -p /var/log/coraza-spoa/audit

# Create necessary log files
touch /var/log/coraza-spoa/server.log

# Repeat for all required log files
for logfile in error.log debug.log audit/audit.log; do
    touch /var/log/coraza-spoa/$logfile
done

Step 4: Add User and Set Permissions

For security, Coraza-SPOA runs under its own user.

# Add a system group and user
addgroup --quiet --system coraza-spoa
adduser --quiet --system --ingroup coraza-spoa --no-create-home --home /nonexistent --disabled-password coraza-spoa

# Set log file permissions
chown -R coraza-spoa:adm /var/log/coraza-spoa
chmod 755 /var/log/coraza-spoa

Step 5: Configure Coraza-SPOA

Create the configuration file for Coraza-SPOA to define how it integrates with HAProxy.

Edit /etc/coraza-spoa/config.yaml:

# Bind address
bind: 127.0.0.1:9000

default_application: haproxy_waf

applications:
  haproxy_waf:
    directives: |
      Include /etc/coraza-spoa/coraza.conf
      Include /etc/coraza-spoa/crs-setup.conf
      Include /etc/coraza-spoa/plugins/*-config.conf
    log_level: info
    log_file: /var/log/coraza-spoa/server.log
    no_response_check: true
    transaction_ttl_ms: 60000
    transaction_active_limit: 100000

Step 6: Configure Coraza Rules

Edit /etc/coraza-spoa/coraza.conf to add security rules. You can start by enabling detection-only mode or blocking mode as per your requirement.

# Basic rules
git clone https://github.com/coreruleset/coreruleset.git
cp -Rp coreruleset/rules /etc/coraza-spoa/

Step 7: System Configuration

Set up system services to start and manage Coraza-SPOA.

# Copy log rotation configuration and systemd unit files
cp -Rp contrib/coraza-spoa.logrotate /etc/logrotate.d/coraza-spoa
cp -Rp contrib/coraza-spoa.service /lib/systemd/system/

# Reload systemd and enable the Coraza-SPOA agent
systemctl daemon-reload
systemctl enable coraza-spoa.service
systemctl start coraza-spoa.service

Step 8: Configure HAProxy

HAProxy configuration consists of four main steps:

Create the frontend.
Create backends for Coraza-SPOA and static content.
Configure the SPOE engine.

Add the following frontend and backend configurations in /etc/haproxy/haproxy.cfg:

frontend static_test
    mode http
    bind *:80
    filter spoe engine coraza config /etc/haproxy/coraza.cfg
    use_backend bsdserver_static

backend bsdserver_static
    mode http
    http-request return status 200 content-type "text/plain" string "Welcome!\n"

backend coraza-spoa
    mode tcp
    balance roundrobin
    server s1 127.0.0.1:9000

Step 9: SPOE Configuration for HAProxy

Create the SPOE configuration file to specify how requests are passed to Coraza.

Edit /etc/haproxy/coraza.cfg:

[coraza]
spoe-agent coraza-agent
    messages coraza-req
    option var-prefix coraza
    use-backend coraza-spoa

spoe-message coraza-req
    args app=str(haproxy_waf) id=unique-id src-ip=src ...

Step 10: Validate and Start HAProxy

To check if your HAProxy configuration is correct:

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

If there are no errors, enable and start HAProxy:

# Enable HAProxy
systemctl enable haproxy.service

# Start HAProxy
systemctl start haproxy.service

# Verify status
systemctl status haproxy.service

Conclusion

You've now set up Coraza-SPOA integrated with HAProxy, creating a robust WAF setup that helps protect your web applications from a wide range of attacks. Coraza allows HAProxy to inspect both incoming and outgoing traffic, adding a strong layer of security.

For more information and additional configurations, visit:

Feel free to explore additional configurations to adapt the setup to your environment!