gitleaks 是什么
gitleaks 是开源的密钥扫描工具：从 git 历史、目录或暂存区检测疑似凭据（API Key、Token、私钥等），规则可自定义、命中可脱敏，输出 JSON 或 SARIF 便于接入报告与门禁。常见组合是「pre-commit 本地拦截 + CI 全历史扫描」双保险：前者拦住新泄漏，后者兜底存量问题。
基本信息
| 适用平台 | 本地开发机与 CI（GitLab、GitHub Actions 均可集成） |
|---|---|
| 命令 | gitleaks detect（历史与目录）、gitleaks protect（暂存区） |
| 配置 | .gitleaks.toml 自定义规则与 allowlist（抑制误报） |
| 输出 | JSON/SARIF，便于接入报告与门禁 |
典型使用场景
- pre-commit 拦截：提交前扫描暂存区，把误提交挡在本地
- CI 门禁：MR 与主干流水线扫描，命中即失败
- 历史体检：存量仓库做一次性全历史扫描，制定清理计划
- 修复验证：凭据轮换与历史清理后扫描确认
- 合规留痕：留存扫描报告，证明流程内有密钥管控
- 平台侧推送保护联动：托管平台自带密钥拦截与本地扫描互补，降低漏报
CI 与本地用法
CI 与本地用法
gitleaks detect --source . --report-format sarif \
--report-path gitleaks.sarif --redact # 全量扫描，报告脱敏
gitleaks protect --staged --redact # 提交前只扫暂存内容
# 命中时退出码非零，可直接作为流水线门禁条件历史扫描的命中要区分「真实凭据」与「示例占位符」：allowlist 精确到路径与规则，别用宽泛忽略换清净。
扫描命中不等于凭据有效：确认是否真实后按「轮换 → 清历史 → 加规则」的顺序处置，顺序颠倒等于先修门后抓贼。
命中后的处置顺序
| 步骤 | 动作 | 验证方式 |
|---|---|---|
| 一、确认 | 判断是否真实有效 | 查该凭据的使用与访问日志 |
| 二、轮换 | 在源头系统吊销并重发 | 旧值确认失效 |
| 三、清理 | 重写历史或加说明 | 全历史复扫通过 |
| 四、复盘 | 补规则与流程 | 例会跟进改进项 |
清理历史要协调全团队：改写后所有人本地仓库需要重置，把通知与操作步骤写成预案，避免有人旧克隆把历史推回来。