shgew/cs-firewall-bouncer-docker
GitHub: shgew/cs-firewall-bouncer-docker
将 CrowdSec 防火墙反弹器容器化，方便在 Docker 环境中自动接收 CrowdSec 决策并下发防火墙封禁规则。
Stars: 33 | Forks: 2
# CrowdSec Firewall Bouncer Docker
[CrowdSec Firewall Bouncer](https://github.com/crowdsecurity/cs-firewall-bouncer) 的 Docker 镜像，基于 Alpine。
## 此镜像的功能
- 在容器中运行 `crowdsec-firewall-bouncer`。
- 在启动时替换 `/config/crowdsec-firewall-bouncer.yaml` 中的环境变量。
## 标签
| 标签 | 描述 |
|-----|-------------|
| `latest` | 最新稳定版本 |
| `stable` | 与 `latest` 相同 |
| `rc` | 总体最新版本（包括候选版本；当没有更新的 RC 时，等同于稳定版镜像） |
| `vX.Y.Z` | 不可变稳定版本 |
| `vX.Y.Z-rcN` | 不可变候选版本 |
| `vX.Y.Z-patchN` | 仅针对 `vX.Y.Z` 的镜像重新构建（git 标签为 `vX.Y.Z+patchN`） |
`latest` 永远不会指向候选版本。在同步后发布两个通道时，`rc` 别名可能会滞后几分钟。
## 运行时要求
- `network_mode: host`
- `cap_add: [NET_ADMIN, NET_RAW]`
- 配置文件挂载到 `/config/crowdsec-firewall-bouncer.yaml`
## Docker Compose
```
services:
crowdsec-firewall-bouncer:
image: ghcr.io/shgew/cs-firewall-bouncer-docker:stable
container_name: crowdsec-firewall-bouncer
network_mode: host
# To run as a non-root user, add: user: "1000:1000"
# and remove the security_opt block (no-new-privileges blocks file capabilities).
cap_add:
- NET_ADMIN
- NET_RAW
security_opt:
- no-new-privileges:true
environment:
API_URL: ${API_URL}
API_KEY: ${API_KEY}
volumes:
- ./config/crowdsec-firewall-bouncer.yaml:/config/crowdsec-firewall-bouncer.yaml:ro
- /etc/localtime:/etc/localtime:ro
restart: unless-stopped
```
## 配置
从上游示例配置开始：
https://github.com/crowdsecurity/cs-firewall-bouncer/blob/main/config/crowdsec-firewall-bouncer.yaml
在启动时，entrypoint 会对配置文件运行 `envsubst` (GNU gettext)。像 `${API_KEY}` 这样的占位符会被替换为容器环境变量中的值。所有 `${VAR}` 引用都会被替换；未定义的变量将变为空字符串。
示例：
- 配置: `api_key: ${API_KEY}`
- 容器环境变量: `API_KEY=abc123`
- 运行时配置: `api_key: abc123`
## 发布流程
每日同步会读取上游版本发布（稳定版和预发布版），将版本号和各架构的 sha256 校验和固定到 `versions.json` 中，进行提交，并创建一个 repo 发布。标记为预发布的版本会触发 RC 通道构建；常规版本发布会触发稳定通道构建。
需要使用 `RELEASE_TOKEN` repo secret（一个具有 `contents:write` 权限的 PAT）。GitHub 不会为使用默认 `GITHUB_TOKEN` 创建的发布触发 `release: published` 工作流事件，因此必须使用 PAT 来创建发布。
## 补丁版本
要在不更改上游二进制文件的情况下为现有的上游版本重新构建镜像：
1. 确保 `versions.json` 将目标版本作为通道的当前版本（head）。
2. 将提交标记为 `vX.Y.Z+patchN`（稳定版）或 `vX.Y.Z-rcN+patchM`（RC，作为预发布版创建）。
3. 从该标签创建 GitHub 发布。
发布工作流会拒绝非当前版本的补丁，并提示 `update versions.json first`。
## 本地测试
运行单元测试：
```
bats test/
```
构建并对稳定版镜像进行冒烟测试：
```
docker build \
--build-arg CS_FIREWALL_BOUNCER_VERSION=v0.0.34 \
--build-arg CS_TARBALL_SHA256_AMD64=sha256:8b07e08fb35a90b33eb2403eb93966679b39adb42c9cd03882de66cdf19a949f \
--build-arg CS_TARBALL_SHA256_ARM64=sha256:41899de18ad928e89de26a6fcd46ae8c7cb9a3b95369e850335106db0bf727aa \
-t local/csfb:stable-test .
scripts/smoke-test.sh local/csfb:stable-test v0.0.34
```
空运行（Dry-run）发布工作流（构建两个通道但不推送）：打开 Actions 标签页，选择“Build and Publish Docker Image”，然后通过 workflow dispatch 运行它。
空运行同步工作流（检测上游更改但不提交）：打开 Actions 标签页，选择“Check Upstream Release”，并以 `dry_run: true` 运行它。
发布后检查：
```
docker buildx imagetools inspect ghcr.io/shgew/cs-firewall-bouncer-docker:stable
```
## Firewall 后端说明
Docker Engine 默认使用 `iptables`。Docker 中的原生 `nftables` 模式仍处于[实验阶段](https://docs.docker.com/engine/network/firewall-nftables/)。
更多背景信息：https://github.com/shgew/cs-firewall-bouncer-docker/issues/6
## 许可证
本项目基于 MIT License 授权。
标签：CrowdSec, Cutter, Docker, 入侵防御, 安全防御评估, 请求拦截, 防火墙组件