流水线密钥检测

流水线密钥检测会在文件提交到 Git 仓库并推送到 GitLab 后扫描文件内容。

启用流水线密钥检测后，扫描将在名为 secret_detection 的 CI/CD 作业中运行。您可以在任何 GitLab 层级运行扫描并查看流水线密钥检测 JSON 报告产物。

使用 GitLab Ultimate 时，流水线密钥检测结果还会被进一步处理，以便您能够：

• 在合并请求小组件、流水线安全报告和漏洞报告中查看结果
• 在审批工作流中使用检测结果
• 在安全仪表盘中查看结果
• 自动响应公开仓库中的密钥泄露
• 通过安全策略在项目间强制执行一致的密钥检测规则

有关此流水线密钥检测文档的交互式阅读和操作演示，请参见：

• 如何在 GitLab 应用安全中启用密钥检测 第1/2部分
• 如何在 GitLab 应用安全中启用密钥检测 第2/2部分

其他交互式阅读和操作演示，请参见 GitLab 应用安全入门播放列表。

可用性

不同功能在GitLab 层级中可用性不同。

入门指南

要开始使用流水线密钥检测，请选择试点项目并启用分析器。

先决条件：

• 您拥有使用 docker 或 kubernetes 执行程序的 Linux 运行器。 如果您使用 GitLab.com 的托管运行器，此功能默认启用。
  • 不支持 Windows 运行器。
  • 不支持 amd64 以外的 CPU 架构。
• 您包含 test 阶段的 .gitlab-ci.yml 文件。

通过以下方式启用密钥检测分析器：

• 手动编辑 .gitlab-ci.yml 文件。如果您的 CI/CD 配置较复杂，请使用此方法。
• 使用自动配置的合并请求。如果您没有 CI/CD 配置或配置较简单，请使用此方法。
• 在扫描执行策略中启用流水线密钥检测。

如果这是您首次在项目中运行密钥检测扫描，请在启用分析器后立即运行历史扫描。

启用流水线密钥检测后，您可以自定义分析器设置。

手动编辑 .gitlab-ci.yml 文件

此方法需要手动编辑现有的 .gitlab-ci.yml 文件。

1. 在左侧边栏选择 Search or go to 并找到您的项目。

2. 选择 Build > Pipeline editor。

3. 将以下内容复制并粘贴到 .gitlab-ci.yml 文件末尾：

   include:
     - template: Jobs/Secret-Detection.gitlab-ci.yml

4. 选择 Validate 标签页，然后选择 Validate pipeline。 显示 Simulation completed successfully 消息表示文件有效。

5. 选择 Edit 标签页。

6. 可选。在 Commit message 文本框中自定义提交信息。

7. 在 Branch 文本框中输入默认分支名称。

8. 选择 Commit changes。

流水线现在包含流水线密钥检测作业。建议在启用分析器后运行历史扫描。

使用自动配置的合并请求

此方法会自动准备合并请求，添加包含流水线密钥检测模板的 .gitlab-ci.yml 文件。合并该合并请求即可启用流水线密钥检测。

启用流水线密钥检测：

1. 在左侧边栏选择 Search or go to 并找到您的项目。
2. 选择 Secure > Security configuration。
3. 在 Pipeline secret detection 行中，选择 Configure with a merge request。
4. 可选。填写字段。
5. 选择 Create merge request。
6. 查看并合并该合并请求。

流水线现在包含流水线密钥检测作业。

覆盖范围

流水线密钥检测经过优化，平衡了覆盖范围和运行时间。仅扫描仓库的当前状态和未来提交的密钥。要识别仓库历史中已存在的密钥，请在启用流水线密钥检测后运行一次历史扫描。扫描结果仅在流水线完成后可用。

具体扫描内容取决于流水线类型以及是否设置了任何额外配置。

默认情况下，运行流水线时：

