Gitleaks 扫描结果怎么导出 SARIF 给代码扫描平台

如果要把 Gitleaks 的扫描结果交给代码扫描平台，关键不是把终端输出复制过去，而是让扫描命令直接生成一个固定路径的 SARIF 文件。最小写法是给 gitleaks dir 或 gitleaks git 同时指定 --report-format sarif 和 --report-path reports/gitleaks.sarif，然后让 CI 把这个文件作为构建产物交给后续步骤。

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

步骤一：先确定扫描目标和产物路径

Gitleaks 官方仓库把扫描入口分为 dir、git 和 stdin。本篇只处理目录扫描和 Git 仓库扫描：前者适合检查当前工作区文件，后者适合把 Git 历史补丁也纳入扫描。无论选择哪种入口，都先约定一个不会和临时日志混在一起的报告目录，例如 reports/。

在团队工具或 CI 配置界面中，先确认三项：Target 指向工作区或仓库，Report format 选择 SARIF，Report path 填写 reports/gitleaks.sarif。这张图是原创界面说明图，用来标记配置关系，不是 Gitleaks 实际截图。

步骤二：用 report-format 和 report-path 写出 SARIF

目录扫描可以这样写。命令中的中文注释说明每个参数的作用；reports 目录要先创建，避免路径不存在导致写报告失败。

# 创建稳定的 CI 报告目录，避免把报告散落在临时目录
mkdir -p reports

# 扫描当前工作区，并把结构化结果写成 SARIF 文件
gitleaks dir . \
  --report-format sarif \
  --report-path reports/gitleaks.sarif

如果需要扫描 Git 仓库，可以把入口换成 git。报告参数保持不变，这样后续 CI 只需要记住一个文件名。

# 扫描仓库历史和当前变更，报告仍写入固定产物路径
gitleaks git . \
  --report-format sarif \
  --report-path reports/gitleaks.sarif

Gitleaks 官方说明支持 JSON、CSV、JUnit、SARIF 和模板等报告格式。这里选择 SARIF，是因为它适合作为结构化安全扫描结果在工具之间传递；它并不会改变规则、扫描范围或误报处理方式。

步骤三：把固定文件交给 CI，而不是复制终端文本

CI 的交接点应该是 reports/gitleaks.sarif 这个文件。扫描步骤负责生成它，产物步骤负责保存它，后续代码扫描平台的导入动作再读取它。这样每一层的责任清楚，也不会因为终端输出被截断而丢失文件位置、规则编号或提交信息。

# 扫描阶段只负责生成 SARIF，不在这里写平台账号配置
security-scan:
  script:
    # 发现秘密时保留非零退出语义，让 CI 能识别风险
    - mkdir -p reports
    - gitleaks dir . --report-format sarif --report-path reports/gitleaks.sarif
  artifacts:
    # 后续导入步骤消费这一份固定报告
    paths:
      - reports/gitleaks.sarif
    when: always

不同 CI 产品的字段名可能不同，但原则相同：扫描报告作为构建产物保存，上传动作使用与 --report-path 完全一致的路径。when: always 这类配置的目的是让失败扫描也留下报告，便于后续定位；它不应该被理解为“忽略扫描失败”。

步骤四：核对文件、格式和退出码

运行结束后先看产物是否真的生成，再看命令退出状态。一个常见误区是“已经有 SARIF 文件，所以任务成功”。实际上 Gitleaks 的默认退出码会把发现结果和执行错误都反映为非零；报告文件存在，只能说明写文件这一步有结果，不能替代风险判定。

# 先确认报告文件存在且路径与 CI 产物配置一致
test -s reports/gitleaks.sarif

# 只查看文件开头，确认它是 JSON 结构而不是终端日志
sed -n '1,12p' reports/gitleaks.sarif

在 CI 中不要用无条件的“忽略错误”包住整个扫描步骤。若项目确实需要先上传报告、再由专门步骤决定是否阻断，应把退出码保存下来，同时让产物上传始终执行，最后再按团队门禁策略返回退出状态。

常见异常怎么处理

把这条交接链固定下来

最稳妥的交接链是“选定扫描入口 → 指定 SARIF 格式 → 写入固定路径 → 保存为 CI 产物 → 分开判断文件生成和退出码”。这样代码扫描平台只需要消费一个明确的结构化文件，Gitleaks 仍负责发现秘密，CI 仍负责传递状态，平台侧的账号和导入权限则由另一层配置管理。

Gitleaks 可以直接导出 SARIF 吗？

可以。官方用法提供 --report-format sarif，再配合 --report-path 指定输出文件。

为什么 SARIF 文件生成了，任务还是失败？

报告写出和进程退出码是两件事。扫描发现秘密或执行异常时，命令仍可能返回非零；这正是 CI 用来阻断风险的信号。

应该上传终端日志还是 SARIF 文件？

后续平台需要结构化发现结果时上传 SARIF 文件。终端日志可以作为调试附件，但不能替代 reports/gitleaks.sarif。