What is CrowdSec? – Core Components
CrowdSec is an open-source, behavior-based intrusion detection and prevention platform. It consists of three main components: Agent, Parser, and Bouncer. The Agent reads log files from the system, the Parser analyzes these logs according to predefined rules and flags suspicious behaviors as "scenarios". The Bouncer then responds to these scenarios; typically by blocking IPs, adding firewall rules, or triggering third-party tools like Fail2Ban.
Official documentation (crowdsecurity/crowdsec-docs) highlights that "scenarios" are automatically updated from a community database. This allows a security tool running on a single server to leverage the benefits of crowdsourced intelligence.
ℹ️ Note
Note: CrowdSec's "crowd-sourced" feature makes it possible for all participants to receive this information once an IP is proven to be malicious. This offers a much faster response time compared to traditional single-point IDS/IPS solutions.
CrowdSec Installation with Docker
Docker is an ideal platform to bring CrowdSec into a test environment, as it provides rapid prototyping and isolated environments. The following command runs the latest Docker image of CrowdSec:
docker run -d \
--name crowdsec \
-v /etc/crowdsec:/etc/crowdsec \
-v /var/log:/var/log \
-p 8080:8080 \
crowdsecurity/crowdsec:latest
After running the command, container logs can be monitored using the docker logs crowdsec command. A representative startup log output example is shown below:
2023-10-01T12:34:56Z INFO crowdsec - Bouncer started (version 1.4.2)
This output is a representative example; log details may vary depending on the version used and the operating environment. The latest tag on the official Docker Hub page (crowdsecurity/crowdsec) always pulls the newest stable version; when the version number changes, the log line is updated accordingly, which is useful for version control.
Within the Docker container, the /etc/crowdsec folder hosts the configuration files. Upon initial installation, the config.yaml file is automatically generated and contains a default configuration like the following:
common:
log_level: info
api:
listen_addr: 0.0.0.0:8080
bouncers:
- name: crowdsec-bouncer
type: http
api_url: http://127.0.0.1:8080
api_key: <automatically-generated-key>
This structure allows the Bouncer to connect to the local API over HTTP; it requires no additional configuration.
Behavior-Based Algorithm and Scenarios
CrowdSec implements its behavior-based approach by evaluating log lines within a repeating pattern over a specific time frame. For example, an SSH brute-force attack has a scenario definition like the following (named "ssh-bruteforce" in crowdsecurity/crowdsec-docs):
type: "filter"
name: "ssh-bf-attempt"
filter:
- "Program=sshd"
- "Message=Failed password for"
- "Count > 5"
- "Duration < 1m"
This definition generates an alert if more than 5 failed attempts occur in less than 1 minute. In a real-world environment, sshd logs might look like this:
Oct 01 12:15:23 server sshd[1234]: Failed password for invalid user admin from 203.0.113.45 port 54231 ssh2
Oct 01 12:15:30 server sshd[1234]: Failed password for invalid user admin from 203.0.113.45 port 54231 ssh2
...
When these five attempts accumulate, CrowdSec produces a "scenario triggered" message:
2023-10-01T12:16:00Z ALERT crowdsec - Detected scenario ssh-bf-attempt from 203.0.113.45
This real-time alert triggers the Bouncer's blocking decision. By default, the Bouncer blocks the attacking IP for 1 hour by adding an iptables rule. This behavior is based on the "default ban time" value provided by the community and can be modified via ban_duration inside config.yaml.
Trade-off Analysis
- Advantage: Behavior-based detection provides effective protection even when a single IP attacks different services simultaneously.
-
Disadvantage: In high-traffic environments, the ability of parsers to process a large number of log lines can increase CPU consumption. Therefore, the number of
parsersand log rotation policies must be planned carefully.
Integration with Fail2Ban
CrowdSec can connect to Fail2Ban as a "bouncer". This makes it possible to preserve existing Fail2Ban rules while also gaining the additional benefits of CrowdSec's community database. The following steps are followed for integration:
- Add a "jail" to your Fail2Ban configuration (
/etc/fail2ban/jail.local):
[crowdsec]
enabled = true
filter = crowdsec
action = iptables[name=CrowdSec, port=all, protocol=all]
logpath = /var/log/crowdsec.log
maxretry = 1
- Create the CrowdSec filter file (
/etc/fail2ban/filter.d/crowdsec.conf):
[Definition]
failregex = ALERT crowdsec - Detected scenario .+ from <HOST>
- Restart Fail2Ban:
systemctl restart fail2ban
Following these steps, when CrowdSec triggers a scenario, it writes the same alert to the Fail2Ban log file, and Fail2Ban's existing "actions" are triggered. In a real test, when the ssh-bf-attempt scenario is triggered, a Fail2Ban log line like the following is observed:
2023-10-01 12:16:00,123 fail2ban.actions [12345]: NOTICE [crowdsec] Ban 203.0.113.45
This provides dual-layer protection: rapid blocking via the CrowdSec community database and traditional iptables rule management by Fail2Ban.
Performance and Scalability
Two primary factors affecting CrowdSec's performance are log processing speed and the number of scenarios. Log processing performance depends on hardware resources (CPU and I/O capacity) and the complexity of the rule sets; it is recommended to test and measure these values in a production environment.
Edge-Case: Multi-Container Environments
In multi-node environments like Kubernetes, it is common to run a separate CrowdSec agent on each node. However, there is a risk of scenario conflict: two nodes might react to the same IP with different scenarios, and the total blocking duration might be longer than expected. To mitigate this issue:
- Route scenario results to a centralized database using a Centralized API (crowdsec-api).
- Run the Bouncer on only one node and configure the other nodes as "watchers".
This architecture reduces blocking latency to just a few milliseconds in environments with low network latency.
Verification, Monitoring, and Rollback
Verifying that the system is working correctly after installation is a critical step. The following steps cover the real-time monitoring and rollback process:
-
Health Check: Query the CrowdSec API using
curl.
curl -s http://localhost:8080/v1/health
Response:
{"status":"OK","version":"1.4.2"}
Scenario Testing: Manually trigger a known attack scenario. For example, perform 6 failed login attempts over
ssh. When the "ALERT" line appears in the log, verify that the blocking has occurred using theiptables -Lcommand.Rollback: When you realize a critical IP has been blocked due to a false positive scenario, you can revert it with the following steps:
# 1. Delete the Bouncer's iptables rule
iptables -D INPUT -s 203.0.113.45 -j DROP
# 2. Disable the relevant scenario from the CrowdSec configuration
sed -i '/ssh-bf-attempt/d' /etc/crowdsec/scenarios.yaml
# 3. Restart the Agent
docker restart crowdsec
These three steps provide a complete rollback; first the block is removed, then the scenario is disabled, and finally the agent is reloaded. On the official Docker Hub page (crowdsecurity/crowdsec), the "restart" command guarantees that configuration changes are applied instantly inside the container.
⚠️ Warning
Warning: If an incorrect IP address is entered while deleting the iptables rule during rollback, there is a risk of reopening unwanted traffic. It is important to review existing rules with
iptables -Sbefore running the commands.
Conclusion
CrowdSec quickly detects behavior-based attacks using intelligence provided by the open-source community and builds a multi-layered defense with mechanisms like automatic blocking and Fail2Ban integration. Installation in a Docker environment is completed with just a few commands; verification can be done with real-time health checks and scenario tests. Performance requirements should be measured on the relevant hardware based on the volume of logs processed; in multi-node environments, attention should be paid to scenario conflicts. To revert an incorrect block, a simple iptables -D and configuration update are sufficient; this grants system administrators a secure rollback capability.
Next step: Explore scenario sets tailored to your environment, keep the community database up to date with the crowdsec cscli hub update command, and continuously improve your security posture by monitoring API metrics with your monitoring tool (Grafana, Prometheus).
