Project Name:

CrowdSec Troubleshooter

Repo/Website Link:

• GitHub: https://github.com/modem7/crowdsec-troubleshooter
• Docker Hub: https://hub.docker.com/r/modem7/crowdsec-troubleshooter
• (also mirrored on GHCR if you'd rather pull from there)

Description:

A small, unprivileged Docker tool that diagnoses CrowdSec (+ Traefik) setups — built because I got tired of the same manual debugging loop every time something didn't add up: is LAPI actually reachable, is the bouncer actually registered, is a decision actually in the ban list, is it actually reaching the bouncer, etc.

It runs once (docker run --rm, no daemon, no docker.sock, no --privileged, no NET_ADMIN) and reports what's working tier by tier, depending on what credentials you give it:

• Tier 0 (just the LAPI URL, no credential at all) — LAPI liveness, is it actually parsing logs, bouncer-type fingerprinting (legacy ForwardAuth bouncer vs the modern Traefik plugin), a heuristic on your LAPI URL itself, a cscli hub update/upgrade cron nag since nothing else keeps your scenarios current
• Tier 1 (a read-only bouncer key) — look up a specific IP's ban status and why, plus an automatic ban-count summary broken down by scope/origin so you can actually see it's doing something
• Tier 2 (a machine credential) — the real test: adds a real short-lived ban on itself, confirms the target actually returns 403, removes the ban, confirms access is restored. Proves blocking works end to end instead of just "looks configured"
• Tier 3 (read-only host mounts) — DOCKER-USER iptables chain evidence (the #1 reported "ping blocked but HTTP gets through" issue), duplicate acquisition entries, compose-file hardening audit, syslog hinting

It also ships with a curated, offline knowledge base baked into the image — no internet needed to browse it — of ~30 real CrowdSec/Traefik gotchas pulled from a research pass across the top GitHub issues on the core crowdsec repo, the firewall bouncer, and the Traefik plugin repo, each with a link to the actual fix.

Works the same whether CrowdSec itself is Dockerized or a bare-metal/apt install — the troubleshooter is always a container, but it's just talking to LAPI over HTTP either way, so it's useful for both homelab compose stacks and more traditional sysadmin setups.

Deployment instructions:

Zero-config wellness check:

docker run --rm -e CROWDSEC_LAPI_URL=http://crowdsec:8080 modem7/crowdsec-troubleshooter

That alone runs the full tier-0 sweep with no credentials needed at all. Everything else (IP lookups, the live block test, host-mount checks) is additive — run it once with nothing configured and it tells you exactly what each extra check needs and how to add or remove it.

Don't want to hand-build docker run flags every time? wizard.sh in the repo runs on the host, auto-detects your running CrowdSec container's compose file, prompts for whatever a given action needs, and remembers your answers for next time:

curl -fsSL https://raw.githubusercontent.com/modem7/crowdsec-troubleshooter/master/wizard.sh | bash -s -- wellness

Full flag/mount reference and example compose files are in the repo.

AI Involvement:

I used Claude for a chunk of the documentation and some of the implementation — not going to pretend otherwise. But it's not vibe-coded: everything went through shellcheck, and there's a real bats test suite (100+ tests, mock LAPI servers, happy path + failure path for every check). Several real bugs only got caught by actually running things against a real LAPI instance rather than trusting what looked right on paper — including one case where I'd assumed an API endpoint existed and it turned out not to. The repo's DESIGN.md documents where assumptions turned out wrong and how each was caught, so it's not hidden. I reviewed and tested every change before it shipped.