From a232824f641a509fcd6d8a18086e76bb74b6fd04 Mon Sep 17 00:00:00 2001 From: Jeremy Date: Wed, 26 Nov 2025 13:40:19 -0500 Subject: [PATCH 1/3] docs: add security documentation --- docs/security.md | 83 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 docs/security.md diff --git a/docs/security.md b/docs/security.md new file mode 100644 index 00000000..1e662f55 --- /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_ENABLED` | `true` / `false` | Enable global rate limiting. | +| `CPM_SECURITY_ACL_ENABLED` | `true` / `false` | 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. From 1b9cf98b9dbce5a3b50a2ffafad9e549a42438af Mon Sep 17 00:00:00 2001 From: Jeremy Date: Wed, 26 Nov 2025 13:46:37 -0500 Subject: [PATCH 2/3] docs: update security env vars to use MODE --- docs/security.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/security.md b/docs/security.md index 1e662f55..1342726a 100644 --- a/docs/security.md +++ b/docs/security.md @@ -68,8 +68,8 @@ environment: | Variable | Value | Description | | :--- | :--- | :--- | -| `CPM_SECURITY_RATELIMIT_ENABLED` | `true` / `false` | Enable global rate limiting. | -| `CPM_SECURITY_ACL_ENABLED` | `true` / `false` | Enable IP-based Access Control Lists. | +| `CPM_SECURITY_RATELIMIT_MODE` | `enabled` / `disabled` | Enable global rate limiting. | +| `CPM_SECURITY_ACL_MODE` | `enabled` / `disabled` | Enable IP-based Access Control Lists. | --- From e8f52b6d1896f2307ae99013df112acdc86aec99 Mon Sep 17 00:00:00 2001 From: Wikid82 Date: Wed, 26 Nov 2025 18:52:56 +0000 Subject: [PATCH 3/3] docs: fix navigation links for cpmp base path --- .github/workflows/docs.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) 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