580132/caddy-cloudflare-crowdsec repository overview

⁠🐳 caddy-cloudflare-crowdsec

The Caddy⁠ Docker image with the added

• caddy-dns/cloudflare⁠ module for DNS-01 ACME validation support
• CrowdSec bouncers⁠ (HTTP, AppSec and Layer 4) for blocking malicious traffic based on decisions made by CrowdSec⁠
• caddy-l4⁠ and transform-encoder⁠

Built for the same platforms as the upstream Caddy project (except Windows, sorry)!

# Docker Hub
docker pull 580132/caddy-cloudflare-crowdsec:latest

# GHCR
docker pull ghcr.io/580132/caddy-cloudflare-crowdsec:latest

⁠Tags

The following tags are the latest available for the 580132/caddy-cloudflare-crowdsec image.

• latest⁠
• 2.11.7⁠
• 2.11⁠
• 2⁠

Check the GitHub Tags⁠ for a list of all versions!

⁠Usage

⁠Docker

Since this is built off the official Docker image all of the same Volumes, Environment variables, etc. can be used with this container. Please refer to the official Caddy⁠ Docker image and docs⁠ for more information on using Caddy.

Simply create the container as usual and include your CF_API_TOKEN (email no longer required for API Tokens). We can utilize Caddy's support for Environment varaiables⁠ to pass these values into our Caddyfile.

docker run --rm -it \
  --name caddy \
  -p 80:80 \
  -p 443:443 \
  -v caddy_data:/data \
  -v caddy_config:/config \
  -v $PWD/Caddyfile:/etc/caddy/Caddyfile \
  -e CF_API_TOKEN=UhKLc...JD9jk \
  580132/caddy-cloudflare-crowdsec:latest

If you prefer docker-compose you can use the provided docker-compose.yml⁠ after updating it with your CF_API_TOKEN.

docker compose up

⁠Caddy

Set the global acme_dns⁠ directive in your Caddyfile

{
  acme_dns cloudflare {env.CF_API_TOKEN}
}

or via JSON

{
  "module": "acme",
  "challenges": {
    "dns": {
      "provider": {
        "name": "cloudflare",
        "api_token": "{env.CF_API_TOKEN}"
      }
    }
  }
}

See the caddy-dns/cloudflare⁠ module and tls⁠ directive for advanced usage.

⁠CrowdSec

The image bundles the CrowdSec bouncer for Caddy⁠, which blocks malicious traffic based on the decisions made by your CrowdSec⁠ Security Engine.

All three share a single Caddy app, so the Local API credentials only have to be configured once in the global options.

⁠Enabling the bouncer

Declare the crowdsec global option, then use the crowdsec directive in your site block:

{
  crowdsec {
    api_url http://crowdsec:8080
    api_key {env.CROWD_SEC_API_KEY}
    ticker_interval 15s
  }
}

example.com {
  route {
    crowdsec
    reverse_proxy localhost:3000
  }
}

The api_key is the value of a bouncer registered on your CrowdSec instance:

docker exec crowdsec cscli bouncers add caddy-bouncer

⁠Configuration options

⁠AppSec

If you run a CrowdSec AppSec⁠ component, point the bouncer at it and add the appsec directive:

{
  crowdsec {
    api_url http://crowdsec:8080
    api_key {env.CROWD_SEC_API_KEY}
    appsec_url http://crowdsec-appsec:7422
  }
}

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

⁠Layer 4

The Layer 4 matcher blocks TCP and UDP traffic by IP address, using the caddy-l4⁠ app:

{
  crowdsec {
    api_url http://crowdsec:8080
    api_key {env.CROWD_SEC_API_KEY}
  }

  layer4 {
    :443 {
      @crowdsec crowdsec
      route @crowdsec {
        proxy {
          upstream localhost:8443
        }
      }
    }
  }
}

⁠Client IP

The bouncer relies on Caddy's native client IP detection. Caddy uses the X-Forwarded-For header by default, so if you run behind a proxy or CDN you must configure the trusted_proxies⁠ global directive, otherwise every request will be checked against the proxy's IP address.

{
  trusted_proxies static private_ranges
}

⁠Blocked request details

The HTTP and AppSec handlers record why a request was blocked, so matchers and logs can tell blocks apart:

handle_errors {
  log_append blocked-by {http.vars.crowdsec.module}
}

⁠Runtime utilities

Building Caddy with the bouncer also enables the caddy crowdsec command, which talks to the Caddy Admin API to inspect the integration:

caddy crowdsec health    # check the integration health
caddy crowdsec info      # show runtime information
caddy crowdsec ping      # ping the Local API endpoint
caddy crowdsec check <IP> # check whether an IP is banned

⁠Creating a Cloudflare API Token

You can generate a Cloudflare API token via the Cloudflare web console using the following steps:

1. Login to your Dashboard⁠
2. Go to Account Profile⁠ > API Tokens⁠
3. Click "Create token" (Use the "Create Custom Token" option)
4. Grant the following permissions:
   • Zone > Zone > Read
   • Zone > DNS > Edit

⁠Building

You can easily build the Docker image locally by doing

docker build -t caddy-cloudflare-crowdsec .

If you prefer docker-compose you can use the provided docker-compose.yml⁠ for building

docker compose build

⁠Container signatures

All container images will be automatically signed via Cosign⁠ using keyless signatures⁠. You can use the following command to verify the integrity of these images yourself.

cosign verify \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp https://github.com/580132/caddy-cloudflare-crowdsec/.github/workflows/ \
  580132/caddy-cloudflare-crowdsec:latest

⁠Contributing

Feel free to contribute and make things better by opening an Issue⁠ or Pull Request⁠.

⁠License

See LICENSE⁠.