diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index c37e3a18..e35d1511 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -289,10 +289,10 @@ jobs:
HEADER diff --git a/docs/security.md b/docs/security.md new file mode 100644 index 00000000..1342726a --- /dev/null +++ b/docs/security.md @@ -0,0 +1,83 @@ +# Security Services + +CaddyProxyManager+ (CPM+) includes optional, high-value security integrations to protect your services. These features are disabled by default to keep the application lightweight but can be easily enabled via environment variables. + +## Available Services + +### 1. CrowdSec (Intrusion Prevention) +[CrowdSec](https://www.crowdsec.net/) is a collaborative security automation tool that analyzes logs to detect and block malicious behavior. + +**Modes:** +* **Local**: Installs the CrowdSec agent *inside* the CPM+ container. Useful for single-container setups. + * *Note*: Increases container startup time and resource usage. +* **External**: Connects to an existing CrowdSec agent running elsewhere (e.g., on the host or another container). + * *Recommended* for production or multi-server setups. + +### 2. WAF (Web Application Firewall) +Uses [Coraza](https://coraza.io/), a Go-native WAF, with the **OWASP Core Rule Set (CRS)** to protect against common web attacks (SQL Injection, XSS, etc.). + +### 3. Access Control Lists (ACL) +Allows you to define IP allow/block lists to restrict access to your services. + +### 4. Rate Limiting +Protects your services from abuse by limiting the number of requests a client can make within a specific time frame. + +--- + +## Configuration + +All security services are controlled via environment variables in your `docker-compose.yml`. + +### CrowdSec Configuration + +| Variable | Value | Description | +| :--- | :--- | :--- | +| `CPM_SECURITY_CROWDSEC_MODE` | `disabled` | (Default) CrowdSec is turned off. | +| | `local` | Installs and runs CrowdSec agent inside the container. | +| | `external` | Connects to an external CrowdSec agent. | +| `CPM_SECURITY_CROWDSEC_API_URL` | URL | (Required for `external`) e.g., `http://crowdsec:8080` | +| `CPM_SECURITY_CROWDSEC_API_KEY` | String | (Required for `external`) Your CrowdSec bouncer API key. | + +**Example (Local Mode):** +```yaml +environment: + - CPM_SECURITY_CROWDSEC_MODE=local +``` + +**Example (External Mode):** +```yaml +environment: + - CPM_SECURITY_CROWDSEC_API_URL=http://192.168.1.50:8080 + - CPM_SECURITY_CROWDSEC_API_KEY=your-bouncer-key-here +``` + +### WAF Configuration + +| Variable | Value | Description | +| :--- | :--- | :--- | +| `CPM_SECURITY_WAF_MODE` | `disabled` | (Default) WAF is turned off. | +| | `enabled` | Enables Coraza WAF with OWASP CRS. | + +**Example:** +```yaml +environment: + - CPM_SECURITY_WAF_MODE=enabled +``` + +### Rate Limiting & ACLs + +| Variable | Value | Description | +| :--- | :--- | :--- | +| `CPM_SECURITY_RATELIMIT_MODE` | `enabled` / `disabled` | Enable global rate limiting. | +| `CPM_SECURITY_ACL_MODE` | `enabled` / `disabled` | Enable IP-based Access Control Lists. | + +--- + +## Dashboard + +You can view the status of these services in the CPM+ web interface under the **Security** tab. + +* **CrowdSec**: Shows connection status and mode. +* **WAF**: Indicates if the Core Rule Set is loaded. +* **ACLs**: Manage your Block/Allow lists. +* **Rate Limits**: Configure global request limits.