guaracloud/purple-wolf

# purple-wolf 一个以 Traefik 插件形式提供的高效、低内存占用的 Web 应用防火墙。 **状态：** 已发布 v0.4.1。当前版本包含审计标签、webhook 中继分发、已签名制品、SBOM、Helm OCI 打包、Kustomize overlays、O(1) 信誉限制器、有界的 percent-decode-to-fixpoint 归一化处理、扩展的签名库、User-Agent SQLi 后缀探测、超出容量的 body 前缀检查、离线配置验证器、中继 SSRF 加固、可选的中继管理员身份验证以及全新的 fuzz 目标。v0.4.1 即使在启用中继管理员身份验证时也保持 `/readyz` 无需认证，从而确保 Kubernetes 的就绪探针正常工作。完整列表请参阅 [CHANGELOG.md](CHANGELOG.md)，了解 WAF 设计目的及局限性请参阅 [THREAT_MODEL.md](THREAT_MODEL.md)，Middleware 配置参考请参阅 [docs/configuration.md](docs/configuration.md)。webhook 协议契约位于 [docs/webhook-protocol.md](docs/webhook-protocol.md)。 ## 功能 `purple-wolf` 会检查每一个到达受其任一 Middleware 保护路由的 HTTP 请求，并决定让其通过或返回 `403 Forbidden`。 检查涵盖 headers、URL、查询参数和请求 body（上限可配置），采用混合引擎：libinjection (SQLi/XSS)、aho-corasick 字面特征签名、结构异常检查以及基于 IP 的速率限制 / 黑名单机制。 ## 架构概览 ``` internet → Traefik (TLS, routing, your existing setup) └─ loads purple-wolf.wasm once at startup └─ for each request matching a route that chains a purple-wolf Middleware: instantiate plugin with that Middleware's config → inspect → allow or block → forward to backend ``` - 三个 crate： [`purple-wolf-core`](crates/purple-wolf-core)（核心引擎，纯 Rust，支持 native + `wasm32-wasip1`）， [`purple-wolf-traefik`](crates/purple-wolf-traefik)（http-wasm guest 插件），以及 [`purple-wolf-relay`](crates/purple-wolf-relay) - 一个独立的 webhook 扇出服务，用于追踪 Traefik 的审计日志流，并向订阅者分发 HMAC 签名的事件。 - 天然支持多租户：每个 `Middleware` CRD 都是一个独立的插件实例，拥有自己的 WASM 内存切片。 - **推送分发：** WAF 专注于检测；如果您希望向 SIEM、Slack 或特定租户的订阅者发送签名的 webhook，请在 Traefik 旁运行中继。请参阅中继的 [README](crates/purple-wolf-relay/README.md) 和 [webhook 协议规范](docs/webhook-protocol.md)。 ## 快速开始 ### 本地演示 运行 Traefik、WASM 插件、backend、中继以及一个 HMAC 验证订阅者： ``` docker compose -f examples/demo/docker-compose.yml up --build ``` 然后尝试 [`examples/demo/README.md`](examples/demo/README.md) 中的请求。 ### Kubernetes 安装 在监控模式下安装 OCI Helm chart： ``` helm install purple-wolf oci://ghcr.io/guaracloud/charts/purple-wolf \ --version 0.4.1 \ -f charts/purple-wolf/values.monitor.yaml ``` Kustomize 用户可以从以下内容开始： ``` kubectl apply -k deploy/kubernetes/overlays/monitor-mode ``` 该 chart 和 Kustomize overlays 会渲染监控/强制执行 Middleware 的示例，但不会将它们附加到任何路由上。请先将 `purple-wolf-monitor` 附加到选定的 IngressRoutes，查看审计输出，然后再选择开启强制执行模式。 ### 验证发布制品 在生产环境使用前，请校验校验和、Cosign 签名、SBOM、镜像摘要以及发布清单： ``` gh release download v0.4.1 --repo guaracloud/purple-wolf --dir purple-wolf-release ``` 请遵循 [`docs/release-verification.md`](docs/release-verification.md) 并部署来自 `release-manifest.json` 中固定摘要的镜像引用。 ### 中继操作 当您希望向 SIEM、Slack 桥接或租户订阅者发送签名的 webhook 时，请运行中继。请参阅 [`docs/operations.md`](docs/operations.md)、[`docs/helm.md`](docs/helm.md) 和 [`docs/kubernetes-production.md`](docs/kubernetes-production.md)。 完整的按字段 Middleware 参考，请参阅 [`docs/configuration.md`](docs/configuration.md)。[`examples/`](examples/) 下现有的原始文件仅作为教学示例保留；生产环境用户应优先使用 Helm 或 Kustomize。 ## 基准测试 - 在同一集群中与 Coraza 的正面交锋 相同的 Kubernetes 拓扑，相同的 Traefik v3.1，相同的 backend，相同的 200 m CPU / 1 GiB 资源预算，相同的 OWASP CRS 语料库 - 只有 WAF 引擎不同。共两轮测试；第二轮将矩阵扩大到了无 WAF 基准 pod、破坏点斜坡测试、12 种 CRS 攻击类别（4536 个向量）、带有资源采样的 10 分钟浸泡测试，以及一个小型的功能健壮性测试套件。 核心结果（完整的方法论、数据表格及注意事项详见 [`docs/benchmark.md`](docs/benchmark.md)）： - **独立的 WAF 开销：+0.1–0.2 ms p99**（对比仅有 Traefik 的基准 pod）。在典型的 backend 延迟下几乎不可见。 - **相同资源下的持续吞吐量：** purple-wolf 在约 8000 RPS 下保持平稳；Coraza http-wasm 在 500 RPS 时崩溃。在测试的极限下，purple-wolf 的持续 RPS 约为前者的 **16–20 倍**。 - **针对 12 种 CRS 规则类别的检测率（4536 个向量）：** purple-wolf 整体 TPR 为 **14.55 %**，而 Coraza inline-PL1 为 **6.11 %** - **多拦截了 2.4 倍的攻击**，且两者在良性语料库上的 FPR 均为 **0 %**。在 Java (+26.5 %)、RCE (+6.3 %)、XSS (+5.1 %) 方面优势最为明显。 - **持续负载下的内存占用：** 在 1000 RPS 的 10 分钟浸泡测试中，稳定在 80–96 MiB 区间内，无内存漂移。Coraza 在第一轮测试中峰值达到 946 MiB（在最初 512 MiB 的限制下被 OOM 终止了 5 次）。 - **已填补基准测试暴露的缺陷：** 第二轮发现了对带有 `Mozilla/` 前缀的 User-Agent SQLi 和纯 `;wget` 查询 payload 的漏报。v0.4 通过 UA 后缀探测和 `rce_cmd` 签名修复了这两个问题；上述基准测试数据仍是最后一次发布的实机栈运行结果，因此需要重新运行才能发布更新后的实机栈覆盖率。 该基准测试可进行端到端复现： [`benchmarks/runner/round2/run-all-round2.sh`](benchmarks/runner/round2/run-all-round2.sh)。 已发布运行的原始 JSONL + CSV 输出结果位于 [`benchmarks/results/`](benchmarks/results/)。 **关于基准测试的说明：** 这并非声称 purple-wolf “优于” Coraza。Coraza 的 *原生*（Go-binding）Traefik 集成比此处测试的 http-wasm 路径更快且规则更丰富，并且完整的 OWASP CRS 能比此次比较中的任何引擎捕获更多的原子 token 测试 - 但代价是更高的 FPR。此比较有着客观明确的边界：相同的插件形态、相同的资源上限、相同的衡量标准。 ## 构建与测试 ``` cargo fmt --all --check cargo clippy --workspace --all-targets -- -D warnings cargo test --workspace --all-targets cargo test --workspace --doc cargo deny check cargo build -p purple-wolf-traefik --target wasm32-wasip1 --release ``` WASM 构建需要 `wasi-sdk`。macOS arm64 开发环境设置： ``` # 从 https://github.com/WebAssembly/wasi-sdk/releases 下载 wasi-sdk export WASI_SDK_PATH=/path/to/wasi-sdk ``` ## 许可证 采用 MIT OR Apache-2.0 双重许可。libinjection（内置 C 代码）采用 BSD-3-Clause 许可证。

标签：AI工具, AppImage, DOE合作, Rust, Traefik插件, WASM, Web应用防火墙, 可视化界面, 子域名突变, 网络安全, 网络流量审计, 请求拦截, 通知系统, 隐私保护