Charon/docs/guides/crowdsec-setup.md

title, description

title	description
CrowdSec Setup Guide	A beginner-friendly guide to setting up CrowdSec with Charon for threat protection.

CrowdSec Setup Guide

Protect your websites from hackers, bots, and other bad actors. This guide walks you through setting up CrowdSec with Charon—even if you've never touched security software before.

---

What Is CrowdSec?

Imagine a neighborhood watch program, but for the internet. CrowdSec watches the traffic coming to your server and identifies troublemakers—hackers trying to guess passwords, bots scanning for vulnerabilities, or attackers probing your defenses.

When CrowdSec spots suspicious behavior, it blocks that visitor before they can cause harm. Even better, CrowdSec shares information with thousands of other users worldwide. If someone attacks a server in Germany, your server in California can block them before they even knock on your door.

What CrowdSec Catches:

• 🔓 Password guessing — Someone trying thousands of passwords to break into your apps
• 🕷️ Malicious bots — Automated scripts looking for security holes
• 💥 Known attackers — IP addresses flagged as dangerous by the global community
• 🔍 Reconnaissance — Hackers mapping out your server before attacking

---

How Charon Makes It Easy

Here's the good news: Charon handles most of the CrowdSec setup automatically. You don't need to edit configuration files, run terminal commands, or understand networking. Just flip a switch in the Settings.

What Happens Behind the Scenes

When you enable CrowdSec in Charon:

1. Charon starts the CrowdSec engine — A security service begins running inside your container
2. A "bouncer" is registered — This allows Charon to communicate with CrowdSec (more on this below)
3. Your websites are protected — Bad traffic gets blocked before reaching your apps
4. Decisions sync in real-time — You can see who's blocked in the Security dashboard

All of this happens in about 15 seconds after you flip the toggle.

---

Quick Start: Enable CrowdSec

Prerequisites:

• Charon is installed and running
• You can access the Charon web interface

Steps:

