.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
Updated 22 October 2026
This page is the map of the fifteen deeper CrowdSec tutorials in this library: the architecture in one section and a deployment order for production, with a pointer into the right deep guide at each stage.
If the name is new to you, CrowdSec is an open source IPS (Intrusion Prevention System) that reads your server logs for attacks and bans the IPs behind them, then trades those detections with every other install for a curated blocklist of currently active attackers. The full tour of that model, including where the free-versus-paid line sits, is in my what is CrowdSec explainer.
Everything below matches the Security Engine 1.8 line, v1.8.1 on the official release page as of October 2026. LumaDock's template still ships 1.7.8; if cscli version says 1.7.x, this brings it current:
sudo apt update
sudo apt install --only-upgrade crowdsecThe version matters more than it sounds. A lot of CrowdSec advice floating around dates from the 1.4 era, before centralized allowlists (cscli allowlists) existed, and following it produces configs that fight the current engine.
The CrowdSec architecture in five parts
You can hold the whole system in your head with five names. The Log Processor (the detection half, called the agent in older docs) tails your logs through acquisition files and parses each line into structured events. Scenarios watch those events for hostile patterns; most are leaky buckets, so enough failed SSH logins from one address inside a short window overflows a bucket and raises an alert. The Local API (LAPI) receives alerts and turns them into decisions, "ban this IP for four hours" being the default, though profiles can hand out a captcha challenge instead, which is the kinder option on anything a paying customer touches. A decision on its own is a database row.
Enforcement belongs to Remediation Components, which everyone calls bouncers: separate programs that subscribe to the LAPI and block at the firewall, the reverse proxy, the CDN or wherever else you attach one. The fifth piece is the community blocklist. Your engine reports confirmed attacks to the Central API (CAPI) as bare signals and pulls back a curated list of addresses the whole network is currently seeing, so most attackers arrive on your server already banned. Without that trade CrowdSec would be fail2ban with YAML and a nicer CLI. With it, a large part of the traffic a new server drops comes from addresses its own detection never had to learn about, and cscli metrics shows the split between local decisions and the blocklist, once the list has arrived. On a fresh install that can take a couple of hours.
The Origin column splits local detection from the community blocklist.
Detection content lives outside the binary. Parsers, scenarios and the collections that bundle them per service sit on a hub and refresh through cscli hub upgrade independently of engine releases, the way apt refreshes packages. The split between detection and enforcement pays off the moment you run more than one machine, since several Log Processors can share a single LAPI and every bouncer in the fleet enforces the merged decision list; a credential stuffer caught on the web node is banned on the mail server seconds later. The official documentation covers each component exhaustively, but the mental model to carry into everything below is smaller than the docs suggest. Every deployment decision reduces to two questions. Where does the engine read logs, and where do bouncers block.
Installing the first Security Engine
Skip your distro's package. Debian 12 ships CrowdSec frozen at 1.4.6, roughly three years behind on detection content and missing the AppSec component entirely, and Debian 13 trails upstream too. The official repository costs one line, the engine one more:
curl -s https://install.crowdsec.net | sudo sh
sudo apt install crowdsecThe post-install step detects your services, installs the matching collections and leaves you with an engine that detects without blocking, which is exactly the right resting state for the first week. My CrowdSec install guide for Debian 12 and 13 walks the full sequence and spends half its length on acquisitions for a reason: modern Debian doesn't install rsyslog, so /var/log/auth.log may simply not exist and SSH events live in journald instead, a wrinkle that leaves detection silently reading nothing when an acquisition points at the wrong place. Every command in that guide works unchanged on Ubuntu 24.04, and it also covers console enrollment and the two-track upgrade routine (apt for the binaries, cscli hub for the detection rules) that are easy to half-forget. On a public address the first SSH brute force alert usually lands within the hour, which makes a better demo than any sales page.
Or skip the assembly. LumaDock ships one-click CrowdSec VPS templates on Ubuntu 24.04, selected during ordering, with nginx and Apache variants where the web server is ready for the bouncer; the box boots protected and you can jump straight to the rollout section below. I'd still read the install guide once so you know what's running on your behalf.
Safe rollout: Allowlists before bouncers
CrowdSec will gladly ban the hand that configured it. Your uptime checker, your backup agent, your dashboard's polling and your API scripts all look like attack traffic to a scenario, and the moment a bouncer attaches, every decision becomes a dropped packet with no grace period. So the order matters more than any individual setting. Run detection alone for a week and read cscli alerts list daily, because every false positive you find in that list is a lockout you won't have in week three. Allowlist your admin addresses while enforcement still doesn't exist; cscli allowlists entries apply the moment you add them and also strip matching IPs out of blocklist imports. Your LAN is already covered by the default private-range whitelist, so it's the public addresses, the office egress and the VPN endpoint, that need entries. Only then attach a bouncer, to one service, and I start with the reverse proxy rather than the firewall on the theory that a wrong HTTP ban costs me a dashboard while a wrong firewall ban costs me SSH. Third-party blocklist subscriptions come last or never.
The reasoning behind each step, the test-ban routine against documentation addresses and the WireGuard tunnel I keep as a permanent side door (its subnet is private, so the default whitelist already trusts it) are in how to roll out CrowdSec without locking yourself out. If I could make one article in this library mandatory, that's the one.
Enforcement layers: Firewall bouncer, Docker, the AppSec WAF and bot detection
On a plain Linux server the firewall bouncer is the natural first enforcement point: a small Go daemon that streams decisions into nftables sets or ipset-backed iptables, where a banned IP loses every port at once and lookup cost stays constant no matter how many thousand entries the sets hold. The defaults are good and the config surface is small. Which package to pick (nftables mode on any modern Debian or Ubuntu, where the iptables command is a shim anyway), how decisions become dropped packets and the checks I repeat after every change are in the firewall bouncer guide for iptables and nftables.
Docker bends the picture twice. Published ports bypass the INPUT chain entirely, so a stock firewall bouncer protects the host's own services while banned IPs keep reaching your containers, a half-working state that goes unnoticed for months; on a container host, enforcement has to land in the DOCKER-USER chain, which the firewall bouncer guide covers. The engine itself usually moves into a container too, reading the reverse proxy's logs through a read-only bind mount. At that point acquisition labels and LAPI networking grow container-shaped failure modes (inside a compose network, 127.0.0.1 means "this container", the classic mistake), and volume persistence becomes the difference between an upgrade and an amnesty for every banned attacker. The compose file I use with Nginx Proxy Manager and Traefik logs, plus why I leave the Docker socket acquisition alone, are in the CrowdSec Docker Compose guide.
The AppSec component moves inspection inline and turns the engine into a WAF: nginx forwards each request to a local inspection endpoint before your application parses it, virtual patching rules block known exploits in-band with few false positives and the OWASP Core Rule Set watches out-of-band, banning repeat offenders rather than challenging every twitchy first match. When the React2Shell RCE went public in December 2025, a virtual patch reached the hub within hours; the CrowdSec writeup of that response is the best argument for running this layer at all. Setup on Ubuntu 24.04, the two-layer rule split and when to move CRS in-band are in CrowdSec AppSec on nginx.
The newest layer arrived with CrowdSec 1.8.0 in August 2026 and is still labelled alpha. Bot detection sits inside AppSec and checks that a visitor is a real browser: it serves a short proof-of-work and fingerprint check, gives clients that pass a cookie, refuses stock headless browsers and automation frameworks, and lets verified crawlers through without a challenge. It needs a recent nginx bouncer and a host CPU that can run its WebAssembly runtime, and a site-wide Content-Security-Policy can freeze the challenge page; CrowdSec bot detection on nginx covers all three.
