gitleaks 使用方式与典型场景

使用方式与典型场景

所有示例的前提同样是：只扫描自有仓库，或已获得书面授权的仓库。扫描他人仓库、把扫描结果对外公开，都不在授权范围内。

示例一：自定义内部 token 规则 + 白名单

公司内部的 token 往往有固定前缀，内置规则不认识。下面这段配置在保留内置规则的基础上，增加一条匹配 ok_ 开头、后接 32 位字母数字的规则，并排除测试目录与文档里的占位写法。

# .gitleaks.toml

[extend]
useDefault = true          # 保留内置规则，本文件只做增量

[[rules]]
id = "ok-internal-token"
description = "OK 平台内部访问令牌（ok_ 前缀 + 32 位）"
regex = '''ok_[A-Za-z0-9]{32}'''
secretGroup = 0
entropy = 3.5
keywords = ["ok_"]

  [rules.allowlist]
  description = "排除测试与示例中的占位写法"
  # 路径级排除：测试目录、文档、示例配置
  paths = [
    '''(^|/)tests?/''',
    '''(^|/)testdata/''',
    '''(^|/)docs?/''',
    '''\.md$''',
    '''\.example$''',
  ]
  # 内容级排除：明显是占位符的写法
  regexes = [
    '''ok_0{32}''',
    '''ok_X{32}''',
    '''ok_EXAMPLE[0-9A-Za-z]*''',
  ]
  # 出现这些词直接跳过，避免注释里的格式说明被误判
  stopwords = ["example", "placeholder", "dummy", "样例"]

写完之后先用工作区验证一遍规则确实生效，再决定是否放进流水线：

# 用自定义配置扫当前目录（不读历史），输出详情
gitleaks dir . --config .gitleaks.toml --no-git --verbose --redact

# 全历史扫，验证自定义规则在历史提交上的表现
gitleaks git --config .gitleaks.toml --log-opts="--all" --redact --verbose

熵阈值不建议一上来就调低。把 entropy 从 3.5 降到 2.5 这类改法，会让大量普通字符串涌入报告，结果是有效告警被淹没、没人再看报告——这比漏报更危险，因为它制造的是「看起来很安全」的假象。

示例二：CI 里全历史扫描 + 基线抑制存量 + 上传 SARIF

老仓库直接上全历史扫描，第一天会报出几十上百条历史存量，团队会立刻失去耐心。正确做法是先固化一份基线，之后只对新增泄露负责。

# 第一步（一次性）：生成基线，这份文件记录「已知存量」
gitleaks git --log-opts="--all" \
  --report-format json \
  --report-path baseline.json \
  --redact \
  --exit-code 0            # 生成基线时不阻断

# 把 baseline.json 提交进仓库，并在 .gitleaks.toml 里用 allowlist 排除它自身

# 第二步（每次 CI）：只报基线之外的新增
gitleaks git --log-opts="--all" \
  --baseline-path baseline.json \
  --report-format sarif \
  --report-path gitleaks.sarif \
  --redact
# 发现新增泄露时退出码非零，流水线自动失败

在 GitHub Actions 里再接一步上传，结果会出现在仓库的 Security 面板里：

- name: Upload SARIF
  if: always()
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: gitleaks.sarif

基线必须有人管。合理的管理方式是：基线只记录「确认过、且短期内无法处理」的项，并指定责任人；每次基线更新都要走代码评审；每个季度复核一次，能处理的就修掉并从基线里删除。基线一旦变成没人看的永久豁免清单，这个工具就失效了。

适合与不适合的场景

适合：pre-commit 提交前拦截、CI 里对 MR 的全历史兜底、老仓库的存量梳理（配基线）、开源前的自查、收购或交接代码时的尽调扫描。

不适合：把它当唯一的凭据防线。gitleaks 只查仓库里的字符串，管不了已经泄露到别处的凭据，也管不了通过环境变量、密钥管理服务下发的凭据轮换。另外它不做有效性验证，「扫到一个 key」和「这个 key 现在还能用」是两回事——后者需要人工或在授权前提下用专用工具验证。