CrowdSec Installation: Collaborative Security

CrowdSec is a modern, collaborative intrusion detection and prevention system designed specifically for web servers and online services. Unlike traditional IDS solutions, CrowdSec leverages crowdsourced threat intelligence, allowing users to share and receive threat information from a global community. This guide walks you through installing CrowdSec on your Linux server, configuring security scenarios, deploying bouncers for Nginx and iptables, accessing the console, and integrating community blocklists for enhanced protection.

Table of Contents

System Requirements

CrowdSec requires minimal resources and runs efficiently on VPS and baremetal servers. Ensure your system meets these prerequisites:

  • Linux kernel 4.15 or newer
  • At least 512 MB RAM (1 GB recommended)
  • 100 MB disk space for application and logs
  • systemd for service management
  • Internet connectivity for threat intelligence sharing

Supported distributions include Ubuntu 18.04+, Debian 10+, CentOS 7+, and other modern Linux distributions. Verify your system version:

lsb_release -a
uname -r
free -h
df -h /

Installation

Begin by installing CrowdSec from the official package repositories. The installation process is streamlined for most distributions.

For Ubuntu and Debian:

curl -s https://packagecloud.io/install/repositories/crowdsec/crowdsec/script.deb.sh | sudo bash
sudo apt-get update
sudo apt-get install -y crowdsec

For CentOS and RHEL:

curl -s https://packagecloud.io/install/repositories/crowdsec/crowdsec/script.rpm.sh | sudo bash
sudo yum install -y crowdsec

For Fedora:

sudo dnf install -y crowdsec

After installation, enable and start the CrowdSec service:

sudo systemctl enable crowdsec
sudo systemctl start crowdsec
sudo systemctl status crowdsec

Verify the installation by checking the version:

sudo crowdsec -version

The installation creates several key directories. Examine the configuration structure:

ls -la /etc/crowdsec/
ls -la /var/lib/crowdsec/
ls -la /var/log/crowdsec/

Configuration Basics

CrowdSec's primary configuration file is located at /etc/crowdsec/config.yaml. This file controls logging, database settings, API configuration, and plugin behavior. Let's examine and modify the default configuration:

sudo cat /etc/crowdsec/config.yaml

The default configuration typically includes support for Linux log monitoring. Ensure your config specifies the correct log sources. Edit the configuration file to add custom data sources if needed:

sudo nano /etc/crowdsec/config.yaml

Key configuration sections include:

  • common: Shared settings like log level and configuration path
  • crowdsec: Core engine settings for processing speed and capacity
  • cscli: Command-line client configuration
  • db: Database backend selection (SQLite by default)
  • api: API server settings for bouncer communication

Test your configuration for syntax errors:

sudo crowdsec -dry-run

View real-time logs to monitor CrowdSec activity:

sudo tail -f /var/log/crowdsec/crowdsec.log

Security Scenarios

Scenarios are rule files that detect malicious behavior patterns. CrowdSec comes with default scenarios covering common attacks like SSH brute force, HTTP probing, and SQL injection attempts. List installed scenarios:

sudo cscli scenarios list

Install additional scenarios from the hub. Common recommended scenarios include:

sudo cscli scenarios install crowdsecurity/http-cve-2021-41773
sudo cscli scenarios install crowdsecurity/ssh-bf
sudo cscli scenarios install crowdsecurity/http-generic-log4shell

Enable a scenario after installation:

sudo cscli scenarios enable crowdsecurity/ssh-bf

Check the status of scenarios:

sudo cscli scenarios status

View detailed information about a specific scenario:

sudo cscli scenarios describe crowdsecurity/ssh-bf

Restart CrowdSec to apply scenario changes:

sudo systemctl restart crowdsec

Create a custom scenario for your specific needs. Scenarios are written in YAML and use pattern matching against logs. Create a new scenario file:

sudo nano /etc/crowdsec/scenarios/custom-attack.yaml

Example custom scenario content:

name: crowdsecurity/custom-api-attack
description: "Detect excessive API requests from single source"
type: leaky
filter: "evt.Parsed.method == 'POST' && evt.Parsed.uri startsWith '/api'"
groupby: "evt.Meta.source_ip"
capacity: 5
duration: 10m

Installing and Configuring Bouncers

Bouncers are enforcement tools that block malicious IPs detected by CrowdSec. They sit between CrowdSec and the actual enforcement mechanism (firewall, reverse proxy, etc.). Install the bouncer packages:

For Ubuntu/Debian:

sudo apt-get install -y crowdsec-firewall-bouncer
sudo apt-get install -y crowdsec-nginx-bouncer

For CentOS/RHEL:

sudo yum install -y crowdsec-firewall-bouncer
sudo yum install -y crowdsec-nginx-bouncer

List available bouncers:

sudo cscli bouncers list

Each bouncer requires registration with CrowdSec before operation. Generate an API token for each bouncer:

sudo cscli bouncers add crowdsec-firewall-bouncer

This creates a unique token that the bouncer uses to communicate with CrowdSec. Store this token securely as it's needed for bouncer configuration.

Nginx Bouncer

The Nginx bouncer integrates directly with Nginx to block malicious requests before they reach your application. First, ensure Nginx is installed:

sudo apt-get install -y nginx

Configure the Nginx bouncer by editing its configuration file:

sudo nano /etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf

Add your bouncer token and set the CrowdSec API endpoint:

API_URL=http://127.0.0.1:8080
API_KEY=your_bouncer_api_key_here
ORIGIN_DOMAIN=localhost
ORIGIN_PORT=80

The Nginx bouncer works by intercepting requests and checking them against CrowdSec decisions. Configure Nginx to use the module. Edit your Nginx configuration:

sudo nano /etc/nginx/nginx.conf

