Charon/docs/features/crowdsec.md

title, description

title	description
CrowdSec Integration	Behavior-based threat detection powered by a global community

CrowdSec Integration

Protect your applications using behavior-based threat detection powered by a global community of security data. Bad actors get blocked automatically before they can cause harm.

Overview

CrowdSec analyzes your traffic patterns and blocks malicious behavior in real-time. Unlike traditional firewalls that rely on static rules, CrowdSec uses behavioral analysis and crowdsourced threat intelligence to identify and stop attacks.

Key capabilities:

• Behavior Detection — Identifies attack patterns like brute-force, scanning, and exploitation
• Community Blocklists — Benefit from threats detected by the global CrowdSec community
• Real-time Blocking — Malicious IPs are blocked immediately via Caddy integration
• Automatic Updates — Threat intelligence updates continuously

Why Use This

• Proactive Defense — Block attackers before they succeed
• Zero False Positives — Behavioral analysis reduces incorrect blocks
• Community Intelligence — Leverage data from thousands of CrowdSec users
• GUI-Controlled — Enable/disable directly from the UI, no environment variables needed

Configuration

Enabling CrowdSec

1. Navigate to Settings → Security
2. Toggle CrowdSec Protection to enabled
3. CrowdSec starts automatically and persists across container restarts

No environment variables or manual configuration required.

Hub Presets

Access pre-built security configurations from the CrowdSec Hub:

1. Go to Settings → Security → Hub Presets
2. Browse available collections (e.g., crowdsecurity/nginx, crowdsecurity/http-cve)
3. Search for specific parsers, scenarios, or collections
4. Click Install to add to your configuration

Popular presets include:

• HTTP Probing — Detect reconnaissance and scanning
• Bad User-Agents — Block known malicious bots
• CVE Exploits — Protection against known vulnerabilities

Console Enrollment

Connect to the CrowdSec Console for centralized management:

1. Go to Settings → Security → Console Enrollment
2. Enter your enrollment key from console.crowdsec.net
3. Click Enroll

The Console provides:

• Multi-instance management
• Historical attack data
• Alert notifications
• Blocklist subscriptions

Live Decisions

View active blocks in real-time:

1. Navigate to Security → Live Decisions
2. See all currently blocked IPs with:
   • IP address and origin country
   • Reason for block (scenario triggered)
   • Duration remaining
   • Option to manually unban

Automatic Startup & Persistence

CrowdSec settings are stored in Charon's database and synchronized with the Security Config:

• On Container Start — CrowdSec launches automatically if previously enabled
• Configuration Sync — Changes in the UI immediately apply to CrowdSec
• State Persistence — Decisions and configurations survive restarts

Troubleshooting Console Enrollment

Engine Shows "Offline" in Console

Your CrowdSec Console dashboard shows your engine as "Offline" even though it's running locally.

Why this happens:

CrowdSec sends periodic "heartbeats" to the Console to confirm it's alive. If heartbeats stop reaching the Console servers, your engine appears offline.

Quick check:

Run the diagnostic script to test connectivity:

./scripts/diagnose-crowdsec.sh

Or use the API endpoint:

curl http://localhost:8080/api/v1/cerberus/crowdsec/diagnostics/connectivity

Common causes and fixes:

Cause	Fix
Firewall blocking outbound HTTPS	Allow connections to api.crowdsec.net on port 443
DNS resolution failure	Verify nslookup api.crowdsec.net works
Proxy not configured	Set HTTP_PROXY/HTTPS_PROXY environment variables
Heartbeat service not running	Force a manual heartbeat (see below)

Force a manual heartbeat:

curl -X POST http://localhost:8080/api/v1/cerberus/crowdsec/console/heartbeat

Enrollment Token Expired or Invalid

Error messages:

• "token expired"
• "unauthorized"
• "invalid enrollment key"

Solution:

1. Log in to console.crowdsec.net
2. Navigate to Instances → Add Instance
3. Generate a new enrollment token
4. Paste the new token in Charon's enrollment form

Tokens expire after a set period. Always use a freshly generated token.

LAPI Not Started / Connection Refused

Error messages:

• "connection refused"
• "LAPI not available"

Why this happens:

CrowdSec's Local API (LAPI) needs 30-60 seconds to fully start after the container launches.

Check LAPI status:

docker exec charon cscli lapi status

If you see "connection refused":

1. Wait 60 seconds after container start
2. Check CrowdSec is enabled in the Security dashboard
3. Try toggling CrowdSec OFF then ON again

Already Enrolled Error

Error message: "instance already enrolled"

Why this happens:

A previous enrollment attempt succeeded but Charon's local state wasn't updated.

Verify enrollment:

1. Log in to console.crowdsec.net
2. Check Instances — your engine may already appear
3. If it's listed, Charon just needs to sync

Force a re-sync:

curl -X POST http://localhost:8080/api/v1/cerberus/crowdsec/console/heartbeat

Network/Firewall Issues

Symptom: Enrollment hangs or times out

Test connectivity manually:

# Check DNS resolution
nslookup api.crowdsec.net

# Test HTTPS connectivity
curl -I https://api.crowdsec.net

Required outbound connections:

Host	Port	Purpose
api.crowdsec.net	443	Console API and heartbeats
hub.crowdsec.net	443	Hub presets download

Using the Diagnostic Script

The diagnostic script checks CrowdSec connectivity and configuration in one command.

Run all diagnostics:

./scripts/diagnose-crowdsec.sh

Output as JSON (for automation):

./scripts/diagnose-crowdsec.sh --json

Use a custom data directory:

./scripts/diagnose-crowdsec.sh --data-dir /custom/path

What it checks:

• LAPI availability and health
• CAPI (Central API) connectivity
• Console enrollment status
• Heartbeat service status
• Configuration file validity

Diagnostic API Endpoints

Access diagnostics programmatically through these API endpoints:

Endpoint	Method	What It Does
/api/v1/cerberus/crowdsec/diagnostics/connectivity	GET	Tests LAPI and CAPI connectivity
/api/v1/cerberus/crowdsec/diagnostics/config	GET	Validates enrollment configuration
/api/v1/cerberus/crowdsec/console/heartbeat	POST	Forces an immediate heartbeat check

Example: Check connectivity

curl http://localhost:8080/api/v1/cerberus/crowdsec/diagnostics/connectivity

Example response:

{
  "lapi": {
    "status": "healthy",
    "latency_ms": 12
  },
  "capi": {
    "status": "reachable",
    "latency_ms": 145
  }
}

Reading the Logs

Look for these log prefixes when debugging:

Prefix	What It Means
[CROWDSEC_ENROLLMENT]	Enrollment operations (token validation, CAPI registration)
[HEARTBEAT_POLLER]	Background heartbeat service activity
[CROWDSEC_STARTUP]	LAPI initialization and startup

View enrollment logs:

docker logs charon 2>&1 | grep CROWDSEC_ENROLLMENT

View heartbeat activity:

docker logs charon 2>&1 | grep HEARTBEAT_POLLER

Common log patterns:

Log Message	Meaning
heartbeat sent successfully	Console communication working
CAPI registration failed: timeout	Network issue reaching CrowdSec servers
enrollment completed	Console enrollment succeeded
retrying enrollment (attempt 2/3)	Temporary failure, automatic retry in progress

Related

• CrowdSec Setup Guide — Beginner-friendly setup walkthrough
• Web Application Firewall — Complement CrowdSec with WAF protection
• Access Control — Manual IP blocking and geo-restrictions
• CrowdSec Troubleshooting — Extended troubleshooting guide
• Back to Features