CrowdSec
CrowdSec reads Traefik’s access logs, detects abusive behavior (such as scans, brute-force attempts, and known exploit probes), and bans the offending IPs. It also uses CrowdSec’s community blocklist. The bans are enforced inside Traefik by the CrowdSec bouncer plugin, so a banned IP gets a 403 Forbidden on every app that it reaches through Traefik. See What CrowdSec does not cover.
It works the same way with Caddy instead of Traefik, see CrowdSec with Caddy.
CrowdSec is most useful when some of your apps are reachable from the internet (expose_to_public in the Container Map).
Enable crowdsec in the Container Map and run the playbook. Traefik (or Caddy) must also be enabled. No other settings are required. With Traefik, the playbook will:
- Run the CrowdSec container with the Traefik collection, reading the
traefikcontainer’s logs - Generate a bouncer API key and register it with CrowdSec
- Install the bouncer plugin in Traefik and apply it to the
webandwebsecureentrypoints (ports80and443), so every route through those ports is covered - Turn on Traefik access logs, which CrowdSec needs
The playbook downloads the plugin from GitHub into <hmsdocker_apps_path>/crowdsec/bouncer-plugin/ (once per version), and Traefik loads it from there. Traefik does not use the Traefik plugin catalog, so it starts without internet access.
When you enable CrowdSec on a server where Traefik is already running, the playbook first recreates Traefik with the plugin, then adds the bouncer to its config and restarts Traefik at the end of the run. If the run stops before that, Traefik keeps working without the bouncer, and the next run adds it.
Settings
Section titled “Settings”These are in inventory/group_vars/all/crowdsec.yml:
| Variable | Default | Description |
|---|---|---|
hmsdocker_crowdsec_enroll_key |
"" |
Optional. Enrollment key from the CrowdSec Console to see alerts and manage the instance there. |
hmsdocker_crowdsec_bouncer_plugin_version |
v1.8.2 |
Version (release tag) of the Traefik bouncer plugin. |
hmsdocker_crowdsec_caddy_bouncer_version |
v0.15.0 |
Version (release tag) of the Caddy bouncer module. |
If a proxy such as a load balancer sits in front of Traefik, add it to hmsdocker_proxy_trusted_proxies (see Proxies in front of Traefik). Otherwise Traefik’s access log, which CrowdSec reads, and the bouncer both see the proxy’s IP instead of the client’s, and a ban would block the proxy.
How it works
Section titled “How it works”- CrowdSec reads the
traefikcontainer’s logs through the Docker API. With the Docker Socket Proxy enabled, it gets a filtered socket that can only list containers and read their details, events and logs. Without it, the Docker socket is mounted read-only, which does not limit the Docker API. - The bouncer runs in stream mode: Traefik pulls the list of banned IPs from CrowdSec every 60 seconds and checks requests locally, so it adds no delay to requests.
- The bouncer never blocks clients in
hmsdocker_proxy_allow_list(by default the Docker network and the private ranges10.0.0.0/8,172.16.0.0/12,192.168.0.0/16), even if they are banned. This keeps the apps and dashboards reachable from your LAN if CrowdSec bans a local device by mistake. CrowdSec’s defaultcrowdsecurity/whitelistsparser also keeps private ranges from being banned in the first place. - If CrowdSec can’t be reached (while it restarts, is updated by Watchtower, or has crashed), the bouncer lets all traffic through instead of blocking it, and keeps using the last list of bans it received. Blocking resumes once CrowdSec is back. Traefik logs
crowdsecQuery:unreachableerrors in the meantime. - Disabling
crowdsecremoves the bouncer from Traefik on the next playbook run. The middleware file is removed after Traefik has restarted, so routes keep working throughout. - After re-enabling,
cscli bouncers listmay show an extratraefik@<ip>entry. This is the same bouncer reconnecting from a new container IP and can be ignored, or removed withcscli bouncers delete. - The bouncer API key is stored in
<hmsdocker_apps_path>/crowdsec/.bouncer_key. If you delete that file, the next playbook run generates a new key and replaces the old one in CrowdSec. The playbook keeps a hash of the registered key in.bouncer_key_registerednext to it, so this also works if a run stops partway. - Traefik’s access log includes the full URL of every request, so tokens that apps put in URLs (such as Plex’s
X-Plex-Tokenor anapikeyparameter) are written to Traefik’s container logs (docker logs traefik), which CrowdSec reads.
CrowdSec with Caddy
Section titled “CrowdSec with Caddy”With caddy enabled instead of traefik, everything above applies, with these differences:
- CrowdSec reads the
caddycontainer’s logs, with thecrowdsecurity/caddycollection, and the bouncer is registered ascaddy - The Caddy bouncer module is built into the Caddy image, together with the DNS provider module (the first build takes a few minutes). Caddy does not download anything when it starts
- Every route Caddy serves runs the bouncer first, before the IP allowlist and the sign-ins: the routes of all containers, the external hosts, and your own
*.caddysites thatimport hmsd_crowdsec(see Adding other Containers to Caddy) - Caddy’s access logs are turned on
The bouncer pulls the banned IPs every 60 seconds, never blocks clients in hmsdocker_proxy_allow_list, and lets traffic through while CrowdSec can’t be reached, like the Traefik plugin. Caddy also starts and reloads while CrowdSec is down. hmsdocker_proxy_trusted_proxies applies to Caddy as well. Caddy reads the client IP from the right end of X-Forwarded-For and skips the trusted proxies, so a client cannot hide behind an X-Forwarded-For value it sends itself.
When you switch between Traefik and Caddy, the playbook reads the logs of the new proxy, replaces the bouncer registration in CrowdSec, and removes the old one.
Caddy logs layer4.matchers.crowdsec module is not available when it starts. That module is only for TCP/UDP traffic, which this project doesn’t route through Caddy, so the warning can be ignored.
What CrowdSec does not cover
Section titled “What CrowdSec does not cover”The bouncer only runs on Traefik’s web and websecure entrypoints (ports 80 and 443). Traffic that reaches an app any other way is not checked:
- Cloudflare Tunnel, which connects
cloudflaredstraight to the container without going through Traefik. - Host ports opened with
expose_portsin the Container Map or withhmsdocker_container_expose_ports. - Traefik’s own dashboard on port
8080. It is published whenhmsdocker_proxy_security_hardeningis off (the default) and Traefik’s ports are exposed, and it has no authentication in that case. Enablehmsdocker_proxy_security_hardening, or don’t expose Traefik’s ports, if the server can be reached from the internet. - Clients that connect over IPv6. The project’s Docker network is IPv4-only, so Docker forwards IPv6 connections to Traefik through its userland proxy, and Traefik sees the Docker network’s gateway as the client. That address is normally in
hmsdocker_proxy_allow_list, so the bouncer never blocks it and CrowdSec never bans it. If the server has a public IPv6 address (for example withhmsdocker_cloudflare_ddns_create_ipv6_aaaa_recordenabled), block incoming IPv6 traffic to ports80and443on your router or firewall.
CrowdSec also only detects attacks in Traefik’s access logs, so it doesn’t see traffic that skips Traefik either.
Useful commands
Section titled “Useful commands”# Show active banssudo docker exec crowdsec cscli decisions list
# Ban an IP for 10 minutes (for testing, use an IP outside hmsdocker_proxy_allow_list), then remove the bansudo docker exec crowdsec cscli decisions add --ip 203.0.113.10 -d 10msudo docker exec crowdsec cscli decisions delete --ip 203.0.113.10
# Check that the Traefik logs are being read and parsedsudo docker exec crowdsec cscli metrics show acquisition parsers
# Check that the Traefik bouncer is registered and pulling decisionssudo docker exec crowdsec cscli bouncers list