Charon/docs/plans/archive/security_features_spec.md

📋 Plan: Security Features Deep Dive - Issues #17, #18, #19

Created: December 5, 2025 Status: Analysis Complete - Implementation Assessment

---

🧐 Executive Summary

After a comprehensive analysis of the CrowdSec (#17), WAF (#18), and Rate Limiting (#19) features, the findings show that all three features are substantially implemented with working frontend UIs, backend APIs, and Caddy integration. However, each has specific gaps that need to be addressed for full production readiness.

---

📊 Implementation Status Matrix

Feature	Backend	Frontend	Caddy Integration	Testing	Status
CrowdSec (#17)	✅ 90%	✅ 90%	⚠️ 70%	⚠️ 50%	Near Complete
WAF (#18)	✅ 95%	✅ 95%	✅ 85%	✅ 80%	Near Complete
Rate Limiting (#19)	⚠️ 60%	✅ 90%	⚠️ 40%	⚠️ 30%	Needs Work

---

🔍 Issue #17: CrowdSec Integration (Critical)

What's Implemented ✅

Backend:

• CrowdSec handler (crowdsec_handler.go) with:

  • Start/Stop process control via CrowdsecExecutor interface
  • Status monitoring endpoint
  • Import/Export configuration (tar.gz)
  • File listing/reading/writing for config files
  • Routes registered at /admin/crowdsec/*

• Security handler integration:

  • security.crowdsec.mode setting (disabled/local)
  • security.crowdsec.enabled runtime override
  • CrowdSec enabled flag computed in computeEffectiveFlags()

Frontend:

• CrowdSecConfig.tsx page with:
  • Mode selection (disabled/local)
  • Import configuration (file upload)
  • Export configuration (download)
  • File editor for config files
  • Loading states and error handling

Docker:

• CrowdSec binary installed at /usr/local/bin/crowdsec
• Config directory at /app/data/crowdsec
• caddy-crowdsec-bouncer plugin compiled into Caddy

Gaps Identified ❌

1. Banned IP Dashboard - Not implemented

   • Need /api/v1/crowdsec/decisions endpoint to list banned IPs
   • Need frontend UI to display and manage banned IPs

2. Manual IP Ban/Unban - Partially implemented

   • SecurityDecision model exists but manual CrowdSec bans not wired
   • Need /api/v1/crowdsec/ban and /api/v1/crowdsec/unban endpoints

3. Scenario/Collection Management - Not implemented

   • No UI for managing CrowdSec scenarios or collections
   • Backend would need to interact with CrowdSec CLI or API

4. CrowdSec Log Parsing Setup - Not implemented

   • Need to configure CrowdSec to parse Caddy logs
   • Acquisition config not auto-generated

5. Caddy Integration Handler - Placeholder only

   • buildCrowdSecHandler() returns Handler{"handler": "crowdsec"} but Caddy's caddy-crowdsec-bouncer expects different configuration:

     {
       "handler": "crowdsec",
       "api_url": "http://localhost:8080",
       "api_key": "..."
     }
     

Acceptance Criteria Assessment

Criteria	Status
CrowdSec blocks malicious IPs automatically	⚠️ Partial - bouncer configured but handler incomplete
Banned IPs visible in dashboard	❌ Not implemented
Can manually ban/unban IPs	⚠️ Partial - backend exists but not wired
CrowdSec status visible	✅ Implemented

---

🔍 Issue #18: WAF Integration (High Priority)

What's Implemented ✅

Backend:

• SecurityRuleSet model for storing WAF rules

• SecurityConfig.WAFMode (disabled/monitor/block)

• SecurityConfig.WAFRulesSource for ruleset selection

• buildWAFHandler() generates Coraza handler config:

  h := Handler{"handler": "waf"}
  h["directives"] = fmt.Sprintf("Include %s", rulesetPath)
  

• Ruleset files written to /app/data/caddy/coraza/rulesets/

• SecRuleEngine On/DetectionOnly auto-prepended based on mode

• Security service CRUD for rulesets

Frontend:

• WafConfig.tsx with:
  • Rule set CRUD (create, edit, delete)
  • Mode selection (blocking/detection)
  • WAF presets (OWASP CRS, SQLi protection, XSS protection, Bad Bots)
  • Source URL or inline content support
  • Rule count display

Docker:

• coraza-caddy/v2 plugin compiled into Caddy

Testing:

• Integration test coraza_integration_test.go
• Unit tests for WAF handler building

Gaps Identified ❌

1. WAF Logging and Alerts - Partially implemented

   • Coraza logs to Caddy but not parsed/displayed in UI
   • No WAF-specific notifications

2. WAF Statistics Dashboard - Not implemented

   • Need metrics collection (requests blocked, attack types)
   • Prometheus metrics defined in docs but not implemented

3. Paranoia Level Selector - Not implemented

   • OWASP CRS paranoia levels (1-4) not exposed in UI
   • Would need SecAction "id:900000,setvar:tx.paranoia_level=2"

4. Per-Host WAF Toggle - Partially implemented

   • host.AdvancedConfig can reference ruleset_name but no UI
   • Need checkbox in ProxyHostForm for "Enable WAF"

5. Rule Exclusion System - Not implemented

   • No UI for excluding specific rules that cause false positives
   • Would need SecRuleRemoveById directive management

Acceptance Criteria Assessment

Criteria	Status
WAF blocks common attacks (SQLi, XSS)	✅ Working with Coraza
Can enable/disable per host	⚠️ Via advanced config only
False positives manageable	❌ No exclusion UI
WAF events logged and visible	⚠️ Logs exist but not in UI

---

🔍 Issue #19: Rate Limiting (High Priority)

What's Implemented ✅

Backend:

• SecurityConfig model fields:

  RateLimitEnable    bool
  RateLimitBurst     int
  RateLimitRequests  int
  RateLimitWindowSec int
  

• security.rate_limit.enabled setting

• buildRateLimitHandler() generates config:

  h := Handler{"handler": "rate_limit"}
  h["requests"] = secCfg.RateLimitRequests
  h["window_sec"] = secCfg.RateLimitWindowSec
  h["burst"] = secCfg.RateLimitBurst
  

Frontend:

• RateLimiting.tsx with:
  • Enable/disable toggle
  • Requests per second input
  • Burst allowance input
  • Window (seconds) input
  • Save configuration

Gaps Identified ❌

1. Caddy Rate Limit Directive - CRITICAL GAP

   • Caddy doesn't have a built-in rate_limit handler
   • Need to use caddy-ratelimit module or Caddy's respond with headers
   • Current handler is a no-op placeholder

2. Rate Limit Presets - Not implemented

   • Issue specifies presets: login, API, standard
   • Need predefined configurations

3. Per-IP Rate Limiting - Not implemented correctly

   • Handler exists but Caddy module not compiled in
   • Need github.com/mholt/caddy-ratelimit in Dockerfile

4. Per-Endpoint Rate Limits - Not implemented

   • No UI for path-specific rate limits
   • Would need rate limit rules per route

5. Bypass List (Trusted IPs) - Not implemented

   • Admin whitelist exists but not connected to rate limiting

6. Rate Limit Violation Logging - Not implemented

   • No logging when rate limits are hit

7. Rate Limit Testing Tool - Not implemented

   • No way to test rate limits from UI

Acceptance Criteria Assessment

Criteria	Status
Rate limits prevent brute force	❌ Handler is placeholder
Presets work correctly	❌ Not implemented
Legitimate traffic not affected	⚠️ No bypass list
Rate limit hits logged	❌ Not implemented

---

🤝 Handoff Contracts (API Specifications)

CrowdSec Banned IPs API

// GET /api/v1/crowdsec/decisions
{
  "response": {
    "decisions": [
      {
        "id": "uuid",
        "ip": "192.168.1.100",
        "reason": "ssh-bf",
        "duration": "4h",
        "created_at": "2025-12-05T10:00:00Z",
        "source": "crowdsec"
      }
    ],
    "total": 15
  }
}

// POST /api/v1/crowdsec/ban
{
  "request": {
    "ip": "192.168.1.100",
    "duration": "24h",
    "reason": "Manual ban - suspicious activity"
  },
  "response": {
    "success": true,
    "decision_id": "uuid"
  }
}

// DELETE /api/v1/crowdsec/ban/:ip
{
  "response": {
    "success": true
  }
}

Rate Limit Caddy Integration Fix

The rate limit handler needs to output proper Caddy JSON:

// Correct Caddy rate_limit handler format (requires caddy-ratelimit module)
{
  "handler": "rate_limit",
  "rate_limits": {
    "static": {
      "match": [{"method": ["GET", "POST"]}],
      "key": "{http.request.remote.host}",
      "window": "1m",
      "max_events": 60
    }
  }
}

---

🏗️ Implementation Phases

Phase 1: Rate Limiting Fix (Critical - Blocking Beta)

Backend Changes:

1. Add github.com/mholt/caddy-ratelimit to Dockerfile xcaddy build
2. Fix buildRateLimitHandler() to output correct Caddy JSON format
3. Add rate limit bypass using admin whitelist

Frontend Changes:

1. Add presets dropdown (Login: 5/min, API: 100/min, Standard: 30/min)
2. Add bypass IP list input (reuse admin whitelist)

Phase 2: CrowdSec Completeness (High Priority)

Backend Changes:

1. Create /api/v1/crowdsec/decisions endpoint (call cscli)
2. Create /api/v1/crowdsec/ban and unban endpoints
3. Fix buildCrowdSecHandler() to include proper bouncer config
4. Auto-generate acquisition.yaml for Caddy log parsing

Frontend Changes:

1. Add "Banned IPs" tab to CrowdSecConfig page
2. Add "Ban IP" button with duration selector
3. Add "Unban" action to each banned IP row

Phase 3: WAF Enhancements (Medium Priority)

Backend Changes:

1. Add paranoia level to SecurityConfig model
2. Add rule exclusion list to SecurityRuleSet model
3. Parse Coraza logs for WAF events

Frontend Changes:

1. Add paranoia level slider (1-4) to WAF config
2. Add "Enable WAF" checkbox to ProxyHostForm
3. Add rule exclusion UI (list of rule IDs to exclude)
4. Add WAF events log viewer

Phase 4: Testing & QA

1. Create integration tests for each feature
2. Add E2E tests for security flows
3. Manual penetration testing

---

🕵️ QA & Security Considerations

CrowdSec Security

• Ensure API key not exposed in logs
• Validate IP inputs to prevent injection
• Rate limit the ban/unban endpoints themselves

WAF Security

• Validate ruleset content (no malicious directives)
• Prevent path traversal in ruleset file paths
• Test for WAF bypass techniques

Rate Limiting Security

• Prevent bypass via IP spoofing (X-Forwarded-For)
• Ensure rate limits apply to all methods
• Test distributed rate limiting behavior

---

📚 Documentation Updates Needed

1. Update docs/cerberus.md with actual implementation status
2. Update docs/security.md user guide with new features
3. Add rate limiting configuration guide
4. Add CrowdSec setup wizard documentation

---

🎯 Priority Order

1. Rate Limiting Caddy Module - Blocking issue, handler is no-op
2. CrowdSec Banned IP Dashboard - High visibility feature
3. WAF Per-Host Toggle - User expectation from issue
4. CrowdSec Manual Ban/Unban - Security operations feature
5. WAF Rule Exclusions - False positive management
6. Rate Limit Presets - UX improvement

---

Summary: What Works vs What Doesn't

✅ Working Now

• WAF rule management and blocking (Coraza integration)
• CrowdSec process control (start/stop/status)
• CrowdSec config import/export
• Rate limiting UI and settings storage
• Security status API reporting

⚠️ Partially Working

• CrowdSec bouncer (handler exists but config incomplete)
• Per-host WAF (via advanced config only)
• Rate limiting settings (stored but not enforced)

❌ Not Working / Missing

• Rate limiting actual enforcement (Caddy module missing)
• CrowdSec banned IP dashboard
• Manual IP ban/unban
• WAF rule exclusions
• Rate limit presets
• WAF paranoia levels