# CrowdSec Security Engine

> Collaborative security engine with crowdsourced threat intelligence.

- Category: Security & Networking
- Difficulty: intermediate
- Components: crowdsec, crowdsec-bouncer, metabase, postgresql
- Tags: crowdsec, security, firewall, threat-intelligence, ids
- Source: https://docker.recipes/security/crowdsec-firewall

## Overview

CrowdSec is a modern, open-source Intrusion Detection System (IDS) that revolutionizes network security through collaborative threat intelligence. Born from the need to address evolving cyber threats, CrowdSec operates on a crowdsourced security model where detection signals from the global community are aggregated and shared to identify malicious actors in real-time. Unlike traditional security solutions that work in isolation, CrowdSec creates a collective intelligence network where blocked IPs and attack patterns from one installation protect all users in the ecosystem. This Docker stack combines CrowdSec's security engine with PostgreSQL for metrics storage, Metabase for comprehensive analytics dashboards, and multiple bouncers including Traefik integration and firewall-level protection. The PostgreSQL database serves as the central repository for security events, decision logs, and behavioral analytics, while Metabase transforms this raw security data into actionable insights through customizable dashboards and reporting. This configuration creates a complete security operations center capable of real-time threat detection, automated response, and detailed forensic analysis, making enterprise-grade security accessible to organizations of all sizes.

## Features

- Collaborative threat intelligence with real-time IP reputation updates from the global CrowdSec community
- Multi-layer bouncer architecture supporting both Traefik reverse proxy integration and iptables firewall enforcement
- PostgreSQL-backed metrics storage with full ACID compliance for reliable security event logging and analysis
- Metabase business intelligence integration providing customizable security dashboards and automated reporting
- Collection-based detection scenarios for Linux, Nginx, and SSH with extensible parser architecture
- RESTful API at port 8080 for programmatic access to decisions, alerts, and community threat intelligence
- Behavioral analysis engine distinguishing between legitimate users and malicious actors through machine learning algorithms
- Hub ecosystem integration allowing installation of community-contributed parsers, scenarios, and collections

## Use cases

- Web application protection with Traefik integration for blocking malicious requests before they reach application servers
- SSH brute force protection for Linux servers with automatic IP blocking and community threat intelligence
- Multi-tenant hosting environments requiring coordinated security across multiple customer applications
- Security operations centers needing centralized threat visibility and automated incident response capabilities
- Compliance environments requiring detailed audit trails and security reporting through Metabase dashboards
- DevOps teams implementing security-first infrastructure with automated threat response and minimal false positives
- Small to medium businesses seeking enterprise-grade security without dedicated security personnel or expensive commercial solutions

## Prerequisites

- Minimum 2GB RAM recommended for PostgreSQL metrics storage and Metabase analytics processing
- Host system with iptables support and NET_ADMIN capabilities for firewall bouncer functionality
- Read access to system log files (/var/log) for CrowdSec parsers to analyze SSH, web server, and system events
- Available ports 8080 (CrowdSec API), 3000 (Metabase), and 6060 (CrowdSec metrics) for service communication
- Basic understanding of firewall rules and network security concepts for bouncer configuration
- PostgreSQL administration knowledge for database maintenance and custom metrics schema modifications

## docker-compose.yml

```yaml
services:
  crowdsec:
    image: crowdsecurity/crowdsec:latest
    ports:
      - "8080:8080"
      - "6060:6060"
    environment:
      GID: "${GID:-1000}"
      COLLECTIONS: "crowdsecurity/linux crowdsecurity/nginx crowdsecurity/sshd"
      CUSTOM_HOSTNAME: crowdsec
    volumes:
      - crowdsec_config:/etc/crowdsec
      - crowdsec_data:/var/lib/crowdsec/data
      - /var/log:/var/log:ro
    networks:
      - crowdsec-net
    restart: unless-stopped

  crowdsec-bouncer-traefik:
    image: fbonalair/traefik-crowdsec-bouncer:latest
    environment:
      CROWDSEC_BOUNCER_API_KEY: ${BOUNCER_API_KEY}
      CROWDSEC_AGENT_HOST: crowdsec:8080
      GIN_MODE: release
    depends_on:
      - crowdsec
    networks:
      - crowdsec-net
    restart: unless-stopped

  crowdsec-bouncer-firewall:
    image: crowdsecurity/cs-firewall-bouncer:latest
    environment:
      BACKEND: iptables
      API_URL: http://crowdsec:8080
      API_KEY: ${BOUNCER_API_KEY}
    cap_add:
      - NET_ADMIN
      - NET_RAW
    network_mode: host
    depends_on:
      - crowdsec
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: crowdsec_metrics
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - crowdsec-net
    restart: unless-stopped

  metabase:
    image: metabase/metabase:latest
    ports:
      - "3000:3000"
    environment:
      MB_DB_TYPE: postgres
      MB_DB_HOST: postgres
      MB_DB_PORT: 5432
      MB_DB_DBNAME: crowdsec_metrics
      MB_DB_USER: ${POSTGRES_USER}
      MB_DB_PASS: ${POSTGRES_PASSWORD}
    depends_on:
      - postgres
    networks:
      - crowdsec-net
    restart: unless-stopped

volumes:
  crowdsec_config:
  crowdsec_data:
  postgres_data:

networks:
  crowdsec-net:
    driver: bridge
```

## .env

```bash
# CrowdSec Bouncer API Key (generate with: cscli bouncers add my-bouncer)
BOUNCER_API_KEY=

# PostgreSQL
POSTGRES_USER=crowdsec
POSTGRES_PASSWORD=secure_postgres_password
```

## Usage notes

- CrowdSec API at http://localhost:8080
- Metabase dashboards at http://localhost:3000
- Generate bouncer key: docker compose exec crowdsec cscli bouncers add my-bouncer
- View decisions: docker compose exec crowdsec cscli decisions list

## Troubleshooting

- CrowdSec container fails with 'permission denied' on /var/log: Ensure Docker has read access to host log directories and GID environment variable matches host log group permissions
- Firewall bouncer exits with 'operation not permitted': Add NET_ADMIN and NET_RAW capabilities and ensure container runs with sufficient privileges for iptables manipulation
- Metabase shows 'database connection failed': Verify PostgreSQL container is fully initialized before Metabase startup and check POSTGRES_USER/POSTGRES_PASSWORD environment variables match
- No threat intelligence updates received: Check internet connectivity and ensure CrowdSec can reach api.crowdsec.net for community threat feed synchronization
- High memory usage from PostgreSQL: Implement log rotation for CrowdSec metrics tables and consider PostgreSQL memory tuning for large-scale deployments
- Traefik bouncer not blocking malicious IPs: Verify BOUNCER_API_KEY matches the key generated via 'cscli bouncers add' command and check bouncer registration status

