CrowdSec

Overview

CrowdSec has two halves. The Security Engine reads logs (and, with the AppSec component, live HTTP requests), matches them against scenarios from the Hub and records decisions such as "ban 203.0.113.50 for 4h". A Remediation Component (called a bouncer) fetches those decisions from the Local API and enforces them in a firewall, reverse proxy or CDN. The engine alone blocks nothing. Signals you report feed a community blocklist that is pushed back to all users. Current release is v1.8.1 (September 2026). Docs: https://docs.crowdsec.net.

Instructions

Step 1: Install the engine

On Debian or Ubuntu add the CrowdSec package repository by hand (the one-line installer from the docs pipes a script into a shell; the manual route is the same repo):

sudo apt update && sudo apt install -y curl gnupg apt-transport-https
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://packagecloud.io/crowdsec/crowdsec/gpgkey | sudo gpg --dearmor -o /etc/apt/keyrings/crowdsec_crowdsec-archive-keyring.gpg
printf 'deb [signed-by=/etc/apt/keyrings/crowdsec_crowdsec-archive-keyring.gpg] https://packagecloud.io/crowdsec/crowdsec/any any main\n' | sudo tee /etc/apt/sources.list.d/crowdsec_crowdsec.list
sudo apt update && sudo apt install -y crowdsec

RHEL-family systems use the crowdsec_crowdsec.repo file shown on the Linux installation page, then sudo yum install crowdsec. Since 1.7 the installer detects running services (sshd, nginx, ...) and enables matching collections and log sources on its own.

Step 2: Check what it watches

sudo cscli metrics show acquisition   # log sources, lines read / parsed
sudo cscli collections list           # installed parsers + scenarios
sudo cscli collections install crowdsecurity/nginx crowdsecurity/http-cve
sudo systemctl reload crowdsec        # after any config or collection change

If a log lives in a custom path, add a file under /etc/crowdsec/acquis.d/ with filenames: and labels: {type: nginx}. Test a parser without waiting for an attack: sudo cscli explain --log 'Oct 3 10:01:02 web01 sshd[2345]: Failed password for root from 203.0.113.50 port 4242 ssh2' --type syslog or --file access.log --type nginx.

Step 3: Add a remediation component

Pick the one that matches where you want to block:

sudo apt install crowdsec-firewall-bouncer-nftables   # or ...-iptables; run `iptables -V`, "nf_tables" means nftables
sudo apt install crowdsec-nginx-bouncer               # Lua bouncer for nginx, supports captcha and AppSec

On the same machine the package registers itself with the Local API. For a remote bouncer create a key with sudo cscli bouncers add edge-firewall (shown once), then set api_url and api_key in its YAML (firewall: /etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml). Other components: Traefik, OpenResty, HAProxy SPOA, Cloudflare, AWS WAF, Fastly, WordPress.

Step 4: Operate

sudo cscli decisions list                                   # active bans
sudo cscli alerts list                                      # detections
sudo cscli decisions add --ip 203.0.113.50 --duration 24h --reason "manual block"
sudo cscli decisions delete --ip 203.0.113.50
sudo cscli allowlists create office --description "Office IPs"   # then: cscli allowlists add office 198.51.100.7
sudo cscli hub update && sudo cscli hub upgrade             # refresh scenarios
sudo cscli bouncers list                                    # is the bouncer pulling?

Step 5: Docker

# compose.yaml
services:
  crowdsec:
    image: crowdsecurity/crowdsec:latest
    restart: always
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      COLLECTIONS: "crowdsecurity/nginx crowdsecurity/http-cve"
      BOUNCER_KEY_firewall: ${CROWDSEC_FIREWALL_KEY}
      TZ: Europe/Berlin
    volumes:
      - ./acquis.yaml:/etc/crowdsec/acquis.yaml
      - /var/log/nginx:/var/log/nginx:ro
      - crowdsec-db:/var/lib/crowdsec/data
      - crowdsec-config:/etc/crowdsec
volumes:
  crowdsec-db:
  crowdsec-config:

BOUNCER_KEY_<name> seeds a bouncer key at first start; generate it with openssl rand -hex 24 and keep it in .env. The compose file does not start a bouncer: install one on the host (Step 3, api_url: http://127.0.0.1:8080/) or use the Traefik plugin.

Examples

Example 1: Stop SSH brute force on an Ubuntu VPS

User request: "Bots hammer my SSH port with passwords, ban them automatically"

sudo apt install -y crowdsec crowdsec-firewall-bouncer-nftables   # repo from Step 1
sudo cscli collections install crowdsecurity/sshd
sudo systemctl reload crowdsec
sudo cscli explain --log 'Oct  3 10:01:02 web01 sshd[2345]: Failed password for root from 203.0.113.50 port 4242 ssh2' --type syslog

Result: cscli explain shows sshd-logs parsed (green) and the crowdsecurity/ssh-bf scenarios evaluated. After repeated failures sudo cscli decisions list shows Ip:203.0.113.50 ... ban, and sudo nft list ruleset contains a crowdsec-blacklists set with that address.

Example 2: Run the engine in Docker next to nginx

User request: "Put CrowdSec in my docker-compose stack and ban IPs that scan my site"

Save the Step 5 file next to an acquis.yaml containing filenames: [/var/log/nginx/access.log] and labels: {type: nginx}, then:

echo "CROWDSEC_FIREWALL_KEY=$(openssl rand -hex 24)" > .env
docker compose up -d
docker compose exec crowdsec cscli metrics show acquisition

Result: the acquisition table lists file:/var/log/nginx/access.log with growing "Lines parsed". Without the /var/lib/crowdsec/data volume the container refuses to start with No volume mounted for /var/lib/crowdsec/data.

Guidelines

• Detection and blocking are separate: always confirm with cscli bouncers list that a bouncer has a recent "Last API pull".
• Persist /var/lib/crowdsec/data (mandatory since 1.7) and /etc/crowdsec in containers; mount logs read-only.
• Do not publish the Local API (port 8080) on a public address; bind it to 127.0.0.1 or a private network.
• Add your own IPs to an allowlist before testing bans so you do not lock yourself out; private LAN ranges are allowed by default.
• A firewall bouncer protects ports and services (SSH, SMTP); for web apps add a WAF-capable bouncer (nginx, OpenResty, Traefik) and the AppSec component, built on Coraza with OWASP CRS support.
• The Console (https://app.crowdsec.net, cscli console enroll) is optional and needs an account; the engine runs without it.
• Not suited to hosts without readable logs, or where you cannot install a bouncer at any layer.