1. Open Charon in your browser (usually http://your-server:8080)
2. Click Security in the left sidebar
3. Find the CrowdSec card
4. Flip the toggle to ON
5. Wait about 15 seconds for the status to show "Active"

That's it! Your server is now protected by CrowdSec.

✨ New in Recent Versions

Charon now automatically generates and registers your bouncer key the first time you enable CrowdSec. No terminal commands needed—just flip the switch and you're protected!

Verify It's Working

After enabling, the CrowdSec card should display:

• Status: Active (with a green indicator)
• PID: A number like 12345 (this is the CrowdSec process)
• LAPI: Connected

If you see these, CrowdSec is running properly.

---

Understanding "Bouncers" (Important!)

A bouncer is like a security guard at a nightclub door. It checks each visitor's ID against a list of banned people and either lets them in or turns them away.

In CrowdSec terms:

• The CrowdSec engine decides who's dangerous and maintains the ban list
• The bouncer enforces those decisions by blocking bad traffic

Critical Point: For the bouncer to work, it needs a special password (called an API key) to communicate with the CrowdSec engine. This key must be generated by CrowdSec itself—you cannot make one up.

✅ Good News: Charon Handles This For You!

When you enable CrowdSec for the first time, Charon automatically:

1. Starts the CrowdSec engine
2. Registers a bouncer and generates a valid API key
3. Saves the key so it survives container restarts

You don't need to touch the terminal or set any environment variables.

⚠️ Common Mistake Alert

If you set CHARON_SECURITY_CROWDSEC_API_KEY=mySecureKey123 in your docker-compose.yml, it won't work. CrowdSec has never heard of "mySecureKey123" and will reject it.

Solution: Remove any manually-set API key and let Charon generate one automatically.

---

How Auto-Registration Works

When you flip the CrowdSec toggle ON, here's what happens behind the scenes:

1. Charon starts CrowdSec and waits for it to be ready
2. A bouncer is registered with the name caddy-bouncer
3. The API key is saved to /app/data/crowdsec/bouncer_key
4. Caddy connects using the saved key

Your Key Is Saved Forever

The bouncer key is stored in your data volume at:

/app/data/crowdsec/bouncer_key

This means:

• ✅ Your key survives container restarts
• ✅ Your key survives Charon updates
• ✅ You don't need to re-register after pulling a new image

Finding Your Key in the Logs

When Charon generates a new bouncer key, you'll see a formatted banner in the container logs:

docker logs charon

Look for a section like this:

╔══════════════════════════════════════════════════════════════╗
║              🔑 CrowdSec Bouncer Registered!                ║
╠══════════════════════════════════════════════════════════════╣
║  Your bouncer API key has been auto-generated.               ║
║  Key saved to: /app/data/crowdsec/bouncer_key                ║
╚══════════════════════════════════════════════════════════════╝

Providing Your Own Key (Advanced)

If you prefer to use your own pre-registered bouncer key, you still can! Environment variables take priority over auto-generated keys:

environment:
  - CHARON_SECURITY_CROWDSEC_API_KEY=your-pre-registered-key

⚠️ Important: This key must be registered with CrowdSec first using cscli bouncers add. See Manual Bouncer Registration for details.

---

Viewing Your Bouncer Key in the UI

Need to see your bouncer key? Charon makes it easy:

1. Open Charon and go to Security
2. Look at the CrowdSec card
3. Your bouncer key is displayed (masked for security)
4. Click the copy button to copy the full key to your clipboard

This is useful when:

• 🔧 Troubleshooting connection issues
• 📋 Sharing the key with another application
• ✅ Verifying the correct key is in use

---

Environment Variables Reference

Here's everything you can configure for CrowdSec. For most users, you don't need to set any of these—Charon's defaults work great.

Safe to Set

Variable	Description	Default	When to Use
CHARON_SECURITY_CROWDSEC_CONSOLE_KEY	Your CrowdSec Console enrollment token	None	When enrolling in CrowdSec Console (optional)

Do NOT Set Manually

Variable	Description	Why You Should NOT Set It
CHARON_SECURITY_CROWDSEC_API_KEY	Bouncer authentication key	Must be generated by CrowdSec, not invented
CHARON_SECURITY_CROWDSEC_API_URL	LAPI address	Uses correct default (port 8085 internally)
CHARON_SECURITY_CROWDSEC_MODE	Enable/disable mode	Use GUI toggle instead

Correct Docker Compose Example

services:
  charon:
    image: ghcr.io/wikid82/charon:latest
    container_name: charon
    restart: unless-stopped
    ports:
      - "8080:8080"   # Charon web interface
      - "80:80"       # HTTP traffic
      - "443:443"     # HTTPS traffic
    volumes:
      - ./data:/app/data
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      - CHARON_ENV=production
      # ✅ CrowdSec is enabled via the GUI, no env vars needed
      # ✅ API key is auto-generated, never set manually

---

Manual Bouncer Registration

In rare cases, you might need to register the bouncer manually. This is useful if:

• You're recovering from a broken configuration
• Automatic registration failed
• You're debugging connection issues

Step 1: Access the Container Terminal

docker exec -it charon bash

Step 2: Register the Bouncer

cscli bouncers add caddy-bouncer

CrowdSec will output an API key. It looks something like this:

Api key for 'caddy-bouncer':

   f8a7b2c9d3e4a5b6c7d8e9f0a1b2c3d4

Please keep it safe, you won't be able to retrieve it!

Step 3: Verify Registration

cscli bouncers list

You should see caddy-bouncer in the list.

Step 4: Restart Charon

Exit the container and restart:

exit
docker restart charon

Step 5: Re-enable CrowdSec

Toggle CrowdSec OFF and then ON again in the Security dashboard. Charon will detect the registered bouncer and connect.

---

CrowdSec Console Enrollment (Optional)

The CrowdSec Console is a free online dashboard where you can:

• 📊 View attack statistics across all your servers
• 🌍 See threats on a world map
• 🔔 Get email alerts about attacks
• 📡 Subscribe to premium blocklists

Getting Your Enrollment Key

1. Go to app.crowdsec.net and create a free account
2. Click Engines in the sidebar
3. Click Add Engine
4. Copy the enrollment key (a long string starting with clapi-)

Enrolling Through Charon

1. Open Charon and go to Security
2. Click on the CrowdSec card to expand options
3. Find Console Enrollment
4. Paste your enrollment key
5. Click Enroll

Within 60 seconds, your instance should appear in the CrowdSec Console.

Enrollment via Command Line

If the GUI enrollment isn't working:

docker exec -it charon cscli console enroll YOUR_ENROLLMENT_KEY

Replace YOUR_ENROLLMENT_KEY with the key from your Console.

---

Troubleshooting

"Access Forbidden" Error

Symptom: Logs show "API error: access forbidden" when CrowdSec tries to connect.

Cause: The bouncer API key is invalid or was never registered with CrowdSec.

Solution:

1. Check if you're manually setting an API key:

   grep -i "crowdsec_api_key" docker-compose.yml
   

2. If you find one, remove it:

   # REMOVE this line:
   - CHARON_SECURITY_CROWDSEC_API_KEY=anything
   

3. Follow the Manual Bouncer Registration steps above

4. Restart the container:

   docker restart charon
   

---

"Connection Refused" to LAPI

Symptom: CrowdSec shows "connection refused" errors.

Cause: CrowdSec is still starting up (takes 30-60 seconds) or isn't running.

Solution:

1. Wait 60 seconds after container start

2. Check if CrowdSec is running:

   docker exec charon cscli lapi status
   

3. If you see "connection refused," try toggling CrowdSec OFF then ON in the GUI

4. Check the logs:

   docker logs charon | grep -i crowdsec
   

---

Bouncer Status Check

To see all registered bouncers:

docker exec charon cscli bouncers list

You should see caddy-bouncer with a "validated" status.

---

How to Delete and Re-Register a Bouncer

If the bouncer is corrupted or misconfigured:

# Delete the existing bouncer
docker exec charon cscli bouncers delete caddy-bouncer

# Register a fresh one
docker exec charon cscli bouncers add caddy-bouncer

# Restart
docker restart charon

---

Console Shows Engine "Offline"

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

Cause: Network issues preventing heartbeats from reaching CrowdSec servers.

Check connectivity:

# Test DNS
docker exec charon nslookup api.crowdsec.net

# Test HTTPS connection
docker exec charon curl -I https://api.crowdsec.net

Required outbound connections:

Host	Port	Purpose
api.crowdsec.net	443	Console heartbeats
hub.crowdsec.net	443	Security preset downloads

If you're behind a corporate firewall, you may need to allow these connections.

---

Advanced Configuration

Using an External CrowdSec Instance

If you already run CrowdSec separately (not inside Charon), you can connect to it.

⚠️ Warning: This is an advanced configuration. Most users should use Charon's built-in CrowdSec.

📝 Note: Auto-Registration Doesn't Apply Here

The auto-registration feature only works with Charon's built-in CrowdSec. When connecting to an external CrowdSec instance, you must manually register a bouncer and provide the key.

Steps:

1. Register a bouncer on your external CrowdSec:

   cscli bouncers add charon-bouncer
   

2. Save the API key that's generated (you won't see it again!)

