Claude Code for NGINX WAF Workflow Tutorial

Securing web applications against malicious traffic is a critical priority for any development team. NGINX WAF (Web Application Firewall) provides powerful protection against common attacks like SQL injection, cross-site scripting (XSS), and other OWASP Top 10 vulnerabilities. However, configuring and managing WAF rules manually can be complex and time-consuming. This tutorial demonstrates how to leverage Claude Code to automate and accelerate your NGINX WAF workflow from initial setup to ongoing management.

Prerequisites

Before getting started, make sure you have the following:

NGINX Plus or open-source NGINX with the ModSecurity module
Claude Code CLI installed (brew install claude or via official installer)
Basic understanding of WAF concepts and NGINX configuration
Access to your NGINX configuration files

Setting Up Your WAF Project

Begin by creating a dedicated project directory for your NGINX WAF configuration:

mkdir nginx-waf-project && cd nginx-waf-project

Initialize your project with a CLAUDE.md file to guide Claude Code’s behavior:

cat > CLAUDE.md << 'EOF'
# NGINX WAF Project

This project manages NGINX WAF configuration for our web application.

## Key Files
- `waf.conf`: Main WAF configuration
- `rules/*.conf`: Custom security rules
- `nginx.conf`: Main NGINX configuration

## WAF Goals
- Block SQL injection attempts
- Prevent XSS attacks
- Mitigate DDoS traffic
- Log all blocked requests for analysis

## Common Tasks
1. Add new WAF rules
2. Test rules before deployment
3. Review blocked request logs
4. Tune rules to reduce false positives
EOF

Configuring ModSecurity for NGINX

Claude Code can help you generate a solid ModSecurity configuration. Ask Claude to create your base WAF configuration:

When working with Claude Code, describe your requirements clearly:

“Create a ModSecurity configuration for NGINX that enables the OWASP Core Rule Set, enables request body scanning, and sets up appropriate logging.”

Claude will generate configuration similar to this:

# /etc/nginx/modsec/main.conf

