A Caddy module that blocks malicious traffic based on decisions made by CrowdSec.

• CrowdSec Bouncer for Caddy
  • Table of Contents
  • Description
    • What is CrowdSec?
  • Usage
    • Option 1: Docker Build
    • Option 2: Custom Go Build (xcaddy)
    • Configuration
  • Demo
  • Utilities
    • Usage
  • Client IP
  • Things That Can Be Done
    • Contributing

The Caddy CrowdSec Bouncer consists of five components:

• Caddy App: Responsible for communicating with CrowdSec via the Local API and keeping track of its decisions. It supports both StreamBouncer (HTTP polling) and LiveBouncer (a request is made on every incoming connection).
• Bouncer HTTP Handler: Checks client IPs of incoming HTTP requests against the decisions stored by the App. Multiple independent HTTP Handlers and Connection Matchers can share the storage exposed by the App.
• Layer 4 Connection Matcher: Matches TCP and UDP IP addresses against the CrowdSec Local API. Uses the Caddy Layer 4 app.
• AppSec HTTP Handler: Communicates with an AppSec component configured on your CrowdSec deployment, seamlessly checking incoming HTTP requests against configured rulesets.
• caddy crowdsec Command: Offers useful Caddy CLI commands for your CrowdSec integration.

CrowdSec is a free and open source security automation tool that uses local logs and a set of scenarios to infer malicious intent. In addition to operating locally, an optional community integration is also available, through which crowd-sourced IP reputation lists are distributed.

The architecture of CrowdSec is very modular. At its core is the CrowdSec Security Engine, which keeps track of all data and related systems. Bouncers are pieces of software that perform specific actions based on the decisions of the Security Engine.

[!TIP] You can find full setup examples in /examples inside this repository.

You can use the bouncer by either building a custom Caddy image with Docker or by fetching the required Go modules directly into your own build.

Note: You will need a recent version of Caddy (v2.7.3+) and Go (1.20+).

To include the bouncer in a Docker Image using xcaddy. Create a Dockerfile:

1ARG CADDY_VERSION=2
2
3FROM caddy:${CADDY_VERSION}-builder-alpine AS builder
4
5RUN xcaddy build \
6    --with github.com/mholt/caddy-l4 \
7    --with github.com/caddyserver/transform-encoder \
8    --with github.com/hslatman/caddy-crowdsec-bouncer/http@main \
9    --with github.com/hslatman/caddy-crowdsec-bouncer/appsec@main \
10    --with github.com/hslatman/caddy-crowdsec-bouncer/layer4@main
11
12FROM caddy:${CADDY_VERSION}
13
14COPY --from=builder /usr/bin/caddy /usr/bin/caddy

If you are compiling outside of Docker, you can fetch the modules using go get:

1# get the CrowdSec Bouncer HTTP handler
2go get github.com/hslatman/caddy-crowdsec-bouncer/http
3
4# get the CrowdSec layer4 connection matcher (only required for TCP/UDP level blocking)
5go get github.com/hslatman/caddy-crowdsec-bouncer/layer4
6
7# get the AppSec HTTP handler (only required for CrowdSec AppSec support)
8go get github.com/hslatman/caddy-crowdsec-bouncer/appsec

Configuration using a Caddyfile is supported for HTTP handlers and Layer 4 matchers.

1{
2  debug
3
4  crowdsec {
5    api_url http://localhost:8080
6    api_key <api_key>
7    ticker_interval 15s
8    appsec_url http://localhost:7422
9    #disable_streaming
10    #enable_hard_fails
11    #enable_caddy_error
12  }
13
14  layer4 {
15    localhost:4444 {
16      @crowdsec crowdsec
17      route @crowdsec {
18        proxy {
19          upstream localhost:6443
20        }
21      }
22    }
23  }
24}
25
26localhost:8443 {
27  route {
28    crowdsec
29    respond "Allowed by Bouncer!"
30  }
31}
32
33localhost:7443 {
34  route {
35    appsec
36    respond "Allowed by AppSec!"
37  }
38}
39
40localhost:6443 {
41  route {
42    crowdsec
43    appsec
44    respond "Allowed by Bouncer and AppSec!"
45  }
46}

Run the Caddy server

1# with a Caddyfile
2caddy run --config Caddyfile 

This repository also contains an example using Docker inside the examples/demo folder. Steps to run this demo are as follows:

1# run CrowdSec container
2docker compose up -d crowdsec
3
4# add the Caddy bouncer, generating an API key
5docker compose exec crowdsec cscli bouncers add caddy-bouncer
6
7# copy and paste the API key in the ./examples/demo/config.json file
8
9# run Caddy; at first run a custom build will be created using xcaddy
10docker compose up -d caddy
11
12# tail the logs
13docker compose logs -tf

You can then access https://localhost:9443 and https://localhost:8443. The latter is an example of using the Layer 4 App and will simply proxy to port 9443 in this case.

When Caddy is built with this module enabled, a new caddy crowdsec command will be enabled. Its subcommands allow you to interact with your CrowdSec integration at runtime using Caddy's Admin API. This is useful to verify the status of your integration, and check if it's configured and working properly. The command requires the Admin API to be reachable from the system it is run from.

Support for the command is currently experimental, and will be improved and extended in future releases. Output of the commands should not be relied upon in automated processes (yet).

1$ caddy crowdsec
2
3Commands related to the CrowdSec integration (experimental)
4
5Usage:
6  caddy crowdsec [command]
7
8Available Commands:
9  check       Checks an IP to be banned or not
10  health      Checks CrowdSec integration health
11  info        Shows CrowdSec runtime information
12  ping        Pings the CrowdSec LAPI endpoint
13
14Flags:
15  -a, --adapter string   Name of config adapter to apply (when --config is used)
16      --address string   The address to use to reach the admin API endpoint, if not the default
17  -c, --config string    Configuration file to use to parse the admin address, if --address is not used
18  -h, --help             help for crowdsec
19  -v, --version          version for crowdsec
20
21Use "caddy crowdsec [command] --help" for more information about a command.
22
23Full documentation is available at:
24https://caddyserver.com/docs/command-line

When your Caddy server is deployed behind a proxy (like a CDN or load balancer), the actual client IP is masked. Starting with v0.3.1, this module relies on Caddy's native logic (introduced in Caddy v2.7.0 via caddy#5104) to determine the correct client IP before checking it against CrowdSec decisions.

Important: Caddy uses the X-Forwarded-For header by default. To trust this header, you must configure the trusted_proxies global directive in your Caddyfile.

You can override the default header using the client_ip_headers directive.

Note: For Caddy versions up to v2.4.6 and older versions of this module, the realip module is required.

• Add integration tests for the HTTP and L4 handlers
• Implement tests for IPv6 support
• Validate project conncept (Caddy layer 4 app: TCP working, UDP needs testing)
• Add support for captcha actions
• Implement support for custom actions (currently defaults to block)
• Integrate with Caddy metrics
• Integrate with Caddy profiling
• Implement caching for the LiveBouncer

...and more things to come!

We are always open to contributions! Whether it's fixing bugs, improving documentation, or adding new features from the Roadmap above, your help is welcome. Feel free to open an issue or submit a pull request.