crowdsec

Identity

• Unit: crowdsec.service
• Config: /etc/crowdsec/config.yaml (main), /etc/crowdsec/acquis.yaml (log sources), /etc/crowdsec/profiles.yaml (decision profiles)
• Decisions DB: /var/lib/crowdsec/data/crowdsec.db
• Log: journalctl -u crowdsec, /var/log/crowdsec/crowdsec.log
• Install: Official script (curl -s https://packagecloud.io/install/repositories/crowdsec/crowdsec/script.deb.sh | sudo bash) or distro package repo

Architecture

CrowdSec has three distinct layers that must all be present for traffic to actually be blocked:

Log files / journald
       ↓
  Agent (crowdsec.service)
  - Reads logs via acquis.yaml
  - Applies parser chains to normalize events
  - Runs scenarios to detect attack patterns
  - Writes decisions to LAPI
       ↓
  LAPI (Local API, port 8080)
  - Stores decisions in crowdsec.db
  - Serves decisions to registered bouncers
  - Optionally syncs with CrowdSec community blocklist
       ↓
  Bouncer (crowdsec-firewall-bouncer, crowdsec-nginx-bouncer, etc.)
  - Polls LAPI for active decisions
  - Enforces bans at the network or application layer

Critical: CrowdSec detects and decides; bouncers enforce. Without an installed and registered bouncer, bans exist in the database but no traffic is actually blocked.

Key Operations

| Goal | Command | |------|---------| | Check service status | systemctl status crowdsec | | Check agent version | sudo cscli version | | List active alerts | sudo cscli alerts list | | List active decisions (bans) | sudo cscli decisions list | | Delete a decision (unban IP) | sudo cscli decisions delete --ip 1.2.3.4 | | Ban an IP manually | sudo cscli decisions add --ip 1.2.3.4 --duration 24h --reason "manual ban" | | List registered bouncers | sudo cscli bouncers list | | List installed collections | sudo cscli collections list | | Install a collection | sudo cscli collections install crowdsecurity/nginx | | Remove a collection | sudo cscli collections remove crowdsecurity/nginx | | Update hub index | sudo cscli hub update | | Upgrade all hub items | sudo cscli hub upgrade | | Inspect a scenario | sudo cscli scenarios inspect crowdsecurity/ssh-bf | | Tail live alerts | sudo cscli alerts list -o human --since 1m (repeat; no live stream by default) | | Test parser against log | sudo cscli explain --log "Failed password for root" --type sshd | | View metrics | sudo cscli metrics | | Reload agent config | sudo systemctl reload crowdsec |

Expected Ports

• 8080/tcp — LAPI (Local API). Listens on 127.0.0.1:8080 by default. Bouncers and remote agents connect here.
• No external ports required for a single-node deployment.

Health Checks

1. systemctl is-active crowdsec — agent running
2. sudo cscli version — CLI and LAPI reachable
3. sudo cscli alerts list — shows recent detections (empty = no attacks detected yet, or parsers not matching)
4. sudo cscli bouncers list — at least one bouncer registered with a recent Last API pull timestamp

Common Failures

| Symptom | Likely cause | Check / Fix | |---------|-------------|-------------| | Bouncer shows "LAPI not reachable" | LAPI not running or wrong API URL in bouncer config | systemctl status crowdsec; check api_url in bouncer config (/etc/crowdsec/bouncers/*.yaml) | | No alerts despite known attacks | Log source not in acquis.yaml, or parser not installed | sudo cscli parsers list; add log path to acquis.yaml; install matching collection | | Decisions exist but traffic not blocked | Bouncer not installed or not registered | sudo cscli bouncers list; install a bouncer (apt install crowdsec-firewall-bouncer-iptables) | | Scenario never triggers | Parser not normalizing events correctly | sudo cscli explain --log "..." --type sshd; check parser stage output | | Legitimate IPs being banned (false positives) | Aggressive scenario thresholds or missing allowlist | sudo cscli decisions delete --ip <ip>; add IP to /etc/crowdsec/allowlists.yaml | | Allowlist not taking effect | Allowlist file not referenced in config.yaml, or old format | Check crowdsec_service.allowlists in config.yaml; restart after editing | | Community blocklist not loading | Instance not enrolled in CrowdSec console | sudo cscli console enroll <token> from app.crowdsec.net | | Hub items stale / scenarios outdated | Hub index not updated | sudo cscli hub update && sudo cscli hub upgrade |

Pain Points

• Agent ≠ bouncer: CrowdSec detects and records decisions; bouncers enforce them. Without a bouncer, bans in cscli decisions list have zero network effect. Install at minimum crowdsec-firewall-bouncer-iptables (or nftables variant).

• Collections vs scenarios vs parsers: Collections bundle parsers + enrichers + scenarios for a service. Always install a collection (cscli collections install crowdsecurity/nginx) rather than individual parsers — collections keep all dependencies in sync.

• Log acquisition (acquis.yaml): CrowdSec does not auto-detect log files. Add an entry for every service you want monitored. Missing an entry means the agent never sees those logs. See references/configuration.md for examples.

• Hub updates: Hub items (parsers, scenarios, collections) are versioned independently of the CrowdSec binary. Run cscli hub update && cscli hub upgrade after upgrading the package and periodically in production.

• Allowlists: Use sudo cscli decisions delete --ip <ip> for one-off unbans. For permanent exceptions, add IPs/CIDRs to /etc/crowdsec/allowlists.yaml and reference the file from config.yaml. The cscli allowlists subcommand is available in v1.6+.

• Community blocklist: Instances enrolled in the CrowdSec console receive shared ban decisions from the community. Requires a free account at app.crowdsec.net and running sudo cscli console enroll <token>. Without enrollment, the instance is local-only.

• nftables vs iptables: The firewall bouncer comes in iptables and nftables variants. On modern Fedora/RHEL/Debian 12+, nftables is the default backend. Installing the wrong variant causes silent failures — bans are registered but no firewall rules are created.

References

See references/ for:

• configuration.md — annotated config files: config.yaml, acquis.yaml, profiles.yaml, bouncers, allowlists
• docs.md — official documentation and hub links