Caddy WAF | Developmi

Hardened Caddy web server distribution with Coraza WAF and OWASP CRS v4 - tested with 122 integration cases, signed supply chain (Cosign/SLSA), and safe DetectionOnly staged rollout.

Curated by Miguel Lozano • GitHub • Container Registry

• Overview
• Quick Start
• Architecture
• Configuration Guide
• Docker Deployment
• Testing & Validation
• Monitoring & Observability
• Operations Documentation
• Security
• Changelog
• Contributing
• License
• Contact & Support

Problem: Deploying a web application firewall typically requires weeks of tuning, dedicated appliances, and specialized security expertise. Most WAF solutions block legitimate traffic on day one, disrupting your users and forcing you to disable protections you just deployed.

This project solves that. It packages Caddy - the web server with automatic TLS - with Coraza WAF and the OWASP Core Rule Set into a single hardened container. The WAF defaults to DetectionOnly mode, giving you a safe observation window before enforcement. It comes preconfigured with OWASP CRS v4.29.0 covering SQL injection, XSS, command injection, and OWASP Top 10 vectors across 12 rule families - allowing you to baseline legitimate application traffic and tune exclusions during observation before enforcing active blocking.

Starting from v3.0.0, the image ships with updated Caddy 2.11.4, official upstream rate limiting and DNS plugins, and native security header support - giving the project full control over maintenance cadence, security patches, and feature development.

• Non-root execution: Runs as caddy user (UID 1337) - no root privileges
• Supply chain security: Pinned versions, SHA256 verification of OWASP CRS rules, Cosign-signed images, SBOM attestations
• Multi-stage builds: Minimal attack surface, optimized layers
• Health monitoring: Process verification healthcheck at both image and compose level
• Structured logging: JSON logs for SIEM integration

• Coraza WAF v2.6.1: Modern, high-performance web application firewall engine
• OWASP CRS v4.29.0: Core Rule Set covering SQLi, XSS, RCE, and protocol violations across 12 rule families
• DetectionOnly by default: Mitigates false-positive operational risk during initial rollout
• Audit logging: JSON audit logs to stdout for easy monitoring
• Rate limiting: Built-in rate limiting via mholt/caddy-ratelimit
• Security headers: Automated security header injection via Caddy's native header directive

• Optimized Alpine base: Small footprint (~45MB compressed)
• TLS by default: Automatic Let's Encrypt integration
• Multi-architecture: Supports linux/amd64 and linux/arm64
• Cloud-native: Perfect for Kubernetes, Docker Swarm, and standalone Docker
• Bare-metal ready: Systemd service file included for non-containerized deployments

• Docker 24.x+ and Docker Compose v2.x+

docker pull ghcr.io/developmi/caddy-waf:v3.5.5

cp .env.example .env
# Edit .env with your domain/backend/image values

cp Caddyfile.example Caddyfile
# Edit Caddyfile for your domain and upstreams

docker build -t your-registry/your-caddy-waf:custom \
  --build-arg CORAZA_CADDY_REF=v2.6.1 \
  --build-arg CADDY_RATELIMIT_REF=5625512 \
  --build-arg CADDY_DNS_CLOUDFLARE_REF=v0.2.4 \
  .

Then set CADDY_WAF_IMAGE=your-registry/your-caddy-waf:custom in .env.

{
    order coraza_waf first
}

yourdomain.com {
    respond "Caddy with Coraza WAF is running" 200
}

docker compose up -d

caddy-waf/
├── assets/                   # Brand assets (logo)
├── deploy/
│   └── systemd/              # Systemd service unit for bare-metal
├── docs/                     # Operations docs (deployment, IR, compliance)
├── .github/workflows/        # CI/CD (build, scan, sign, push)
├── metrics/                  # Backend-agnostic Prometheus scrape config
├── grafana/                  # Provisioned datasources + dashboards
├── Dockerfile                # Multi-stage build with pinned plugins
├── docker-compose.yml        # Production-grade compose with security hardening
├── Caddyfile                 # Runtime configuration - untracked, generated from Caddyfile.example (WAF + TLS + reverse proxy)
├── Caddyfile.example         # Templated configuration with 5 deployment examples
├── .env.example              # Environment variable template (3 groups)
├── TUNING.md                 # WAF tuning guide per application type
├── ROADMAP.md                # Planned enhancements and compliance roadmap
├── CHANGELOG.md              # Version history (Keep a Changelog)
├── CONTRIBUTING.md           # Contribution guidelines
├── SECURITY.md               # Vulnerability disclosure policy
└── LICENSE                   # MIT License

