How to Set Up CrowdSec for Server Security

Last updated: March 22, 2026

CrowdSec is a modern, open-source intrusion prevention system that learns from attacks across thousands of deployments. When one node gets attacked, the offending IP is shared with the community and blocked everywhere. This guide covers installing the CrowdSec agent, connecting bouncers to actually block traffic, and tuning scenarios for a typical web server.

How CrowdSec Works

CrowdSec has two components:

Agent. reads log files, runs scenarios, raises “alerts” when thresholds are met
Bouncer. sits at the firewall or application layer and enforces the block list

The agent never blocks anything itself. You can have multiple bouncers. firewall, Nginx, Traefik. each enforcing the same decisions.

Install CrowdSec Agent

Add repository and install
curl -s https://install.crowdsec.net | sudo bash
sudo apt install -y crowdsec

Verify
sudo cscli version
sudo systemctl status crowdsec

CrowdSec auto-detects running services (SSH, Nginx, Apache, MySQL) and installs relevant parsers and scenarios automatically.

Review Auto-Detected Configuration

See what collections were installed
sudo cscli collections list

See active parsers
sudo cscli parsers list

See active scenarios (detection logic)
sudo cscli scenarios list

See where CrowdSec is reading logs from
sudo cat /etc/crowdsec/acquis.yaml

A typical acquis.yaml entry:

filenames:
  - /var/log/auth.log
labels:
  type: syslog
---
filenames:
  - /var/log/nginx/access.log
labels:
  type: nginx

Add More Log Sources

If CrowdSec missed a log file, add it:

sudo tee -a /etc/crowdsec/acquis.yaml > /dev/null <<'EOF'
---
filenames:
  - /var/log/nginx/error.log
labels:
  type: nginx
---
filenames:
  - /var/log/postgresql/postgresql-*.log
labels:
  type: postgresql
EOF

sudo systemctl restart crowdsec

Install Collections for Your Services

Collections bundle parsers + scenarios for a specific service:

Common collections
sudo cscli collections install crowdsecurity/nginx
sudo cscli collections install crowdsecurity/sshd
sudo cscli collections install crowdsecurity/linux
sudo cscli collections install crowdsecurity/http-cve          # CVE scanner detection
sudo cscli collections install crowdsecurity/wordpress         # if running WP
sudo cscli collections install crowdsecurity/postfix           # if running mail

Reload after installing collections
sudo systemctl reload crowdsec

Install the firewall Bouncer

The firewall bouncer translates CrowdSec decisions into nftables or iptables rules:

sudo apt install -y crowdsec-firewall-bouncer-nftables

Connect to the local agent (auto-configures on install)
sudo systemctl enable --now crowdsec-firewall-bouncer

Verify the bouncer registered
sudo cscli bouncers list

Test it’s working:

Manually add a test ban
sudo cscli decisions add --ip 198.51.100.1 --reason "test ban" --duration 5m

Check it appears in nftables
sudo nft list table ip crowdsec

Remove test ban
sudo cscli decisions delete --ip 198.51.100.1

Install the Nginx Bouncer (Optional, Deeper Inspection)

The Nginx bouncer blocks at the application layer before requests hit your app. useful for rate limiting per-endpoint:

sudo apt install -y crowdsec-nginx-bouncer

Edit /etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf
Set api_url = http://127.0.0.1:8080 and api_key (generated automatically)

Add to nginx.conf in the http block:
lua_package_path '/usr/lib/crowdsec/lua/?.lua;;';
lua_shared_dict crowdsec_cache 50m;
init_by_lua_block { require "crowdsec" }

sudo systemctl restart nginx

Monitor Decisions in Real Time

Watch live alerts as they fire
sudo cscli alerts list --limit 20

Watch decisions (actual blocks)
sudo cscli decisions list

Filter by scenario
sudo cscli alerts list --scenario crowdsecurity/ssh-bf

See current banned IPs with reason
sudo cscli decisions list -o human

Sample output:

 ID  Scope:Value        Reason                          ActionCountry

 101 Ip:203.0.113.5     crowdsecurity/ssh-bf            ban   CN     
 102 Ip:198.51.100.22   crowdsecurity/nginx-req-limit-ipban   RU     

Write a Custom Scenario

CrowdSec scenarios are YAML files. Here’s one that fires when an IP hits 404 errors more than 15 times in 30 seconds (scanner detection):

/etc/crowdsec/scenarios/custom-404-scan.yaml
type: leaky
name: custom/http-404-scan
description: "Detect HTTP 404 scanners"
filter: "evt.Meta.http_status == '404'"
groupby: "evt.Meta.source_ip"
capacity: 15
leakspeed: "30s"
blackhole: 5m
labels:
  service: http
  type: scan
  remediation: true

sudo cscli scenarios install --file /etc/crowdsec/scenarios/custom-404-scan.yaml
sudo systemctl reload crowdsec

Enroll with the CrowdSec Console (Optional)

The cloud console gives you a dashboard and access to the community block list (CTI feed):

Get your enrollment key from app.crowdsec.net
sudo cscli console enroll <your-enrollment-key>
sudo systemctl restart crowdsec

This unlocks the "blocklist mirror". subscribe to curated IP lists
(premium) or use the free community decisions

Even without enrollment, CrowdSec pulls a community blocklist of known scanners and attackers via the API on startup.

Notifications and Alerting

Configure Slack or email notifications
sudo cscli notifications install crowdsecurity/slack

Edit /etc/crowdsec/notifications/slack.yaml
Set webhook_url and min_severity (default: alert)

Test notification
sudo cscli notifications test slack

Assign notification to a profile
Edit /etc/crowdsec/profiles.yaml. add 'notifications: [slack]' under relevant profile
sudo systemctl reload crowdsec

Tuning False Positives

Check the simulation mode. preview what decisions WOULD be made without banning
sudo cscli simulation enable crowdsecurity/nginx-req-limit-ip
sudo cscli simulation status

Whitelist your own IP to avoid locking yourself out
sudo tee /etc/crowdsec/parsers/s02-enrich/whitelist.yaml > /dev/null <<'EOF'
name: my/whitelist
description: "Whitelist office and monitoring IPs"
whitelist:
  reason: "Internal IPs"
  ip:
    - "203.0.113.10"
    - "10.0.0.0/8"
EOF

sudo systemctl reload crowdsec

Metrics

Show agent metrics - alerts fired, scenarios triggered
sudo cscli metrics

Prometheus endpoint (if enabled in config.yaml)
metrics_addr: 127.0.0.1:6060
curl http://127.0.0.1:6060/metrics | grep crowdsec