srbsa/diffgate

# DiffGate [](https://www.npmjs.com/package/diffgate-review) [](https://www.npmjs.com/package/diffgate-review) [](https://marketplace.visualstudio.com/items?itemName=srbsa.diffgate-review) [](https://open-vsx.org/extension/srbsa/diffgate-review) [](LICENSE) [](https://github.com/srbsa/diffgate) **对你的 AI 生成的 diff 进行分类——查看首先该审查什么。** DiffGate 根据实际影响对每一行更改进行评级——🟢 合并，🟡 瞥一眼，🟠 验证——这样你的注意力就会集中在少数可能造成危害的更改上，而略过其余部分。**高信噪比，低噪音**（100% 精确度，0 误报阻断），确定且足够快，适用于内部循环——*从你的 agent 敲下第一个按键到点击合并按钮，结果始终如一。* 如果这听起来有用，请 **[给仓库点个 Star ⭐](https://github.com/srbsa/diffgate)** —— 这是其他人找到它的方式。 Coding agent 发布 diff 的速度超过了任何人审查的速度，而且编写代码的模型在审查时具有相同的盲点。DiffGate 是一个独立的、**确定性的**检查流程，它**仅在更改的行上**运行（对比已提交的基线），并在几毫秒内将每一行排序到相应的风险层级——这样你就可以略过安全的大多数，并将注意力集中在真正有影响的地方。高影响的更改不仅会被标记；它们还会被**拦截**——DiffGate 仅在更改有此需要时才运行你的测试，并且仅在必要时才升级为阻断。它不是模型在给自己的作业打分。它也不是一个让你淹没在各种发现中的全仓库扫描器。在你的 agent、你的编辑器、你的终端和你的 PR 中，引擎相同，结论一致——今天供个人使用，扩展后即可供整个团队使用。 | 层级 | 含义 | 你该做什么 | 示例 | |------|---------|-------------|----------| | 🟢 **绿色** | 安全 / 独立 | 放心合并 | 注释，本地日志 | | 🟡 **黄色** | 审查（弱依赖） | 查看一下 | 已弃用的 API、原生 SQL、网络调用、依赖项编辑 | | 🟠 **橙色** | 高影响，进行拦截 | 合并前验证 | schema/migration、硬编码 secret、auth/crypto、公共 API 更改、injection sink | ## 为什么是分类，而不是扫描 Linter 会标记所有问题；DiffGate 则**决定什么值得你关注、运行测试或进行阻断**——高信噪比，低噪音，并在其他情况下保持安静。这就是该产品的全部核心： - **限定在 diff 范围内。** 发现的问题仅针对已更改的行进行报告，并对比已提交的基线——没有全文件范围的噪音，也不会对你没有修改的代码进行重复审查。 - **分层分类，而不是扁平列表。** 三个层级引导注意力：绿色直接合并，黄色瞥一眼，橙色进行拦截。 - **拦截机制有选择地运行*你的*测试。** 遇到橙色更改时，DiffGate 会运行你的 `testCommand` 并显示真实的退出代码和输出。绿色和黄色会立即通过。pre-commit hook 速度很快，因为只有在更改确实具有高影响时才会触发测试。 - **实至名归的阻断。** 广泛的跨语言 injection 发现本身仅作为建议；**只有当可选的 code graph 证明该 sink 可以从不受信任的入口点（HTTP/事件处理程序）到达时**，它们才会升级为阻断性发现（从规则的角度来看，是通过 graph 获得阻断的权利）。 - **感知更改影响。** 借助可选的 code graph，发现的问题会带有其跨文件的爆炸半径——调用者计数、建议的审查者、未经测试的调用点——而无人调用的导出 symbol 会被*降级*。跨文件的上下文使审查变得**更安静**，而不是更吵闹。 - **快速。** 对已更改行的审查在几毫秒内完成——快到足以嵌入 agent 和编辑器的内部循环中，而不仅仅是在 CI 中。 - **经得起验证的低噪音。** `diffgate bench` 离线运行一个版本化的语料库：对干净的更改实现 **100% 精确度 / 0 误报阻断**。你可以自行复现——这就是发布该语料库的意义所在。请参阅 [BENCHMARK.md](BENCHMARK.md)。 ### 针对 agent 实际产出的内容进行调优 现代 agent 已经能在无需提示的情况下避免教科书式的 bug（SQL injection、XSS、secret）。它们依然会产出的是**二阶陷阱**——一个不受保护的递归合并（prototype 污染）、一个裸露的 `cors()`（默认允许任何来源）、一个由请求数据构建且没有边界限制检查的路径——而且它们在**编辑现有代码时**最容易丢弃这些保护，而这正是 agent 工作的主要部分。我们对此进行了测量：在本地到前沿模型中，教科书式的 OWASP 问题出现率为 **0%**，但从头开始编写出 **零** 问题的一个前沿模型，在**编辑文件时**重新引入了这些陷阱（0% → 13%）。DiffGate 正是专门针对这些残留问题进行调优的。请参阅[该测量数据](docs/MEASUREMENT.md)。 ## 快速开始 ``` npm install -g diffgate-review cd your-repo diffgate init # auto-detects language + test command, writes .diffgate.json diffgate check --since=HEAD~20 # see what it catches in your own history — no PR required diffgate check # review your pending changes right now ``` 还没有 git 历史记录或未提交的更改？请先查看捆绑示例上的输出： ``` diffgate init --demo # live scan, no config or git changes needed ``` ## 各个表面（一个共享引擎，一个结论） ### 1. 在你的 coding agent 中（通过 MCP） 影响力最大的位置：agent **在将生成的代码写入磁盘之前先进行自我检查**，获取结构化的发现结果（零 LLM token 消耗），并展示它所纠正的内容（原始代码 + 修复 + 原因），而不是默默地进行重写。一个值得信赖的、确定性的自我检查，正是让赋予 agent 更多自主权变得安全的基础。 ``` # Claude Code — 一条命令： claude mcp add diffgate -- diffgate mcp # 通过 Smithery 一键安装（零配置）： npx @smithery/cli install diffgate-review --client claude # Cursor — 添加到 MCP 设置： # { "diffgate": { "command": "diffgate", "args": ["mcp"] } } ``` 或者在 Claude Desktop 中一键安装：下载 [`diffgate.mcpb`](https://github.com/srbsa/diffgate/releases/latest) 并打开它。服务器还公开了 **prompts** 和 **resources**；请参阅 [MCP.md](MCP.md)。 ### 2. 在你的编辑器中（VS Code / Cursor） 在已更改的行上有内联波浪线、悬停卡片（原因 · 负责人 · 快速修复）、Risk Review 树、状态栏摘要，以及 **Deep Review**（针对橙色发现结果的 agent 式爆炸半径分析）。你正在审查的 diff 上得到的结论，与使用 CLI 得到的结论一样。 从 [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=srbsa.diffgate-review) 或 [Open VSX](https://open-vsx.org/extension/srbsa/diffgate-review) 安装（Cursor / Windsurf / Gitpod）。 ### 3. 在命令行——以及 CI 中 `diffgate check` 审查你的 diff，并在发现高影响结果时以非零状态退出：在本地是一个 pre-commit hook，在你的流水线中则是相同的拦截机制。 ``` diffgate install-hook # adds .git/hooks/pre-commit; only runs tests on 🟠 orange changes ``` 本地循环是切入点——在上下文记忆犹新时进行修复——并且**相同的引擎作为 PR gate 运行**，从而将结论传递到整个团队强制执行的地方。有关 GitHub Action、共享经验教训和组织策略包，请参阅 [docs/TEAM.md](docs/TEAM.md)。CI 运行时可以选择通过相同的 gate 分层外部扫描器，以获得更广泛的语言覆盖范围——仅作建议，默认关闭（[docs/CONFIG.md](docs/CONFIG.md)）。 **常用命令：** ``` diffgate check # review pending changes (the gate) diffgate check --staged # staged-only (pre-commit) diffgate check --since=HEAD~20 # audit recent history, per-commit (see below) diffgate check --agent # machine verdict for coding agents diffgate scan # analyze files directly (no git needed) diffgate watch # live review as you edit diffgate guidelines # review diff against AGENTS.md / CLAUDE.md etc. diffgate feedback --dismiss # suppress a false positive (shared via git) diffgate mcp # start the MCP stdio server ``` **审查最近的 AI 编写历史。** 将 `check` 指向你日志中已有的 commit——每一个发现结果都归因于特定的 commit，因此你得到的是一个故事，而不是一份全仓库范围的评分报告： ``` diffgate check --since=HEAD~20 # last 20 commits, one block per commit diffgate check --since="2 weeks ago" # by date instead of a rev diffgate check --ai-authored # only agent commits (Claude/Copilot/Cursor/… — heuristic) diffgate check --author="Claude" # matches author *and* Co-authored-by trailers diffgate check # a single commit by hash ``` 历史模式仅用于报告（它审查过去——从不运行你的测试命令或拦截 commit），并支持 `--json` 和 `--limit=`（默认为 50）。Merge commit 会被跳过。 运行 `diffgate --help` 获取完整列表（`report`、`bench`、`stats`、`graph`、`marginal` 等）。 ## 工作原理 - **Diff 感知：** `git diff`（CLI）或内存中的 LCS diff（编辑器，对未保存的缓冲区很准确）查找已更改的行；发现结果仅在这些行上报告。 - **在关键处使用真正的 AST：** `@babel/parser` (JS/TS) 和 tree-sitter (Python、PHP、Go、Ruby、Java、C#、Kotlin —— 通过 WASM 实现，无需原生构建) 为精确的规则提供支持：已弃用的调用不会在注释或字符串中被匹配到，导出签名的更改会被结构性地检测到，并且 SQL injection 是**针对 sink、具备参数感知和 sanitizer 感知的**——`cur.execute(f"… {uid}")` / `$pdo->query("… $id")` 会被拦截，而 `cur.execute("… %s", (uid,))`、`$pdo->prepare("… ?")`、单引号的 `'… $id'` 以及日志行中的 `SELECT` 则不会。 - **在其他所有地方建立确定性基准：** 针对跨 Go、Java、Ruby 以及任何文本文件的 secret、破坏性/schema 更改、auth/crypto、动态执行 / shell 调用、原生查询和网络调用，使用具备注释感知能力的模式规则。注释掉的代码（`# os.system(x)`）不会被标记；但提交在注释*内部*的 secret 仍然会被标记。文档/纯文本文件（`.md`、`.rst` 等）遵循相同的标准：更新日志中的单词“oauth2-provider”不是 auth 代码，但粘贴在 README 中的 key 仍然是泄露。 - **实至名归的阻断：** 对于没有 AST 支持的语言（Ruby 的 `#{}`，Go/Ruby 的 shell 调用），广泛的跨语言 injection 建议**只有在可选的 code graph 证明了其可以从不受信任的入口点到达时**，才会升级为阻断——社区版的 CodeGraph，无需 Pro 级别的 taint 引擎。（JS/TS、Python 和 PHP 会根据本地 AST 证据进行阻断，不需要此功能。） - **拦截机制：** 遇到高影响更改时，DiffGate 会运行你的 `testCommand` 并显示实际的退出代码和输出。 - **经验积累：** `diffgate feedback` 记录驳回/确认的结论；被驳回的发现结果（相同的规则 + 相同的代码）将在所有地方被抑制。存储在 `.diffgate/learnings.json` 中；将其提交以在整个团队中共享。 - **可选附加功能：** 一个与提供商无关的 AI 层（通俗的英文解释 + 修复）以及通过可选 code graph 实现的跨文件爆炸半径检查。两者默认关闭，并会平滑降级为无操作。 引擎布局：[`src/core`](src/core)（共享）· [`src/cli.ts`](src/cli.ts)（CLI）· [`src/mcp.ts`](src/mcp.ts)（MCP）· [`extension/`](extension)（VS Code）。 ## 覆盖范围随语言而扩展 DiffGate 对更改的分析深度取决于文件的语言——对此请明确了解，以便你能够校准对干净结果的信任程度。 | 层级 | 语言 | 深度 | |------|-----------|-------| | **深度 (AST)** | JS / TS (`@babel`) | 所有 injection 类别 + 公共 API 及签名更改 + 已弃用 API 的快速修复。**Prototype 污染**和 **NoSQL injection** 仅限 JS/TS；JS/TS 的发现结果也有资格进行 code-graph 的 **taint 确认**。 | | **深度 (AST)** | Python、PHP、Go、Ruby、Java、C#、Kotlin (tree-sitter) | 针对 sink、具备参数和 sanitizer 感知的 injection 检测——占位符、参数向量和转义器被正确地视为安全。各语言的 sink 类别如下。 | 各深度 AST 语言的 sink 类别（完整详情——每个 sanitizer 和安全形式，以及 code-graph 边界——请参阅 [docs/SCOPE.md](docs/SCOPE.md)）： - **Python** (7) — SQL · XSS · 路径遍历 · CORS · 命令 · 代码 · 反序列化 - **PHP** (8) — SQL · 命令 · 代码 · 文件包含 · 反序列化 · XSS · 路径遍历 · CORS - **Go** (4) — SQL · 命令 · 路径遍历 · CORS - **Ruby** (6) — SQL · 命令 · 代码 · 反序列化 · XSS · CORS - **Java** (6) — SQL · 命令 · 反序列化 · 路径遍历 · XXE CORS - **C#** (7) — SQL · 命令 · 反序列化 · 路径遍历 · XSS · XXE · CORS - **Kotlin** (6) — SQL · 命令 · 反序列化 · 路径遍历 · XXE · CORS **SSRF** 是跨越所有八种深度 AST 语言的跨语言建议（将请求中被污染的 URL 传递给出站请求 sink；由库限定且仅限被污染的 URL，因此静态/配置 URL 不会被标记）。**XXE** 涵盖 JVM（Java、Kotlin）和 .NET（C#），当文件显示出已知的强化措施时会被抑制。**宽松的 CORS** 现在也涵盖所有八种语言——通配符 `Access-Control-Allow-Origin`、允许所有来源的框架配置（gin/rs-cors、Spring `@CrossOrigin`、ASP.NET `AllowAnyOrigin()`、Ktor `anyHost()`、rack-cors）以及请求反射的来源；明确的允许列表则不会被标记。 | 层级 | 语言 | 深度 | |------|-----------|-------| | **基准 (模式)** | C/C++、Rust、Swift、Scala 等 | secret、破坏性/schema 更改、auth/crypto、动态执行 / shell 调用、原生查询、网络调用、TODO。通过 code graph 升级的跨语言 injection 建议。 | | **文本** | YAML、Terraform、JSON、任何文本 | secret 和 TODO/FIXME 标记。 | **设计上的快速——且范围与之匹配。** 对已更改行的审查在几毫秒内完成，这正是让相同的检查能够融入 agent 和编辑器内部循环的原因。这种速度是一种深思熟虑的权衡：DiffGate 是 diff 上的确定性**拦截机制**，而不是一个详尽无遗的全仓库 taint 引擎。覆盖范围是按语言划分的（在有 AST 的地方提供深度支持，在其他地方提供模式基准），安全规则针对 agent 实际产出的残留问题进行了调优，而不是为了最大化原始规则数量，而且一个干净的结果意味着“*在此语言的层级上没有匹配到任何内容*”，而不是“*被证明是安全的*”。如需针对多种语言进行深度的跨文件 taint 分析，请搭配使用专门的 SAST。各语言的完整详情及 code-graph 边界：**[docs/SCOPE.md](docs/SCOPE.md)**。 ## 配置 `diffgate init` 会在你的仓库根目录下写入一个定制的 `.diffgate.json`。最小示例： ``` { "testCommand": "npm test", // run for orange changes (the gate) "gate": { "mode": "working", "failOn": "orange" }, "deprecated": [ { "pattern": "StripeClient.charge", "replacedBy": "StripeClient.createPaymentIntent" } ] } ``` 任何规则——无论是内置的还是自定义的——都可以通过 `include`/`exclude` glob 进行路径范围限定，对于那些某个被禁止的惯用法属于合法操作的文件（例如配置加载器本身的 `process.env`），这是一种逃生通道。完整的 schema、内置规则表、LLM 提供商以及各规则的调优说明：**[docs/CONFIG.md](docs/CONFIG.md)**。 ## 更多 - **[docs/SCOPE.md](docs/SCOPE.md)：** 各语言的覆盖层级（深度 AST vs. 模式 vs. 仅文本）以及 code graph 的作用范围和局限性。 - **[docs/CONFIG.md](docs/CONFIG.md)：** 完整的 `.diffgate.json` schema、所有内置规则、LLM 提供商、原生精确度和测试范围行为。 - **[docs/TEAM.md](docs/TEAM.md)：** 在团队中推广 DiffGate（GitHub Action / PR gate、共享经验教训、组织级策略包、SOC 2 证据、面向管理者的指标）。 - **[docs/CODE-GRAPH.md](docs/CODE-GRAPH.md)：** 可选的跨文件爆炸半径（调用者计数、建议的审查者、测试盲点、可达性、taint 分析）。 - **[docs/MEASUREMENT.md](docs/MEASUREMENT.md)：** agent 在无提示下实际产出的内容以及如何进行复现（`diffgate marginal`）。 - **[MCP.md](MCP.md)：** MCP 工具、prompts、resources 和 AI 配置。 ## 试用一下 ``` diffgate scan mock_project ``` 你将看到绿色的发现结果（日志记录）、黄色的发现结果（已弃用的调用）以及橙色的发现结果（一个 `DROP COLUMN` migration，一个公共导出）。 ## 测试 ``` npm test # builds the extension, runs the full unit/integration suite + extension smoke test ``` ## 支持本项目 如果 DiffGate 帮你发现了什么——或者你只是喜欢为 agent 代码提供一个确定性拦截机制的想法——请 **[给仓库点个 Star ⭐](https://github.com/srbsa/diffgate)**。这是告诉其他人这值得尝试的信号。 - 🐛 **发现了误报阻断，或者它漏掉了一个 sink？** [提交一个 issue](https://github.com/srbsa/diffgate/issues/new) —— 误报阻断是我们视为 P0 级别的 bug。 - 💡 **希望覆盖某种语言或规则？** 带上你希望被捕获的惯用法[提交功能请求](https://github.com/srbsa/diffgate/issues/new)。 - 🔒 **安全报告？** 请私下披露——参阅 [SECURITY.md](SECURITY.md)。 ## 贡献与许可 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。Apache 2.0 协议；请参阅 [LICENSE](LICENSE)。

标签：AI编程助手, MCP, MITM代理, 代码审查, 威胁情报, 开发者工具, 暗色界面, 自动化攻击