flowchart LR
    Client[Client] -->|HTTPS :443| Caddy[Caddy v2.11.4]
    Caddy -->|WAF layer| Coraza[Coraza WAF v2.6.1]
    Coraza -->|OWASP CRS v4.29.0| Rules[CRS v4 Rules]
    Coraza -->|Decision| Action{Allow?}
    Action -->|Yes| Backend[Upstream Backend]
    Action -->|No| Block[Block + Audit Log]
    Block -->|JSON| SIEM[SIEM / Log Aggregator]
    Caddy -->|Auto TLS| LE[Let's Encrypt]

The WAF operates in three modes (configured in Caddyfile):

1. DetectionOnly (Default): Logs attacks without blocking - perfect for initial deployment
2. On: Active protection - blocks malicious requests
3. Off: Disables WAF completely

Recommended rollout: Keep SecRuleEngine DetectionOnly for a 7–14 day observation window. Review audit logs, tune CRS exclusions, then switch to SecRuleEngine On only after establishing a stable false-positive baseline.

{
    email [email protected]
    order coraza_waf first

    # JSON logging for observability
    log {
        output stdout
        format json
    }
}

(waf) {
    coraza_waf {
        directives `
            Include /etc/caddy/coraza.conf
            Include /etc/caddy/owasp-crs/crs-setup.conf
            Include /etc/caddy/owasp-crs/rules/*.conf

            # Start with DetectionOnly, change to On after tuning
            SecRuleEngine DetectionOnly

            # Audit logging
            SecAuditEngine RelevantOnly
            SecAuditLog /dev/stdout
            SecAuditLogFormat JSON
        `
    }
}

# Your site configuration
example.com {
    import waf
    reverse_proxy backend:8080
}

For detailed WAF tuning, rule exceptions, and performance optimization, see the complete TUNING GUIDE.

Project roadmap and planned security integrations are tracked in ROADMAP.md.

Mount your custom rules directory:

volumes:
  - ./custom-crs:/etc/caddy/owasp-crs

• github.com/corazawaf/coraza-caddy/[email protected] - Coraza WAF integration
• github.com/mholt/[email protected] - Rate limiting (DDoS protection)

Note: caddy-ratelimit development is active but releases are not tagged beyond v0.1.0. This image pins the module by commit SHA (5625512) to include post-tag fixes. See Dockerfile for the pinned reference.

• github.com/caddy-dns/[email protected] - Cloudflare DNS for ACME challenges

Security headers are handled via Caddy's native header directive - no external plugin needed.

# Start with example backend
cp .env.example .env
cp Caddyfile.example Caddyfile
docker compose up -d

docker build \
  --build-arg CORAZA_CADDY_REF=v2.6.1 \
  --build-arg CADDY_RATELIMIT_REF=5625512 \
  --build-arg CADDY_DNS_CLOUDFLARE_REF=v0.2.4 \
  -t caddy-waf:custom .

The unit runs on the host network namespace, so it uses the zero-trust config deploy/systemd/Caddyfile.systemd - the admin API is bound to loopback only (admin localhost:2019). Never use 0.0.0.0:2019 on a host network: the admin API accepts config POSTs.

Prerequisite: caddy binary with Coraza and /etc/caddy/coraza.conf + /etc/caddy/owasp-crs installed on the host (see pre-flight checklist in docs/deployment-checklist.md).

sudo cp deploy/systemd/caddy-waf.service /etc/systemd/system/
sudo useradd -r -s /usr/sbin/nologin caddy-waf
sudo install -D -o caddy-waf -g caddy-waf -m 0640 deploy/systemd/Caddyfile.systemd /etc/caddy/Caddyfile
sudo -u caddy-waf caddy validate --config /etc/caddy/Caddyfile
sudo systemctl daemon-reload
sudo systemctl enable --now caddy-waf

Verify the image signature before pulling in production:

cosign verify \
  --certificate-identity "https://github.com/developmi/caddy-waf/.github/workflows/docker-build-scan-sign.yml@refs/heads/main" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  ghcr.io/developmi/caddy-waf@sha256:<digest>

Tip: Use immutable image digests (@sha256:...) instead of version tags in production for deterministic deployments.

# Check container health
docker ps --filter "name=caddy-waf"

# View logs
docker logs caddy-waf

# Test WAF is working
curl -I https://yourdomain.com

# Scan image with Trivy
docker run --rm aquasec/trivy image ghcr.io/developmi/caddy-waf:v3.5.5

# Scan with Docker Scout
docker scout quickview ghcr.io/developmi/caddy-waf:v3.5.5

The WAF and perimeter defenses are rigorously verified using the go-ftw framework and automated HTTP assertion gates across 122 automated integration tests structured under Screaming Architecture:

# General test suite (runs all linters + 122 WAF tests + live security headers + bare-boot regression)
make test

# Granular suites (run in milliseconds for fast feedback loops)
make test-waf        # Runs all 122 integration tests + live security header verification
make test-baseline   # Runs 00-baseline (12 tests: clean traffic + false-positive resilience)
make test-evasion    # Runs 01-evasion (6 tests: double-encoding, fullwidth, bypass vectors)
make test-hardening  # Runs 02-hardening (10 tests: .env, .git, .aws, Docker, .sql, .bak + headers)
make test-crs        # Runs crs/ (94 tests across all 12 OWASP CRS v4.29.0 rule families)
make test-suite SUITE=crs/942-attack-sqli  # Target any specific family or subdirectory
make test-boot       # Runs bare-boot regression gate (proves baked container boots as UID 1337)

{
  "level": "info",
  "ts": 1678901234.567,
  "logger": "http.log.access",
  "msg": "handled request",
  "request": {
    "method": "GET",
    "uri": "/test",
    "proto": "HTTP/2",
    "remote_ip": "192.168.1.100"
  },
  "waf_action": "detected",
  "waf_rule_id": "941100"
}

The Caddy admin endpoint (:2019/metrics) exposes real Prometheus metrics:

• caddy_http_requests_total - Total requests (labels: server, handler, method)
• caddy_http_request_duration_seconds - Request latency histogram (labels include code)
• caddy_http_requests_in_flight - Concurrent requests gauge
• caddy_reverse_proxy_upstreams_healthy - Backend upstream health (0/1)
• caddy_config_last_reload_successful - Config reload status

Note: coraza-caddy (up to v2.6.1) does not export coraza_waf_* metrics (upstream limitation tracked in coraza-caddy#82). WAF rule IDs and decisions are available in the JSON audit log on stdout, not on /metrics.

Dual-backend observability: the same metrics/prometheus.yml scrape config works with both VictoriaMetrics and Prometheus (identical Prometheus exposition format), so Caddy's /metrics output needs no changes. Pick one profile:

# VictoriaMetrics + Grafana (Grafana on http://localhost:3000)
docker compose --profile observability-vm up -d

# Prometheus + Grafana (Grafana on http://localhost:3001)
docker compose --profile observability-prom up -d

Profile services are not started by plain docker compose up - default behavior is unchanged. Grafana is bound to loopback only (127.0.0.1), with anonymous read access so the dashboard opens without login (admin UI: admin / admin, override with GRAFANA_ADMIN_USER / GRAFANA_ADMIN_PASSWORD).

• metrics/prometheus.yml - single canonical scrape config, mounted read-only: VictoriaMetrics consumes it via -promscrape.config, Prometheus via --config.file. Targets the internal caddy-waf:2019.
• Caddyfile.example exposes the admin endpoint (/metrics) on 0.0.0.0:2019 and enables caddy_http_* metric collection.
• Each profile provisions its own Grafana datasource (VictoriaMetrics or Prometheus) pointing at the backend, and loads the same dashboard (grafana/dashboards/caddy-waf.json): request rate, status codes, p95 latency, in-flight requests, backend health, throughput, request errors, plus a WAF mode note.

Port 2019 (Caddy admin API) is never published to the host - the admin API can accept config POSTs, so it stays strictly inside the internal Docker network. Scraping happens over the caddy-network bridge only. Backends (VictoriaMetrics:8428, Prometheus:9090) are also internal-only.

docker compose --profile observability-vm down -v
docker compose --profile observability-prom down -v

See TUNING.md for metric details.

Operational runbooks live in docs/:

This project follows a coordinated disclosure policy. If you discover a vulnerability, do not open a public issue. See SECURITY.md for:

• Supported versions
• Reporting instructions (GitHub Advisory + email)
• Response timelines (48h acknowledgment, 30-day fix target)
• Supply chain verification (Cosign + Trivy)

Security advisories and resolved CVEs are documented in SECURITY.md.

See CHANGELOG.md for the full version history. The project follows Keep a Changelog and Semantic Versioning.

Contributions are welcome. Please read CONTRIBUTING.md before opening a pull request. This project follows Conventional Commits and the Developmi engineering standard.

• Report a bug or request a feature: GitHub Issues
• Advanced configuration: TUNING.md
• Roadmap: ROADMAP.md

For commercial support, custom configurations, or security consulting:

• Website: developmi.com
• Email: [email protected]
• GitHub: developmi

Copyright © 2026 Miguel Lozano | Developmi. All rights reserved. Licensed under the MIT License.

• Caddy Server - Amazing web server with automatic HTTPS
• Coraza WAF - Open-source OWASP Coraza WAF engine
• OWASP Core Rule Set - Industry-standard protection rules
• Developmi - DevOps & Security consulting

Maintained by: Miguel Lozano | Developmi

• Role: Cloud & Infrastructure Engineer | FinOps & Bare Metal Specialist | AI Sovereignty Strategist under NIST/DORA Standards
• Philosophy: Security is not a feature; it is the baseline.
• Website: developmi.com
• GitHub: developmi
• LinkedIn: Miguel Lozano

© 2026 Miguel Lozano | Developmi. All rights reserved.