caddy-waf

Appearance

caddy-wafWeb Application Firewall for Caddy

Runs inside Caddy itself. No sidecar, no cloud service in the request path.

Get started
Configuration reference
caddy-waf

Rule engine

Regular expressions compiled by Go's RE2, so matching is linear-time with no catastrophic backtracking. Rules carry a score; a request is blocked once the total reaches the anomaly threshold.

Rule schema

Four inspection phases

Request headers, request body, response headers and response body, each with its own rule set and target identifiers.

Phases and directives

Blacklists and geo controls

IP and CIDR ranges in a prefix trie, exact-match DNS lookups, MaxMind country and ASN filtering, and a periodically refreshed Tor exit-node list.

File formats

Rate limiting

Per-IP sliding window, optionally scoped to specific paths with regular expressions.

Limiter behaviour

Observability

A JSON metrics endpoint, an async log worker with sensitive-data redaction, and worked examples for Prometheus, Grafana and ELK.

Metrics schema

Hot reload

File watchers on the rule files and both blacklists, with a documented matrix of what each reload covers and what still needs a caddy reload.

Reload matrix

Install ​

Build a Caddy binary with the module using xcaddy:

bash
xcaddy build --with github.com/fabriziosalmi/caddy-waf
./caddy list-modules | grep waf    # http.handlers.waf

Or run the published container image, which needs no Go toolchain:

bash
docker run --rm -p 8080:8080 ghcr.io/fabriziosalmi/caddy-waf:0.4.1

The module is also selectable on the Caddy download page, and caddy add-package github.com/fabriziosalmi/caddy-waf works for a one-off install — though Caddy's maintainers have proposed moving that command out of core, so do not build a deployment around it (#138).

See Installation for every supported path.

Minimal configuration ​

caddyfile
:8080 {
    route {
        waf {
            rule_file          rules.json
            ip_blacklist_file  ip_blacklist.txt
            dns_blacklist_file dns_blacklist.txt
            anomaly_threshold  20
            metrics_endpoint   /waf_metrics
        }
        reverse_proxy localhost:3000
    }
}

Reading order ​

A first-time reader is recommended to follow this sequence:

  1. Introduction — what the middleware does and where it fits.
  2. Installation — supported build paths and prerequisites.
  3. Configuration — the request lifecycle, every Caddyfile directive, every JSON-only field, blocking precedence.
  4. Rules — the JSON rule schema and target identifiers.
  5. Blacklists — file formats for IP and DNS blacklists.
  6. Rate limiting — sliding-window limiter, path matching.
  7. Country and ASN blocking — GeoIP / ASN behaviour.

Every page ​

DocumentTopic
introduction.mdWhat the middleware does and where it sits in the request pipeline.
installation.mdBuild with xcaddy, the install script, or from source.
add-package-guide.mdInstalling with caddy add-package.
docker.mdBuilding and running the supplied Dockerfile / docker-compose.yml.
configuration.mdCaddyfile directives, JSON fields, request phases, blocking precedence.
rules.mdrules.json schema, target identifiers, regex semantics.
blacklists.mdIP and DNS blacklist file formats.
ratelimit.mdThe rate_limit block and behaviour.
geoblocking.mdblock_countries, whitelist_countries, block_asns, fallback.
dynamicupdates.mdFile watchers, what each reload covers and what it does not.
metrics.mdThe /waf_metrics JSON document.
prometheus.mdA small exporter that scrapes the JSON metrics for Prometheus.
caddy-waf-elk.mdShipping the JSON log file to an ELK stack with Filebeat.
attacks.mdAttack categories targeted by the bundled rule sets.
testing.mdRunning test.py against a live WAF.
caddytest.mdTraffic generator for benchmarks and rule validation.
scripts.mdThe Python helpers under the project root.

Bundled rule files ​

  • rules.json — the default rule set wired into the supplied Caddyfile.
  • rules/ — modular rule files grouped by attack category. Each file is a JSON array of rules and can be referenced directly with one or more rule_file directives.

Security ​

Only the latest release receives security fixes. Published advisories are listed under Security → Advisories.

v0.3.3 and earlier are affected by GHSA-gfj3-cmff-q8wh, a high-severity unauthenticated denial of service. Fixed in v0.3.4.

To report a vulnerability, use private vulnerability reporting rather than a public issue.