Charon/docs/security.md

Security Features

Charon includes Cerberus, a security system that protects your websites. It's enabled by default so your sites are protected from the start.

You can disable it in System Settings → Optional Features if you don't need it, or configure it using this guide.

---

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:

1. CrowdSec — Blocks bad IP addresses
2. WAF (Web Application Firewall) — Blocks bad requests
3. 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.

1. Go to Access Lists
2. Click Add List
3. Name it "US Only"
4. Type: Geo Whitelist
5. Countries: United States
6. 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.

1. Create an access list
2. Type: Local Network Only
3. 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.

1. Create a list
2. Type: Geo Blacklist
3. Pick the country
4. Assign to the targeted website

---

Certificate Management Security

What it protects: Certificate deletion is a destructive operation that requires proper authorization.

How it works:

• Certificates cannot be deleted while in use by proxy hosts (conflict error)
• Automatic backup is created before any certificate deletion
• Authentication required (when auth is implemented)

Backup & Recovery:

• Every certificate deletion triggers an automatic backup
• Find backups in the "Backups" page
• Restore from backup if you accidentally delete the wrong certificate

Best Practice:

• Review which proxy hosts use a certificate before deleting it
• When deleting proxy hosts, use the cleanup prompt to delete orphaned certificates
• Keep custom certificates you might reuse later

---

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

1. Go to Settings → Security
2. Find "Admin Whitelist"
3. Add your IP address (find it at ifconfig.me)
4. Save

Now you can never accidentally block yourself.

Break-Glass Token (Emergency Exit)

If you do lock yourself out:

1. Log into your server directly (SSH)
2. 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

1. Go to Security → Decisions in the sidebar
2. You'll see a list of recent blocks
3. If you see activity, it's working!

---

Turn It Off

If security is causing problems:

Option 1: Via Web UI

1. Go to Settings → Security
2. 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

---

Zero-Day Protection

What We Protect Against

Web Application Exploits:

• ✅ SQL Injection (SQLi) — even zero-days using SQL syntax
• ✅ Cross-Site Scripting (XSS) — new XSS vectors caught by pattern matching
• ✅ Remote Code Execution (RCE) — command injection patterns
• ✅ Path Traversal — attempts to read system files
• ⚠️ CrowdSec — protects hours/days after first exploitation (crowd-sourced)

How It Works

The WAF (Coraza) uses the OWASP Core Rule Set to detect attack patterns. Even if the exploit is brand new, the pattern is usually recognizable.

Example: A zero-day SQLi exploit discovered today:

https://yourapp.com/search?q=' OR '1'='1

• Pattern: ' OR '1'='1 matches SQL injection signature
• Action: WAF blocks request → attacker never reaches your database

What We DON'T Protect Against

• ❌ Zero-days in Charon itself (keep Charon updated)
• ❌ Zero-days in Docker, Linux kernel (keep OS updated)
• ❌ Logic bugs in your application code (need code reviews)
• ❌ Insider threats (need access controls + auditing)
• ❌ Social engineering (need user training)

Recommendation: Defense in Depth

1. Enable all Cerberus layers:

   • CrowdSec (IP reputation)
   • ACLs (restrict access by geography/IP)
   • WAF (request inspection)
   • Rate Limiting (slow down attacks)

2. Keep everything updated:

   • Charon (watch GitHub releases)
   • Docker images (rebuild regularly)
   • Host OS (enable unattended-upgrades)

3. Monitor security logs:

   • Check "Security → Decisions" weekly
   • Set up alerts for high block rates

---

More Technical Details

Want the nitty-gritty? See Cerberus Technical Docs.