implementing-secrets-scanning-in-ci-cd

在 CI/CD 中实现密钥扫描

概述

本技能涵盖如何使用 gitleaks 和 trufflehog 在 CI/CD 流水线中实现自动化密钥扫描。它使安全团队能够检测被意外提交到源代码仓库中的 API 密钥、令牌、密码和其他凭据，并提供一个 CI 门禁，用于阻止包含高危发现项的部署。

Gitleaks 使用正则表达式模式和熵分析扫描 git 仓库和目录中的硬编码密钥。TruffleHog 执行文件系统和 git 历史扫描，并可选择针对在线服务进行密钥验证。二者结合可提供全面的密钥检测覆盖。

何时使用

• 在环境中部署或配置 CI/CD 中的密钥扫描实现能力时
• 在建立符合合规要求的安全控制时
• 在为此领域构建或改进安全架构时
• 在执行需要此实现的安全评估时

前置条件

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

步骤

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 报告，按严重级别（严重、高、中、低）过滤发现项，并确定 CI 流水线应通过还是失败。

6. 集成到 CI 流水线：将扫描步骤作为部署前门禁添加到你的 GitHub Actions 工作流、GitLab CI 配置或 Jenkins 流水线中。在 gitleaks 中使用 --exit-code 标志来控制流水线行为。

7. 配置 pre-commit 钩子：使用 gitleaks protect --staged 将 gitleaks 设置为 pre-commit 钩子，以在密钥被提交之前将其捕获。

8. 审查并分类发现项：检查 JSON 输出中的误报，将合法条目添加到 .gitleaksignore，并立即轮换任何已确认泄露的凭据。

预期输出

Agent 脚本生成一份 JSON 报告，其中包含：

• 每个扫描器的发现项总数
• 按严重级别分组的发现项
• 单个发现项详情，包括文件路径、行号、规则 ID 和已脱敏密钥
• 基于配置的严重级别阈值的 CI 门禁结论（通过/失败）
• 执行元数据，包括扫描时长和工具版本

{
  "scan_summary": {
    "tool": "both",
    "total_findings": 3,
    "critical": 1,
    "high": 1,
    "medium": 1,
    "low": 0,
    "ci_gate": "FAIL",
    "fail_reason": "Found 1 critical and 1 high severity findings"
  },
  "findings": [...]
}