CrowdSec Cheat Sheet

Overview

CrowdSec is a modern, open-source security engine that detects and blocks attacks by analyzing system logs and behavioral patterns. It is architecturally designed around two distinct components: the Security Engine (formerly the Agent), which reads logs and detects threats, and Bouncers, which enforce the decisions made by the engine. This separation allows flexible deployment — the engine can run on one machine while bouncers enforce blocks across multiple services, firewalls, or CDNs.

What makes CrowdSec distinctive is its crowdsourced threat intelligence model. When an attacker is detected by one CrowdSec instance, that IP is reported to the Central API (CAPI), aggregated across thousands of deployments, and optionally shared back as a community blocklist. This transforms every CrowdSec installation into a contributor and consumer of shared threat data, creating a real-time, community-maintained blocklist that grows more accurate as more users deploy it.

CrowdSec uses a layered detection system. Parsers normalize log lines from various sources (sshd, nginx, Apache, etc.) into a common format. Scenarios define sequences of events (e.g., five failed SSH logins in 30 seconds) that constitute an attack. Collections bundle parsers and scenarios together for easy deployment. Profiles determine what decision to apply (ban, captcha, throttle) when a scenario is triggered. This modular architecture means you can write custom parsers and scenarios for any log format and detection need.

Installation

Linux (Official Script)

# Install CrowdSec via official install script
curl -s https://install.crowdsec.net | sudo sh

# Verify installation
sudo cscli version
sudo systemctl status crowdsec

Ubuntu/Debian (Repository)

# Add CrowdSec repository
curl -1sLf 'https://dl.cloudsmith.io/public/crowdsec/crowdsec/setup.deb.sh' | sudo -E bash

# Install
sudo apt update && sudo apt install -y crowdsec

# Install a bouncer (firewall bouncer for iptables/nftables)
sudo apt install -y crowdsec-firewall-bouncer-iptables
# Or for nftables
sudo apt install -y crowdsec-firewall-bouncer-nftables

RHEL/CentOS/Fedora

# Add repository
curl -1sLf 'https://dl.cloudsmith.io/public/crowdsec/crowdsec/setup.rpm.sh' | sudo -E bash

# Install
sudo dnf install -y crowdsec

# Install firewall bouncer
sudo dnf install -y crowdsec-firewall-bouncer-iptables

Docker

# Run CrowdSec engine
docker run -d \
  --name crowdsec \
  -e COLLECTIONS="crowdsecurity/nginx crowdsecurity/sshd" \
  -v /var/log:/var/log:ro \
  -v /etc/crowdsec:/etc/crowdsec \
  -v /var/lib/crowdsec/data:/var/lib/crowdsec/data \
  --restart unless-stopped \
  crowdsecurity/crowdsec

# Docker Compose setup
cat > docker-compose.yml << 'EOF'
version: "3.9"
services:
  crowdsec:
    image: crowdsecurity/crowdsec:latest
    container_name: crowdsec
    environment:
      - COLLECTIONS=crowdsecurity/nginx crowdsecurity/sshd
      - GID=${GID:-1000}
    volumes:
      - /var/log:/var/log:ro
      - ./crowdsec/config:/etc/crowdsec
      - ./crowdsec/data:/var/lib/crowdsec/data
    restart: unless-stopped
    networks:
      - crowdsec_net

  bouncer-traefik:
    image: fbonalair/traefik-crowdsec-bouncer:latest
    container_name: bouncer-traefik
    environment:
      - CROWDSEC_BOUNCER_API_KEY=${BOUNCER_KEY}
      - CROWDSEC_AGENT_HOST=crowdsec:8080
    restart: unless-stopped
    networks:
      - crowdsec_net
EOF

Installing Bouncers

# List available bouncers
sudo cscli bouncers list

# Install via cscli hub
sudo cscli bouncers install crowdsecurity/cs-firewall-bouncer

# Register a bouncer and get API key
sudo cscli bouncers add my-bouncer-name

# Install Nginx bouncer
sudo apt install -y crowdsec-nginx-bouncer

# Install Cloudflare bouncer
sudo cscli bouncers install crowdsecurity/cloudflare-bouncer

Configuration

Main Config (/etc/crowdsec/config.yaml)

common:
  daemonize: true
  log_media: file
  log_level: info
  log_dir: /var/log/crowdsec/
  working_dir: .

config_paths:
  config_dir: /etc/crowdsec/
  data_dir: /var/lib/crowdsec/data/
  simulation_path: /etc/crowdsec/simulation.yaml
  hub_dir: /etc/crowdsec/hub/

crowdsec_service:
  acquisition_path: /etc/crowdsec/acquis.yaml
  parser_routines: 1
  buckets_routines: 1
  output_routines: 1

capi_whitelists_path: /etc/crowdsec/capi-whitelists.yaml

