zairo

Diff 安全扫描器会遗漏变更带来的影响，Zairo 会找出这些影响并寻找漏洞。 Zairo 会结合上下文扫描你代码中的变更，为你生成一个子图供查看，并使用你选择的 LLM 查找漏洞。

安装

pipx install zairo

用法

# 扫描你尚未提交的所有内容
zairo .

# 扫描 PR/分支差异
zairo . --base main --target HEAD

# 如果出现任何高危问题，则使构建失败
zairo . --base main --target HEAD --fail-on high

给它多个仓库，可以作为额外参数传入，也可以每行一个写在 --repos-file 中（或两者兼有，合并为一个列表），它会自动切换到多仓库模式：每个仓库都会获得自己的报告，外加一份合并后的摘要。

zairo backend frontend infra --base main --fail-on high -o zairo_multi_out

--base/--target（以及所有其他选项）对列表中的每个仓库都以相同方式生效，因此多仓库模式最适合所有仓库都针对同一参照（例如所有人的 main）进行差异比较的情况。约定不同的仓库需要分开运行。

标志

扫描什么

• --base、-b （无）：要与之进行差异比较的引用，例如 main 或 HEAD~3。如果省略，zairo 将扫描未提交的更改。
• --target、-t （无）：要差异比较到的引用。需要 --base；如果省略（在设置了 --base 的情况下），它将与你的工作树进行差异比较。
• --depth、-d （1）：围绕每个变更，将多少跳的调用者/被调用者拉入影响图。
• --language、-l （自动）：强制指定一种语言，而不是让 Trailmark 自动检测。

LLM 扫描

• --graph-only （关闭）：跳过漏洞扫描，仅构建影响图——不产生发现结果，也不生成 report.sarif。
• --model （gemini/gemini-2.5-pro）：任意 LiteLLM 模型字符串。
• --concurrency、-c （5）：单个仓库扫描内的并行 LLM 请求数。
• --batch-size （1）：将这么多节点分组到单个 LLM 请求中，而不是每个节点一次调用——请求更少（有助于应对提供商的速率限制），但代价是共享故障隔离：一个错误/格式错误的响应会使该批次中的每个节点都失败，而不仅仅是其中一个。无论哪种方式，缓存都保持按节点进行。
• --max-tokens （4096）：每个请求的输出预算。推理模型也会在内部思考上消耗这部分预算，因此如果你看到空响应，请调高此值。
• --cache / --no-cache （缓存开启）：跳过重新扫描自上次运行以来未更改的代码（按内容哈希缓存在 <output>/.llm_cache.json 中）。
• --tokens ：打印扫描实际使用的 token 数量（缓存命中不计入，因为它们没有发起调用）。

输出与门禁

• --output、-o （zairo_out）：报告输出位置。多仓库模式：每个仓库获得自己的 <output>/<repo-slug>/，此外这里还会有一份合并的 rollup.*。
• --fail-on （无）：如果出现达到或超过此严重级别的发现结果（low/medium/high/critical），则以非零状态退出。与 --graph-only 结合使用时出错（没有可门禁的内容）。多仓库模式：对所有仓库合并检查。参见 CI / PR 门禁。
• --verbose、-v （关闭）：逐步打印正在发生的事情（git 命令、工作树设置、每个节点的扫描进度）。
• --debug、 ： 打印的所有内容，外加发送给 LLM 的确切提示词及其对每个节点的原始响应——写入 （多仓库模式下每个仓库一份），因为内容太多无法打印到控制台。

仅多仓库模式

• --repos-file （无）：每行一个仓库路径（允许 # 注释），与直接给出的任何仓库合并。
• --repo-concurrency （1）：一次扫描多少个仓库。在途 LLM 请求总数最高可达 --concurrency × --repo-concurrency，因此请注意提供商的速率限制。高于 1 时，进度会在每个仓库完成时打印一行摘要，而不是实时的逐步详细信息。
• --continue-on-error / --stop-on-error （继续）：当一个仓库失败时，是继续扫描列表的其余部分，还是停止。无论哪种方式，任何失败的仓库仍会使整体退出代码失败。

随时运行 zairo --help 即可从 CLI 获取此相同列表。

输出文件

• report.json （始终）：原始影响图（节点、边以及任何附加的发现结果），以数据形式呈现。
• report.html （始终）：一个自包含的交互式依赖图查看器（Cytoscape.js）。点击节点可查看其发现结果。
• report.sarif （除非使用了 --graph-only）：以 SARIF 2.1.0 格式呈现的发现结果，适用于 GitHub 代码扫描或任何其他 SARIF 消费者。即使扫描干净也始终写入（一个空但有效的日志），以便扫描 UI 可以将先前报告的警报标记为已解决。当模型标记了 CWE 时，发现结果会按 CWE 分组为规则，因此同类反复出现的问题会合并为一条规则，而不是每种措辞变体都生成一条新规则。

多仓库模式会为每个仓库生成相同的三个文件，外加 rollup.json / rollup.html / rollup.sarif：每个仓库的状态和严重级别计数、一个链接到每个仓库报告的仪表板表格，以及将所有仓库的 SARIF 结果合并为一个多运行日志。

已删除的代码

被完全移除（而不仅仅是编辑）的函数/类/模块仍会出现在 report.html 中，状态为 deleted：一个虚线、淡化的节点标记其原先所在位置。Trailmark 的图本身无法表示这一点（它只反映当前存在的树），因此 zairo 会单独检测删除：它还会解析变更文件在 --base（如果未给出 --base，则为 HEAD）时的状态，并对两组符号进行差异比较。已删除的函数永远不会发送给 LLM 扫描器（没有可扫描的现存代码），因此它只携带其名称、种类和先前位置，绝不携带发现结果。

CI / PR 门禁

--fail-on <low|medium|high|critical> 如果发现任何达到或高于该严重级别的发现结果（多仓库模式下，对所有仓库合并检查），则以非零状态退出，因此 CI 步骤可以据此阻止合并。有几件事值得了解：

• 与 --graph-only 结合使用时出错（那样就没有可门禁的内容了）。
• 它绝不会抑制 SARIF 输出：即使在门禁失败时也会写入，因此扫描 UI 无论哪种方式都能反映当前状态。

zairo . --base "$BASE_REF" --target HEAD --fail-on high -o zairo_out

参见 examples/github-actions/zairo-pr-scan.yml 获取完整的 PR 扫描工作流：它在 PR 差异上运行 zairo，将 report.sarif 上传到 GitHub 的代码扫描，并在门禁失败时使作业失败。