magnus919_agent-skills/crowdsec/references/nginx-bouncer.md

Nginx Bouncer Configuration

The CrowdSec Nginx bouncer integrates via Lua directives to check incoming requests against CrowdSec decisions.

Installation

sudo apt install crowdsec-firewall-bouncer-nginx

Bouncer Configuration

The bouncer YAML config lives at /etc/crowdsec/bouncers/crowdsec-nginx-bouncer.yaml:

# /etc/crowdsec/bouncers/crowdsec-nginx-bouncer.yaml
api_url: http://127.0.0.1:8080
api_key: "<your-bouncer-api-key>"
mode: stream            # stream (push) or live (pull per request)
update_frequency: 10s   # Decision refresh interval (stream mode)

Modes

• stream (recommended): LAPI pushes decisions to the bouncer over a persistent connection. Lower latency, fewer API calls.
• live: The bouncer queries LAPI on each request. Higher latency but simpler to debug.

Nginx Configuration

Add to your Nginx server {} block or to nginx.conf:

# Load the CrowdSec Lua module
lua_package_path "/usr/lib/crowdsec/lua/?.lua;;";

# Shared dictionary for caching decisions (10MB)
lua_shared_dict crowdsec_cache 10m;

# Initialize on worker start
init_by_lua_block {
    local bouncer = require "crowdsec"
    bouncer.init()
}

# Check each request against CrowdSec decisions
access_by_lua_block {
    local bouncer = require "crowdsec"
    if bouncer.check() then
        return ngx.exit(ngx.FORBIDDEN)
    end
}

Cloudflare / CDN

If Nginx is behind Cloudflare or another CDN, the real client IP must be passed to the bouncer. Set the real IP header in Nginx:

set_real_ip_from 103.21.244.0/22;
# ... all Cloudflare CIDR ranges
real_ip_header CF-Connecting-IP;

Then configure the bouncer to trust the forwarded header:

trusted_forwarded_ip_count: 1
trusted_forwarded_header_name: "X-Forwarded-For"

Verification

# Check bouncer is registered and active
sudo cscli bouncers list

# Test with a manually banned IP
sudo cscli decisions add --ip 203.0.113.99 --duration 5m
curl -I http://your-server/  # From the banned IP → should return 403
sudo cscli decisions delete --ip 203.0.113.99

Troubleshooting

• 403 on all requests: Check api_key matches what sudo cscli bouncers add <name> returned
• Lua errors in Nginx logs: Verify lua_package_path points to the correct install directory
• IP not being banned: Check forwardedHeadersTrustedIPs if behind a proxy/CDN
• Bouncer not showing in cscli bouncers list: Restart crowdsec after adding the bouncer