mirror of
https://github.com/fabriziosalmi/caddy-waf.git
synced 2026-07-30 14:25:56 -04:00
bb8fa2de56
The module was claimed on 2026-07-28 at v0.3.5, once the RegisterModule scan
fix landed. README.md, docs/installation.md and docs/add-package-guide.md all
still told users the install path did not exist and would return HTTP 400.
CADDY_MODULE_REGISTRATION.md keeps the root-cause writeup so the &Middleware{}
pattern is not reintroduced, and adds maintenance notes.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Caddy WAF — Documentation
A Web Application Firewall middleware for the Caddy web server.
- Module ID:
http.handlers.waf - Module type: HTTP handler middleware
- Go module path:
github.com/fabriziosalmi/caddy-waf - Latest version: see
caddywaf.go—const wafVersion
Reading order
A first-time reader is recommended to follow this sequence:
- Introduction — what the middleware does and where it fits.
- Installation — supported build paths and prerequisites.
- Configuration — the request lifecycle, every Caddyfile directive, every JSON-only field, blocking precedence.
- Rules — the JSON rule schema and target identifiers.
- Blacklists — file formats for IP and DNS blacklists.
- Rate limiting — sliding-window limiter, path matching.
- Country and ASN blocking — GeoIP / ASN behavior.
Reference
| Document | Topic |
|---|---|
| installation.md | Build with xcaddy, the install script, or from source. |
| configuration.md | Caddyfile directives, JSON fields, request phases, blocking precedence. |
| rules.md | rules.json schema, target identifiers, regex semantics. |
| blacklists.md | IP and DNS blacklist file formats. |
| ratelimit.md | The rate_limit block and behavior. |
| geoblocking.md | block_countries, whitelist_countries, block_asns, fallback. |
| attacks.md | Attack categories targeted by the bundled rule sets. |
| dynamicupdates.md | File watchers, what each reload covers and what it does not. |
| metrics.md | The /waf_metrics JSON document. |
| prometheus.md | A small exporter that scrapes the JSON metrics for Prometheus. |
| caddy-waf-elk.md | Shipping the JSON log file to an ELK stack with Filebeat. |
| scripts.md | The Python helpers under the project root. |
| testing.md | Running test.py against a live WAF. |
| caddytest.md | Traffic generator for benchmarks and rule validation. |
| docker.md | Building and running the supplied Dockerfile / docker-compose.yml. |
| add-package-guide.md | Installing with caddy add-package. |
Bundled rule files
rules.json— the default rule set wired into the suppliedCaddyfile.rules/— modular rule files grouped by attack category. Each file is a JSON array of rules and can be referenced directly with one or morerule_filedirectives.