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

The Caddy CrowdSec Bouncer consists of the following five main pieces:

• A Caddy App
• A Caddy Bouncer HTTP Handler
• A Caddy Layer 4 Connection Matcher
• A Caddy AppSec HTTP Handler
• The caddy crowdsec command

The App is responsible for communicating with a CrowdSec Agent via the CrowdSec Local API and keeping track of the decisions of the Agent. The Bouncer HTTP Handler checks client IPs of incoming requests against the decisions stored by the App. This way, multiple independent HTTP Handlers and Connection Matchers can use the storage exposed by the App. The App can be configured to use either the StreamBouncer, which gets decisions via a HTTP polling mechanism, or the LiveBouncer, which sends a request on every incoming HTTP request or Layer 4 connection setup. The Layer 4 Connection Matcher matches TCP and UDP IP addresses against the CrowdSec Local API. The AppSec HTTP Handler communicates with an AppSec component configured on your CrowdSec deployment, and will check incoming HTTP requests against the rulesets configured. Finally, the caddy crowdsec command offers some useful commands for you 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 Agent, which keeps track of all data and related systems. Bouncers are pieces of software that perform specific actions based on the decisions of the Agent.

Get the module

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 if you need support for TCP/UDP level blocking)
5go get github.com/hslatman/caddy-crowdsec-bouncer/layer4
6
7# get the AppSec HTTP handler (only required if you want CrowdSec AppSec support)
8go get github.com/hslatman/caddy-crowdsec-bouncer/appsec

Create a (custom) Caddy server (or use xcaddy)

1package main
2
3import (
4  cmd "github.com/caddyserver/caddy/v2/cmd"
5  _ "github.com/caddyserver/caddy/v2/modules/standard"
6  // import the bouncer HTTP handler
7  _ "github.com/hslatman/caddy-crowdsec-bouncer/http"
8  // import the layer4 matcher (in case you want to block connections to layer4 servers using CrowdSec)
9  _ "github.com/hslatman/caddy-crowdsec-bouncer/layer4"
10  // import the appsec HTTP handler (in case you want to block requests using the CrowdSec AppSec component)
11  _ "github.com/hslatman/caddy-crowdsec-bouncer/appsec"
12)
13
14func main() {
15  cmd.Main()
16}

Configuration using a Caddyfile is supported for HTTP handlers and Layer 4 matchers. You'll also need to use a recent version of Caddy (i.e. 2.7.3 and newer) and Go 1.20 (or newer).

Example Caddyfile:

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  }
12
13  layer4 {
14    localhost:4444 {
15      @crowdsec crowdsec
16      route @crowdsec {
17        proxy {
18          upstream localhost:6443
19        }
20      }
21    }
22  }
23}
24
25localhost:8443 {
26  route {
27    crowdsec
28    respond "Allowed by Bouncer!"
29  }
30}
31
32localhost:7443 {
33  route {
34    appsec
35    respond "Allowed by AppSec!"
36  }
37}
38
39localhost:6443 {
40  route {
41    crowdsec
42    appsec
43    respond "Allowed by Bouncer and AppSec!"
44  }
45}

Run the Caddy server

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

This repository also contains an example using Docker. Steps to run this demo are as follows:

1# run CrowdSec container
2$ docker compose up -d crowdsec
3
4# add the Caddy bouncer, generating an API key
5$ docker compose exec crowdsec cscli bouncers add caddy-bouncer
6
7# copy and paste the API key in the ./docker/config.json file
8# below is the git diff after changing the appropriate line:
9$ git diff
10
11- "api_key": "<api_key>",
12+ "api_key": "9e4ac94cf9aebaa3625a1d51951230a9",
13
14# run Caddy; at first run a custom build will be created using xcaddy
15$ docker compose up -d caddy
16
17# tail the logs
18$ docker 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

If your Caddy server with this bouncer is deployed behind a proxy, a CDN or another system fronting the web server, the IP of the client requesting a resource is masked by the system that sits between the client and your server. Starting with v0.3.1, the HTTP handler relies on Caddy to determine the actual client IP of the system performing the HTTP request. The new logic was implemented as part of caddy#5104, and released with Caddy v2.7.0. The IP that Caddy determines is used to check against the CrowdSec decisions to see if it's allowed in or not.

Caddy determines the actual client IP from the X-Forwarded-For header by default, but it is possible to change this using the client_ip_headers directive in the global settings. The setting depends on the trusted_proxies directive to be set, so that the IP reported in the X-Forwarded-For (or one of the headers you configure as override) can be trusted.

For older versions of this Caddy module, and for older versions of Caddy (up to v2.4.6), the realip module can be used instead.

• Add integration tests for the HTTP and L4 handlers
• Tests with IPv6
• Test with project conncept (Caddy layer 4 app; TCP seems to work; UDP to be tested)
• Add captcha action (currently works the same as a ban)?
• Add support for custom actions (defaults to blocking access now)?
• Add Caddy metrics integration?
• Add Caddy profiling integration?
• Caching the LiveBouncer (for the duration of the decision)?
• ...