• 在分支上：
  • 在默认分支上，扫描 Git 工作树。这意味着整个仓库会被扫描，就像扫描普通目录一样。
  • 在新的非默认分支上，扫描从父分支最新提交到最新提交的所有提交内容。
  • 在现有的非默认分支上，扫描从上次推送提交到最新提交的所有提交内容。
• 在合并请求上，扫描该分支的所有提交内容。如果分析器无法访问每个提交，则扫描从父提交到最新提交的所有提交内容。要扫描所有提交，您必须启用合并请求流水线。

要覆盖默认行为，请使用可用的 CI/CD 变量。

运行历史扫描

默认情况下，流水线密钥检测仅扫描 Git 仓库的当前状态。仓库历史中包含的密钥不会被检测到。运行历史扫描可检查 Git 仓库中所有提交和分支的密钥。

您应在启用流水线密钥检测后仅运行一次历史扫描。历史扫描可能需要很长时间，特别是对于具有较长 Git 历史的大型仓库。完成初始历史扫描后，仅将标准流水线密钥检测作为流水线的一部分使用。

如果您通过扫描执行策略启用流水线密钥检测，默认情况下首次计划扫描将是历史扫描。

运行历史扫描：

1. 在左侧边栏选择 Search or go to 并找到您的项目。
2. 选择 Build > Pipelines。
3. 选择 New pipeline。
4. 添加 CI/CD 变量：
   1. 从下拉列表中选择 Variable。
   2. 在 Input variable key 框中输入 SECRET_DETECTION_HISTORIC_SCAN。
   3. 在 Input variable value 框中输入 true。
5. 选择 New pipeline。

高级漏洞跟踪

当开发者修改包含已识别密钥的文件时，这些密钥的位置也可能随之变化。流水线密钥检测可能已将这些密钥标记为漏洞，并记录在漏洞报告中。这些漏洞与特定密钥关联，便于识别和操作。然而，如果检测到的密钥在移动过程中未被准确跟踪，管理漏洞将变得困难，可能导致重复的漏洞报告。

流水线密钥检测使用高级漏洞跟踪算法，更准确地识别因重构或无关更改导致同一密钥在文件内移动的情况。

更多信息，请参阅保密项目 https://gitlab.com/gitlab-org/security-products/post-analyzers/tracking-calculator。此项目内容仅对 GitLab 团队成员可见。

不支持的工作流

• 该算法不支持现有发现缺少跟踪签名且与最新检测发现位置不同的工作流。
• 对于某些规则类型（如加密密钥），流水线密钥检测通过匹配密钥前缀而非整个密钥值来识别泄露。在此场景下，算法会将文件中相同规则类型的不同密钥合并为一个发现，而不是将每个不同的密钥视为单独发现。例如，SSH 私钥规则类型仅匹配值的前缀 -----BEGIN OPENSSH PRIVATE KEY----- 来确认 SSH 私钥的存在。如果同一文件中有两个不同的 SSH 私钥，算法会将这两个值视为相同，并仅报告一个发现而非两个。
• 算法范围仅限于单个文件，即同一密钥出现在两个不同文件中时，会被视为两个不同的发现。

检测到的密钥

流水线密钥检测扫描仓库内容以匹配特定模式。每个模式对应特定类型的密钥，并通过 TOML 语法在规则中指定。GitLab 维护默认规则集。

使用 GitLab Ultimate 时，您可以扩展这些规则以满足需求。例如，虽然使用自定义前缀的个人访问令牌默认不会被检测到，但您可以自定义规则来识别这些令牌。详情请参见自定义分析器规则集。

要确认流水线密钥检测检测哪些密钥，请参见检测到的密钥。为提供可靠的高置信度结果，流水线密钥检测仅在特定上下文（如 URL）中查找密码或其他非结构化密钥。

