CrowdSec

Last reviewed Aug 26, 2026 · 844 words

A freshly installed CrowdSec detects attacks and blocks nothing. That is not a bug; it is the architecture, and it is the single fact that trips up most first installs. The Security Engine reads logs, matches behaviour against scenarios from the hub, and writes a "decision" (ban this IP for 4 hours) into its local API. Something else, a bouncer, has to read those decisions and enforce them at the firewall or the proxy. Install the engine, forget the bouncer, and you get a very well-informed system that lets everyone in. Get both parts running and you have the best free replacement for fail2ban that exists, with 14,647 stars, MIT licensing, and about 256 MB of RAM in use.

Engine plus bouncer, always both

The engine ships as a Docker image (crowdsecurity/crowdsec) or a native package, and its config lives under /etc/crowdsec. Two files matter: acquis.yaml lists the log files or journald units to read, and the hub collections tell it what to look for. On a typical homelab box:

cscli collections install crowdsecurity/linux
cscli collections install crowdsecurity/sshd
cscli collections install crowdsecurity/traefik
cscli hub update && systemctl reload crowdsec
cscli metrics          # confirm lines are being parsed
cscli decisions list   # see what it has decided so far

If cscli metrics shows zero lines parsed for a source, the engine cannot see the log and nothing downstream will work. Fix that before anything else. In Docker, mount the host log directories read-only and set COLLECTIONS="crowdsecurity/linux crowdsecurity/traefik" in the environment to pull the same collections on start.

Pick the bouncer that matches your front door

Bouncers are separate installs, and the right one depends on where traffic enters. For a Linux host with SSH exposed, the firewall bouncer (crowdsec-firewall-bouncer-iptables or the nftables variant) adds banned IPs to a set and drops them before any service sees them. For web traffic behind Traefik, the community Traefik plugin runs inside the proxy and returns a 403 to banned addresses; behind Caddy there is a Caddy module that does the same. Each bouncer needs an API key from the engine:

cscli bouncers add traefik-bouncer

Paste the printed key into the bouncer's config, point it at the engine's local API on port 8080, and check cscli bouncers list shows it pulling decisions. I run the firewall bouncer on every host and a proxy bouncer only on the box terminating TLS; there is no harm in both, since the firewall one catches SSH scans that never reach the proxy.

The community blocklist is the part fail2ban cannot copy

Every engine that opts in reports the IPs it bans to CrowdSec's central API, and receives in return a blocklist of addresses currently attacking other members. On a fresh public IP I typically see the community list pre-emptively banning several hundred addresses before my own logs have caught a single one. That is the reason to choose CrowdSec over a simpler log-watcher, and the fail2ban versus CrowdSec comparison goes through what you trade for it. The trade is real: the engine phones home with ban data (source IP, scenario, timestamp), and you should read the data policy before enabling it. Turning it off keeps everything local and loses the shared list.

What costs money and what does not

The engine, hub scenarios, bouncers, and community blocklist are free. The web console at app.crowdsec.net, which shows alerts across your engines and offers curated premium blocklists, has a free tier limited to a few enrolled engines and paid tiers above that. A single homelab never needs the paid console; cscli alerts list and cscli decisions list show you the same data on the command line. Alerting out to a phone is done with a notification plugin (HTTP, Slack, email) configured in the engine's notifications directory.

Gotchas that bit me

Reverse proxies and CDNs hide the real client IP; if Traefik or Cloudflare sits in front, make sure the proxy logs the X-Forwarded-For address and the parser uses it, or you will ban your own proxy. Docker's default networking can present container traffic to the firewall bouncer from a bridge address, so test a ban against a phone on mobile data before trusting it. And whitelist your own networks in /etc/crowdsec/parsers/s02-enrich/ so a typo in a password does not lock you out of your own VPN; the reverse proxy showdown covers where the proxy fits in the whole chain.

What I'd do

Engine in Docker on the proxy host, linux plus sshd plus the collection for your proxy, community sharing on, firewall bouncer on every host, proxy bouncer on the one that terminates TLS. Verify with cscli metrics and a deliberate failed login from outside. Skip the paid console. That is an afternoon, and it turns your proxy layer from a door with a lock into one with a bouncer.