3eadb2bee3
- Added comprehensive tests for CrowdSec configuration, including preset application and validation error handling. - Introduced new test cases for importing CrowdSec configurations, ensuring backup creation and successful import. - Updated existing tests to reflect changes in UI elements and functionality, including toggling CrowdSec mode and exporting configurations. - Created utility functions for building export filenames and handling downloads, improving code organization and reusability. - Refactored existing tests to use new test IDs and ensure accurate assertions for UI elements and API calls.
336 lines
9.0 KiB
Markdown
336 lines
9.0 KiB
Markdown
# 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. The sidebar now shows **Cerberus → Dashboard**; the page header reads **Cerberus Dashboard**.
|
|
|
|
Want the quick reference? See https://wikid82.github.io/charon/security.
|
|
|
|
---
|
|
|
|
## 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`:
|
|
|
|
```yaml
|
|
environment:
|
|
- CERBERUS_SECURITY_WAF_MODE=monitor
|
|
- CERBERUS_SECURITY_CROWDSEC_MODE=local
|
|
```
|
|
|
|
Restart Charon:
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```yaml
|
|
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
|
|
|
|
- **Web UI:** The Cerberus Dashboard shows a single **Start/Stop** toggle. Use it to run or stop CrowdSec; there is no separate mode selector.
|
|
- **Configuration page:** Uses a simple **Disabled / Local** toggle (no Mode dropdown). Choose Local to run the embedded CrowdSec agent.
|
|
- **Environment variables (optional):**
|
|
|
|
```yaml
|
|
environment:
|
|
- CERBERUS_SECURITY_CROWDSEC_MODE=local
|
|
```
|
|
|
|
That's it. CrowdSec starts automatically and begins blocking bad IPs.
|
|
|
|
**What you'll see:** The Cerberus pages show 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
|
|
|
|
```yaml
|
|
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
|
|
|
|
---
|
|
|
|
## Configuration Packages
|
|
|
|
- **Import/Export:** You can import or export Cerberus configuration packages; exports prompt you to confirm the filename before saving.
|
|
- **Presets (CrowdSec Hub):** Pull presets from the CrowdSec Hub over HTTPS using cache keys/ETags, prefer `cscli` execution, and require Cerberus to be enabled with an admin-scoped session. Workflow: pull → preview → apply with an automatic backup and reload flag.
|
|
- **Fallbacks:** If the Hub is unreachable (503 uses retry or cached data), curated/offline presets stay available; invalid slugs return a 400 with validation detail; apply failures remind you to restore from the backup; if apply is not supported (501), stay on curated/offline presets.
|
|
|
|
---
|
|
|
|
## 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](https://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:
|
|
|
|
```bash
|
|
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](cerberus.md).
|