CrowdSec — operations, deployment, configuration, and debugging

Glossary: AppSec is the engine component name (in configs, hub paths, cscli appsec-, Helm workload); WAF* is the user-facing term for the same thing. This skill uses both interchangeably.

Boundary — what this skill does and does not do

Step 1 — Detect the environment

Run probes in this order. Stop at the first match.

# systemd / bare-metal
systemctl list-unit-files crowdsec.service >/dev/null 2>&1 && systemctl is-enabled crowdsec >/dev/null 2>&1
# docker
docker ps --format '{{.Names}} {{.Image}}' 2>/dev/null | grep -E '(^|/)(crowdsec)([: ]|$)'
# kubernetes
kubectl get pods -A 2>/dev/null | grep -i crowdsec

If nothing matches and the user reports CrowdSec is installed, ask where: a vendor appliance, a custom image, a binary in /opt/, or a remote host. Otherwise pivot to install: see [references/install/](./references/install/).

pfSense detection:

uname -i   # → pfSense  (pfSense CE or Plus)

If confirmed pfSense, go directly to [references/install/pfsense.md](./references/install/pfsense.md) — paths, service names, and activation flow are entirely different from Linux/systemd.

Privileges — bare-metal / systemd prerequisite

On bare-metal/systemd, cscli and crowdsec need root (they read /etc/crowdsec/, the DB under /var/lib/crowdsec/, and control the systemd unit). Before running anything that touches config or state, confirm the user is root or has sudo:

id -u   # 0 = root; otherwise the user needs sudo

If they are neither root nor a sudoer, stop and ask them to grant it — don't guess. Once confirmed, run bare-metal commands as root or prefixed with sudo. Docker/k8s commands run inside the container/pod and do not need this.

Step 1.5 — Version & install-source sanity check (Linux)

Do this first on any install task and on any "weird behavior" report (missing cscli commands/flags, hub items that won't install, behavior ≠ docs). An engine installed from the wrong source can be years behind — a Linux-distro-only trap.

Compare the running engine to the latest published release:

curl -s https://version.crowdsec.net/latest    # → {"tag_name":"v1.7.8",...}; parse tag_name
cscli version                                  # bare-metal: prefix sudo

Then check where the package came from:

# Debian/Ubuntu
apt-cache policy crowdsec                       # read the *** installed line's origin
ls /etc/apt/sources.list.d/ | grep -i crowdsec
# RHEL-family
dnf info crowdsec ; dnf repolist | grep -i crowdsec

The official source is the packagecloud repo (packagecloud.io/crowdsec/crowdsec, repo id crowdsec_crowdsec). A distro origin (archive.ubuntu.com, deb.debian.org, ports.ubuntu.com) — or no crowdsec repo file at all — means it was installed from the distro's own ancient package.

Rule: if the source isn't the official repo or the version is well behind tag_name, treat it as a likely-outdated install — stop debugging config and migrate onto the official repo first: [references/operate/upgrades.md](./references/operate/upgrades.md) § Detect & fix an outdated / distro-packaged install.

Docker/Kubernetes: no repo-source trap — the version is the image tag pulled from Docker Hub. If it's far behind version.crowdsec.net/latest, pull a newer tag ([references/operate/upgrades.md](./references/operate/upgrades.md) happy path).

Step 1.6 — Feature compatibility

Some features only exist past a given engine version, and a few also need a capable bouncer. Check here before debugging "the config is right but nothing happens" — on an older engine the answer is an upgrade, not a config change.

Version-gated behaviour is recorded here rather than repeated in each reference doc — when a feature is added, give it a row instead of sprinkling "x.y+" through the prose.

Step 2 — Detect the intent

For anything debug-shaped, the first move is almost always:

bash ${CLAUDE_SKILL_DIR}/scripts/diagnose.sh

(or --env docker --container <name> / --env k8s --namespace ... --pod ...).

Step 3 — Universal cscli cheat sheet

These work in every environment. On bare-metal/systemd, prefix with sudo (unless you are root) — see Privileges above. In docker/k8s prefix with docker exec <name> / kubectl exec -n <ns> <pod> -- (which run as root inside the container/pod).

Where things live on a default bare-metal install:

• Binaries: /usr/bin/crowdsec, /usr/bin/cscli
• Config root: /etc/crowdsec/
• Acquisition: /etc/crowdsec/acquis.yaml and/or /etc/crowdsec/acquis.d/*.yaml
• Hub items: /etc/crowdsec/hub/, enabled symlinks under /etc/crowdsec/{parsers,scenarios,collections,postoverflows,contexts}/
• Local overrides: /parsers//custom/, /scenarios//custom/, etc.
• Data (sqlite DB, geoip): /var/lib/crowdsec/data/
• Logs: /var/log/crowdsec.log (agent) and /var/log/crowdsec_api.log (LAPI)
• LAPI default listen: 127.0.0.1:8080
• Systemd unit: crowdsec.service

Step 4 — Hard don'ts

Confirm with the user before any of these:

• cscli decisions delete --all — wipes every active ban including CAPI-pulled blocklists. Use targeted delete -i, delete -r, delete --id, delete --origin lists --scenario <name>.
• Editing hub-managed files under /etc/crowdsec/{parsers,scenarios,collections,postoverflows,contexts}/ instead of the sibling _custom/ directory — see [references/debug/common/triage.md](./references/debug/common/triage.md) § Hard don'ts.
• Disabling a signature collection wholesale to silence a false positive — pick the right suppression layer (allowlist / whitelist parser / postoverflow) per [references/configure/allowlists.md](./references/configure/allowlists.md) § Suppression mechanisms.
• Mutating host firewall state (firewall bouncer install, ipset flush, iptables↔nftables switch) without confirming — the firewall bouncer can wipe rule chains other tools depend on.
• Skipping --reset-then-reuse-values on helm upgrade crowdsec — silently drops values.

Docs

Canonical reference: <https://docs.crowdsec.net/>;. Each file in references/ cites the specific page it relies on — follow the link rather than paraphrasing from memory.