CrowdSec

CrowdSec watches Traefik’s access logs and decides which IPs to ban for attack patterns (brute force, CVE probes, path traversal). On its own it detects but doesn’t block — blocking is added separately, in layers you choose.

Verified 29 Jul 2026 against v1.7.8

Not exercised: SSH and host log sources — Debian 13 keeps no `auth.log`, so only the proxy layer feeds the engine.

Needs: Traefik running.

Installation

The required baseline — detection only, blocks nothing yet.

1. From core/crowdsec/:

   cp .env.example .env

2. Find the GID that owns Traefik’s log files, and set it as CROWDSEC_LOG_GID in .env:

   stat -c '%g' ../traefik/volumes/logs/access.log

3. Start:

   docker compose up -d

Note

First boot takes about 5 minutes — CrowdSec installs its detection collections before it starts reading logs. Metrics commands return mostly empty output during that window; that’s normal, not broken.

Verify

docker exec crowdsec cscli lapi status
docker exec crowdsec cscli metrics show acquisition

Expect “You can successfully interact with Local API” and a row for file:/var/log/traefik/access.log with lines_read > 0.

Tip

If the acquisition table stays empty after 5 minutes: CrowdSec only reads log lines written after it started, and Traefik buffers access-log writes — on a quiet server that can take a while to flush. Force it:

for i in $(seq 1 110); do
  curl -sk -o /dev/null -H "Host: <any-app-domain>" https://127.0.0.1/
done
docker exec crowdsec cscli metrics show acquisition

The three layers, and what each one covers

They are separate components with one thing in common: the engine decides, nothing else does. It writes decisions to a list; each enforcement layer polls that list and applies it in its own place. A decision with no enforcer attached does nothing at all.

	Where it acts	Catches
Engine	reads the proxy’s access log	decides — blocks nothing itself
Proxy plugin	inside Traefik, per request	HTTP attacks; answers 403 and sees the decrypted request
Firewall bouncer	nftables on the host	everything, on every port — the packet is dropped before a connection exists

The proxy plugin has the better view: it knows the URL and can say why it refused. The firewall bouncer has the wider one — SSH, port scans and anything not behind the proxy never reach Traefik at all.

Running both is not redundancy. Measured here: a decision reaches the kernel in about 15 seconds and clears again in about 10, while the proxy plugin acts on its own polling cycle in between.

What the firewall layer inherits the moment you enable it

The engine subscribes to CrowdSec’s community blocklist from the start. On this host that had quietly accumulated roughly 15,800 addresses — known-bad, with nothing enforcing them, because Phase 1 only decides.

Alongside them sat one the engine had found itself: an address probing this host for common exploit paths, eleven events, banned three hours earlier. Until the firewall layer existed, that ban applied only to HTTP through the proxy.

What it can and cannot see

The two protective layers in this Blueprint do not add up — they take turns, and that determines where it is worth attaching.

Measured here: 120 requests against a VPN-only host moved CrowdSec’s counter by 3. Behind acc-tailscale or acc-private, the engine sees close to nothing — which is not a problem, because nothing got through either. It becomes worth its keep the moment an application is public.

Note

That measurement is a result, not an explanation. The obvious reading is that rejected requests never reach the log the engine reads, but the proxy’s access log is configured for status codes 200-599 and a rejected request is answered with a 403, so those lines should be there. The gap could equally be log buffering, which parser the acquisition applies, or what that particular counter counts. The number is what was observed; the cause has not been established here, and a targeted look at the log would settle it.

The WAF layer is narrower than the name suggests

The optional AppSec engine inspects each request against rule sets. Measured against a public router:

Request	Result
?id=1' OR '1'='1	passes
?q=<script>alert(1)</script>	passes
?f=../../../../etc/passwd	passes
/vendor/phpunit/…/eval-stdin.php	blocked

The shipped rules are virtual patches for named CVEs plus a small generic set — not a general injection filter. It stops the mass scanning that finds any public host within minutes of a certificate being issued, which is most of what arrives uninvited. It will not stop an attack crafted against your application’s own parameters, and it is no reason to relax anything about input handling.

The upside of that narrowness: far fewer false positives than a full WAF, which makes it a reasonable default for a public app.

Going further

Phase 1 above is detection only. Two more layers, each independently optional, add blocking.

Phase 2 — HTTP blocking

Rejects requests from banned IPs with a 403, inside Traefik.

1. Generate a key:

   docker exec crowdsec cscli bouncers add traefik-bouncer

2. In core/traefik/.env, add CROWDSEC_BOUNCER_KEY=<key>.

3. Uncomment the plugin block in ops/templates/traefik.yml.tmpl and the sec-crowdsec middleware in ops/templates/dynamic/integrations.yml.tmpl, then:

   bash ops/scripts/render.sh
   docker compose up -d --force-recreate traefik

4. Add sec-crowdsec@file to at least one router’s middleware list, then recreate that app:

   - "traefik.http.routers.${COMPOSE_PROJECT_NAME}.middlewares=sec-crowdsec@file,${APP_TRAEFIK_ACCESS}@file,${APP_TRAEFIK_SECURITY}@file"

Caution

Step 4 is required, not optional. The plugin loading successfully does not make the bouncer do anything — its polling loop only starts once the middleware is attached to a router. Skip this and cscli bouncers list will show the bouncer as registered but never pulling, with no error anywhere to explain why.

