How to Install CrowdSec as a Community WAF

Actualizado: 2026-05-03

CrowdSec^[1] is the modern evolution of fail2ban with a very different approach: it decouples detection from blocking, exposes an API, and leverages a blocklist fed by thousands of voluntary installations around the world. After several years of active development, it is a mature tool that deserves a spot in any administrator’s toolkit for internet-facing services. This guide walks through installation and Traefik integration with emphasis on understanding why each piece exists, not just copying commands.

Key takeaways

• CrowdSec separates detection (agent + LAPI) from blocking (bouncers): the same decision source can feed an HTTP bouncer in Traefik and a network bouncer in iptables simultaneously.
• Acquisition is the most often forgotten step: telling the agent which logs to read, with correct labels, is critical.
• Captcha remediation (Cloudflare Turnstile) is smarter than direct banning for brute-force scenarios.
• The community blocklist blocks hundreds of known IPs before they reach you.
• On a hobby VPS, fail2ban is still simpler; CrowdSec pays from the moment you have multiple layers to protect.

Why the switch from fail2ban is worth it

The most important difference is architectural. fail2ban reads logs, decides, and runs an iptables rule in the same process. CrowdSec separates those responsibilities:

• The agent reads logs and emits decisions to the LAPI (a local REST API).
• Bouncers query the LAPI and execute the blocking.

This separation has important consequences. You can have a bouncer on the firewall for SSH, another on Traefik for HTTP, and both act on the same decisions. You change detection without touching blocking. And if you decide to contribute your detections to the community, you receive in return an updated list of IPs currently attacking others.

The second difference is expressiveness. fail2ban uses regex over log lines; CrowdSec uses declarative YAML scenarios combining detection, capacity, time window and grouping. Writing a scenario for a new pattern is a fifteen-minute exercise.

Installing the agent

On Debian or Ubuntu:

curl -s https://install.crowdsec.net | sudo sh
sudo apt install crowdsec

The agent and LAPI run in the same process, listening on localhost. sudo cscli version and sudo systemctl status crowdsec confirm everything started.

Collections: work saved from day one

A collection bundles parsers (how to read a specific log format) and scenarios (attack patterns) for a specific technology. For a typical stack with Traefik, WordPress and Gitea:

sudo cscli collections install crowdsecurity/traefik
sudo cscli collections install crowdsecurity/wordpress
sudo cscli collections install crowdsecurity/gitea

Each collection brings what you need: the WordPress one detects login brute force, user scanning and access to sensitive paths like wp-config.php. Within a few days you will have reviewed which ones fire on your real traffic.

Telling the agent what to read

This is the most often forgotten step. Configuration goes in /etc/crowdsec/acquis.yaml. For a setup with Traefik in Docker and SSH via systemd:

- filenames:
    - /var/log/traefik/access.log
  labels:
    type: traefik
- source: journald
  journalctl_filter:
    - "_SYSTEMD_UNIT=sshd.service"
  labels:
    type: syslog

The type label is not arbitrary: parsers filter by it. If you put type: traefik-access when the parser expects type: traefik, nothing will be detected and there will be no explicit error. This is the most common mistake among new users. After editing: sudo systemctl restart crowdsec. Within minutes, sudo cscli metrics should show lines being processed.

Diagnosis: what to look at in the first days

Three commands that should become routine:

• sudo cscli alerts list: triggered alerts (detections).
• sudo cscli decisions list: active decisions (IPs currently blocked or under captcha).
• sudo cscli metrics: detection rate, cache hits, general state.

If you have been running 24 hours and none of these shows activity, your acquisition is almost certainly not reading what you think.

Bouncers: from detection to effective blocking

CrowdSec detects, but does not block anything yet. You need at least one bouncer. For Traefik, the official plugin is maxlerebourg/crowdsec-bouncer-traefik-plugin.

It is declared in Traefik’s static configuration as an experimental plugin and in dynamic config as a middleware. The plugin queries the LAPI in stream mode (caches decisions, refreshes every few seconds), keeping perceived latency at zero.

Generate the bouncer API key:

sudo cscli bouncers add traefik-bouncer

Copy the token shown once and put it in the middleware configuration.

For SSH, add the firewall bouncer:

sudo apt install crowdsec-firewall-bouncer-iptables

It configures itself. You now have two bouncers sharing the same decision source.

Captcha remediation: not everything is a ban

The classic WAF mistake is banning everything suspicious and discovering a week later you were blocking legitimate customers. CrowdSec allows captcha-type decisions instead of ban. The Traefik bouncer knows how to interpret them: it shows a Cloudflare Turnstile challenge instead of cutting off.

The pattern that works well in production:

• Brute force (someone trying passwords) → captcha. The legitimate user solves it and moves on.
• Known exploits (CVEs, sensitive path access) → direct ban. An exploit bot does not solve captchas.

Turnstile integration only requires two keys (site key and secret key) from the Cloudflare panel, both free with no practical limits for normal use.

The real value of the community blocklist

Registering your installation with the central CAPI (sudo cscli capi register) puts you in the community network. You start receiving an updated list of IPs currently attacking others, and contribute (anonymising) your own. The impact is clearly measurable: review your metrics before and after enabling CAPI and you will see how noise from typical endpoint-access attempts drops.

Ethical nuance: sharing detections contributes to collective defence, but you are also sending information about your traffic. For most installations the trade-off is acceptable; for environments with strict privacy requirements, read the terms before enabling.

Monitoring

CrowdSec exposes Prometheus metrics on a local HTTP endpoint. Useful metrics:

• cs_bucket_overflow_count: accumulated detections.
• cs_active_decisions: currently blocked IPs.

There is an official Grafana dashboard ready to use. The most important alert is not a detection spike (can be noisy) but absence of metrics for more than five minutes: signal that the agent stopped or acquisition broke.

Whitelists and common mistakes

Before blocking anything seriously, make sure your own IPs are whitelisted: your office, the VPN you use, CI/CD deployments, external uptime monitors. This goes in /etc/crowdsec/parsers/s02-enrich/whitelists.yaml and accepts individual IPs and CIDR ranges. The number of admins who have blocked themselves in the first hours exceeds the number of real attackers they frustrated that same day.

Another frequent mistake: not restarting the agent after editing configuration. CrowdSec does not hot-reload most files; a systemctl restart crowdsec after editing is basic discipline.

When CrowdSec does not pay off

Scenarios where fail2ban is still simpler and more appropriate:

• Single server with low traffic and no need to share intelligence between nodes.
• No Traefik (no HTTP plugin) and no multiple layers to protect.

CrowdSec starts paying when you have more than one layer (web + SSH + specific applications), when the community blocklist cuts significant noise, or when you want to integrate with Ansible for centralised whitelist and configuration management.

My recommendation

If you are going to try it, progressive rollout:

1. Install the agent, configure acquisition, and leave it a week in detection-only mode with no bouncer.
2. Review what fires, tune scenarios if noisy, add whitelists for legitimate IPs.
3. Only then activate the first bouncer (Traefik).
4. Wait another week, add captcha remediation for brute force.
5. Finally, connect to CAPI.

Reaching this maturity level takes two or three weeks of living with it. The investment is reasonable for any stack with serious internet exposure.

1. CrowdSec