# CrowdSec — Open Source Collaborative Security Engine

> CrowdSec is a collaborative security engine that analyzes logs, detects attacks, and shares threat intelligence. Like fail2ban but with crowd-sourced IP reputation and modern architecture.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

## Quick Use

```bash
# Install on Linux
curl -s https://install.crowdsec.net | sudo sh
sudo apt install crowdsec crowdsec-firewall-bouncer-iptables

# Or Docker
docker run -d --name crowdsec 
  -v /var/log:/var/log:ro 
  -v crowdsec-data:/var/lib/crowdsec/data 
  -v crowdsec-config:/etc/crowdsec 
  crowdsecurity/crowdsec:latest
```

CrowdSec immediately starts analyzing logs and blocking malicious IPs.

## Intro

**CrowdSec** is an open-source, collaborative security engine that detects and blocks malicious behavior. It analyzes server logs (nginx, SSH, WordPress, etc.), identifies attack patterns, and takes remediation actions (block IPs, CAPTCHA, throttle). The key differentiator: CrowdSec shares anonymized threat signals across all users, creating a crowd-sourced IP reputation network.

With 13K+ GitHub stars and MIT license, CrowdSec is the modern replacement for fail2ban, offering better performance, crowd-sourced intelligence, and a modular architecture.

## What CrowdSec Does

- **Log Analysis**: Parse and analyze logs from nginx, Apache, SSH, WordPress, Traefik, and 100+ sources
- **Attack Detection**: Identify brute force, DDoS, web scanning, credential stuffing, and bot attacks
- **IP Blocking**: Automatically block malicious IPs via iptables, nginx, Cloudflare, or any bouncer
- **Crowd Intelligence**: Share and receive threat signals from the CrowdSec community network
- **IP Reputation**: Access crowd-sourced IP reputation database (1M+ malicious IPs)
- **Scenarios**: Customizable detection rules for any type of attack pattern
- **Bouncers**: Remediation components for firewalls, reverse proxies, CDNs, and applications
- **Console**: Web dashboard for monitoring and managing your CrowdSec fleet
- **API**: Local API for managing decisions and querying threat intelligence

## Architecture

```
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Log Sources │────▶│  CrowdSec    │────▶│  Bouncers    │
│  nginx       │     │  Engine      │     │  iptables    │
│  SSH         │     │  (Go)        │     │  nginx       │
│  WordPress   │     │              │     │  Cloudflare  │
│  Traefik     │     │  Parsers     │     │  HAProxy     │
│  Custom logs │     │  Scenarios   │     └──────────────┘
└──────────────┘     │  Decisions   │
                     └──────┬───────┘
                            │
                     ┌──────┴───────┐
                     │  CrowdSec    │
                     │  Central API │
                     │  (Community  │
                     │   Blocklists)│
                     └──────────────┘
```

## Self-Hosting

### Docker Compose

```yaml
services:
  crowdsec:
    image: crowdsecurity/crowdsec:latest
    volumes:
      - /var/log/nginx:/var/log/nginx:ro
      - /var/log/auth.log:/var/log/auth.log:ro
      - crowdsec-data:/var/lib/crowdsec/data
      - crowdsec-config:/etc/crowdsec
    environment:
      COLLECTIONS: "crowdsecurity/nginx crowdsecurity/linux crowdsecurity/sshd"
    restart: unless-stopped

  bouncer-firewall:
    image: crowdsecurity/crowdsec-firewall-bouncer-nftables:latest
    network_mode: host
    cap_add:
      - NET_ADMIN
    volumes:
      - crowdsec-bouncer:/etc/crowdsec
    depends_on:
      - crowdsec

volumes:
  crowdsec-data:
  crowdsec-config:
  crowdsec-bouncer:
```

## How It Works

### 1. Parsing (Log Analysis)

```
Nginx access log:
192.168.1.100 - - [10/Apr/2024:14:30:00] "POST /wp-login.php HTTP/1.1" 401 ...

CrowdSec parses:
  → Source IP: 192.168.1.100
  → Action: POST
  → Target: /wp-login.php
  → Status: 401 (unauthorized)
```

### 2. Detection (Scenarios)

```yaml
# Brute force scenario
type: leaky
filter: evt.Meta.log_type == 'http_access-log' && evt.Meta.http_path == '/wp-login.php' && evt.Meta.http_status == '401'
groupby: evt.Meta.source_ip
capacity: 5        # 5 failed attempts
leakspeed: 10s     # within 10 seconds
blackhole: 5m      # ban for 5 minutes
labels:
  type: wordpress_bruteforce
```

### 3. Decision (Action)

```
Alert: IP 192.168.1.100 triggered wordpress_bruteforce
Decision: Ban for 5 minutes
  → Local: iptables bouncer blocks IP
  → Community: Signal shared (anonymized)
  → Console: Alert visible in dashboard
```

### 4. Community Intelligence

```
Your CrowdSec ←→ CrowdSec Central API
  → Share: "IP X performed brute force attack"
  → Receive: Blocklist of 1M+ known malicious IPs
  → Benefit: Pre-emptively block known attackers
```

## Available Collections

```bash
# Install detection scenarios
cscli collections install crowdsecurity/nginx
cscli collections install crowdsecurity/sshd
cscli collections install crowdsecurity/linux
cscli collections install crowdsecurity/wordpress
cscli collections install crowdsecurity/traefik
cscli collections install crowdsecurity/postfix
cscli collections install crowdsecurity/dovecot
```

## Bouncers (Remediation)

| Bouncer | Action |
|---------|--------|
| iptables/nftables | Block at firewall level |
| nginx | Return 403 or CAPTCHA |
| Cloudflare | Add to CF firewall rules |
| HAProxy | Block at load balancer |
| WordPress | Block at application level |
| Traefik | Middleware plugin |
| Custom webhook | Any custom action |

## CrowdSec vs fail2ban

| Feature | CrowdSec | fail2ban |
|---------|----------|---------|
| Language | Go | Python |
| Performance | High (compiled) | Moderate |
| Community blocklist | Yes (1M+ IPs) | No |
| Architecture | Modular (parser+scenario+bouncer) | Monolithic |
| Dashboard | Web console | CLI only |
| Multi-server | Centralized API | Per-server |
| CAPTCHA option | Yes | No |
| API | REST API | No |
| Container support | Native Docker | Manual |

## FAQ

**Q: CrowdSec or fail2ban — which should I pick?**
A: If you only need basic SSH brute-force protection, fail2ban is enough. If you need multi-service protection, community threat intel, a web UI, and better performance, pick CrowdSec. Its crowdsourced IP reputation database is its biggest advantage.

**Q: Is community intel sharing safe?**
A: CrowdSec only shares anonymized attack signals (attacker IP + attack type) — it doesn't share your log contents or server info. You can opt out of community sharing, but you'll lose access to the community blocklist.

**Q: Will it accidentally block legitimate users?**
A: CrowdSec uses a "scenario"-based trigger system that requires multiple malicious actions before issuing a ban (e.g., 5 failed logins). You can allowlist IPs, tune thresholds, or use CAPTCHA instead of outright blocks to cut down false positives.

## Sources & Credits

- GitHub: [crowdsecurity/crowdsec](https://github.com/crowdsecurity/crowdsec) — 13K+ ⭐ | MIT
- Website: [crowdsec.net](https://crowdsec.net)

---
Source: https://tokrepo.com/en/workflows/crowdsec-open-source-collaborative-security-engine-ed64dcb7
Author: AI Open Source