Verify:

docker exec crowdsec cscli bouncers list
# Expect an IP address and a recent "Last API pull"

Phase 3 — network-layer blocking

Drops packets from banned IPs at the host firewall — every port, not just HTTP. Runs as a host package, not a container.

Worth it mainly if SSH is reachable from the public internet (Traefik never sees SSH brute force). Skip if SSH is Tailscale-only.

1. Install and register:

   sudo apt install crowdsec-firewall-bouncer   # Debian 13, from Debian main
   docker exec crowdsec cscli bouncers add firewall-bouncer

   Note

   The package name depends on where you get it from. Debian 13 ships one package, crowdsec-firewall-bouncer, from its own archive — that is what the line above installs, and no extra repository is needed. CrowdSec’s own repository splits it by backend into crowdsec-firewall-bouncer-nftables and -iptables, so guides written against that source name a package Debian 13 does not have. Check with apt policy crowdsec-firewall-bouncer before assuming either.

2. Edit /etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml.local — never the base .yaml, the package manages that:

   api_url: http://127.0.0.1:8080/
   api_key: <key from above>
   mode: nftables

3. Start:

   sudo systemctl enable --now crowdsec-firewall-bouncer

Verify:

sudo systemctl status crowdsec-firewall-bouncer
docker exec crowdsec cscli bouncers list

Note

Banned IPs live in an nftables set, not as individual rules — nft list chain ip crowdsec crowdsec-chain shows the rule but not which IPs are currently banned. There is one set per address family:

sudo nft list set ip  crowdsec  crowdsec-blacklists     # IPv4
sudo nft list set ip6 crowdsec6 crowdsec6-blacklists    # IPv6

Caution

Emergency — stop enforcement now. Flush the sets, not the chain: flushing the chain deletes the enforcement rule itself, leaving the host with no drop logic until the service is restarted.

sudo nft flush set ip  crowdsec  crowdsec-blacklists
sudo nft flush set ip6 crowdsec6 crowdsec6-blacklists

Both lines, or you have only half-stopped it — IPv4 and IPv6 are separate tables, and clearing one leaves the other enforcing.

This buys you minutes, not a resolution: the bouncer keeps polling the engine and refills the sets on its next cycle. To actually stop enforcement, stop the service (sudo systemctl stop crowdsec-firewall-bouncer); to lift a ban permanently, delete the decision at the engine, because the firewall is only applying what the engine decided.

Troubleshooting

“The site does not load for me” — check this first, not last. Once the firewall layer is running, the most likely cause of one person being unable to reach a service is that their address is on a blocklist. The packet is dropped in the kernel, so there is no log line anywhere to tell you — not in the proxy, not in the application.

docker exec crowdsec cscli decisions list --ip <their address>
docker exec crowdsec cscli decisions delete --ip <their address>

Most of those decisions did not come from your server. The engine subscribes to CrowdSec’s community blocklist, which on a running host means around 15,000 addresses other installations reported. That is what the subscription delivers, and it also means a shared CGNAT address, a VPN exit or a compromised neighbour can take a legitimate visitor with it.

The bouncer never polls — cscli bouncers list shows no Last API pull. Loading the plugin is not enough: the polling loop starts only once a router actually uses the middleware. Attach it to one, then check again. There is no error message for this.

A ban you set does not seem to work when you test it from the server itself — it is the test that is wrong. A request made on the host arrives through the Docker bridge, so the proxy records the gateway as the client and the address you banned never appears as a sender. Read the address out of the access log, ban that one, and have the real client retry.

AppSec refuses every request — the engine is unreachable and the profile is fail-closed. Check that something answers on 7422 from the proxy container; a 401 is correct there, connection refused is not.

A legitimate IP got banned. Start narrow, and check the result rather than assuming it:

docker exec crowdsec cscli decisions list --ip <ip>      # what exists, and from which origin
docker exec crowdsec cscli decisions delete --ip <ip>
docker exec crowdsec cscli decisions list --ip <ip>      # expect nothing

Caution

Do not reach for --all. Upstream documents that flag as delete all decisions — every ban on the engine, local and community alike, not the ones for your address. It is not a wider form of --ip, and there is no situation on this page where it is the right answer.

If the decision comes back after you delete it, deleting harder is not the fix. Find out where it comes from:

docker exec crowdsec cscli decisions list --ip <ip> -o json   # origin, scenario, duration
docker exec crowdsec cscli alerts list --ip <ip>              # what triggered it

An origin of crowdsec means your own engine decided it and will decide it again from the same traffic. lists or CAPI means it arrived with the community blocklist. A local re-detection needs a whitelist entry, not a deletion.

A ban that keeps coming back is a different problem — the engine is still seeing the behaviour that caused it. A whitelist entry stops decisions being created at all, which is the right tool for your own monitoring, office address or a known crawler.

Full operational reference — health checks, whitelisting, false positives, SSH detection, geo-blocking, emergency procedures: core/crowdsec/docs/runbook.md.

Repository files

• core/crowdsec/README.md — full setup for all three phases
• core/crowdsec/docs/runbook.md — day-to-day operations
• core/crowdsec/docs/firewall-bouncer.md — Phase 3 in depth, including SSH detection