# Load OWASP Core Rule Set
Include /etc/modsecurity/crs/crs-setup.conf
Include /etc/modsecurity/crs/rules/*.conf

# Custom configuration
SecRuleEngine On
SecRequestBodyAccess On
SecResponseBodyAccess Off
SecRequestBodyLimit 13107200
SecRequestBodyNoFilesLimit 131072
SecRequestBodyLimitAction Reject
SecPcreMatchLimit 1000
SecPcreMatchLimitRecursion 1000

# Audit logging configuration
SecAuditEngine RelevantOnly
SecAuditLogRelevantStatus "^(?:5|4(?!04))"
SecAuditLogParts ABIJDEFHZ
SecAuditLogType Serial

# Error handling
SecArgumentSeparator &
SecCookieFormat 0

Creating Custom WAF Rules

One of Claude Code’s strengths is helping you write custom security rules tailored to your application. Here’s how to request custom rules:

“Create a WAF rule that blocks requests with suspicious patterns in URL parameters, specifically looking for command injection attempts like ;, |, or backticks.”

Claude might respond with:

# Block command injection attempts in URL parameters
SecRule REQUEST_URI|ARGS "@rx [;&|`$()]|\b(cat|ls|echo|wget|curl)\b" \
    "id:1001,\
    phase:1,\
    deny,\
    status:403,\
    msg:'Command injection attempt detected',\
    logdata:'Matched %{MATCHED_VAR}',\
    severity:'CRITICAL',\
    tag:'attack-command-injection'"

Managing Rulesets with Claude Code

Organize your WAF rules logically. Claude can help you structure a rules directory:

waf-project/
├── nginx.conf
├── modsec/
│   ├── main.conf
│   └── custom-rules/
│       ├── sql-injection.conf
│       ├── xss-protection.conf
│       ├── command-injection.conf
│       └── api-protection.conf
└── tests/
    └── rule-tests.yaml

Ask Claude to create a ruleset for API protection:

“Create a custom ModSecurity rule file for protecting REST APIs that rate limits by IP and blocks unusual HTTP methods.”

Claude generates:

# /modsec/custom-rules/api-protection.conf

# Rate limiting - block IPs making too many requests
SecRule IP:REQUEST_COUNT "@gt 100" \
    "id:2001,\
    phase:1,\
    deny,\
    status:429,\
    msg:'Rate limit exceeded',\
    logdata:'Request count: %{IP:REQUEST_COUNT}',\
    tag:'rate-limit'"

# Block unusual HTTP methods
SecRule REQUEST_METHOD "@rx ^(?:GET|POST|PUT|DELETE|OPTIONS)$" \
    "id:2002,\
    phase:1,\
    pass,\
    msg:'Allowing standard HTTP methods'"

SecRule REQUEST_METHOD "!@rx ^(?:GET|POST|PUT|DELETE|OPTIONS)$" \
    "id:2003,\
    phase:1,\
    deny,\
    status:405,\
    msg:'Method not allowed',\
    logdata:'Method: %{REQUEST_METHOD}'"

# Protect against JSON-based attacks
SecRule REQUEST_HEADERS:Content-Type "@rx application/json" \
    "id:2004,\
    phase:1,\
    pass,\
    chain"
SecRule REQUEST_BODY "@rx <script|javascript:|onerror=|onload=" \
    "id:2005,\
    deny,\
    status:400,\
    msg:'XSS attempt in JSON body'"

Testing WAF Rules Before Deployment

Always test rules in a staging environment before production deployment. Claude can help you create test cases:

“Create a test file that verifies our SQL injection rules are working correctly, including both blocked and allowed requests.”

# tests/sql-injection-test.yaml
test_cases:
  - name: "SQL injection - OR 1=1"
    request:
      uri: "/api/users?id=1 OR 1=1"
      method: GET
    expected:
      status: 403
      logged: true
      
  - name: "SQL injection - UNION SELECT"
    request:
      uri: "/api/users?id=1 UNION SELECT null--"
      method: GET
    expected:
      status: 403
      logged: true
      
  - name: "Valid query - allowed"
    request:
      uri: "/api/users?id=1"
      method: GET
    expected:
      status: 200
      logged: false

Analyzing Blocked Requests

When legitimate traffic gets blocked, you need to investigate quickly. Ask Claude:

“Help me analyze the ModSecurity audit log to find common false positives in the last 24 hours.”

Claude can parse log patterns and suggest rule tuning:

# Example: Extract 403 errors from audit log
grep "status:403" /var/log/modsec_audit.log | tail -100

Claude might suggest adding exceptions:

# Add exceptions for false positives
# Example: Allow specific user agent
SecRule REQUEST_HEADERS:User-Agent "@rx ^MyCustomClient/1\.0$" \
    "id:9001,\
    phase:1,\
    pass,\
    ctl:ruleEngine=Off"

Automating WAF Management

You can create a Claude Code skill to standardize WAF operations. Create skills/nginx-waf-skill.md:

# NGINX WAF Skill

## Triggers
- Working with ModSecurity configuration
- Creating or editing WAF rules
- Analyzing security logs
- Troubleshooting blocked requests

## Capabilities
- Generate ModSecurity rules from description
- Parse and summarize audit logs
- Suggest rule optimizations
- Create test cases for WAF rules

## Guidelines
- Always test rules in staging before production
- Include proper rule IDs (follow ModSecurity numbering)
- Log all blocked requests for analysis
- Review false positives regularly
- Document custom rules with clear messages

Best Practices for NGINX WAF with Claude Code

Follow these recommendations when managing NGINX WAF with Claude Code:

Start with detection mode: Enable SecRuleEngine to DetectionOnly initially to identify false positives before blocking.
Use proper rule IDs: Assign unique IDs (1000-99999 for custom rules) to easily track and disable problematic rules.
Include comprehensive logging: Always log matched variables and relevant data for troubleshooting.
Test extensively: Create automated tests for each custom rule to prevent regressions.
Review regularly: Schedule periodic reviews of blocked requests to tune rules and reduce false positives.
Document everything: Use clear msg and tag fields in rules for easier log analysis.

Conclusion

Claude Code significantly simplifies NGINX WAF management by automating rule creation, testing, and analysis. By integrating Claude into your security workflow, you can deploy robust WAF protection faster while maintaining the flexibility to customize rules for your specific application needs. Start with the basics outlined in this tutorial, then gradually add custom rules as you identify unique threats to your application.

Built by theluckystrike — More at zovo.one