# CrowdSec Security Engine

> CrowdSec behavior detection engine with community-driven IP blocklists.

- Category: Security & Networking
- Difficulty: intermediate
- Components: crowdsec, crowdsec-dashboard
- Tags: crowdsec, security, ids, firewall, threat-detection
- Source: https://docker.recipes/security/crowdsec-security

## Overview

CrowdSec is a modern, open-source security engine that detects aggressive behaviors and protects against attacks through collaborative intelligence. Born from the need for a more effective alternative to traditional fail2ban solutions, CrowdSec analyzes log files in real-time using behavioral detection patterns and shares threat intelligence with a global community of users. Unlike signature-based systems, CrowdSec focuses on behavioral analysis to identify malicious activities such as brute force attacks, web scraping, and DDoS attempts.

This Docker stack combines the CrowdSec security engine with a Metabase dashboard to provide comprehensive threat detection and visualization capabilities. CrowdSec processes system logs and applies collections of parsers and scenarios to detect suspicious behaviors, while automatically sharing anonymized attack signatures with the community blocklist. The Metabase dashboard connects to CrowdSec's database to provide rich visualizations of detected threats, attack patterns, and security metrics, making it easier to understand your security posture.

This configuration is ideal for system administrators managing web servers, security engineers implementing defense-in-depth strategies, and organizations wanting to participate in collaborative threat intelligence. The combination of real-time behavioral detection with community-driven IP reputation makes this stack particularly valuable for environments facing automated attacks, while the dashboard component enables data-driven security decisions and compliance reporting.

## Features

- Real-time behavioral analysis using crowdsecurity/linux and crowdsecurity/nginx collections for comprehensive threat detection
- Community-driven IP blocklist sharing with automatic contribution of anonymized attack signatures to global threat intelligence
- Metabase-powered security dashboard with customizable visualizations of attack patterns, geographic threat distribution, and temporal analysis
- SQLite-based local threat database with persistent storage for historical attack data and pattern analysis
- Multi-scenario detection engine supporting brute force, web scraping, port scanning, and application-layer attack identification
- RESTful API interface for integration with external security tools, SIEM systems, and custom automation workflows
- Bouncer architecture enabling protection deployment across multiple services including firewalls, load balancers, and web servers
- Log file monitoring with read-only access to system logs for non-intrusive security analysis

## Use cases

- Web server protection against brute force attacks on SSH, HTTP authentication, and application login endpoints
- E-commerce platform security monitoring to detect credential stuffing, card testing, and automated fraud attempts
- Multi-tenant hosting environment protection with shared threat intelligence across customer deployments
- Development team security operations providing visual attack analysis and security metrics for sprint reviews
- Compliance reporting for SOC2, PCI-DSS, or ISO27001 requirements using dashboard analytics and historical attack data
- Small business security enhancement replacing traditional fail2ban with community intelligence and modern visualization
- Homelab and self-hosted service protection with minimal configuration overhead and professional-grade threat detection

## Prerequisites

- Docker host with minimum 2GB RAM for Metabase dashboard operation and CrowdSec processing
- Access to system log files in /var/log directory with appropriate read permissions for container mounting
- Available ports 8080 and 3000 for CrowdSec API and Metabase dashboard access respectively
- Basic understanding of log analysis, IP blocking concepts, and security monitoring principles
- Network connectivity to CrowdSec community API for blocklist updates and threat intelligence sharing
- Sufficient disk space for persistent volumes storing threat databases, configuration files, and dashboard metadata

## docker-compose.yml

```yaml
services:
  crowdsec:
    image: crowdsecurity/crowdsec:latest
    container_name: crowdsec
    environment:
      - GID=1000
      - COLLECTIONS=crowdsecurity/linux crowdsecurity/nginx
    volumes:
      - crowdsec_db:/var/lib/crowdsec/data
      - crowdsec_config:/etc/crowdsec
      - /var/log:/var/log:ro
    ports:
      - "8080:8080"
    restart: unless-stopped
    networks:
      - crowdsec-network

  dashboard:
    image: metabase/metabase:latest
    container_name: crowdsec-dashboard
    environment:
      - MB_DB_TYPE=sqlite
    volumes:
      - metabase_data:/metabase-data
    ports:
      - "3000:3000"
    depends_on:
      - crowdsec
    networks:
      - crowdsec-network

volumes:
  crowdsec_db:
  crowdsec_config:
  metabase_data:

networks:
  crowdsec-network:
    driver: bridge
```

## .env

```bash
# CrowdSec
# Add collections as needed
```

## Usage notes

- CrowdSec API at http://localhost:8080
- Dashboard at http://localhost:3000
- Install bouncers on services
- Register at app.crowdsec.net
- Share blocklists with community

## Troubleshooting

- CrowdSec container exits with permission errors: Ensure /var/log directory has proper read permissions and GID=1000 matches host user group
- No threats detected despite obvious attacks: Verify log file paths in collections match actual system log locations and formats
- Metabase dashboard shows no data: Check CrowdSec database initialization by examining container logs and ensure services start in correct order
- API connection refused on port 8080: Confirm firewall rules allow traffic and CrowdSec service has fully initialized before bouncer connections
- Community blocklist updates failing: Verify outbound internet connectivity and register at app.crowdsec.net for API authentication
- High memory usage in Metabase container: Increase Docker host memory allocation or configure Metabase JVM heap settings for large datasets

