xiwuqi/scopediff
GitHub: xiwuqi/scopediff
ScopeDiff 是一个面向 Pull Request 的 AI agent 权限和工具面差异比对工具，帮助在合并前发现 MCP 服务器、工作流权限、Agent 指令等配置变更带来的潜在风险。
Stars: 0 | Forks: 0
# ScopeDiff
[](https://www.npmjs.com/package/scopediff)
[](https://github.com/xiwuqi/scopediff/actions/workflows/ci.yml)
[](LICENSE)
用于 Pull Request 审查的 AI agent 权限和工具面差异比对。
[翻译](#translations)：[简体中文](docs/i18n/README.zh-CN.md) · [日本語](docs/i18n/README.ja-JP.md) · [Español](docs/i18n/README.es.md) · [Français](docs/i18n/README.fr.md) · [Português (Brasil)](docs/i18n/README.pt-BR.md) · [Deutsch](docs/i18n/README.de.md)
ScopeDiff 帮助维护者发现针对 MCP 服务器、agent 指令、GitHub Actions 权限、包生命周期脚本、Docker 设置以及其他可能改变 AI agent 或自动化行为能力的文件变更。
它是一个审查辅助工具，而不是一个完整的安全审计、漏洞扫描器或运行时保护系统。
## 为什么选择 ScopeDiff
- 在合并前查看 agent/工具的权限变更。
- 在本地或 CI 中运行，无需上传代码。
- 获取带有证据和建议审查步骤、可直接用于 PR 的 Markdown 和 JSON 报告。
## 为什么开发这个工具
AI agent 的配置开始驻留在代码库中：MCP 服务器、`AGENTS.md`、Cursor 规则、Claude 技能、GitHub Actions 权限和包生命周期脚本。现在，一个 Pull Request 不仅能更改应用程序代码，还能更改 agent 可以运行哪些工具、它期望哪些 token，以及哪些自动化路径可以发布或部署。
ScopeDiff 使这些边界变更在人工审查时变得清晰可见。
## 快速安装
```
npx scopediff@latest scan
```
在项目中安装：
```
npm install -D scopediff
```
从源码运行：
```
npm install
npm run build
node dist/cli.js scan
```
## 30 秒快速入门
扫描当前代码库：
```
npx scopediff@latest scan
```
将你的分支与 `main` 进行比较：
```
npx scopediff@latest diff --base main
```
生成 Markdown：
```
npx scopediff@latest report --format markdown
```
在 CI 中运行，遇到高风险发现时失败：
```
npx scopediff@latest ci --fail-on high
```
## 示例报告
此截图是根据针对临时演示代码库的真实 ScopeDiff CLI 输出生成的。完整的演示报告可在 [docs/demo/scopediff-report.md](docs/demo/scopediff-report.md) 中找到。
```
## ScopeDiff 报告
Risk: High
New agent capability detected:
- MCP server added: github
- Command: npx -y @modelcontextprotocol/server-github
- Env required: GITHUB_TOKEN
- Possible scope: repository read/write depending on token permissions
Review notes:
- Pin package version instead of using latest
- Prefer a read-only token for first setup
- Document why this server is needed
- Check whether this PR also changed workflow permissions
```
## ScopeDiff 检查什么
- MCP 服务器的添加以及 command/args/env 的变更。
- 类似凭证的环境变量名，如 `GITHUB_TOKEN` 或 `API_KEY`。
- 未固定版本的 `npx`、`uvx`、`pipx` 以及使用 Docker `latest` 标签的情况。
- GitHub Actions 权限扩大、敏感触发器、secrets 以及未固定版本的 action。
- `package.json` 生命周期脚本，如 `postinstall` 和 `prepare`。
- 增加了读取、写入、shell、网络、发布、部署、推送或删除行为的 Agent 指令。
- Docker 特权模式、主机网络、root 用户或 Docker socket 访问。
- 远程脚本执行模式，例如 `curl | bash`。
## GitHub Actions
使用已发布的 GitHub Action：
```
name: ScopeDiff
on:
pull_request:
permissions:
contents: read
jobs:
scopediff:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/setup-node@v4
with:
node-version: 20
- name: Run ScopeDiff
uses: xiwuqi/scopediff@v0.1.0
with:
base: origin/${{ github.base_ref }}
fail-on: high
```
默认情况下，ScopeDiff 会写入 GitHub Step Summary，并且不会对 Pull Request 发表评论。
上图是基于 ScopeDiff Markdown 输出的布局模型。添加 workflow 后，从你的代码库中捕获真实的 Step Summary。
你也可以直接运行 npm 包：
```
- name: Run ScopeDiff
run: npx scopediff@0.1.0 ci --base origin/${{ github.base_ref }} --fail-on high
```
为长期使用的 CI 固定 action 标签或 npm 版本。请勿使用未固定版本的分支（如 `main`）。
## 适用场景
- 使用 MCP 服务器的代码库。
- 包含 `AGENTS.md`、Cursor 规则、Claude 技能或 Copilot 指令的项目。
- 正在审查自动化变更的开源项目维护者。
- 将 AI 编码 agent 添加到现有工作流中的团队。
## 不适用的场景
- 完整的恶意软件检测。
- 运行时阻断或沙箱强制执行。
- 对真实 `.env` 文件的 Secret 扫描。
- 漏洞数据库检查。
- 未经明确启用的自动 PR 评论。
## 安全与隐私
ScopeDiff 是本地优先的：
- 无遥测。
- 无代码上传。
- 默认无网络访问。
- 默认不读取 `.env`。
- 无 token 存储。
- 不执行发现的命令。
## 文档
- [产品规范](docs/product-spec.md)
- [风险模型](docs/risk-model.md)
- [扫描范围](docs/scanning-scope.md)
- [CLI 设计](docs/cli-design.md)
- [报告 Schema](docs/report-schema.md)
- [评分机制](docs/scoring.md)
- [架构](docs/architecture.md)
- [MVP 验收标准](docs/mvp-acceptance.md)
- [测试计划](docs/test-plan.md)
## 翻译
英文是关于行为、限制和发布状态的权威信息来源。提供本地化的 README 摘要是为了方便国际用户发现，并应保持严谨保守：
- [简体中文](docs/i18n/README.zh-CN.md)
- [日本語](docs/i18n/README.ja-JP.md)
- [Español](docs/i18n/README.es.md)
- [Français](docs/i18n/README.fr.md)
- [Português (Brasil)](docs/i18n/README.pt-BR.md)
- [Deutsch](docs/i18n/README.de.md)
## 路线图
- 针对特定客户端配置文件的 JSONC 支持。
- 为 YAML 和 JSON 发现提供更好的行映射。
- 一流的 GitHub Action 包装器。
- 可选的、明确配置的 PR 评论。
- 规则贡献指南和规则文档页面。
## 贡献
欢迎提交 Issue 和 Pull Request。误报报告尤其有用，因为 ScopeDiff 应该保持严谨保守且具备良好的可解释性。
请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 许可证
MIT
如果 ScopeDiff 能帮助你更清晰地审查 agent/工具的变更，欢迎点个 Star。
标签：DevSecOps, Docker, GitHub Actions, GNU通用公共许可证, MCP, MITM代理, Node.js, 上游代理, 云安全监控, 人工智能代理, 代码安全, 代码审查, 安全审查, 安全防御评估, 工具安全, 开源, 拉取请求, 文档结构分析, 暗色界面, 权限变更, 漏洞枚举, 自动化攻击, 自动笔记, 软件开发工具包, 静态分析