caddy-waf

What is caddy-waf

caddy-waf is a Caddy middleware module that adds web application firewall controls directly inside Caddy. It is designed to inspect traffic before it reaches your upstream app, so you can block suspicious requests without placing a sidecar or external security service in front of the server.

The module is focused on request filtering and observability rather than full application security management. Its documented capabilities include rule-based inspection, blacklist enforcement, geographic filtering, rate limiting, and metrics output in JSON.

Key features

caddy-waf centers on a few concrete controls that can be combined in one Caddy route:

• Regex rule engine: rules use Go's RE2 regular expressions, which gives linear-time matching and avoids catastrophic backtracking.
• Anomaly scoring: each rule carries a score, and a request is blocked once the total reaches the configured threshold.
• Four inspection phases: request headers, request body, response headers, and response body each have their own rule sets and target identifiers.
• Blacklists and geo controls: it supports IP and CIDR prefix-trie matching, exact DNS lookups, MaxMind-based country and ASN checks, and a periodically refreshed Tor exit-node list.
• Rate limiting: per-IP sliding-window limiting is available, and it can be scoped to specific paths with regular expressions.
• Observability: it exposes a JSON metrics endpoint and includes an async log worker with sensitive-data redaction.
• Hot reload support: file watchers track rule files and the blacklists, with a documented reload matrix that clarifies what updates automatically and what still needs a Caddy reload.

How to use it

A typical setup places the waf handler inside a route block before reverse_proxy.

1. Build or install the module into Caddy.
   • The project documents xcaddy build --with github.com/fabriziosalmi/caddy-waf.
   • It also documents a published container image at ghcr.io/fabriziosalmi/caddy-waf:0.4.14.
   • A one-off install via caddy add-package github.com/fabriziosalmi/caddy-waf is mentioned, but the docs warn not to rely on that path for deployment planning.
2. Add the handler to your Caddyfile.
   • The minimal example sets rule_file, ip_blacklist_file, dns_blacklist_file, anomaly_threshold, and metrics_endpoint.
3. Define rules and lists.
   • Rules live in JSON, and the bundled default rule file is rules.json.
   • IP and DNS blacklist files are supported separately.
4. Tune thresholds and limits.
   • Adjust the anomaly threshold to decide how quickly accumulated rule scores trigger a block.
   • Add a rate limit block if you want per-IP sliding windows on specific paths.
5. Read the metrics and logs.
   • Use the JSON metrics endpoint for machine-readable status.
   • The documentation also shows how to bridge metrics into Prometheus, Grafana, or ELK.

Who it is for

caddy-waf fits operators who already run Caddy and want embedded request filtering rather than an external WAF appliance. It is useful for:

• small teams that want a security layer inside their web server configuration;
• site operators who need regex-driven detection with scoring instead of only allow/deny lists;
• deployments that want IP, DNS, ASN, or country controls alongside app routing;
• people who prefer Caddy modules and Caddyfile-based configuration over a separate security stack.

It is also a fit for users who want measurable protection without sending traffic through another hosted service.

What to know before you use it

caddy-waf is powerful, but it is not a substitute for every kind of security control. A few practical limits are documented or implied by the project:

• The rule engine uses RE2, so patterns must be compatible with Go's regex engine; features from other regex dialects may not behave the same way.
• Country and ASN decisions depend on MaxMind data, so geoblocking accuracy is only as good as the database and your update process.
• DNS blacklists rely on exact-match lookups, which means they are not a general reputation system.
• The Tor exit-node list is refreshed periodically, but the docs do not imply real-time threat intelligence coverage.
• File watchers cover certain rule and blacklist changes, yet the reload matrix explicitly notes that some changes still require a Caddy reload.
• The project documents metrics and logging, but not every downstream exporter or dashboard is built in; Prometheus, Grafana, and ELK examples are provided as guidance.
• For compliance, incident response, or authoritative security verification, use the official Caddy module docs, release notes, and security advisories rather than relying only on this directory summary.

For teams running Caddy in production, caddy-waf can be a practical web application firewall layer, but it should be validated against your own traffic, rule set, and operational requirements before you depend on it for blocking decisions.