✕   

Drop-in Caddy reverse proxy with CrowdSec WAF protection

中文文档

---

A pre-compiled Caddy Docker image shipping the following modules:

Module	Purpose
caddy-crowdsec-bouncer (http/appsec/layer4)	Block malicious IPs using CrowdSec reputation data
caddy-l4	TCP/UDP Layer 4 proxying
transform-encoder	Custom log output formatting

Paired with docker-compose.yml, spin up a full Caddy + CrowdSec protection stack in one command.

.
├── Dockerfile                    # Multi-stage: xcaddy build → slim runtime
├── docker-compose.yml            # Caddy + CrowdSec orchestration
├── .env.example                  # Environment variable template
├── config/
│   ├── caddy/
│   │   └── Caddyfile             # Caddy config (bouncer example included)
│   └── crowdsec/
│       └── acquis.yaml           # CrowdSec log acquisition config
├── LICENSE
├── CONTRIBUTING.md
└── README_en.md

Internet ──▶ Caddy (:80/:443) ──▶ CrowdSec LAPI lookup
                │                       │
                │  IP clean ─────────▶  proxy to upstream
                │  IP malicious ─────▶  403 Forbidden
                │
                └──▶ access logs ──▶ CrowdSec Agent ──▶ update decisions

Pre-built images support linux/amd64 and linux/arm64:

docker.cnb.cool/hakurei/caddy-crowdsec-bouncer

Tag	Caddy Version	Notes
latest / 2	Caddy 2.x latest	Recommended
2.11	Caddy 2.11.x	Current stable

Note: caddy-l4 module requires Caddy >= 2.11, so images for 2.10 and earlier are not provided.

# Pull latest
docker pull docker.cnb.cool/hakurei/caddy-crowdsec-bouncer:latest

# Pull specific version
docker pull docker.cnb.cool/hakurei/caddy-crowdsec-bouncer:2.11

# ARM devices (Raspberry Pi, Apple Silicon) auto-pull arm64
docker pull docker.cnb.cool/hakurei/caddy-crowdsec-bouncer:latest

# 1. Copy env template
cp .env.example .env

# 2. Tweak the Caddyfile to your needs
vim config/caddy/Caddyfile

# 3. Bring it up
docker compose up -d

# 4. Register the bouncer & grab the API key
docker compose exec crowdsec cscli bouncers add caddy-bouncer
# Paste the key into .env as CROWDSEC_BOUNCER_API_KEY

# 5. Restart caddy to pick up the key
docker compose restart caddy

First run note: CrowdSec will pull collections (crowdsecurity/caddy, crowdsecurity/http-cve, crowdsecurity/base-http-scenarios) on first boot — allow ~30 s for initialization.

Variable	Default	Description
CADDY_VERSION	2	Caddy base image tag
CROWDSEC_BOUNCER_API_KEY	—	Bouncer API key (required)
CROWDSEC_LAPI_URL	http://crowdsec:8080	CrowdSec LAPI endpoint
CADDY_HTTP_PORT	80	Published HTTP port
CADDY_HTTPS_PORT	443	Published HTTPS port

Located at config/caddy/Caddyfile. Key snippet:

{
    order crowdsec first
    order appsec after crowdsec

    crowdsec {
        api_url {$CROWDSEC_LAPI_URL}
        api_key {$CROWDSEC_BOUNCER_API_KEY}
        ticker_interval 15s
        appsec_url http://crowdsec:7422   # Uncomment to enable AppSec
    }
}

example.com {
    route {
        crowdsec   # Layer 1: IP reputation blocking
        appsec     # Layer 2: AppSec WAF deep inspection
        reverse_proxy localhost:8080
    }
    log {
        output file /var/log/caddy/access.log
        format json
    }
}

⚠️ Log format must be format json. CrowdSec's caddy-logs parser only supports JSON-formatted logs. Using transform-encoder or other custom formats will cause logs to be unparsed, and CrowdSec will not detect any attacks.

Full syntax: Caddyfile docs · bouncer options

config/crowdsec/acquis.yaml tells CrowdSec which logs to analyze:

filenames:
  - /var/log/caddy/access.log
labels:
  type: caddy

Persistent data (decision DB, hub items) lives in Docker volumes — safe across container recreates.

AppSec inspects request content for attacks (SQL injection, XSS, known CVE exploits, etc.) — a second defense layer on top of IP reputation blocking.

docker compose exec crowdsec cscli collections install crowdsecurity/appsec-virtual-patching
docker compose exec crowdsec cscli collections install crowdsecurity/appsec-generic-rules

Append to config/crowdsec/acquis.yaml:

---
listen_addr: 0.0.0.0:7422
appsec_config: crowdsecurity/appsec-default
name: appsec
source: appsec
labels:
  type: appsec

Add appsec_url to the global block and appsec directive to your site:

{
    order crowdsec first
    order appsec after crowdsec

    crowdsec {
        api_url {$CROWDSEC_LAPI_URL}
        api_key {$CROWDSEC_BOUNCER_API_KEY}
        appsec_url http://crowdsec:7422
    }
}

example.com {
    route {
        crowdsec
        appsec
        reverse_proxy localhost:8080
    }
}

docker compose restart crowdsec
docker compose restart caddy

# Normal request should return 200
curl http://your-server/

# CVE exploit should return 403
curl http://your-server/vendor/phpunit/phpunit/src/Util/PHP/eval-stdin.php

# Check AppSec metrics
docker compose exec crowdsec cscli metrics show appsec

# Default
docker build -t caddy-crowdsec-bouncer .

# Pin Caddy version
docker build --build-arg CADDY_VERSION=2.9 -t caddy-crowdsec-bouncer .

Need extra modules? Append --with lines to xcaddy build in the Dockerfile.

Already running CrowdSec elsewhere? Skip the compose CrowdSec service:

docker run -d \
  -p 80:80 -p 443:443 \
  -v ./config/caddy/Caddyfile:/etc/caddy/Caddyfile \
  -e CROWDSEC_LAPI_URL=http://your-crowdsec:8080 \
  -e CROWDSEC_BOUNCER_API_KEY=<your-key> \
  caddy-crowdsec-bouncer

CrowdSec Console is the official web management platform for monitoring alerts, managing blocklists, and pushing rules to your instances.

Sign up at https://app.crowdsec.net/ and log in.

Go to Security Engines → Add Security Engine to generate an enrollment key.

docker compose exec crowdsec cscli console enroll <your-enrollment-key>

Back on the Console, find the new engine in the Security Engines list and click Accept.

docker compose restart crowdsec

Once enrolled, the Console gives you:

• 📊 Instance overview — engine version, online status, installed scenarios/parsers
• 🚨 Alerts & decisions — blocked IPs and triggered scenarios
• 📋 Blocklist management — subscribe to community or custom blocklists, auto-synced to your instance
• 🖥️ Multi-instance management — unified view across all your nodes

# List active bans
docker compose exec crowdsec cscli decisions list

# List registered bouncers
docker compose exec crowdsec cscli bouncers list

# Manually ban an IP (for testing)
docker compose exec crowdsec cscli decisions add -i 1.2.3.4 -d 10m -t ban

# Tail logs
docker compose logs -f caddy
docker compose logs -f crowdsec

PRs and issues welcome! See CONTRIBUTING.md.

MIT

• Caddy · CrowdSec · caddy-crowdsec-bouncer · caddy-l4 · transform-encoder