3. In your docker-compose.yml:

   environment:
     - CHARON_SECURITY_CROWDSEC_API_URL=http://your-crowdsec-server:8080
     - CHARON_SECURITY_CROWDSEC_API_KEY=your-generated-key
   

4. Restart Charon:

   docker restart charon
   

Why manual registration is required:

Charon cannot automatically register a bouncer on an external CrowdSec instance because:

• It doesn't have terminal access to the external server
• It doesn't know the external CrowdSec's admin credentials
• The external CrowdSec may have custom security policies

---

Installing Security Presets

CrowdSec offers pre-built detection rules called "presets" from their Hub. Charon includes common ones by default, but you can add more:

1. Go to Security → CrowdSec → Hub Presets
2. Browse or search for presets
3. Click Install on the ones you want

Popular presets:

• crowdsecurity/http-probing — Detect reconnaissance scanning
• crowdsecurity/http-bad-user-agent — Block known malicious bots
• crowdsecurity/http-cve — Protect against known vulnerabilities

---

Viewing Active Blocks (Decisions)

To see who's currently blocked:

In the GUI:

1. Go to Security → Live Decisions
2. View blocked IPs, reasons, and duration

Via Command Line:

docker exec charon cscli decisions list

---

Manually Banning an IP

If you want to block someone immediately:

GUI:

1. Go to Security → CrowdSec
2. Click Add Decision
3. Enter the IP address
4. Set duration (e.g., 24h)
5. Click Ban

Command Line:

docker exec charon cscli decisions add --ip 1.2.3.4 --duration 24h --reason "Manual ban"

---

Unbanning an IP

If you accidentally blocked a legitimate user:

docker exec charon cscli decisions delete --ip 1.2.3.4

---

Summary

Task	Method
Enable CrowdSec	Toggle in Security dashboard
Verify it's running	Check for "Active" status in dashboard
Fix "access forbidden"	Remove hardcoded API key, let Charon generate one
Register bouncer manually	docker exec charon cscli bouncers add caddy-bouncer
Enroll in Console	Paste key in Security → CrowdSec → Console Enrollment
View who's blocked	Security → Live Decisions

---

Related Guides

• Web Application Firewall (WAF) — Additional application-layer protection
• Access Control Lists — Manual IP blocking and GeoIP rules
• Rate Limiting — Prevent abuse by limiting request rates
• CrowdSec Feature Documentation — Detailed feature reference

---

Need Help?

• 📖 Full Documentation
• 🐛 Report an Issue
• 💬 Community Discussions