用途
本技能用于在 Git 仓库中实现 Gitleaks 密钥扫描，检测并防止硬编码的敏感信息（如 API 密钥、密码、令牌、私钥）被提交到代码库。
适用场景包括：
- 开发者可能意外将 API 密钥、密码、令牌或私钥提交到仓库时；
- 建立 pre-commit 门禁，防止密钥进入 Git 历史时；
- 扫描已有仓库历史，查找此前提交的、需要轮换的密钥时；
- 合规要求对所有源代码仓库进行密钥检测时；
- 从人工密钥审计迁移到自动化持续扫描时。
不适用场景：检测运行中应用或内存中的密钥（应使用运行时密钥检测）；检测后的密钥管理（应使用 Vault 或 AWS Secrets Manager）；扫描容器镜像（应使用 Trivy 或 Grype）。
前提条件
- 通过二进制、Go install 或 Docker 安装 Gitleaks v8.18+；
- 安装 pre-commit 框架用于本地钩子集成；
- 存在待扫描历史的 Git 仓库；
- 具备 CI/CD 平台访问权限（GitHub Actions、GitLab CI 或等效平台）。
主要能力与使用方式
1. 安装并执行初始仓库扫描
在 macOS 上可用 brew install gitleaks，或从 https://github.com/gitleaks/gitleaks/releases 下载二进制。
- 扫描整个 Git 历史：
gitleaks detect --source . --report-format json --report-path gitleaks-report.json -v - 仅扫描暂存变更（用于 pre-commit）：
gitleaks protect --staged --report-format json --report-path gitleaks-staged.json - 扫描特定提交范围：
gitleaks detect --source . --log-opts="HEAD~10..HEAD" --report-format json - 不扫描 Git 历史（仅文件系统）：
gitleaks detect --source . --no-git --report-format json
2. 配置 pre-commit 钩子
在 .pre-commit-config.yaml 中引入 gitleaks 仓库与钩子，使用 gitleaks protect --staged --verbose --redact 作为 entry。安装框架使用 pip install pre-commit，然后 pre-commit install。可用 pre-commit run gitleaks --all-files 对所有文件运行，并通过提交包含示例密钥的文件验证钩子会阻止提交。
3. 集成到 GitHub Actions
在 .github/workflows/secret-scanning.yml 中定义工作流，在 push 和 pull_request 时触发。使用 actions/checkout@v4 并设置 fetch-depth: 0 以获取完整历史，然后使用 gitleaks/gitleaks-action@v2（需要 GITLEAKS_LICENSE）或直接下载安装 Gitleaks 运行。对 pull request 扫描 base 与 head 之间的提交范围，对 push 扫描全历史并使用基线文件，报告格式使用 SARIF，并通过 github/codeql-action/upload-sarif@v3 上传结果。
4. 编写自定义检测规则
在 .gitleaks.toml 中通过 [extend] useDefault = true 保留默认规则，并添加组织特定的规则，例如内部 API 令牌、数据库连接字符串、JWT 签名密钥等，可配置正则、熵阈值、关键词与标签。通过 [allowlist] 指定排除的路径与正则（如测试目录、示例值、占位符等）。
5. 管理基线
对已有仓库，先用 gitleaks detect 生成基线 JSON 文件，后续扫描使用 --baseline-path .gitleaks-baseline.json 使只有新增发现才触发失败，从而在历史密钥轮换期间不阻塞开发。需定期审查基线并移除已解决条目。
6. 修复暴露的密钥
检测到密钥后：立即在服务提供方吊销旧凭据并生成新凭据，将新凭据存入密钥管理器；使用 git-filter-repo 配合替换表达式从 Git 历史中移除密钥；团队协调后强制推送清理后的历史；将密钥模式加入 .gitleaks.toml 规则；更新基线文件移除已解决发现。
关键概念
- Secret（密钥）：不应出现在源代码中的任何凭据、令牌、密钥或敏感字符串。
- Pre-commit Hook（提交前钩子）：在提交创建前运行的 Git 钩子，阻止包含检测到密钥的提交。
- Entropy（熵）：字符串随机性的度量，高熵字符串更可能是密钥。
- Baseline（基线）：现有发现的快照，用于区分新密钥与既有密钥。
- Allowlist（允许列表）：指定从检测中排除的路径、模式或提交的配置。
- SARIF：静态分析结果交换格式，用于将发现上传到安全仪表板。
- git-filter-repo：用于重写 Git 历史以从所有提交中移除敏感数据的工具。
工具与系统
- Gitleaks：开源密钥检测工具，支持 pre-commit 钩子、CI/CD 和历史扫描。
- pre-commit：管理多语言 pre-commit 钩子的框架。
- git-filter-repo：从 Git 历史中移除密钥的历史重写工具。
- TruffleHog：另一种具备已验证密钥检测能力的密钥扫描器。
- GitHub Secret Scanning：GitHub 原生功能，检测匹配合作方模式的密钥。
常见场景：为遗留仓库启用密钥扫描
对一个多年未扫描的仓库，先对完整历史运行 gitleaks detect 生成基线 JSON，逐条分类（活跃需轮换、已失效、误报），立即轮换所有活跃密钥并更新使用方服务，提交基线文件（排除已修复的活跃密钥），立即为新开发启用 pre-commit 钩子，添加带基线的 CI/CD 扫描以仅捕获新密钥，并随着历史密钥轮换逐步缩减基线。
注意：不分类就生成基线意味着接受未轮换密钥的风险；未经与服务提供方核实不应假设历史密钥已失效；未协调就在共享仓库运行 git-filter-repo 会导致所有团队成员出现 rebase 冲突。
输出格式示例
报告包含仓库、扫描类型、扫描提交数、日期，以及发现总数、新增（不在基线中）与基线数量。新增发现列为阻塞项，包含规则、文件与行号、提交哈希与作者、被遮蔽的密钥及熵值。最后给出质量门禁结果（如 FAILED）与建议动作（立即轮换暴露的凭据）。