RyanCoreAI/patchbrake

# PatchBrake [English](README.md) | [简体中文](README.zh-CN.md) [](https://www.npmjs.com/package/patchbrake) [](https://github.com/RyanCoreAI/patchbrake/actions/workflows/ci.yml) [](LICENSE) **AI 生成代码变更的本地安全闸门。** AI 编码工具的编辑速度极快，但在提交前很容易遗漏有风险的 diff： 删除测试、泄露密钥、扩大 CI 权限、破坏性迁移以及 prompt/config 漂移。 PatchBrake 会在你的 Git diff 发布之前在本地对其进行扫描。 ``` npx patchbrake scan --staged ```  不使用 LLM。无需控制台。不上传代码。仅提供可解释的本地 diff 检查。 ## 它能捕获什么 | 风险 | 示例 | |---|---| | 密钥泄露 | API keys 或 tokens 被添加到 config 或代码中 | | 删除测试 | 测试文件、测试调用或断言被移除 | | CI 权限漂移 | GitHub Actions 权限被扩大 | | 破坏性迁移 | 有风险的 schema 或数据变更 | | Agent config 漂移 | Prompts、规则或 agent 指令发生更改 | ## 为什么使用 PatchBrake - 在你的本地 Git diff 上运行 - 可在 commit 前或 CI 中工作 - 生成可解释的检测结果 - 支持 JSON 和 SARIF 输出 - 专为 AI 生成的补丁设计，而非通用的代码 lint ## 快速开始 环境要求： - Node.js 20+ 及 npm。`npx` 随 npm 一起提供。 - Git，位于你要扫描的代码仓库内。 在提交 AI 生成的变更之前运行 PatchBrake： ``` git add . npx patchbrake scan --staged ``` 如果 PatchBrake 发现错误，请在提交前修复 diff： ``` git commit -m "feat: ..." ``` 如有需要，可固定版本： ``` npx patchbrake@0.2.0 scan --staged ``` 可选的全局安装： ``` npm install -g patchbrake patchbrake scan --staged ``` 可选设置： ``` npx patchbrake init ``` 扫描 commit 范围： ``` npx patchbrake scan --base origin/main --head HEAD ``` 为 CI 或脚本输出 JSON： ``` npx patchbrake scan --staged --format json --output patchbrake-report.json ``` 为 GitHub code scanning 输出 SARIF： ``` npx patchbrake scan --base origin/main --head HEAD --format sarif --output patchbrake.sarif ``` 创建配置文件： ``` npx patchbrake init ``` 为已接受的现有检测结果创建基线： ``` npx patchbrake baseline --staged ``` ## 示例输出 ``` PatchBrake found 3 risky diff finding(s). Scanned 3 file(s) with 5 rule(s). ERROR secret-leak src/config.ts:4 Possible secret assignment added in this diff. > OPENAI_API_KEY=sk-test... Fix: Remove the value from git history, rotate it if real, and load it from environment or CI secrets. ERROR deleted-tests tests/auth.test.ts:12 2 test case or assertion line(s) removed. > it("rejects anonymous users", async () => { Fix: Confirm the deleted coverage is replaced or intentionally obsolete. WARN workflow-permissions .github/workflows/release.yml:8 Workflow permission was widened to write scope. > contents: write Fix: Restrict the permission to the minimum read/write scope needed for this job. ``` ## 规则 | 规则 | 默认级别 | 成熟度 | 捕获内容 | |---|---:|---| | `secret-leak` | error | stable | 新增的 API keys、私钥、tokens 或 env 密钥 | | `deleted-tests` | mixed | stable | 被删除的测试文件或被移除的测试/断言代码行 | | `workflow-permissions` | warn | stable | GitHub Actions 中的 `write-all`、write 权限范围和 `pull_request_target` | | `migration-risk` | warn | stable | `DROP`、`TRUNCATE`、不安全的 `DELETE` 以及破坏性的迁移语句 | | `prompt-config-drift` | warn | stable | 对 `AGENTS.md`、`CLAUDE.md`、`.cursor/rules`、prompts 和策略文件的更改 | | `auth-regression` | warn | beta | 被移除的 auth、role、session、JWT 或路由守卫检查 | | `package-script-risk` | warn | beta | 有风险的 npm 生命周期脚本或重度依赖 shell 的脚本 | | `dangerous-shell` | warn | beta | 管道至 shell 及破坏性的 shell 命令 | | `dependency-risk` | warn | beta | `latest`、通配符、URL、git、文件和链接形式的依赖项 | 列出规则： ``` npx patchbrake rules npx patchbrake explain secret-leak ``` ## 配置 PatchBrake 会读取当前工作目录中的 `.patchbrakerc.json` 或 `patchbrake.config.json`。 ``` { "failOn": "error", "outputFormat": "text", "include": ["**"], "exclude": ["node_modules/**", "dist/**", "coverage/**", ".git/**"], "rules": { "secret-leak": "error", "workflow-permissions": "warn", "migration-risk": "warn", "prompt-config-drift": "warn", "auth-regression": "warn", "package-script-risk": "warn", "dangerous-shell": "warn", "dependency-risk": "warn" } } ``` 禁用嘈杂的规则： ``` { "rules": { "prompt-config-drift": "off" } } ``` ## GitHub Action 在 pull requests 中使用复合 action： ``` name: PatchBrake on: pull_request: permissions: contents: read jobs: patchbrake: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - uses: RyanCoreAI/patchbrake@v0.2.0 with: base: origin/${{ github.base_ref }} head: HEAD version: "0.2.0" fail-on: error ``` 该 Action 默认采用对 CI 安全的行为：禁用本地自定义规则，内联忽略（inline ignores）不会抑制检测结果，并且运行会因为新增的 `patchbrake-ignore*` 注释而失败。详情请参阅 [docs/github-action.md](docs/github-action.md)。 ## 项目范围 PatchBrake 不是 SaaS、Web 控制台、AI PR 审查工具或完整的 SAST 扫描器。它最初被刻意设计为一个确定性的本地 CLI，用于检测明显的 diff 级别风险信号。 ## 开发 ``` npm install npm run build npm test npm run check npm run benchmark ``` 构建后在本地运行： ``` node dist/cli.js scan --staged ``` 发布检查清单在 [docs/implementation-status.md](docs/implementation-status.md) 和 [docs/release-checklist.md](docs/release-checklist.md) 中进行跟踪。 更多文档： - [规则参考](docs/rule-reference.md) - [演示案例](docs/demo-case.md) - [对比](docs/comparison.md) - [基线与忽略](docs/baseline-ignore.md) - [Git hooks](docs/hooks.md) - [CI 配置方案](docs/ci-recipes.md) - [AI 编码工作流](docs/ai-coding-workflows.md) - [自定义规则](docs/custom-rules.md) - [稳定契约](docs/stable-contract.md) - [发布策略](docs/release-policy.md) ## 路线图 - v0.1：CLI 扫描器、JSON/SARIF 输出、config、GitHub Action、基础规则。 - v0.2：runtime config 验证、CI 安全的 Action 默认设置、扩展的工作流权限覆盖范围。 - v0.3：处于 beta 阶段的 auth/package/shell/dependency 规则。 - v0.5：自定义规则 SDK 和可共享的 configs。 - v1.0：在收集真实世界反馈后，提供稳定的 CLI/config/output/rule 契约。 ## 贡献 最有用的贡献是误报报告和真实世界的不良 diff 固件。请使用 issue 模板，以确保每个报告都包含 diff 形式、预期结果和实际检测结果。 ## License MIT

标签：AI辅助开发, Git Hooks, MITM代理, SOC Prime, 云安全监控, 代码安全, 开发工具, 暗色界面, 机密检测, 漏洞枚举, 网络安全研究, 自动化攻击, 静态分析