patterns/docs/nginx.md

Nginx Integration

This guide explains how to integrate the WAF patterns into your Nginx configuration.

Quick Start

1. Download nginx_waf.zip from Releases
2. Extract to your Nginx configuration directory
3. Include the configuration files as shown below

Configuration Files

The Nginx WAF package includes:

File	Purpose	Include Location
waf_maps.conf	Map directives for pattern matching	http block
waf_rules.conf	If statements for blocking	server block
bots.conf	Bad bot detection maps	http block

Integration

Step 1: Include Maps in HTTP Block

The map directives must be included in the http context:

http {
    # Include WAF maps (pattern definitions)
    include /path/to/waf_patterns/nginx/waf_maps.conf;
    
    # Include bot detection maps
    include /path/to/waf_patterns/nginx/bots.conf;
    
    # ... other http configurations ...
}

Step 2: Include Rules in Server Block

The blocking rules go inside your server or location block:

server {
    listen 80;
    server_name example.com;
    
    # Include WAF rules
    include /path/to/waf_patterns/nginx/waf_rules.conf;
    
    # ... other server configurations ...
}

Step 3: Reload Nginx

Test and reload the configuration:

sudo nginx -t && sudo systemctl reload nginx

How It Works

The WAF uses Nginx's map directive for efficient pattern matching:

map $request_uri $waf_block_sqli {
    default 0;
    "~*union.*select" 1;
    "~*insert.*into" 1;
}

if ($waf_block_sqli) {
    return 403;
}

Customization

Enable Logging

To log blocked requests, edit waf_rules.conf and uncomment the logging lines:

if ($waf_block_sqli) {
    return 403;
    access_log /var/log/nginx/waf_blocked.log;
}

Whitelist Specific Paths

Add exceptions before the WAF rules:

location /api/webhook {
    # Skip WAF for this path
    # ... your configuration ...
}

# WAF rules for other paths
include /path/to/waf_patterns/nginx/waf_rules.conf;

::: warning Important Individual category files like attack.conf or xss.conf should not be included directly. They contain both map and if directives which cannot be used in the same context. Always use waf_maps.conf + waf_rules.conf. :::

Testing

Test your WAF configuration with common attack patterns:

# Should be blocked (SQL injection)
curl -I "http://example.com/?id=1' OR '1'='1"

# Should be blocked (XSS)
curl -I "http://example.com/?q=<script>alert(1)</script>"

Troubleshooting

Configuration errors

Always run nginx -t before reloading to catch syntax errors.

False positives

If legitimate requests are being blocked, check /var/log/nginx/error.log and consider adding path-specific exceptions.

Performance

The map-based approach is highly efficient. For high-traffic sites, consider enabling caching for the map variables.