DEV Community

Cover image for Behavior-Based Intrusion Prevention with CrowdSec
Mustafa ERBAY
Mustafa ERBAY

Posted on Originally published at mustafaerbay.com.tr

Behavior-Based Intrusion Prevention with CrowdSec

#guide #software

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
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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
...
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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 parsers and 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:

  1. 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
Enter fullscreen mode Exit fullscreen mode
  1. Create the CrowdSec filter file (/etc/fail2ban/filter.d/crowdsec.conf): 
   [Definition]
   failregex = ALERT  crowdsec - Detected scenario .+ from <HOST>
Enter fullscreen mode Exit fullscreen mode
  1. Restart Fail2Ban: 
   systemctl restart fail2ban
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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:

  1. Health Check: Query the CrowdSec API using curl. 
   curl -s http://localhost:8080/v1/health
Enter fullscreen mode Exit fullscreen mode

Response:

   {"status":"OK","version":"1.4.2"}
Enter fullscreen mode Exit fullscreen mode

  1. 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 the iptables -L command.

  2. 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
Enter fullscreen mode Exit fullscreen mode

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.

Diagram

⚠️ 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 -S before 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).

Official Sources

Top comments (0)