إنتقل إلى المحتوى الرئيسي

CrowdSec — operations

CrowdSec runs as the shambus-crowdsec container, reads Traefik access logs, and bans malicious IPs at the Traefik proxy via the crowdsec-bouncer-traefik-plugin. This runbook is the operator's day-to-day reference.

For the initial bring-up procedure see the script infrastructure/scripts/deploy-crowdsec.sh.

Active bans​

# All currently-banned IPs (with reason + duration)
docker exec shambus-crowdsec cscli decisions list

# Recent alerts (scenario hits — may or may not have led to a ban)
docker exec shambus-crowdsec cscli alerts list

# Live tail of the engine
docker logs -f shambus-crowdsec

Whitelist an IP​

To prevent operator workstations from getting accidentally banned, edit the whitelist parser — it runs early in the pipeline and short-circuits all scenarios for whitelisted IPs.

docker exec -i shambus-crowdsec sh -c 'cat > /etc/crowdsec/parsers/s02-enrich/operator-whitelist.yaml' <<'EOF'
name: shambus/operator-whitelist
description: "Operator workstations — never ban"
whitelist:
  reason: "operator IPs"
  ip:
    - 94.72.132.96
    - <add more here>
EOF

docker exec shambus-crowdsec kill -HUP 1   # reload config without restart

Verify it took:

docker exec shambus-crowdsec cscli parsers list | grep operator

Manually ban / unban an IP​

# Ban for 4 hours
docker exec shambus-crowdsec cscli decisions add --ip 1.2.3.4 --duration 4h --reason "manual: spam"

# Unban
docker exec shambus-crowdsec cscli decisions delete --ip 1.2.3.4

The Traefik plugin pulls the decision list every 60s in stream mode, so manual changes take up to 1 minute to propagate.

False positives — disable a scenario​

If a legitimate workflow keeps tripping a scenario:

# Find which scenario fired
docker exec shambus-crowdsec cscli alerts list

# Inspect what the scenario detects
docker exec shambus-crowdsec cscli scenarios inspect crowdsecurity/http-crawl-non_statics

# Disable just that scenario
docker exec shambus-crowdsec cscli scenarios remove crowdsecurity/http-crawl-non_statics
docker exec shambus-crowdsec kill -HUP 1

For per-route or per-pattern carve-outs, write a custom whitelist parser under /etc/crowdsec/parsers/s02-enrich/ matching on evt.Meta.http_path, evt.Meta.user_agent, etc. See CrowdSec docs on whitelists.

Bouncer status​

# Verify the Traefik plugin is connected
docker exec shambus-crowdsec cscli bouncers list
# Look for: "Last API pull" within the last 60s

# Plugin-side logs
docker logs shambus-traefik 2>&1 | grep -i crowdsec

If Last API pull is stale (> 5 min), recreate Traefik:

docker compose --env-file .env.prod \
  -f docker-compose.yml -f docker-compose.prod.yml \
  -f docker-compose.authentik.yml -f docker-compose.security.yml \
  --profile prod up -d --no-deps --force-recreate traefik

Community blocklist (CAPI)​

CrowdSec automatically pulls the global community blocklist from CrowdSec Central API. To inspect:

docker exec shambus-crowdsec cscli decisions list -o human | head -20
docker exec shambus-crowdsec cscli capi status

To opt out of CAPI (we recommend keeping it on — it's the main value-add of CrowdSec over fail2ban):

# In docker-compose.security.yml, set DISABLE_LOCAL_API: "false" already.
# To disable CAPI specifically, set CAPI_DISABLED: "true".

Upgrading CrowdSec​

The image tag in docker-compose.security.yml should be pinned. To upgrade:

# 1. Bump the tag locally
sed -i 's|crowdsecurity/crowdsec:v1.6.3|crowdsecurity/crowdsec:v1.7.7|' \
  docker-compose.security.yml

# 2. Test in dev (or directly recreate prod since CrowdSec state is in volumes)
docker compose --env-file .env.prod \
  -f docker-compose.yml -f docker-compose.prod.yml \
  -f docker-compose.authentik.yml -f docker-compose.security.yml \
  --profile prod pull crowdsec
docker compose ... up -d --no-deps --force-recreate crowdsec

# 3. Update collections after the engine upgrade
docker exec shambus-crowdsec cscli hub upgrade
docker exec shambus-crowdsec kill -HUP 1

Notifications​

Security alerts (new bans, scenario fires) are pushed to the internal ntfy instance — see infrastructure/docker/crowdsec-notifications/http.yaml and /etc/crowdsec/profiles.yaml. To send to a different channel, edit those files and kill -HUP 1 the engine to reload.

Tuning blocking duration​

Default ban duration comes from the scenario definition (typically 4h for HTTP probing, 24h for SQLi). To change globally, edit the profile:

docker exec shambus-crowdsec cat /etc/crowdsec/profiles.yaml
# Edit the duration field for the matching profile

See also​