db_config:
  log_level: warn
  type: sqlite
  db_path: /var/lib/crowdsec/data/crowdsec.db
  flush:
    max_items: 5000
    max_age: 7d

api:
  client:
    insecure_skip_verify: false
    credentials_path: /etc/crowdsec/local_api_credentials.yaml
  server:
    log_level: info
    listen_uri: 127.0.0.1:8080
    profiles_path: /etc/crowdsec/profiles.yaml
    use_forwarded_for_headers: false
    trusted_proxies:
      - 127.0.0.1/32

Acquisition Config (/etc/crowdsec/acquis.yaml)

# SSH logs
filenames:
  - /var/log/auth.log
  - /var/log/secure
labels:
  type: syslog

---
# Nginx access logs
filenames:
  - /var/log/nginx/access.log
labels:
  type: nginx

---
# Apache logs
filenames:
  - /var/log/apache2/access.log
labels:
  type: apache2

---
# Docker container logs via journald
source: journalctl
journalctl_filter:
  - "_SYSTEMD_UNIT=nginx.service"
labels:
  type: nginx

Core Commands

Command	Description
cscli version	Display CrowdSec version info
cscli hub list	List all hub items (collections, parsers, scenarios)
cscli hub update	Update hub index
cscli hub upgrade	Upgrade all installed hub items
cscli collections list	List installed collections
cscli collections install NAME	Install a collection
cscli collections remove NAME	Remove a collection
cscli parsers list	List installed parsers
cscli parsers install NAME	Install a parser
cscli scenarios list	List installed scenarios
cscli scenarios install NAME	Install a scenario
cscli decisions list	List current bans/decisions
cscli decisions add -i IP	Manually ban an IP
cscli decisions delete -i IP	Remove a ban for an IP
cscli decisions delete --all	Remove all decisions
cscli alerts list	List triggered alerts
cscli alerts inspect ID	Show detail for an alert
cscli bouncers list	List registered bouncers
cscli bouncers add NAME	Register a new bouncer
cscli bouncers delete NAME	Remove a bouncer
cscli machines list	List registered agent machines
cscli machines add NAME	Register a new machine
cscli metrics	Show Prometheus metrics summary
cscli simulation enable SCENARIO	Enable simulation mode for scenario
cscli simulation disable SCENARIO	Disable simulation mode
cscli whitelists list	List IP/range whitelists
cscli lapi status	Check LAPI connection status
cscli capi status	Check CAPI connection status

Advanced Usage

Collections and Hub Management

# Search the hub
cscli hub list -g collection
cscli collections list --all

# Install common security collections
sudo cscli collections install crowdsecurity/linux
sudo cscli collections install crowdsecurity/nginx
sudo cscli collections install crowdsecurity/sshd
sudo cscli collections install crowdsecurity/wordpress
sudo cscli collections install crowdsecurity/http-cve

# Inspect a collection
cscli collections inspect crowdsecurity/nginx

# Upgrade everything
sudo cscli hub upgrade --all
sudo systemctl restart crowdsec

Decision Management

# List current decisions with details
cscli decisions list -o json

# Ban an IP for 24 hours
cscli decisions add --ip 1.2.3.4 --duration 24h --reason "Manual ban"

# Ban a CIDR range
cscli decisions add --range 1.2.3.0/24 --duration 48h --reason "Malicious range"

# Remove specific ban
cscli decisions delete --ip 1.2.3.4

# Delete by decision ID
cscli decisions delete --id 42

# Import a blocklist from file
while IFS= read -r ip; do
  cscli decisions add --ip "$ip" --duration 720h --reason "Blocklist import"
done < blocklist.txt

# Export current decisions
cscli decisions list -o json > decisions-backup.json

Whitelisting IPs and Ranges

Create /etc/crowdsec/parsers/s02-enrich/whitelist.yaml:

name: crowdsecurity/whitelists
description: "Whitelist trusted IPs and ranges"
whitelist:
  reason: "trusted sources"
  ip:
    - "192.168.1.0/24"
    - "10.0.0.0/8"
    - "172.16.0.0/12"
  cidr:
    - "192.168.0.0/16"
  expression:
    - "evt.Parsed.source_ip startsWith '127.'"

# Reload after whitelist change
sudo systemctl reload crowdsec

Custom Parser Example

Create /etc/crowdsec/parsers/s01-parse/my-app.yaml:

name: myorg/my-app-logs
description: "Parser for my application logs"
filter: "evt.Line.Labels.type == 'my-app'"
onsuccess: next_stage
nodes:
  - grok:
      pattern: '%{TIMESTAMP_ISO8601:timestamp} \[%{LOGLEVEL:level}\] %{IP:source_ip} - %{GREEDYDATA:message}'
      apply_on: Line.Raw
    statics:
      - target: evt.StrTime
        expression: "evt.Parsed.timestamp"
      - target: Meta.source_ip
        expression: "evt.Parsed.source_ip"
      - target: Meta.service
        value: "my-app"

