Guide · Open source
How to use CrowdSec: setup, bouncers and blocklists
Updated · written with AI from the project's own documentation and checked against our catalogue data
CrowdSec is an open-source security engine that watches logs and web requests for suspicious behavior, such as brute-force attempts and port scans, and blocks the IP addresses responsible. It suits system administrators, teams running several servers or containers, and website operators who want a web application firewall. After this guide you will understand how its parts fit together and what you need to configure before it protects anything.
CrowdSeccrowdsecurity/crowdsec · ★ 15.4k · MIT Install options & downloads Quick start
- 1Read the documentation. Open the official CrowdSec docs and find the guide for your platform, such as Linux, Docker or Kubernetes.
- 2Install the Security Engine. Follow the platform guide to install the engine. The README's only listed command clones the repository.
- 3Configure log sources. Tell CrowdSec which logs to read, such as SSH or web server logs.
- 4Enable scenarios. Keep the default scenarios for brute force, port scan and web scan, and add others from the hub if needed.
- 5Install a bouncer. Set up a remediation component for your firewall, reverse proxy or CDN so that decisions are enforced.
- 6Decide on the community blocklist. Decide whether your setup can use the central API and the shared blocklist, then verify blocks are working.
Understand how CrowdSec is built
CrowdSec separates detection from blocking. The Security Engine analyzes log sources and HTTP requests to detect bad behavior. Remediation Components, also called bouncers, carry out the blocking, and they can run on a different machine from the engine.
The project describes itself as an all-in-one IDS/IPS and WAF. Detection rules are available on the CrowdSec hub under the MIT license.
- Security Engine: detects bad behavior from logs and HTTP requests.
- Bouncers (Remediation Components): enforce blocks, for example at a firewall, reverse proxy or CDN.
- Hub: a catalogue of scenarios and remediation components you can add.
- Console: optional web interface for visualization, management and extra blocklists.
Install CrowdSec on your platform
The README points to the official documentation for installation on Linux, Windows, Docker, OPNsense, Kubernetes and other platforms. The README lists no prerequisites, so check the documentation for what your platform needs.
The README's install command clones the source repository. Most users will instead follow the platform-specific guide at the documentation site.
git clone https://github.com/crowdsecurity/crowdsecConfigure log sources and scenarios
CrowdSec needs to know which logs to read. You configure log sources, then choose scenarios that describe attack patterns. The engine ships with default scenarios for brute force, port scan and web scan, and you can add more from the hub.
The project notes that setup requires configuration. Someone needs to decide which services to monitor and which behaviors count as attacks.
- Pick the log sources for SSH, web servers or other services you run.
- Enable the default scenarios that match your environment.
- Add extra scenarios from the hub, or adapt or write your own.
Set up a bouncer to block IPs
Detection alone does not block anything. A bouncer enforces decisions made by the engine. The README gives firewall, reverse proxy and CDN as examples of where blocking can happen, so the bouncer can sit close to the service it protects.
Because bouncers can run on other machines, you can analyze logs from several servers in one place and block at the edge of your stack.
- Choose a bouncer that matches your firewall, proxy or CDN.
- Connect it to the Security Engine so it receives block decisions.
Use the web application firewall and bot detection
The AppSec component is a WAF built on Coraza. According to the README, SecLang rules and the OWASP Core Rule Set load as they are, and CrowdSec adds a YAML rule format on top.
AppSec can also answer suspicious requests with a JavaScript proof-of-work challenge at adjustable difficulty. The README says this stops headless browsers and scrapers while letting verified crawlers such as Googlebot through.
- Load existing SecLang rules and the OWASP Core Rule Set.
- Write rules in the YAML format where you need custom logic.
- Adjust challenge difficulty for bot and scraper detection.
Use the community blocklist
Participating users can share attacks they detect with a shared community blocklist. An IP seen attacking one member can then be blocked for others. The Community Blocklist is a curated list of IP addresses identified as malicious by CrowdSec, and the Security Engine blocks those addresses proactively.
This feature depends on a central API. If your setup cannot send or receive threat data from an external service, it will not work as described.
What people use it for
- Protecting a Linux server from SSH brute-force attempts with more flexibility than fail2ban.
- Analyzing logs from several servers or containers in one place.
- Running a web application firewall and bot challenges in front of a website.
- Blocking IPs listed in the community blocklist at your firewall or proxy.
Frequently asked questions
Is CrowdSec free to use?
CrowdSec is open source under the MIT license, and its detection rules on the hub are also under MIT. The README also mentions a Console with premium features and extra blocklists, so check the project's current offering before you rely on any paid option.
What are the requirements for CrowdSec?
The README does not list prerequisites. Check the official documentation for the requirements of your platform, such as Linux, Windows, Docker or Kubernetes.
How do I install CrowdSec?
The README's install command clones the repository with git clone https://github.com/crowdsecurity/crowdsec. For a normal install, follow the platform-specific guide at docs.crowdsec.net.
Is CrowdSec a replacement for fail2ban?
CrowdSec reads the same kinds of log files and bans the same IPs as fail2ban, according to the README. Its main difference is that detection and blocking can run on different machines, and reported attacks feed a community blocklist.
Does CrowdSec work without an internet connection?
The community blocklist depends on a central API. The README says setups that cannot send or receive threat data from an external service are not a good fit, so local detection may still be useful but the shared list will not work.
How does CrowdSec compare to ModSecurity or Coraza?
ModSecurity and Coraza are WAFs. According to the README, CrowdSec's AppSec component is built on Coraza, so SecLang rules and the OWASP Core Rule Set load as they are, and CrowdSec adds log-based detection and a shared reputation layer.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
CrowdSec suits administrators who run Linux servers, multiple machines or containers, and websites that need a WAF and bot challenges. It is not a good choice if you want a one-click desktop tool, if your setup cannot use an external threat-data service, or if no one is available to configure log sources and rules.
Install options & downloads