ewanyonyi/saugra

# Saugra Web 应用防火墙 [](https://github.com/ewanyonyi/saugra/actions/workflows/ci.yml?query=branch%3Amain) [](https://codecov.io/github/ewanyonyi/saugra) [](LICENSE) [](Cargo.toml)  Saugra 是一款轻量级、自托管的 Web 应用防火墙，专为开发者和 小型团队设计，提供 OWASP 风格防护、速率限制、行为评分、机器人评分、持久化安全日志以及可解释的决策，无需采用 大型企业或云 WAF 平台。 产品方向为： ``` Rules-first protection + rate limiting + behavior scoring + bot scoring + AI explanations ``` ## 问题所在 许多小型团队、初创公司和自托管应用所有者需要防护 常见 Web 攻击，但现有 WAF 选项可能价格昂贵、调整复杂、难以解释或 与特定云提供商绑定。 传统 WAF 功能强大，但团队常因误报、不透明的拦截决策 以及运维复杂性而困扰。API 优先的应用也需要 适配现代 HTTP、JSON API、WebSockets 及 开发者主导部署工作流的防护方案。 ## 解决方案 Saugra 运行在公共代理与后端应用之间： ``` Client -> Nginx/Apache -> Saugra -> Backend app ``` 它检查请求，应用确定性安全规则，限制滥用流量， 对重复可疑行为和机器人活动进行评分，记录结构化安全事件，并解释请求被监控或拦截的原因。 Saugra 以规则为核心：AI 用于帮助解释和调整决策，但拦截依据来自规则、速率限制、行为评分、机器人评分及显式配置。 ## 适用对象 Saugra 适用于： - 小型 SaaS 团队 - API 优先的初创公司 - 后端开发者 - DevOps 工程师 - 自托管应用所有者 - 安全学习者和学生 - 希望获得轻量级防护且不完全依赖云 WAF 的团队 ## 选择 Saugra 的理由 成熟的 WAF 平台功能强大且广泛应用，但许多团队认为它们 价格高昂、配置复杂、难以调整或难以解释。 Saugra 专注于不同的体验：轻量级、自托管的防护， 配置简单，默认监控优先，决策透明， 且对现代 API 优先应用友好。 如果您需要以下特性，请选择 Saugra： - 简单的 YAML 配置 - 监控优先的部署 - 清晰的 JSON 安全日志 - 可解释的规则决策 - Nginx 和 Apache 兼容性 - 基于规则 + AI 辅助的自托管 WAF ## 当前状态 本仓库现已具备面向生产的基础功能： - Rust CLI 脚手架 - YAML 配置加载与验证 - 内置规则元数据及基础正则检查 - 监控/拦截/关闭模式模型 - 结构化日志配置 - 代理所有正常应用流量，并暴露 `/_saugra/health` 端点用于检查 WAF 服务状态 - 基于路由的多上游 HTTP 与 WebSocket 转发 - WebSocket 握手检查与升级隧道 - Redis 支持的生产级速率限制选项 - 轮转式本地 JSONL 安全事件存储 - 示例配置文件位于 `configs/saugra.example.yml` 请参阅 `ROADMAP.md` 了解公开的开发路线图。 公开文档： - `docs/ARCHITECTURE.md` — 技术架构 - `docs/PRODUCT_SPEC.md` — 产品规格 - `docs/LICENSING.md` — 许可、商业用途、责任和商标指南 - `docs/PRODUCTION_DEPLOYMENT.md` — Nginx/Apache 生产部署指南 - `docs/ADMIN_GUIDE.md` — 操作员命令、故障排除、白名单、拦截、日志及解释 - `docs/OWASP_TOP_10_STRATEGY.md` — 分层 OWASP Top 10 覆盖策略 - `docs/CRS_IMPORT.md` — OWASP CRS 转换支持与限制 - `docs/DEBIAN_PACKAGING.md` — `.deb` 构建及 GitHub Release 发布指南 - `docs/APT_REPOSITORY.md` — 签名的 Ubuntu/Debian APT 仓库计划 - `docs/OFFICIAL_DEBIAN_RELEASE.md` — 官方 Debian 归档发布计划 - `docs/RELEASE_PROCESS.md` — 维护者发布检查清单 - `docs/RUNTIME_ALLOWLIST.md` — 无需重启的本地运行时白名单设计 - `TRADEMARKS.md` — Saugra 名称、标识及品牌政策 安装状态： - 当前支持：从 Git/源代码构建并使用 systemd 运行。 - 当前支持：使用 `cargo-deb` 构建 `.deb` 软件包并发布到 GitHub Releases。 - 进行中：通过 GitHub Pages 发布签名的 Saugra 官方 Ubuntu/Debian APT 仓库。 - 计划后续：提交至官方 Debian 归档，并在可行时同步至 Ubuntu。 ## 快速开始 ### 前置条件 - 来自 [rustup](https://rustup.rs/) 的 Rust 工具链 - 用于生产级速率限制的 Redis - 当 Saugra 部署在真实应用前端时，需要 Nginx 或 Apache ### 从源码本地运行 ``` git clone https://github.com/ewanyonyi/saugra.git cd saugra cargo build cargo run -- test-config --config configs/saugra.example.yml cargo run -- rules list --config configs/saugra.example.yml cargo run -- run --config configs/saugra.example.yml ``` 保持 Saugra 运行，然后使用另一个终端进行以下检查。 检查健康端点： ``` curl http://127.0.0.1:8787/_saugra/health ``` 运行本地冒烟测试： ``` scripts/smoke-local.sh ``` 冒烟测试会启动一个临时后端，使用临时配置运行 Saugra， 验证正常流量被转发，验证 SQL 注入载荷被拦截， 检查 JSONL 事件格式，并清理资源。 ## 常用命令 查看 OWASP Top 10:2025 映射覆盖情况： ``` cargo run -- owasp coverage --config configs/saugra.example.yml ``` 按操作和 OWASP 类别汇总最近的安全事件： ``` cargo run -- logs summary --config configs/saugra.example.yml --limit 200 ``` 从本地事件日志生成每日安全摘要： ``` cargo run -- summary daily --config configs/saugra.example.yml ``` 预览清理过期生成的文件： ``` cargo run -- cleanup run --dry-run --config configs/saugra.example.yml ``` 解释已记录的请求决策： ``` cargo run -- explain --config configs/saugra.example.yml ``` 运行本地部署状态检查： ``` cargo run -- posture check --config configs/saugra.example.yml ``` 将支持的 OWASP CRS 正则规则转换为 Saugra YAML： ``` cargo run -- rules convert-crs --input /path/to/coreruleset/rules --output configs/rules/converted-crs.yml ``` 请参阅 `docs/CRS_IMPORT.md` 了解支持的 CRS 操作符、转换映射、数据文件导入行为及不支持的功能报告。 ## 生产部署 推荐的生产部署架构： ``` Client -> Nginx/Apache TLS -> Saugra on 127.0.0.1:8787 -> Backend app ``` 以 `monitor` 模式启动，使用 `logs tail`、`logs summary`、`explain` 和 `posture check` 审查真实流量，调整后切换至 `block` 模式。 生产环境注意事项： - 将 Saugra 部署在私有地址上，例如 `127.0.0.1:8787`。 - 在前端部署 Nginx 或 Apache 处理公共 TLS。 - 配置 `forwarded_headers.trusted_proxies` 为允许提供客户端 IP 和协议头的代理地址。 - 使用 `rate_limit.backend: redis`。 - 将事件存储在持久化路径，例如 `/var/log/saugra/saugra-events.jsonl`。 - 在通过 Saugra 路由浏览器 WebSocket 流量前，配置精确的 WebSocket `allowed_origins` 和 `allowed_hosts`。 完整的生产指南和示例： - `docs/PRODUCTION_DEPLOYMENT.md` - `configs/saugra.production.example.yml` - `configs/nginx.production.example.conf` - `configs/apache.production.example.conf` - `examples/django-channels-daphne-nginx/` ## 在服务器上安装 完整的 Ubuntu 安装路径，包括从 Git 构建、安装二进制文件、创建 `/etc/saugra/saugra.yml` 以及使用 systemd 运行 Saugra，请参见 `docs/PRODUCTION_DEPLOYMENT.md`。 简要步骤： ``` git clone https://github.com/ewanyonyi/saugra.git /opt/saugra cd /opt/saugra cargo build --release sudo install -m 0755 target/release/saugra /usr/local/bin/saugra saugra --version sudo useradd --system --home /var/lib/saugra --shell /usr/sbin/nologin saugra sudo mkdir -p /etc/saugra/rules /etc/saugra/standards /var/log/saugra /var/lib/saugra sudo cp configs/saugra.production.example.yml /etc/saugra/saugra.yml sudo cp configs/rules/REQUEST-*.yml /etc/saugra/rules/ sudo cp configs/standards/*.yml /etc/saugra/standards/ sudo cp configs/saugra.service.example /etc/systemd/system/saugra.service sudo chown -R saugra:saugra /var/log/saugra /var/lib/saugra sudo systemctl daemon-reload sudo systemctl enable --now redis-server sudo systemctl enable --now saugra ``` 验证已安装的配置： ``` saugra test-config --config /etc/saugra/saugra.yml ``` 检查服务状态： ``` curl -i http://127.0.0.1:8787/_saugra/health ``` ## 构建 Debian 软件包 Saugra 可以打包为 `.deb` 软件包，适用于 Debian 和 Ubuntu： ``` cargo install cargo-deb --version 3.6.0 --locked cargo test --locked --all-targets --all-features cargo deb --locked ``` 软件包构件将写入 `target/debian/` 目录。请参阅 `docs/DEBIAN_PACKAGING.md` 了解本地安装测试及 GitHub Release 发布流程。 ## 验证部署 对于您拥有的预发布或生产环境部署： ``` scripts/verify-remote-waf.sh https://staging.example.com --yes-i-am-authorized ``` 对于 `/` 路由不适用的应用，选择一个无害的 GET 路径： ``` scripts/verify-remote-waf.sh https://staging.example.com \ --path /accounts/login/ \ --yes-i-am-authorized ``` 远程验证器会发送安全的纯 GET 探针，检测常见 WAF 信号，如 SQL 注入、XSS、路径遍历、命令注入、扫描器用户代理、包含敏感信息的 URL、方法重写头、可疑内容类型、供应链标记、原型污染、日志注入及解析器边界情况。POST 请求体探针可通过 `--include-post` 选项启用。 ## 调整配置 在监控模式下审查日志后，使用排除项调整误报。 建议使用窄范围排除项： ``` rules: exclusions: - name: Allow article HTML previews rule_ids: - SAUGRA-XSS-001 - SAUGRA-BODY-001 path_prefixes: - /api/articles query_params: - content ``` 全局排除会降低整个应用的防护级别。仅当规则需在所有位置禁用时才使用。 ## 许可信息 有关商业用途、修改后的网络部署、保修和责任限制以及商标政策指南，请参阅 `docs/LICENSING.md`。

标签：AI辅助, API安全, AppImage, JSON输出, LangChain, OWASP防护, Rust语言, Web应用防火墙, 入侵防御, 可视化界面, 可解释AI, 威胁情报, 安全日志, 安全防护, 小团队部署, 开发者工具, 搜索引擎查询, 机器人检测, 流量过滤, 现代Web应用, 网络安全, 自托管, 行为评分, 规则基于, 轻量级, 通知系统, 隐私保护