检测到密钥时会为其创建漏洞。即使密钥已从扫描文件中移除且流水线密钥检测已再次运行，该漏洞仍会保持为“仍检测到”状态。这是因为泄露的密钥在被撤销前仍构成安全风险。已移除的密钥也会保留在 Git 历史中。要从 Git 仓库历史中移除密钥，请参见从仓库中擦除文本。

密钥检测结果

流水线密钥检测将输出文件 gl-secret-detection-report.json 作为作业产物。该文件包含检测到的密钥。您可以下载该文件在 GitLab 外进行处理。

更多信息，请参见报告文件架构和示例报告文件。

其他输出

作业结果还会报告在：

• 合并请求小组件：显示合并请求中引入的新发现。
• 流水线安全报告：显示最新流水线运行的所有发现。
• 漏洞报告：提供所有安全发现的集中管理。
• 安全仪表盘：提供跨项目和组的所有漏洞的组织级可见性。

理解结果

流水线密钥检测提供有关在仓库中发现的潜在密钥的详细信息。每个密钥包含泄露的密钥类型和修复指南。

查看结果时：

1. 查看周围代码，判断检测到的模式是否实际为密钥
2. 测试检测到的值是否为有效凭据。
3. 考虑仓库的可见性和密钥的作用域。
4. 优先处理活动的高权限密钥。

常见检测类别

流水线密钥检测的检测通常分为以下三类：

• 真实阳性：应轮换并移除的有效密钥。例如：
  • 活动的 API 密钥、数据库密码、认证令牌
  • 私钥和证书
  • 服务账户凭据
• 假阳性：检测到的模式并非实际密钥。例如：
  • 文档中的示例值
  • 测试数据或模拟凭据
  • 包含占位符值的配置模板
• 历史发现：先前提交但可能未活动的密钥。这些检测：
  • 需要调查以确定当前状态
  • 仍应作为预防措施进行轮换

修复泄露的密钥

检测到密钥后，应立即轮换它。GitLab 会尝试自动撤销某些类型的泄露密钥。对于未自动撤销的密钥，您必须手动操作。

从仓库历史中清除密钥并不能完全解决泄露问题。原始密钥仍存在于仓库的任何现有分支或克隆中。

有关如何响应泄露密钥的说明，请在漏洞报告中选择该漏洞。

优化

在组织中全面部署流水线密钥检测之前，请优化配置以减少误报并提高特定环境的准确性。

误报可能导致警报疲劳并降低对工具的信任度。考虑使用自定义规则集配置（仅 Ultimate）：

• 排除代码库中已知的安全模式。
• 调整频繁触发非密钥检测的规则的敏感度。
• 添加组织特定的密钥格式的自定义规则。

要在大型仓库或拥有多个项目的组织中优化性能，请检查：

• 扫描范围管理：
  • 在项目中运行历史扫描后关闭历史扫描。
  • 在低使用时段安排历史扫描。
• 资源分配：
  • 为大型仓库分配足够的运行器资源。
  • 考虑为安全扫描工作负载使用专用运行器。
  • 监控扫描时长并根据仓库大小进行优化。

测试优化更改

在组织范围内应用优化之前：

1. 验证优化不会遗漏有效密钥。
2. 跟踪误报减少和扫描性能改进。
3. 记录有效的优化模式。

部署

您应分阶段实施流水线密钥检测。在组织范围内推广该功能前，先从小规模试点开始，以了解工具的行为。

部署流水线密钥检测时遵循以下指南：

1. 选择试点项目。合适的项目具有：
   • 活跃的开发和定期提交。
   • 可管理的代码库大小。
   • 熟悉 GitLab CI/CD 的团队。
   • 愿意迭代配置。
2. 从简单开始。在试点项目上使用默认设置启用流水线密钥检测。
3. 监控结果。运行分析器一到两周，了解典型发现。
4. 处理检测到的密钥。修复发现的任何有效密钥。
5. 调整配置。根据初始结果调整设置。
6. 记录实施过程。记录常见的误报和修复模式。

