Gitleaks 密钥泄漏扫描实战：Git 仓库敏感信息防护

作者

Gitleaks 密钥泄漏扫描是代码安全与供应链安全中的重要防线，用于在 Git 提交中自动发现 API 密钥、口令与令牌等敏感信息，防止密钥随代码一起泄露到仓库与 CI 流程。本文介绍 Gitleaks 的安装、规则配置与 pre-commit/CI 集成实战。

适用场景

  • 对新建仓库与存量历史仓库进行密钥泄露排查
  • 在 CI/CD 流水线中阻断包含密钥的提交合并
  • 供应链安全审计，防止密钥随开源或内部代码外流

前置条件

  • Git 2.24+
  • 已安装 Gitleaks（Go 1.21+ 编译或官方预编译二进制）
  • 对待扫描仓库具备读权限，CI 场景需写权限

原理说明

Gitleaks 基于 正则规则与 Shannon 熵检测双机制：正则匹配已知厂商密钥格式（AWS、GitHub、Slack、阿里云等数百种规则），熵检测识别高随机性的疑似令牌串。规则文件 .gitleaks.toml 支持自定义 regex、keywords 与 allowlist（排除误报）。命令分为 detect（扫描仓库全部历史与暂存区）与 protect（用于 pre-commit 在提交前拦截）两种模式。

操作步骤

1. 安装 Gitleaks

# macOS
brew install gitleaks
# Linux 二进制（以 v8.18.4 为例）
wget https://github.com/gitleaks/gitleaks/releases/download/v8.18.4/gitleaks_8.18.4_linux_x64.tar.gz
tar -xzf gitleaks_8.18.4_linux_x64.tar.gz && install gitleaks /usr/local/bin/
# 或 go install github.com/gitleaks/gitleaks/v8@latest

2. 全仓库历史扫描

gitleaks detect --source . --report-path gitleaks-report.json --report-format json --verbose

–report-path 导出 JSON 报告，–verbose 打印每条命中详情。

3. 提交前扫描暂存区

git add .
gitleaks protect --staged --verbose

4. 自定义规则 .gitleaks.toml（追加片段）

[[rules]]
id = "my-custom-api-key"
description = "内部平台 API 密钥"
regex = '''myapp_[a-zA-Z0-9]{32}'''
keywords = ["myapp_"]

[extend]
useDefault = true

[extend] useDefault = true 保留官方全部默认规则，只追加自定义规则。

5. 集成 pre-commit

# 项目根目录 .pre-commit-config.yaml
repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.18.4
    hooks:
      - id: gitleaks

6. 集成 GitHub Actions

name: Secret Scan
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: gitleaks/gitleaks-action@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

配置验证

  • 创建测试文件 echo "AKIAIOSFODNN7EXAMPLE" > test.txt，git add 后执行 gitleaks protect --staged 应返回非 0 退出码并提示命中
  • 查看 gitleaks-report.json 中 Finding 数量与匹配的规则 ID、commit 哈希
  • 在自定义规则 allowlist 中排除测试密钥后，protect 应恢复通过
  • detect 与 protect 发现泄露时退出码为 1，未发现为 0，可据此驱动 CI 失败

常见问题

FAQ 1：密钥已经提交到历史提交中，如何彻底清理？

使用 git filter-repo（推荐）或 BFG Repo-Cleaner 重写历史移除密钥，随后强制推送并通知所有协作者重新克隆仓库；同时立即在云平台吊销并轮换该密钥，仅清理历史不能保证安全。

FAQ 2：测试用假密钥总被误报，如何排除？

在对应规则的 allowlist 中配置 regex、paths 或 commits 白名单；更推荐把测试密钥统一放入 test/ 等指定目录，并在 allowlist.paths 中排除。

FAQ 3：扫描发现真实密钥被泄露，先做什么？

第一步是吊销并轮换密钥（云平台 IAM、GitHub Settings 等入口），第二步清理仓库历史，第三步重跑 gitleaks detect 确认清零，最后排查泄露时间窗口内的日志以评估影响面。

总结

Gitleaks 把密钥检测”左移”到开发与 CI 阶段，比事后人工排查成本低得多。建议企业将其作为强制质量门禁接入 pre-commit 与 GitHub Actions，配合定期全仓 detect 巡检与密钥管理平台（如 HashiCorp Vault）统一托管密钥，形成”扫描拦截 + 集中管理 + 泄露应急”的完整闭环。