Add the crowdsec module to the main Nginx configuration:

load_module /usr/lib/nginx/modules/ngx_crowdsec_module.so;

In your server block, add the bouncer directive:

server {
    listen 80;
    server_name example.com;
    
    crowdsec on;
    crowdsec_socket "/tmp/crowdsec.sock";
    
    location / {
        proxy_pass http://backend;
    }
}

Test the Nginx configuration:

sudo nginx -t

Reload Nginx to apply changes:

sudo systemctl reload nginx

Enable and start the bouncer service:

sudo systemctl enable crowdsec-nginx-bouncer
sudo systemctl start crowdsec-nginx-bouncer

Monitor bouncer activity:

sudo tail -f /var/log/crowdsec/nginx-bouncer.log

iptables Bouncer

The firewall bouncer provides kernel-level protection by managing iptables rules to block malicious IP addresses. Install if not already present:

sudo apt-get install -y crowdsec-firewall-bouncer

Configure the firewall bouncer:

sudo nano /etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml

Key configuration options:

crowdsec_config: /etc/crowdsec/config.yaml
crowdsec_url: http://127.0.0.1:8080
api_key: your_firewall_bouncer_token
update_frequency: 10s
monitor_interfaces:
  - eth0
  - eth1
chains:
  INPUT: DROP
  FORWARD: DROP
blacklists:
  whitelist_ips:
    - 127.0.0.1
    - 192.168.1.0/24

Enable and start the firewall bouncer:

sudo systemctl enable crowdsec-firewall-bouncer
sudo systemctl start crowdsec-firewall-bouncer

The bouncer dynamically adds iptables rules to block detected attackers. View active iptables rules:

sudo iptables -L -n
sudo iptables -L CROWDSEC -n

Save iptables rules for persistence across reboots:

sudo iptables-save > /etc/iptables/rules.v4

Monitor firewall bouncer logs:

sudo tail -f /var/log/crowdsec/firewall-bouncer.log

Test the bouncer by triggering a false detection. Generate a test alert:

sudo cscli decisions add --ip 192.0.2.1 --duration 5m --type ban

Verify the IP appears in iptables rules:

sudo iptables -L CROWDSEC -n | grep 192.0.2.1

Remove the test decision:

sudo cscli decisions delete --ip 192.0.2.1

CrowdSec Console

The CrowdSec Console provides a centralized dashboard for managing alerts, viewing statistics, and configuring advanced threat intelligence sharing. Register for a free console account at https://app.crowdsec.net.

After registration, link your server to the console by generating an enrollment token:

sudo cscli console enroll

This command displays an enrollment URL. Open it in a browser to authorize your server. The console connection is now established.

View decisions and alerts through the console:

sudo cscli decisions list

The console displays real-time alerts from your server, historical statistics, and community threat intelligence. Configure which alerts are shared with the community:

sudo cscli console status

Review console settings in the configuration:

sudo nano /etc/crowdsec/console/

Community Blocklists

CrowdSec maintains community blocklists of known malicious IPs. Subscribe to these lists to benefit from collective threat intelligence. List available blocklists:

sudo cscli lists list

Add a community blocklist:

sudo cscli lists add crowdsecurity/http-crawler-user-agents
sudo cscli lists add crowdsecurity/ips

Update blocklists manually:

sudo cscli hub update
sudo cscli lists update

Configure automatic blocklist updates in the config:

sudo nano /etc/crowdsec/config.yaml

Ensure the update frequency is set appropriately:

db:
  type: sqlite
  db_path: /var/lib/crowdsec/crowdsec.db
  update_frequency: 24h

View statistics on blocklist matches:

sudo cscli metrics

Managing Decisions

Decisions are CrowdSec's mechanism for marking IPs or ranges as blocked, validated, or allowed. View all active decisions:

sudo cscli decisions list

Manually add a decision to block an IP:

sudo cscli decisions add --ip 203.0.113.45 --duration 48h --type ban --reason "Manual block for malicious activity"

Block an entire subnet:

sudo cscli decisions add --ip 203.0.113.0/24 --duration 7d --type ban --reason "Subnet block"

Add an IP to the whitelist to prevent blocking:

sudo cscli decisions add --ip 198.51.100.5 --duration infinite --type allow

Delete a specific decision:

sudo cscli decisions delete --ip 203.0.113.45

Export decisions to JSON format:

sudo cscli decisions list -o json > decisions.json

Import decisions from external sources:

sudo cscli decisions import decisions.json

Advanced Features

CrowdSec supports various advanced configurations for enterprise deployments. Enable remote logging to send alerts to external SIEM systems:

sudo nano /etc/crowdsec/config.yaml

Configure webhook notifications for critical alerts:

api:
  server:
    listen_uri: 127.0.0.1:8080

Set up mutual TLS authentication between bouncers and CrowdSec:

sudo cscli bouncers add --tls my-bouncer

Implement custom output plugins to integrate with third-party systems:

sudo cscli plugins list

Configure horizontal scaling by deploying multiple CrowdSec instances in a cluster. Use a centralized database:

sudo nano /etc/crowdsec/config.yaml

Change database backend to remote MySQL/PostgreSQL for shared state across instances.

Conclusion

CrowdSec provides a powerful, community-driven approach to intrusion detection and prevention. By following this guide, you've learned to install CrowdSec, configure security scenarios, deploy bouncers at the Nginx and firewall levels, leverage the community console, and implement blocklists for collaborative threat protection. The modular architecture allows you to scale protections as needed, from simple HTTP protection with Nginx bouncers to comprehensive network-level blocking with firewall bouncers. Regular maintenance includes updating scenarios, monitoring alert volumes, and reviewing false positives in the console. As threats evolve, CrowdSec's community-driven approach ensures your defenses remain current with minimal manual intervention.