Gitleaks 怎么用 baseline 只报告新增泄露结果

先用 Gitleaks 生成一份历史扫描 JSON 报告，再在后续扫描中通过 --baseline-path 传入它，并使用另一个 --report-path 保存本轮报告。与基线匹配的历史发现会从新增输出中排除；这只是增量比较，不表示历史密钥已失效或问题已修复。

Gitleaks 官方地址：https://github.com/gitleaks/gitleaks

VS Code 官方地址：https://code.visualstudio.com/

下面以已有授权的本地 Git 仓库为对象，用 VS Code 管理报告与扫描脚本。Gitleaks 本身是命令行工具，编辑器只提供文件入口，不存在一个内置的“生成基线”按钮。文中命令与三张界面图均为演示，没有扫描真实仓库或读取秘密。

1. 生成历史报告并在编辑器确认基线文件

先选定需要记录的历史扫描范围，并固定 Gitleaks 版本和规则配置。基线应对应明确的历史状态，不能每次发现新问题都顺手重新生成。下面在仓库根目录执行一次生成命令，输出目录放在仓库外；正式环境应使用团队认可的受控报告位置。

# 在仓库根目录运行；报告放在仓库外的受控目录，避免成为后续扫描输入。
mkdir -p ../scan-reports
# 输出JSON基线。发现泄露时默认可返回1，不能仅因此认定报告未生成。
gitleaks git . --report-format json --report-path ../scan-reports/gitleaks-baseline.json

随后在 VS Code 点击 File → Open File…，选择 scan-reports/gitleaks-baseline.json 并打开。界面应出现同名标签页，内容是扫描产生的 JSON 报告。确认文件确实来自这次预期扫描，而不是目录里留下的旧文件；扫描执行出错时，应先处理错误。

发现泄露时，默认退出码可以是 1，但报告仍可能已经正常生成。反过来，仅有一个报告文件也不能证明扫描成功完成。生成阶段应结合执行状态和错误消息处理，不能把所有非零码都吞掉后继续创建“合格基线”。

报告可能包含敏感的匹配内容或上下文，应限制存储和分享范围，不把它直接粘贴到公开工单、截图或仓库文档中。对于确认有效的泄露凭据，仍应按实际权限执行撤销或轮换等处置；基线文件承担记录职责，不承担凭据处置职责。

2. 保存增量扫描脚本，传入固定基线

在编辑器通过 File → New Text File 新建脚本，粘贴下面的内容，再用 File → Save As… 保存为 scan-new.sh。如已有扫描脚本，则在原脚本中加入基线输入和独立输出路径，避免维护两个不一致入口。

#!/usr/bin/env bash
# 在目标仓库根目录调用；不修改固定基线。
# exec让调用方直接收到Gitleaks的退出状态。
exec gitleaks git . \
  --baseline-path ../scan-reports/gitleaks-baseline.json \
  --report-format json \
  --report-path ../scan-reports/gitleaks-new.json

保存后，编辑器标签显示 scan-new.sh，代码中 baseline 与 new 是不同文件名。基线是输入，本轮报告是输出，两者不能写成同一路径，否则比较依据可能被覆盖。不要为通过一次扫描而把本轮发现自动加入基线。

脚本示例用 exec 把扫描退出状态交给调用者；它不运行额外的交互 shell，不增加无限等待。CI 可以用 Bash 调用这个脚本，并保留默认的发现失败行为，而不是设置 --exit-code 0 或追加忽略错误的后缀。这里的状态传递只是为新增问题保持可见性。

生成和比较都采用 git 模式，扫描的是 Git 历史补丁，不等于只检查当前未提交工作区。若生成基线时扫描完整历史，后续却只提供浅克隆或切换成目录模式，范围和发现定位都发生变化。应让版本、规则和 Git 历史可见性保持可解释，避免把不一致的输入误当作真实增量。

3. 打开新增报告，分开处理历史与新增发现

在目标仓库根目录运行保存的脚本后，再通过 File → Open File… → gitleaks-new.json 打开本轮报告，同时保留基线标签页。新增报告是本次比较的输出；编辑器底部 JSON 模式与文件名有助于确认当前读的是哪个文件。

若报告显示新增发现，保留规则标识、文件和提交等必要定位信息，在受控范围中核实。不要只按“密码字符串是否相同”判断是不是旧问题，发现匹配还涉及扫描产生的定位信息；重写历史、调整规则或移动相关内容后，应重新审阅增量口径。

需要更新基线时，把它作为独立维护动作：记录扫描版本、规则与历史范围，审阅变化，再批准替换。平时的增量流程继续读取固定版本，历史发现保留单独的处理清单。这样新增报告可以保持聚焦，而不会把历史问题从治理过程里删除。

baseline 会让扫描更快吗？不要把它当作只扫描新提交的参数。它的主要作用是过滤已存在于基线的发现，扫描范围另行决定。

报告为空就是仓库绝对没有秘密吗？不是，它只表达当前规则、范围与基线下的结果，不能替代完整的凭据管理。

为什么新增结果里又出现以前见过的内容？先比较版本、规则、扫描模式和历史定位是否变化，不要未经核实就把所有相似内容加入基线。

参考：Gitleaks 基线用法；VS Code JSON 文件阅读。