FIPS 启用镜像

默认扫描器镜像基于 Alpine 基础镜像构建，以优化大小和可维护性。GitLab 提供Red Hat UBI版本的镜像，这些镜像符合 FIPS 标准。

要使用 FIPS 启用镜像，可以：

• 将 SECRET_DETECTION_IMAGE_SUFFIX CI/CD 变量设置为 -fips。
• 在默认镜像名称后添加 -fips 扩展名。

例如：

variables:
  SECRET_DETECTION_IMAGE_SUFFIX: '-fips'

include:
  - template: Jobs/Secret-Detection.gitlab-ci.yml

故障排除

调试级别日志

调试级别日志有助于故障排除。详情请参见调试级别日志。

警告：gl-secret-detection-report.json: no matching files

有关此问题的信息，请参见通用应用安全故障排除部分。

错误：Couldn't run the gitleaks command: exit status 2

流水线密钥检测分析器依赖在提交间生成补丁来扫描内容中的密钥。如果合并请求中的提交数量大于 GIT_DEPTH CI/CD 变量的值，密钥检测将无法检测密钥。

例如，您可能有一个由包含 60 个提交的合并请求触发的流水线，且 GIT_DEPTH 变量设置为小于 60。在这种情况下，流水线密钥检测作业会失败，因为克隆深度不足，无法包含所有相关提交。要验证当前值，请参见流水线配置。

要确认此错误原因，请启用调试级别日志，然后重新运行流水线。日志应类似于以下示例。文本 “object not found” 是此错误的症状。

ERRO[2020-11-18T18:05:52Z] object not found
[ERRO] [secrets] [2020-11-18T18:05:52Z] ▶ Couldn't run the gitleaks command: exit status 2
[ERRO] [secrets] [2020-11-18T18:05:52Z] ▶ Gitleaks analysis failed: exit status 2

要解决此问题，请将 GIT_DEPTH CI/CD 变量设置为更高的值。若仅应用于流水线密钥检测作业，可添加到您的 .gitlab-ci.yml 文件中：

secret_detection:
  variables:
    GIT_DEPTH: 100

错误：ERR fatal: ambiguous argument

如果仓库的默认分支与触发作业的分支无关，流水线密钥检测可能失败并显示 ERR fatal: ambiguous argument 错误。有关详细信息，请参见问题 !352014。

要解决此问题，请确保在仓库上正确设置默认分支。您应将其设置为与运行 secret-detection 作业的分支具有相关历史的分支。

作业日志中的 exec /bin/sh: exec format error 消息

GitLab 流水线密钥检测分析器仅支持在 amd64 CPU 架构上运行。此消息表示作业正在其他架构（如 arm）上运行。

错误：fatal: detected dubious ownership in repository at '/builds/<project dir>'

密钥检测可能以退出状态 128 失败。这可能是 Docker 镜像中用户更改导致的。

例如：

$ /analyzer run
[INFO] [secrets] [2024-06-06T07:28:13Z] ▶ GitLab secrets analyzer v6.0.1
[INFO] [secrets] [2024-06-06T07:28:13Z] ▶ Detecting project
[INFO] [secrets] [2024-06-06T07:28:13Z] ▶ Analyzer will attempt to analyze all projects in the repository
[INFO] [secrets] [2024-06-06T07:28:13Z] ▶ Loading ruleset for /builds....
[WARN] [secrets] [2024-06-06T07:28:13Z] ▶ /builds/....secret-detection-ruleset.toml not found, ruleset support will be disabled.
[INFO] [secrets] [2024-06-06T07:28:13Z] ▶ Running analyzer
[FATA] [secrets] [2024-06-06T07:28:13Z] ▶ get commit count: exit status 128

要解决此问题，添加以下 before_script：

before_script:
    - git config --global --add safe.directory "$CI_PROJECT_DIR"

有关此问题的更多信息，请参见 issue 465974。