Skip to main content

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.

Admin only. Enabling, disabling, and managing CrowdSec — bans, bouncer keys, rulesets, and configuration — requires an administrator account. Standard users don't see the CrowdSec controls.

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:

CauseFix
Firewall blocking outbound HTTPSAllow connections to api.crowdsec.net on port 443
DNS resolution failureVerify nslookup api.crowdsec.net works
Proxy not configuredSet HTTP_PROXY/HTTPS_PROXY environment variables
Heartbeat service not runningForce 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:

HostPortPurpose
api.crowdsec.net443Console API and heartbeats
hub.crowdsec.net443Hub 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:

EndpointMethodWhat It Does
/api/v1/cerberus/crowdsec/diagnostics/connectivityGETTests LAPI and CAPI connectivity
/api/v1/cerberus/crowdsec/diagnostics/configGETValidates enrollment configuration
/api/v1/cerberus/crowdsec/console/heartbeatPOSTForces 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:

PrefixWhat 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 MessageMeaning
heartbeat sent successfullyConsole communication working
CAPI registration failed: timeoutNetwork issue reaching CrowdSec servers
enrollment completedConsole enrollment succeeded
retrying enrollment (attempt 2/3)Temporary failure, automatic retry in progress