documents/CROWDSEC-CLOUDFLARE-WORKER.md
Rama main · réplica de lectura del repositorio original.
# CrowdSec + Cloudflare Workers bouncer
[Documentation](README.md)
This guide shows how to take **decisions from your CrowdSec engine** (running in the `stacks/crowdsec` stack) and **enforce them at Cloudflare's edge** using the **Cloudflare Workers bouncer**.
- Requests from bad IPs can be **blocked or challenged at Cloudflare** before they reach your tunnel or Caddy.
- This complements, not replaces, Cloudflare Access / SSO and your existing Caddy configuration.
- Examples below are **sanitized** – replace placeholder tokens, keys, and hostnames with your own values on the host. Do **not** commit those secrets to git.
---
## When to use this
Use the Cloudflare Workers bouncer if:
- You already expose services through **Cloudflare Tunnel** or `*.yourdomain.com` DNS.
- You want CrowdSec detections (SSH brute force, HTTP abuse, scanners, etc.) to result in **Cloudflare firewall actions** (block or challenge).
- You prefer bans to happen at the **edge** instead of only on your homelab host.
If you only ever access services on your LAN and don't use Cloudflare for them, you may not need this bouncer.
---
## Prerequisites
- **CrowdSec stack running** from this repo (`stacks/crowdsec`):
- LAPI is exposed on the host as `http://127.0.0.1:8080/` via the compose file.
- You've configured at least some **acquisitions** (Caddy logs, SSH logs, Docker logs, etc.) and installed appropriate **collections**.
- **Cloudflare**:
- A Cloudflare account that manages the zones you want to protect (e.g. your homelab domain).
- A Cloudflare **API token** with permissions for Workers, Workers KV, Zones, and Firewall rules.
- **Linux host**:
- The same machine that runs Docker and the CrowdSec container.
- Ability to install packages and run `systemctl` (or equivalent service manager).
> All tokens and keys in this guide are examples only. Keep real values on your host under `/etc/crowdsec/bouncers/` or a secrets manager – never in this repo.
---
## 1. Install the Cloudflare Workers bouncer
On the Docker host (not in a container), install the **Cloudflare Workers bouncer** package:
```bash
# Example for Debian/Ubuntu
sudo apt update
sudo apt install crowdsec-cloudflare-worker-bouncer
# Example for RHEL/CentOS/Fedora
sudo yum install crowdsec-cloudflare-worker-bouncer
```
See the official docs for up‑to‑date package names and supported distributions:
- Cloudflare Workers bouncer docs: https://docs.crowdsec.net/u/bouncers/cloudflare-workers/
---
## 2. Create a Cloudflare API token
In the Cloudflare dashboard (SANITIZED outline):
1. Go to **My Profile → API Tokens**.
2. Create a token with:
- Permissions to manage **Workers**, **Workers KV**, **Zones**, and **Firewall rules**.
- Scope limited to the account/zones you want to protect.
3. Copy the token (for example: `CLOUDFLARE_API_TOKEN_EXAMPLE`).
Keep this token safe on the host; you will **not** commit it to git.
---
## 3. Generate the bouncer configuration
Run the bouncer once in **config generation** mode to discover your accounts/zones and create a base config:
```bash
sudo crowdsec-cloudflare-worker-bouncer \
-g CLOUDFLARE_API_TOKEN_EXAMPLE \
-o /etc/crowdsec/bouncers/crowdsec-cloudflare-worker-bouncer.yaml
```
This:
- Contacts Cloudflare using the API token.
- Writes a YAML config describing your accounts, zones, and the Workers/KV resources it will use.
Review the generated file:
```bash
sudo vi /etc/crowdsec/bouncers/crowdsec-cloudflare-worker-bouncer.yaml
```
Do **not** hardcode secrets from this file into this repo.
---
## 4. Register the bouncer with CrowdSec (LAPI key)
Your Workers bouncer needs a **LAPI key** to authenticate to the CrowdSec Local API.
From the CrowdSec host (either on the host if `cscli` is installed there, or inside the `crowdsec` container via `docker compose exec`):
```bash
# Example: add a new bouncer and get a raw key
sudo cscli -oraw bouncers add cloudflare-workers-bouncer
```
This prints a key such as:
```text
cloudflare-workers-bouncer 0123456789abcdef0123456789abcdef
```
Copy the key value (not the name).
---
## 5. Wire the bouncer to CrowdSec LAPI
Edit `/etc/crowdsec/bouncers/crowdsec-cloudflare-worker-bouncer.yaml` and set the CrowdSec section to point at your LAPI:
```yaml
crowdsec:
lapi_url: "http://127.0.0.1:8080/"
lapi_key: "REPLACE_WITH_LAPI_KEY_FROM_CSCLI"
```
Leave the `cloudflare` section (accounts/zones, Workers, KV) as generated unless you have specific needs.
Save the file and exit.
---
## 6. Start the bouncer (daemon mode)
Daemon mode keeps a small Go process running on the host that:
- Polls CrowdSec LAPI for new/expired decisions.
- Synchronizes IPs into Cloudflare Workers/KV and firewall rules.
Start and enable the service:
```bash
sudo systemctl start crowdsec-cloudflare-worker-bouncer
sudo systemctl enable crowdsec-cloudflare-worker-bouncer
```
Check that it is running without errors:
```bash
sudo systemctl status crowdsec-cloudflare-worker-bouncer
```
You should see logs indicating:
- Successful connection to CrowdSec LAPI.
- Successful setup of Workers, KV store, and Cloudflare firewall rules.
---
## 7. How this interacts with your homelab
Once the Workers bouncer is running:
- **CrowdSec** analyzes logs (Caddy, SSH, Docker containers) and emits decisions (`ban`, `challenge`, etc.).
- The **Workers bouncer** syncs those decisions to Cloudflare.
- Requests from banned IPs are **blocked or challenged at Cloudflare's edge** before they reach:
- Your Cloudflare Tunnel,
- Your Caddy instance,
- Your Docker host and apps.
This works alongside:
- **Cloudflare Access / Zero Trust** rules for SSO.
- **Caddy** routing and TLS.
CrowdSec decisions are just another signal feeding Cloudflare's firewall.
---
## 8. Maintenance and safety
- To **change** Cloudflare configuration (zones, actions, etc.), edit the YAML file and, if necessary, run the bouncer's cleanup/init flows as described in the official docs.
- To **rotate** your LAPI key:
- Remove/re‑add the bouncer with `cscli bouncers delete/add`.
- Update `lapi_key` in the bouncer config.
- Restart the service.
- To **disable** the Workers bouncer but keep CrowdSec running locally, stop and disable the service:
```bash
sudo systemctl disable --now crowdsec-cloudflare-worker-bouncer
```
All sensitive values (Cloudflare tokens, LAPI keys) stay on the host in `/etc/crowdsec/bouncers/` or a similar secure location and are **never committed to this git repo**.