Skip to content

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:

  1. Run the CrowdSec container with the Traefik collection, reading the traefik container’s logs
  2. Generate a bouncer API key and register it with CrowdSec
  3. Install the bouncer plugin in Traefik and apply it to the web and websecure entrypoints (ports 80 and 443), so every route through those ports is covered
  4. 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.

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.

  • CrowdSec reads the traefik container’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 ranges 10.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 default crowdsecurity/whitelists parser 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:unreachable errors in the meantime.
  • Disabling crowdsec removes 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 list may show an extra traefik@<ip> entry. This is the same bouncer reconnecting from a new container IP and can be ignored, or removed with cscli 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_registered next 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-Token or an apikey parameter) are written to Traefik’s container logs (docker logs traefik), which CrowdSec reads.

With caddy enabled instead of traefik, everything above applies, with these differences:

  1. CrowdSec reads the caddy container’s logs, with the crowdsecurity/caddy collection, and the bouncer is registered as caddy
  2. 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
  3. 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 *.caddy sites that import hmsd_crowdsec (see Adding other Containers to Caddy)
  4. 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.

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 cloudflared straight to the container without going through Traefik.
  • Host ports opened with expose_ports in the Container Map or with hmsdocker_container_expose_ports.
  • Traefik’s own dashboard on port 8080. It is published when hmsdocker_proxy_security_hardening is off (the default) and Traefik’s ports are exposed, and it has no authentication in that case. Enable hmsdocker_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 with hmsdocker_cloudflare_ddns_create_ipv6_aaaa_record enabled), block incoming IPv6 traffic to ports 80 and 443 on your router or firewall.

CrowdSec also only detects attacks in Traefik’s access logs, so it doesn’t see traffic that skips Traefik either.

Terminal window
# Show active bans
sudo 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 ban
sudo docker exec crowdsec cscli decisions add --ip 203.0.113.10 -d 10m
sudo docker exec crowdsec cscli decisions delete --ip 203.0.113.10
# Check that the Traefik logs are being read and parsed
sudo docker exec crowdsec cscli metrics show acquisition parsers
# Check that the Traefik bouncer is registered and pulling decisions
sudo docker exec crowdsec cscli bouncers list