implementing-secrets-scanning-in-ci-cd

用途

该技能用于在 CI/CD 流水线中实现自动化的密钥扫描，帮助安全团队发现被意外提交到源代码仓库中的 API 密钥、令牌、密码及其他凭据，并提供一个 CI 门禁，阻止包含高危发现的部署。

主要能力

• 使用 gitleaks 通过正则模式和熵分析扫描 Git 仓库与目录中的硬编码密钥。
• 使用 trufflehog 执行文件系统与 Git 历史扫描，并可选地对活跃服务进行密钥验证。
• 将两款工具结合使用，提供较全面的密钥检测覆盖。
• 解析扫描结果并按严重级别（critical、high、medium、low）过滤，判断 CI 流水线应通过还是失败。
• 生成 JSON 报告，包含每个扫描器的发现总数、按严重级别分组的发现、单条发现的文件路径、行号、规则 ID 与脱敏后的密钥，以及 CI 门禁结论（pass/fail）和扫描时长、工具版本等执行元数据。

使用方式

1. 安装扫描工具：通过包管理器或二进制下载安装 gitleaks；通过 brew install trufflehog 或从 GitHub releases 下载安装 trufflehog。
2. 配置 gitleaks：在仓库根目录创建 .gitleaks.toml 配置文件，定义自定义规则、允许列表和路径排除项，使用 --config 指定自定义配置。
3. 运行 gitleaks 目录扫描：执行 gitleaks dir --source . --report-format json --report-path gitleaks-report.json 扫描工作目录并生成 JSON 报告。
4. 运行 trufflehog 文件系统扫描：执行 trufflehog filesystem /path/to/repo --json > trufflehog-report.json 扫描文件并输出 JSON 发现。
5. 解析与过滤发现：由 agent 脚本解析两份 JSON 报告，按严重级别过滤，并判断流水线是否通过。
6. 集成到 CI 流水线：在 GitHub Actions、GitLab CI 或 Jenkins 中作为部署前门禁加入扫描步骤，使用 gitleaks 的 --exit-code 控制流水线行为。
7. 配置 pre-commit 钩子：使用 gitleaks protect --staged 将其设置为 pre-commit 钩子，在提交前捕获密钥。
8. 复核与分流发现：检查 JSON 输出中的误报，将合法条目加入 .gitleaksignore，并立即轮换已确认泄露的凭据。

适用场景

• 在环境中部署或配置 CI/CD 密钥扫描能力时。
• 建立符合合规要求的安全控制措施时。
• 构建或改进该领域的安全架构时。
• 需要实施该方案的安全评估场景。

限制与前置条件

需要 Python 3.9 或更高版本；gitleaks v8.x 与 trufflehog v3.x 需已安装并可在 PATH 中使用；需要待扫描的 Git 仓库或目录；需要可访问的 CI/CD 平台（GitHub Actions、GitLab CI、Jenkins）。