3e4323155f
- Implemented new CSS animations for UI elements including bobbing, pulsing, rotating, and spinning effects. - Integrated loading overlays in CrowdSecConfig, Login, ProxyHosts, Security, and WafConfig pages to enhance user experience during asynchronous operations. - Added contextual messages for loading states to inform users about ongoing processes. - Created tests for Login and Security pages to ensure overlays function correctly during login attempts and security operations.
5.5 KiB
Security Features
Charon includes Cerberus, a security system that protects your websites. It's turned off by default so it doesn't get in your way while you're learning.
When you're ready to turn it on, this guide explains everything.
What Is Cerberus?
Think of Cerberus as a guard dog for your websites. It has three heads (in Greek mythology), and each head watches for different threats:
- CrowdSec — Blocks bad IP addresses
- WAF (Web Application Firewall) — Blocks bad requests
- Access Lists — You decide who gets in
Turn It On (The Safe Way)
Step 1: Start in "Monitor" Mode
This means Cerberus watches but doesn't block anyone yet.
Add this to your docker-compose.yml:
environment:
- CERBERUS_SECURITY_WAF_MODE=monitor
- CERBERUS_SECURITY_CROWDSEC_MODE=local
Restart Charon:
docker-compose restart
Step 2: Watch the Logs
Check "Security" in the sidebar. You'll see what would have been blocked. If it looks right, move to Step 3.
Step 3: Turn On Blocking
Change monitor to block:
environment:
- CERBERUS_SECURITY_WAF_MODE=block
Restart again. Now bad guys actually get blocked.
CrowdSec (Block Bad IPs)
What it does: Thousands of people share information about attackers. When someone tries to hack one of them, everyone else blocks that attacker too.
Why you care: If someone is attacking servers in France, you block them before they even get to your server in California.
How to Enable It
Local Mode (Runs inside Charon):
environment:
- CERBERUS_SECURITY_CROWDSEC_MODE=local
That's it. CrowdSec starts automatically and begins blocking bad IPs.
What you'll see: The "Security" page shows blocked IPs and why they were blocked.
WAF (Block Bad Behavior)
What it does: Looks at every request and checks if it's trying to do something nasty—like inject SQL code or run JavaScript attacks.
Why you care: Even if your app has a bug, the WAF might catch the attack first.
How to Enable It
environment:
- CERBERUS_SECURITY_WAF_MODE=block
Start with monitor first! This lets you see what would be blocked without actually blocking it.
Access Lists (You Decide Who Gets In)
Access lists let you block or allow specific countries, IP addresses, or networks.
Example 1: Block a Country
Scenario: You only need access from the US, so block everyone else.
- Go to Access Lists
- Click Add List
- Name it "US Only"
- Type: Geo Whitelist
- Countries: United States
- Assign to your proxy host
Now only US visitors can access that website. Everyone else sees "Access Denied."
Example 2: Private Network Only
Scenario: Your admin panel should only work from your home network.
- Create an access list
- Type: Local Network Only
- Assign it to your admin panel proxy
Now only devices on 192.168.x.x or 10.x.x.x can access it. The public internet can't.
Example 3: Block One Country
Scenario: You're getting attacked from one specific country.
- Create a list
- Type: Geo Blacklist
- Pick the country
- Assign to the targeted website
Don't Lock Yourself Out!
Problem: If you turn on security and misconfigure it, you might block yourself.
Solution: Add your IP to the "Admin Whitelist" first.
How to Add Your IP
- Go to Settings → Security
- Find "Admin Whitelist"
- Add your IP address (find it at ifconfig.me)
- Save
Now you can never accidentally block yourself.
Break-Glass Token (Emergency Exit)
If you do lock yourself out:
- Log into your server directly (SSH)
- Run this command:
docker exec charon charon break-glass
It generates a one-time token that lets you disable security and get back in.
Recommended Settings by Service Type
Internal Admin Panels (Router, Pi-hole, etc.)
Access List: Local Network Only
Blocks all public internet traffic.
Personal Blog or Portfolio
No access list
WAF: Enabled
CrowdSec: Enabled
Keep it open for visitors, but protect against attacks.
Password Manager (Vaultwarden, etc.)
Access List: IP Whitelist (your home IP)
Or: Geo Whitelist (your country only)
Most restrictive. Only you can access it.
Media Server (Plex, Jellyfin)
Access List: Geo Blacklist (high-risk countries)
CrowdSec: Enabled
Allows friends to access, blocks obvious threat countries.
Check If It's Working
- Go to Security → Decisions in the sidebar
- You'll see a list of recent blocks
- If you see activity, it's working!
Turn It Off
If security is causing problems:
Option 1: Via Web UI
- Go to Settings → Security
- Toggle "Enable Cerberus" off
Option 2: Via Environment Variable
Remove the security lines from docker-compose.yml and restart.
Common Questions
"Will this slow down my websites?"
No. The checks happen in milliseconds. Humans won't notice.
"Can I whitelist specific paths?"
Not yet, but it's planned. For now, access lists apply to entire websites.
"What if CrowdSec blocks a legitimate visitor?"
You can manually unblock IPs in the Security → Decisions page.
"Do I need all three security features?"
No. Use what you need:
- Just starting? CrowdSec only
- Public service? CrowdSec + WAF
- Private service? Access Lists only
More Technical Details
Want the nitty-gritty? See Cerberus Technical Docs.