Mergesafe Scanner

MergeSafe扫描仪（V0核心）

MCP服务器代码库的确定性扫描器。扫描在本地运行；启用时，可选工具引导和更新流可以下载二进制文件或漏洞数据库。

快速启动

npx mergesafe scan .

或全局安装：

npm i -g mergesafe
mergesafe scan .

对于本地monorepo开发：

pnpm install
pnpm test
pnpm -C packages/cli dev -- scan fixtures/node-unsafe-server

具有显式输出的示例：

mergesafe scan fixtures/node-unsafe-server --out-dir mergesafe-test --format json,sarif,md,html --fail-on none

生成的输出：

• mergesafe/report.json
• mergesafe/summary.md
• mergesafe/results.sarif
• mergesafe/report.html

默认引擎为 mergesafe,semgrep,gitleaks,cisco,osv.可选支持的发动机（例如 trivy)都是 不 包括在内，除非你通过 --engines。默认情况下，缺少的引擎二进制文件会自动安装到 ${HOME}/.mergesafe/tools （用覆盖 MERGESAFE_TOOLS_DIR).自动安装可能会下载工具，除非使用禁用 --no-auto-install 或 --auto-install false.

工作空间包

• packages/cli: `mergesafe scan

` 命令

• packages/core：规范模式、重复数据消除、评分/失败逻辑
• packages/rules：确定性静态规则+工具表面提取
• packages/report：标记和HTML报告
• packages/sarif：SARIF 2.1.0转换

CLI标志

• --out-dir 默认 mergesafe
• --format 默认 json,html,sarif,md
• --mode standard|fast 默认 standard
• --timeout 默认 30
• --concurrency 默认 4
• --fail-on critical|high|none 默认 high
• --fail-on-scan-status 默认 none （单独执行扫描完整性）
• `--config

` （可选YAML）

• --engines 默认 mergesafe,semgrep,gitleaks,cisco,osv；使用 all 包括所有可用的发动机（包括可选发动机，如 trivy)
• --auto-install 默认 true
• --no-auto-install 禁用工具引导
• --redact
• --verify-downloads 默认 warn 在CLI中(strict GitHub Action）
• --path-mode 默认 relative

YAML配置(--config)最小示例

scan.yml:

mode: standard
failOn: high
failOnScanStatus: none
format:
  - json
  - html
  - sarif
  - md
verifyDownloads: warn
pathMode: relative
timeout: 30
concurrency: 4
autoInstall: true

运行方式：

mergesafe scan . --config scan.yml

扫描完整性与策略门

MergeSafe现在报告两个独立的状态：

• scanStatus: OK | PARTIAL | FAILED （选定的发动机是否成功完成？）
• gateStatus: PASS | FAIL （调查结果是否违反 --fail-on 政策？)

确定性的 scanStatus 来自选定引擎的规则：

• OK：所有选定的引擎都成功。
• PARTIAL：至少一个选定的引擎成功，至少一个选择的引擎未成功(failed, timeout, skipped，或飞行前失败）。
• FAILED：没有选定的引擎成功，或者出现硬错误阻止了扫描。

向后兼容的默认行为保持不变，因为 --fail-on-scan-status 默认为 none.

退出代码

当两个条件都失败时，解决方案优先： 闸门故障获胜 (2).

示例：

• --fail-on high，结果包括严重程度高，扫描为部分→ exit 2.
• --fail-on none --fail-on-scan-status partial，扫描为部分→ exit 3.
• --fail-on none --fail-on-scan-status failed，扫描为部分→ exit 0.

窗户烟雾测试：

pnpm -C packages/cli dev -- scan fixtures/node-unsafe-server --out-dir mergesafe-test --fail-on none

预期输出文件：

• mergesafe-test/report.json
• mergesafe-test/summary.md
• mergesafe-test/results.sarif
• mergesafe-test/report.html

下载验证和缓存行为

• MergeSafe引脚可下载工具版本 packages/engines/src/toolManifest.ts 从不使用 latest 二进制下载的URL。
• 缓存根： ~/.mergesafe/tools （或 MERGESAFE_TOOLS_DIR).
• 缓存密钥布局： /bin/// （工具+固定版本+平台/拱形特定工件）。
• 每次运行时，缓存的二进制文件在执行前都会根据清单校验和进行验证（除非 --verify-downloads off).
• 重新下载发生在以下情况：

- 缺少预期的缓存二进制文件， - 固定版本路径缺失， - 校验和验证失败（严格阻止执行；警告记录警告并继续）。

• 最小化驱逐策略：通过删除手动清除缓存 ~/.mergesafe/tools （或你的习惯 MERGESAFE_TOOLS_DIR).

v0.1.0发动机行为

• 跑步 `mergesafe scan

没有 --engines 现在尝试： mergesafe, semgrep, gitleaks, cisco, osv`.

• trivy 可用，但未包含在默认设置中。
• 如果 --no-auto-install 已设置，缺失的发动机标记为 skipped 其中包含安装提示 report.json.
• 引擎故障不是致命的：扫描输出文件仍在写入。

工具缓存+本地扫描行为

• 默认缓存目录： ~/.mergesafe/tools
• 覆盖缓存目录： MERGESAFE_TOOLS_DIR
• 代码在本地扫描，默认情况下不会上传，但工具引导程序可能会下载引擎二进制文件，除非禁用自动安装。
• 默认情况下，远程分析器（包括LLM支持的分析）是选择加入和关闭的。