Custom Scenario Example

Create /etc/crowdsec/scenarios/my-app-bruteforce.yaml:

name: myorg/my-app-bruteforce
description: "Detect brute force on my application"
filter: "evt.Meta.service == 'my-app' && evt.Meta.log_type == 'failed_login'"
groupby: "evt.Meta.source_ip"
distinct: "evt.Meta.target_user"
capacity: 5
leakspeed: "10s"
blackhole: 5m
labels:
  type: bruteforce
  service: my-app
  confidence: 3
  spoofable: 0
  classification:
    - attack.T1110

Multi-Server Setup (LAPI)

# On the LAPI server — register remote agent
cscli machines add agent-hostname --url http://lapi-server:8080

# On the agent machine — configure to use remote LAPI
# Edit /etc/crowdsec/local_api_credentials.yaml
cat > /etc/crowdsec/local_api_credentials.yaml << EOF
url: http://lapi-server:8080
login: agent-hostname
password: <generated-password>
EOF

# Verify connection
cscli lapi status

CrowdSec Console Integration

# Register with CrowdSec Console (https://app.crowdsec.net)
sudo cscli console enroll <ENROLLMENT_KEY>

# Check console status
sudo cscli capi status

# Enable/disable features
sudo cscli console enable tainted
sudo cscli console disable manual

# Opt into community blocklist
sudo cscli capi register

Prometheus Metrics

# View metrics summary
cscli metrics

# Expose metrics endpoint (already enabled by default)
curl http://127.0.0.1:6060/metrics

# Key metrics to monitor
# cs_buckets — active scenario buckets
# cs_parser_hits — log lines processed
# cs_decisions — current decisions by type
# cs_http_requests_total — LAPI request count

Common Workflows

Initial Setup Workflow

# 1. Install and verify
sudo apt install -y crowdsec crowdsec-firewall-bouncer-iptables
sudo cscli version

# 2. Install core collections
sudo cscli collections install \
  crowdsecurity/linux \
  crowdsecurity/sshd \
  crowdsecurity/nginx

# 3. Configure log acquisition
sudo vim /etc/crowdsec/acquis.yaml

# 4. Validate configuration
sudo crowdsec -c /etc/crowdsec/config.yaml -t

# 5. Restart and verify
sudo systemctl restart crowdsec
sudo systemctl status crowdsec

# 6. Check that scenarios are triggering
sudo cscli alerts list
sudo cscli decisions list

# 7. Register bouncer
sudo cscli bouncers add firewall-bouncer
# Copy the API key to bouncer config
sudo vim /etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml
sudo systemctl restart crowdsec-firewall-bouncer

Debugging Detection

# Test parser against a log line
cscli explain --log '2024-01-15 10:23:45 [WARN] 192.168.1.100 - Failed login' \
  --type my-app -v

# Replay log file through detection engine
cscli explain --file /var/log/auth.log --type syslog

# Check which scenarios an alert triggered
cscli alerts inspect 42 --details

# Watch decisions in real time
watch -n 2 cscli decisions list

# Monitor metrics for parser hits
cscli metrics | grep parser

# Test scenario simulation (no real bans)
cscli simulation enable crowdsecurity/ssh-bruteforce
# ... observe without banning ...
cscli simulation disable crowdsecurity/ssh-bruteforce

Threat Intelligence Sharing

# Check CAPI connection
cscli capi status

# View community blocklist pull
cscli hub list

# Check if an IP is in the community blocklist
cscli decisions list | grep "1.2.3.4"

# View signal sharing statistics
cscli metrics | grep capi

# Pull latest community blocklist manually
sudo systemctl restart crowdsec

Tips and Best Practices

Practice	Details
Start in simulation mode	Use cscli simulation enable SCENARIO while tuning to avoid false bans
Whitelist management IPs	Add your admin IPs to whitelist.yaml before going live
Monitor cscli metrics	Watch parser hit rates — zero hits means log acquisition is misconfigured
Use collections	Install vendor collections rather than individual parsers for better coverage
Set up Console	Register at app.crowdsec.net for GUI, dashboards, and community sharing
Review alerts regularly	Run cscli alerts list daily; investigate unexpected alerts
Backup decisions	Export decisions before upgrades: cscli decisions list -o json > backup.json
Pin bouncer API keys	Rotate bouncer keys periodically via cscli bouncers delete + re-add
Test parsers	Always use cscli explain to validate new parser/scenario before deploying
Join community blocklist	Opt into CAPI for mutual threat intelligence sharing

# Quick health check script
echo "=== CrowdSec Health ==="
sudo systemctl is-active crowdsec
cscli lapi status
cscli capi status
echo "Active decisions: $(cscli decisions list | wc -l)"
echo "Recent alerts: $(cscli alerts list | head -5)"
cscli metrics | grep -E "parsers|buckets|decisions"