1. What CrowdSec is #
The principle in a few minutes.
The problem #
Expose a server on the Internet: within minutes, bots try SSH passwords, look for a .env file or test a known flaw. These attacks show up in your logs, but nobody reads them continuously.
CrowdSec reads these logs for you, recognizes attack behaviors and has the addresses blocked. Its engine is free software (MIT license), written in Go.
Two strong ideas #
- Separate detection from blocking. The engine decides; other components, the bouncers, enforce the decision where it is useful: firewall, reverse proxy, CDN or application.
- Share intelligence. Each installation can report the attacks it faces and receive in return a list of addresses recognized as malicious.
2. The architecture #
The components and their role.
Overview #
| Component | Role |
|---|---|
| Security Engine | The crowdsec service: it reads logs and detects attacks. |
| Parsers | Turn a log line into a structured event. |
| Scenarios | Recognize a behavior, such as too many failed logins. |
| Local API (LAPI) | Stores alerts and decisions. It listens on port 8080 by default. |
| Central API (CAPI) | CrowdSec's service: receives signals, returns community reputation. |
| Profiles | Turn an alert into a decision: 4 h ban by default. |
| Bouncers | Enforce decisions. They are also called remediation components. |
| Hub | Catalog of ready-to-use collections, parsers and scenarios. |
| cscli | The command-line tool to manage everything. |
The full cycle #
Classic mistake. Installing the crowdsec package blocks nothing: you need at least one bouncer. Without it, decisions have no effect.3. Collaborative intelligence #
What is shared, and how the list stays reliable.
What is sent #
When a scenario triggers, CrowdSec sends a signal to the CAPI: the attacker's address, the scenario and the timestamp. Your logs do not leave your server. In return, the LAPI downloads a list of addresses, visible with the CAPI origin in decisions.
cscli capi status
cscli decisions list --origin CAPIAvoiding poisoning #
A participatory list could be polluted by false signals. CrowdSec therefore cross-checks signals from many participants and assesses their reliability before publishing an address. Well-known legitimate addresses, such as large DNS resolvers, are excluded through allow lists, for example the crowdsecurity/whitelist-good-actors collection.
Optional. You can turn this sharing off: DISABLE_ONLINE_API=true in Docker, or with no CAPI credentials. Local detection keeps working, without the community list.Sources #
My progress
Sign in to track your progress and take notes. Sign in
Recommended Articles
CrowdSec bouncers: principles and firewall bouncer
Understanding CrowdSec bouncers: where to block, live and stream modes, API keys, decisions API, ...
CrowdSec bouncers: Cloudflare, network devices, Kubernetes and custom bouncer
Block at the CDN with Cloudflare Workers, feed pfSense or MikroTik with Blocklist Mirror, protect...
CrowdSec collections, parsers and scenarios
The Hub, collections, the parser pipeline and scenarios: install, understand with cscli explain, ...
CrowdSec in production: best practices
Good habits for running CrowdSec in production: LAPI, keys, false positives, database, upgrades a...
CrowdSec or Fail2ban: what are the differences?
Comparing CrowdSec and Fail2ban: detection, blocking, sharing, performance, multi-server, and how...
Protecting Traefik with CrowdSec: the bouncer plugin
Setting up the CrowdSec bouncer in Traefik: plugin, middleware, stream and live modes, real IP be...
CrowdSec bouncers for Nginx, Apache and HAProxy
Setting up CrowdSec bouncers for Nginx, OpenResty, Apache and HAProxy SPOA: configuration, block ...
Installing and configuring CrowdSec: packages, Docker, acquisition
Install CrowdSec with packages or Docker, understand its files, declare the logs to read, enroll ...
Les plugins Traefik : l'exemple de CrowdSec pour bloquer les attaques
Étendre Traefik avec des plugins (catalogue officiel, interpréteur Yaegi), puis protéger ses appl...