A simple Web Application Firewall (WAF) middleware for the Caddy server, designed to provide comprehensive protection against web attacks. This middleware integrates seamlessly with Caddy and offers a wide range of security features to safeguard your applications.
- Rule-based request filtering with regex patterns.
- IP and DNS blacklisting to block malicious traffic.
- Country-based blocking using MaxMind GeoIP2.
- Rate limiting per IP address to prevent abuse.
- Anomaly scoring system for detecting suspicious behavior.
- Request inspection (URL, args, body, headers, cookies, user-agent).
- Protection against common attacks (SQL injection, XSS, RCE, Log4j, etc.).
- Detailed logging and monitoring for security analysis.
- Dynamic reloading on changes for rules, IP and DNS blacklists
curl -fsSL -H "Pragma: no-cache" https://raw.githubusercontent.com/fabriziosalmi/caddy-waf/refs/heads/main/install.sh | bash
Example output
INFO Starting caddy-waf {"version": "v0.0.0-20250109090908-5a8c1c74fab0"}
INFO Rate limit configuration {"requests": 1000, "window": 60, "cleanup_interval": 300}
INFO [INFO] Starting rate limiter cleanup goroutine
INFO GeoIP database loaded successfully {"path": "GeoLite2-Country.mmdb"}
INFO Rules loaded {"file": "rules.json", "total_rules": 14, "invalid_rules": 0}
INFO IP blacklist loaded successfully {"file": "ip_blacklist.txt", "valid_entries": 3, "total_lines": 3}
INFO DNS blacklist loaded successfully {"file": "dns_blacklist.txt", "valid_entries": 2, "total_lines": 2}
INFO Rules and Blacklists loaded successfully {"total_rules": 14}
INFO WAF middleware provisioned successfully
- 🚀 Installation
- 🛠️ Configuration
- ⚙️ Configuration Options
- 📜 Rules Format (
rules.json) - 🛡️ Protected Attack Types
- 🚫 Blacklist Formats
- ⏱️ Rate Limiting
- 🌍 Country Blocking
- 🔄 Dynamic Updates
- 🧪 Testing
- 🐳 Docker Support
- 🐍 Rule/Blacklist Population Scripts
- 📜 License
- 🙏 Contributing
# Step 1: Clone the caddy-waf repository from GitHub
git clone https://github.com/fabriziosalmi/caddy-waf.git
# Step 2: Navigate into the caddy-waf directory
cd caddy-waf
# Step 3: Clean up and update the go.mod file
go mod tidy
# Step 4: Fetch and install the required Go modules
go get github.com/caddyserver/caddy/v2
go get github.com/caddyserver/caddy/v2/caddyconfig/caddyfile
go get github.com/caddyserver/caddy/v2/caddyconfig/httpcaddyfile
go get github.com/caddyserver/caddy/v2/modules/caddyhttp
go get github.com/oschwald/maxminddb-golang
go get github.com/fsnotify/fsnotify
go get -v github.com/fabriziosalmi/caddy-waf
go mod tidy
# Step 5: Download the GeoLite2 Country database
wget https://git.io/GeoLite2-Country.mmdb
# Step 6: Build Caddy with the caddy-waf module
xcaddy build --with github.com/fabriziosalmi/caddy-waf=./
# Step 7: Fix Caddyfile format
caddy fmt --overwrite
# Step 8: Run the compiled Caddy server
./caddy run- If you encounter any issues, ensure that your Go environment is set up correctly and that you're using a compatible version of Go (as specified in the
caddy-wafrepository'sgo.modfile). - After building Caddy with
xcaddy, the resulting binary will include the WAF middleware. You can verify this by running:Look for the./caddy list-modules
http.handlers.wafmodule in the output.
{
auto_https off
admin off
}
:8080 {
log {
output stdout
format console
level DEBUG
}
route {
waf {
# Anomaly threshold will block request if the score is => the threshold
anomaly_threshold 10
# Rate limiting: 1000 requests per 1 minute
rate_limit 1000 1m 5m
# Rules and blacklists
rule_file rules.json
ip_blacklist_file ip_blacklist.txt
dns_blacklist_file dns_blacklist.txt
# Country blocking (requires MaxMind GeoIP2 database)
block_countries GeoLite2-Country.mmdb RU CN KP
# Whitelist countries (requires MaxMind GeoIP2 database)
# whitelist_countries GeoLite2-Country.mmdb US
# Set Log Severity
log_severity info
# Set Log JSON output
log_json
# Set Log JSON file path
log_path debug.json
}
respond "Hello, world! This is caddy-waf" 200
}
}| Option | Description | Example |
|---|---|---|
anomaly_threshold |
Sets the anomaly score threshold. | anomaly_threshold 20 |
rule_file |
JSON file containing WAF rules | rule_file rules.json |
ip_blacklist_file |
File with blocked IPs/CIDR ranges | ip_blacklist_file blacklist.txt |
dns_blacklist_file |
File with blocked domains | dns_blacklist_file domains.txt |
rate_limit |
Rate limiting config | rate_limit 100 1m |
block_countries |
Country blocking config | block_countries GeoLite2-Country.mmdb RU CN KP |
whitelist_countries |
Country whitelisting config | whitelist_countries GeoLite2-Country.mmdb US |
log_severity |
Sets the minimum logging severity level for this module. | log_severity debug |
log_json |
Enables JSON log output | log_json |
log_path |
JSON debug log | debug.json |
Rules are defined in a JSON file. Each rule specifies a pattern to match, targets to inspect, and actions to take.
[
{
"id": "wordpress-brute-force",
"phase": 2,
"pattern": "(?i)(?:wp-login\\.php|xmlrpc\\.php).*?(?:username=|pwd=)",
"targets": ["URI", "ARGS"],
"severity": "HIGH",
"action": "block",
"score": 8,
"description": "Block brute force attempts targeting WordPress login and XML-RPC endpoints."
}
]| Field | Description | Example |
|---|---|---|
id |
Unique identifier for the rule, used to track and manage security policies. | sql_injection |
phase |
Processing phase, executed in order (1 - request headers, 2 - body, 3 - response headers, 4 - response body). | 1 |
pattern |
Regular expression pattern for detecting threats, allows precise filtering of malicious payloads. | (?i)(?:insert) |
targets |
Specifies areas of the request to inspect for malicious content (URI, ARGS, BODY, HEADERS, COOKIES). | ["ARGS", "BODY"] |
severity |
Rule severity indicates the risk level of the threat (CRITICAL, HIGH, MEDIUM, LOW). |
CRITICAL |
action |
Defines the action to take when the rule matches (block or log). If unspecified, the default action is block. |
default: block |
score |
Score added to the anomaly detection system when a rule matches, contributing to overall request evaluation. | 10 |
description |
Provides a human-readable explanation of the rule's purpose and conditions it checks for. | Block SQL injection attempts. |
mode |
Optional field that allows switching between strict blocking and passive logging. | block or log |
enabled |
Boolean flag to enable or disable specific rules dynamically. | true |
log_detail |
Additional logging level for matched rules, providing extended information during forensic analysis. | true or false |
Rules can be fine-tuned by adjusting the score and severity values, allowing greater flexibility in blocking decisions. More complex patterns targeting multiple request areas can be designed using regexes, ensuring multi-layered defense strategies are effectively enforced.
- SQL Injection
- Basic
SELECT/UNIONinjections - Time-based injection attacks
- Boolean-based injections
- Basic
- Cross-Site Scripting (XSS)
- Script tag injection
- Event handler injection
- SVG-based XSS
- Path Traversal
- Directory traversal attempts
- Encoded path traversal
- Double-encoded traversal
- Remote Code Execution (RCE)
- Command injection
- Shell command execution
- System command execution
- Log4j Exploits
- JNDI lookup attempts
- Nested expressions
- Protocol Attacks
- Git repository access
- Environment file access
- Configuration file access
- Scanner Detection
- Common vulnerability scanners
- Web application scanners
- Network scanning tools
192.168.1.1
10.0.0.0/8
2001:db8::/32
malicious.com
evil.example.org
Configure rate limits using requests count and time window:
# 100 requests per minute
rate_limit 100 1m 5m
# 10 requests per second
rate_limit 10 1s 5m
# 1000 requests per hour
rate_limit 1000 1h 5m
# note the last 5m is the cleanup routine cycle to remove stale address from memoryBlock traffic from specific countries using ISO country codes:
# Block requests from Russia, China, and North Korea
block_countries /path/to/GeoLite2-Country.mmdb RU CN KPRules and blacklists can be updated without server restart:
- Modify
rules.jsonor blacklist files. - Reload Caddy:
caddy reload.
A test.sh script is included in this repository to perform a comprehensive security test suite. This script sends a series of forged curl requests, each designed to simulate a different type of attack.
caddy-waf % ./test.sh
WAF Security Test Suite
Target: http://localhost:8080
Date: Mar 7 Gen 2025 01:12:22 CET
----------------------------------------
[✗] SQL Injection - SQL Server Version [200]
[✗] SQL Injection - SQL Server Time Delay [200]
[✓] SQL Injection - Oracle Time Delay [403]
[✗] SQL Injection - Error Based 1 [200]
[✗] SQL Injection - Error Based 2 [200]
[✗] SQL Injection - Error Based 3 [200]
[✗] SQL Injection - MySQL user [200]
[✗] SQL Injection - PostgreSQL user [200]
[✗] SQL Injection - Case Variation [200]
[✗] SQL Injection - Whitespace Variation [200]
[✗] SQL Injection - Obfuscation Variation [200]
[✗] SQL Injection - Unicode Variation [200]
[✗] SQL Injection - Triple URL Encoded Variation [200]
[✗] SQL Injection - OOB DNS Lookup [200]
[✗] SQL Injection - Oracle OOB DNS Lookup [200]
[✓] SQL Injection - Header - Basic Select [403]
[✓] SQL Injection - Cookie - Basic Select [403]
[✗] SQL Injection - Header - Basic Select [200]
[✗] SQL Injection - JSON body [200]
[✓] XSS - Basic Script Tag [403]
[✓] XSS - IMG Onerror [403]
[✓] XSS - JavaScript Protocol [403]
[✓] XSS - SVG Onload [403]
[✓] XSS - Anchor Tag JavaScript [403]
[✓] XSS - URL Encoded Script [403]
[✓] XSS - Double URL Encoded [403]
[✓] XSS - URL Encoded IMG [403]
[✓] XSS - Body Onload [403]
[✓] XSS - Input Onfocus Autofocus [403]
[✓] XSS - Breaking Out of Attribute [403]
[✓] XSS - HTML Encoded [403]
[✓] XSS - IFRAME srcdoc [403]
[✓] XSS - Details Tag [403]
[✓] XSS - HTML Comment Breakout [403]
[✓] Path Traversal - Basic [403]
[✓] Path Traversal - Double Dot [403]
[✓] Path Traversal - Triple Dot [403]
[✓] Path Traversal - URL Encoded [403]
[✗] Path Traversal - Double URL Encoded [200]
[✓] Path Traversal - Mixed Slashes [403]
[✗] Path Traversal - UTF-8 Encoded [200]
[✓] Path Traversal - Encoded and Literal [403]
[✓] Path Traversal - Mixed Encoding [403]
[✗] Path Traversal - Multiple Slashes [200]
[✓] RCE - Basic Command [403]
[✓] RCE - Base64 Command [403]
[✗] RCE - Backticks [200]
[✗] RCE - List Files [200]
[✗] RCE - Uname [200]
[✗] RCE - ID [200]
[✓] RCE - whoami Command [403]
[✓] RCE - Echo Test [403]
[✗] RCE - Hex Encoded Command [200]
[✓] RCE - Curl Request [403]
[✓] RCE - Wget Request [403]
[✗] RCE - Ping [200]
[✗] RCE - PowerShell Command [200]
[✗] Log4j - JNDI LDAP [200]
[✗] Log4j - Environment [200]
[✗] Log4j - JNDI RMI [200]
[✗] Log4j - System Property [200]
[✗] Log4j - Lowercase [200]
[✗] Log4j - Uppercase [200]
[✗] Log4j - Date [200]
[✓] Log4j - Base64 [403]
[✗] Log4j - Partial Lookup [200]
[✗] Log4j - URL Encoded [200]
[✓] Header - SQL Injection [403]
[✓] Header - XSS Cookie [403]
[✓] Header - Path Traversal [403]
[✓] Header - Custom X-Attack [403]
[✗] Header - X-Forwarded-Host [200]
[✓] Header - User-Agent SQL [403]
[✗] Header - Host Spoof [200]
[✓] Header - Accept-Language [403]
[✓] Protocol - Git Access [403]
[✓] Protocol - Env File [403]
[✓] Protocol - htaccess [403]
[✗] Protocol - Web.config Access [200]
[✓] Protocol - Java Web Descriptor [403]
[✓] Protocol - SVN Access [403]
[✗] Protocol - Robots.txt [200]
[✗] Protocol - VS Code Settings [200]
[✗] Protocol - config.php Access [200]
[✗] Protocol - Apache Server Status [200]
[✓] Valid - Homepage [200]
[✓] Valid - API Endpoint [200]
[✓] Scanner - SQLMap [403]
[✓] Scanner - Acunetix [403]
[✓] Scanner - Nikto [403]
[✓] Scanner - Nmap [403]
[✓] Scanner - Dirbuster [403]
[✓] Valid - Health Check [200]
[✓] Valid - Chrome Browser [200]
[✗] Scanner - Burp Suite [200]
[✓] Scanner - OWASP ZAP [403]
[✓] Scanner - Nessus [403]
[✓] Scanner - Qualys [403]
[✓] Scanner - Wfuzz [403]
[✓] Scanner - OpenVAS [403]
----------------------------------------
Results Summary
Total Tests: 100
Passed: 57
Failed: 43
Pass Percentage: 57%
Warning: Test pass percentage is below 90%. Review the failures!
Detailed results saved to: waf_test_results.logab -n 1000 -c 100 http://localhost:8080/A Dockerfile is included to simplify building a Docker image with the Caddy server and WAF middleware. Here's how to use it:
# Build the Docker image
docker build -t caddy-waf .
# Run the Docker container
docker run -p 8080:8080 caddy-wafThree Python scripts are provided in this repository to help automate the population of your rules and blacklists:
This script fetches the OWASP core rules and converts them into the JSON format required for the WAF rules.
python3 get_owasp_rules.pyThis script downloads the blacklisted IPs from several external sources.
python3 get_blacklisted_ip.pyThis script downloads blacklisted domains from various sources.
python3 get_blacklisted_dns.pyDid you know you can combine caddy-waf, caddy-mib, and caddy-mlf to create a robust multi-layered security solution for your web applications? By chaining these modules, you can leverage their unique features to provide comprehensive protection against web attacks, abusive behavior, and suspicious traffic patterns.
By chaining these modules, you can set up a flow where each layer contributes to filtering, banning, and analyzing traffic for maximum security:
| Module | Role in the Chain | Repository Link |
|---|---|---|
| caddy-waf | Acts as the first gate, inspecting and filtering malicious requests based on anomaly scores, rate limits, and blacklists. | GitHub: caddy-waf |
| caddy-mib | Handles IP banning for repeated errors, such as 404 or 500, to prevent brute force or abusive access attempts. | GitHub: caddy-mib |
| caddy-mlf | Provides an additional layer of protection by analyzing request attributes and marking/blocking suspicious traffic based on anomaly thresholds. | GitHub: caddy-mlf |
Here’s an example configuration to chain the modules:
- caddy-waf: Listens on
localhost:8080and forwards requests to caddy-mib. - caddy-mib: Listens on
localhost:8081and forwards requests to caddy-mlf. - caddy-mlf: Listens on
localhost:8082and returns a200 OKresponse for legitimate requests or forwards requests to your origin applications.
This project is licensed under the AGPLv3 License.
Contributions are welcome! Please open an issue or submit a pull request.
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}
