threatailwaf/threatail-node

# Threatail Node 一个作为反向代理运行在您的站点之前的 Web 应用防火墙。使用 Rust 编写，以单个静态二进制文件发布，并将所有流量保留在您自己的基础设施中。 ``` client ──▶ threatail-node ──▶ your backend (inspect, block, log) ``` **状态：** beta。请先以 `detect` 模式运行 —— 参见[模式](#modes)。 ## 功能 - **签名检测** — SQL 注入、XSS、路径遍历、命令注入、扫描器。 - **抗规避检查** — 在匹配前解码请求体：gzip、deflate、brotli、UTF-16、UTF-7 和基于注释的 SQL 混淆 (`union/**/select`)。检查 `Content-Type` 声称为二进制但实际并非如此的请求体。 - **速率限制** — 基于路径前缀，以 IP、token、header 或 cookie 为键。超过限制将阻止请求或提供工作量证明挑战。 - **Bot 处理** — 通过正向确认反向 DNS 验证爬虫，因此伪造的 `Googlebot` user-agent 会被捕获。 - **撞库保护** — 监控每个 IP 和用户名的登录尝试速度。 - **异常检测** — 为每个站点建立正常流量画像并对偏差进行评分。 - **访问控制** — IP 允许/拒绝列表、地理策略、HTTP 方法允许列表、TLS 指纹识别。 - **威胁评分** — 将加权信号组合成一个数值，具有可配置的阻断阈值。 - **响应检查 (DLP)** — 扫描后端响应中泄露的密钥和堆栈跟踪。 - **API 保护** — 带有算法允许列表的 JWT 验证、JSON 请求体限制以及 OpenAPI 正向模型验证。参见 [`docs/api-protection.md`](docs/api-protection.md)。 每个请求都在进程内进行检查。不会向任何第三方发送数据。 ## 要求 - Linux, x86-64 - 可用的 80 和 443 端口 - 一个用于代理的后端 无运行时依赖 —— release 二进制文件与 musl 静态链接。 ## 安装 ### Docker ``` git clone https://github.com/threatailwaf/threatail-node cd threatail-node docker build -t threatail-node . docker run -d --name threatail \ -p 80:80 -p 443:443 \ -v /etc/threatail:/etc/threatail:ro \ -v threatail-data:/var/lib/threatail \ threatail-node ``` 还有一个 `docker-compose.yml` 可以在演示后端前运行该节点。完整说明：[`docs/deployment-docker.md`](docs/deployment-docker.md)。 ### Kubernetes 普通清单，无模板引擎： ``` $EDITOR deploy/k8s/02-configmap.yaml # your domain and backends $EDITOR deploy/k8s/03-deployment.yaml # your image kubectl apply -f deploy/k8s/ ``` 创建一个 namespace、ConfigMap、2 副本 Deployment（非 root 用户，只读根文件系统）以及用于流量和指标的 Service。在生产环境之前请阅读 [`docs/deployment-kubernetes.md`](docs/deployment-kubernetes.md) —— 关于客户端 IP 和每个 pod 状态的部分非常重要。 ### 从源码构建 ``` cargo build --release sudo install -m755 target/release/threatail-node /usr/local/bin/ ``` 需要 Rust 1.87 或更高版本。该 crate 本身是 2021 edition；需要更新的工具链是因为某些依赖项使用了 2024 edition。 ## 快速开始 ``` sudo mkdir -p /etc/threatail /var/lib/threatail sudo cp config.example.json /etc/threatail/config.json sudo nano /etc/threatail/config.json # set your domain and backend sudo threatail-node # reads /etc/threatail/config.json ``` 使用 `threatail-node /path/to/config.json` 指定不同的配置。 验证它是否正在检查： ``` curl -i "http://localhost/?id=1'+UNION+SELECT+password+FROM+users--" ``` 在 `detect` 模式下，它会返回您的后端响应并写入一条日志。在 `protect` 模式下，它会返回 403。 ## 配置 最小配置： ``` { "listen_http": "0.0.0.0:80", "listen_https": "0.0.0.0:443", "sites": [ { "domain": "example.com", "backends": ["http://127.0.0.1:8080"], "mode": "detect" } ] } ``` 有关带有注释的真实场景设置，请参见 [`config.example.json`](config.example.json)，有关各个子系统的参考，请参见 [`docs/`](docs/)。 多个后端通过轮询进行负载均衡。多个站点通过 `Host` 匹配。 ### 模式 | 模式 | 阻止 | 记录日志 | 学习 | |-----------|--------|------|--------| | `learn` | 否 | 否 | 是 | | `detect` | 否 | 是 | 是 | | `protect` | 是 | 是 | 是 | 先以 `learn` 模式运行几天，以便异常画像反映您的真实流量，然后切换到 `detect` 查看哪些内容*会*被阻止，最后切换到 `protect`。 当站点的其余部分处于 `protect` 模式时，个别硬性拦截门可以保持非阻止状态 —— 参见 `traversal_logonly`、`method_logonly`、`ipv6_logonly`。 ### TLS 为每个站点提供证书，或者在上游终止 TLS，并在其后面以 HTTP 方式运行节点。参见 [`docs/certificates.md`](docs/certificates.md)。 ### 指标 设置 `metrics_listen` 以在 `/metrics` 暴露 Prometheus 指标。**将其绑定到内部接口** (`127.0.0.1:9100`)，或者如果必须可访问，请设置 `metrics_token`。查询和警报请参见 [`docs/prometheus-grafana.md`](docs/prometheus-grafana.md)。 ## 机器学习 节点具有两个 ML 层，它们开箱即用的表现各不相同： **异常检测（无监督）—— 独立运行。** 节点为每个站点学习流量画像，并对偏差进行评分。无需安装任何东西。给它几天的 `learn` 模式时间，并可选择设置 `ml_trusted_ips`，使其仅在您信任的流量上进行训练。 **监督模型 —— 本仓库不附带任何模型。** 推理引擎位于此处，但内置的模型文件只是一个空的占位符。训练需要带标签的攻击数据和本仓库未包含的 pipeline。如果没有模型，监督评分仅处于非活动状态；签名、规则、速率限制和异常检测均正常工作。 您可以通过 `ml_model_path` 提供自己的模型 —— 其格式记录在 [`docs/supervised-model.md`](docs/supervised-model.md) 中 —— 或者从 Threatail Cloud（见下文）获取维护的模型。 ## 独立或托管 该节点可独立运行且功能完整。以上所有功能均可通过配置文件实现，无需账户，也不需要向我们发起任何网络调用。 或者，它可以通过设置两个环境变量连接到 **Threatail Cloud**（一个托管控制平面）： ``` THREATAIL_CLOUD_URL=https://lk.threatail.com THREATAIL_ENROLLMENT_TOKEN= ``` 连接后，节点将从云端而不是本地文件中拉取其策略，并报告事件和每分钟汇总数据。完整的请求流量仍然永远不会离开您的服务器。 | | 独立 | 搭配 Cloud | |---|---|---| | 检测、规则、速率限制、Bot、异常 | ✅ | ✅ | | 配置 | 每个节点的 JSON 文件 | Web 面板，所有节点 | | 针对新 CVE 的托管规则 / 虚拟补丁 | — | ✅ | | 经过训练的监督 ML 模型 + 重训练 | 自带 | ✅ | | 多节点、多租户、团队访问 | — | ✅ | | 面板、警报、日志保留 | 自带 Prometheus/Grafana | ✅ | | 证书自动化 (ACME) | 手动 | ✅ | 如果您从未设置 `THREATAIL_CLOUD_URL`，节点将在启动时记录 `cloud mode disabled`，并且永远不会联系我们。 ## 安全 这是位于您生产流量路径上的软件。为此我们采取了以下几项措施： - Rust，在请求路径中没有 `unsafe`。 - 依赖项在每次发布时都经过审计 (`cargo audit`)。 - 请求体解压具有边界限制，以防止解压炸弹。 - 始终阻止代理到链路本地元数据地址 (`169.254.*`)。 发现漏洞？请私下报告 —— 参见 [SECURITY.md](SECURITY.md)。请勿公开发布 issue。 ## 测试您的部署 该节点已通过 [GoTestWAF](https://github.com/wallarm/gotestwaf) 测试。您可以自己运行： ``` docker run --rm --network host wallarm/gotestwaf \ --url http://localhost --noEmailReport ``` ## 贡献 欢迎提交 issue 和 pull request。请： - 在提交 PR 之前运行 `cargo test` 和 `cargo clippy`。 - 为任何检测更改添加测试 —— 参见 `src/verdict.rs` 中的测试模块。 - 检测规则应附带绕过测试，而不仅仅是正向测试。 ## 许可证 [Apache-2.0](LICENSE)。

标签：API安全, AppImage, Bot防护, CISA项目, JSON输出, Rust, StruQ, WAF, Web应用防火墙, 反向代理, 可视化界面, 子域名突变, 网络流量审计, 自定义请求头, 请求拦截, 通知系统