131 lines
5.0 KiB
Markdown
131 lines
5.0 KiB
Markdown
# Security Services Implementation Plan
|
|
|
|
## Overview
|
|
|
|
This document outlines the plan to implement a modular Security Dashboard in Charon (previously 'CPM+'). The goal is to provide optional, high-value security integrations (CrowdSec, WAF, ACLs, Rate Limiting) while keeping the core Docker image lightweight.
|
|
|
|
## Core Philosophy
|
|
|
|
1. **Optionality**: All security services are disabled by default.
|
|
2. **Environment Driven**: Activation is controlled via `CHARON_SECURITY_*` environment variables (legacy `CPM_SECURITY_*` names supported for backward compatibility).
|
|
3. **Minimal Footprint**:
|
|
* Lightweight Caddy modules (WAF, Bouncers) are compiled into the binary (negligible size impact).
|
|
* Heavy standalone agents (e.g., CrowdSec Agent) are only installed at runtime if explicitly enabled in "Local" mode.
|
|
4. **Unified Dashboard**: A single pane of glass in the UI to view status and configuration.
|
|
|
|
---
|
|
|
|
## 1. Environment Variables
|
|
|
|
We will introduce a new set of environment variables to control these services.
|
|
|
|
| Variable | Values | Description |
|
|
| :--- | :--- | :--- |
|
|
| `CHARON_SECURITY_CROWDSEC_MODE` (legacy `CPM_SECURITY_CROWDSEC_MODE`) | `disabled` (default), `local`, `external` | `local` installs agent inside container; `external` uses remote agent. |
|
|
| `CPM_SECURITY_CROWDSEC_API_URL` | URL (e.g., `http://crowdsec:8080`) | Required if mode is `external`. |
|
|
| `CPM_SECURITY_CROWDSEC_API_KEY` | String | Required if mode is `external`. |
|
|
| `CPM_SECURITY_WAF_MODE` | `disabled` (default), `enabled` | Enables Coraza WAF with OWASP Core Rule Set (CRS). |
|
|
| `CPM_SECURITY_RATELIMIT_MODE` | `disabled` (default), `enabled` | Enables global rate limiting controls. |
|
|
| `CPM_SECURITY_ACL_MODE` | `disabled` (default), `enabled` | Enables IP-based Access Control Lists. |
|
|
|
|
---
|
|
|
|
## 2. Backend Implementation
|
|
|
|
### A. Dockerfile Updates
|
|
|
|
We need to compile the necessary Caddy modules into our binary. This adds minimal size overhead but enables the features natively.
|
|
|
|
* **Action**: Update `Dockerfile` `caddy-builder` stage to include:
|
|
* `github.com/corazawaf/coraza-caddy/v2` (WAF)
|
|
* `github.com/hslatman/caddy-crowdsec-bouncer` (CrowdSec Bouncer)
|
|
|
|
### B. Configuration Management (`internal/config`)
|
|
|
|
* **Action**: Update `Config` struct to parse `CHARON_SECURITY_*` variables while still accepting `CPM_SECURITY_*` as legacy fallbacks.
|
|
* **Action**: Create `SecurityConfig` struct to hold these values.
|
|
|
|
### C. Runtime Installation (`docker-entrypoint.sh`)
|
|
|
|
To satisfy the "install locally" requirement for CrowdSec without bloating the image:
|
|
|
|
* **Action**: Modify `docker-entrypoint.sh` to check `CHARON_SECURITY_CROWDSEC_MODE` (and fallback to `CPM_SECURITY_CROWDSEC_MODE`).
|
|
* **Logic**: If `local`, execute `apk add --no-cache crowdsec` (and dependencies) before starting the app. This keeps the base image small for users who don't use it.
|
|
|
|
### D. API Endpoints (`internal/api`)
|
|
|
|
* **New Endpoint**: `GET /api/v1/security/status`
|
|
* Returns the enabled/disabled state of each service.
|
|
* Returns basic metrics if available (e.g., "WAF: Active", "CrowdSec: Connected").
|
|
|
|
---
|
|
|
|
## 3. Frontend Implementation
|
|
|
|
### A. Navigation
|
|
|
|
* **Action**: Add "Security" item to the Sidebar in `Layout.tsx`.
|
|
|
|
### B. Security Dashboard (`src/pages/Security.tsx`)
|
|
|
|
* **Layout**: Grid of cards representing each service.
|
|
* **Empty State**: If all services are disabled, show a clean "Security Not Enabled" state with a link to the GitHub Pages documentation on how to enable them.
|
|
|
|
### C. Service Cards
|
|
|
|
1. **CrowdSec Card**:
|
|
* **Status**: Active (Local/External) / Disabled.
|
|
* **Content**: If Local, show basic stats (last push, alerts). If External, show connection status.
|
|
* **Action**: Link to CrowdSec Console or Dashboard.
|
|
2. **WAF Card**:
|
|
* **Status**: Active / Disabled.
|
|
* **Content**: "OWASP CRS Loaded".
|
|
3. **Access Control Lists (ACL)**:
|
|
* **Status**: Active / Disabled.
|
|
* **Action**: "Manage Blocklists" (opens modal/page to edit IP lists).
|
|
4. **Rate Limiting**:
|
|
* **Status**: Active / Disabled.
|
|
* **Action**: "Configure Limits" (opens modal to set global requests/second).
|
|
|
|
---
|
|
|
|
## 4. Service-Specific Logic
|
|
|
|
### CrowdSec
|
|
|
|
* **Local**:
|
|
* Installs CrowdSec agent via `apk`.
|
|
* Generates `acquis.yaml` to read Caddy logs.
|
|
* Configures Caddy bouncer to talk to `localhost:8080`.
|
|
* **External**:
|
|
* Configures Caddy bouncer to talk to `CPM_SECURITY_CROWDSEC_API_URL`.
|
|
|
|
### WAF (Coraza)
|
|
|
|
* **Implementation**:
|
|
* When enabled, inject `coraza_waf` directive into the global Caddyfile or per-host.
|
|
* Use default OWASP Core Rule Set (CRS).
|
|
|
|
### IP ACLs
|
|
|
|
* **Implementation**:
|
|
* Create a snippet `(ip_filter)` in Caddyfile.
|
|
* Use `@matcher` with `remote_ip` to block/allow IPs.
|
|
* UI allows adding CIDR ranges to this list.
|
|
|
|
### Rate Limiting
|
|
|
|
* **Implementation**:
|
|
* Use `rate_limit` directive.
|
|
* Allow user to define "zones" (e.g., API, Static) in the UI.
|
|
|
|
---
|
|
|
|
## 5. Documentation
|
|
|
|
* **New Doc**: `docs/security.md`
|
|
* **Content**:
|
|
* Explanation of each service.
|
|
* How to configure Env Vars.
|
|
* Trade-offs of "Local" CrowdSec (startup time vs convenience).
|