Help us learn about your current experience with the documentation. Take the survey.

推送保护

  • Tier: Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

推送保护会阻止密钥、API 令牌等机密信息推送到 GitLab。

有关概述，请观看播放列表 Get Started with Secret Push Protection。

将 流水线密钥检测 与推送保护结合使用，可以进一步加强您的安全性。

推送保护工作流程

推送保护在 pre-receive hook 中执行。当您向 GitLab 推送更改时，推送保护会检查每个 文件或提交 是否包含机密信息。默认情况下，如果检测到机密信息，推送将被阻止。

显示密钥保护如何阻止推送的流程图

当推送被阻止时，GitLab 会显示包含以下信息的消息：

  • 包含机密信息的提交 ID。
  • 包含机密信息的文件名和行号。
  • 机密信息的类型。

例如，以下是在使用 Git CLI 客户端推送被阻止时返回的消息摘录。当使用其他客户端（包括 GitLab Web IDE）时，消息格式不同，但内容相同。

remote: PUSH BLOCKED: Secrets detected in code changes
remote: Secret push protection found the following secrets in commit: 37e54de5e78c31d9e3c3821fd15f7069e3d375b6
remote:
remote: -- test.txt:2 GitLab Personal Access Token
remote:
remote: To push your changes you must remove the identified secrets.

如果推送保护没有在您的提交中检测到任何机密信息，则不会显示任何消息。

检测到的机密信息

推送保护会扫描 文件或提交 中的特定模式。每个模式对应特定类型的机密信息。要确认推送保护检测到哪些机密信息，请参阅 检测到的机密信息。推送保护仅选择高置信度的模式，以减少推送提交时的延迟并减少误报数量。例如，使用自定义前缀的个人访问令牌不会被推送保护检测到。您可以通过 排除 选项，让推送保护忽略选定的机密信息。

入门指南

在 GitLab Dedicated 和 GitLab Self-Managed 实例上，您必须：

  1. 允许在整个实例上使用推送保护。
  2. 启用推送保护。您可以选择：

允许在 GitLab 实例中使用推送保护

在 GitLab Dedicated 和 GitLab Self-Managed 实例上，您必须在项目中启用推送保护前先允许使用它。

先决条件：

  • 您必须是 GitLab 实例的管理员。

要在 GitLab 实例中允许使用推送保护：

  1. 以管理员身份登录您的 GitLab 实例。
  2. 在左侧边栏底部，选择 管理员。
  3. 选择 设置 > 安全与合规。
  4. 在 密钥检测 下，选择或取消选择 允许推送保护。

推送保护已在实例上被允许。要使用此功能，您必须按项目启用它。

在项目中启用推送保护

先决条件：

  • 您必须拥有项目的维护者角色。
  • 在 GitLab Dedicated 和 GitLab Self-Managed 上，您必须在实例上允许推送保护。

要在项目中启用推送保护：

  1. 在左侧边栏，选择 搜索或跳转 并找到您的项目。
  2. 在左侧边栏，选择 安全 > 安全配置。
  3. 打开 推送保护 开关。

您也可以使用 API 为组中的所有项目启用推送保护。

覆盖范围

在以下情况下，推送保护不会阻止机密信息：

  • 推送提交时使用了 跳过推送保护 选项。
  • 机密信息被 排除 在推送保护之外。
  • 机密信息位于定义为 排除 的路径中。

在以下情况下，推送保护不会检查提交中的文件：

  • 文件是二进制文件。
  • 文件大于 1 MiB。
  • 文件的 diff 补丁大于 1 MiB（使用 差异扫描 时）。
  • 文件被重命名、删除或移动，但内容未更改。
  • 文件内容与源代码中另一个文件的内容相同。
  • 文件包含在创建仓库的初始推送中。

差异扫描

推送保护仅扫描通过 HTTP(S) 和 SSH 推送的提交的差异。如果机密信息已存在于文件中且不是更改的一部分，则不会被检测到。

理解结果

推送保护可以识别多种类别的机密信息：

  • API 密钥和令牌：特定服务的身份验证凭据
  • 数据库连接字符串：包含嵌入式凭据的 URL
  • 私钥：用于身份验证或加密的加密密钥
  • 通用高熵字符串：看起来是随机生成的机密信息模式

当推送被阻止时，推送保护会提供详细信息，帮助您定位和解决检测到的机密信息：

  • 提交 ID：包含机密信息的特定提交。有助于跟踪 Git 历史记录中的更改。
  • 文件路径和行号：检测到的模式的确切位置，便于快速导航。
  • 机密信息类型：检测到的模式的分类。例如，GitLab Personal Access Token 或 AWS Access Key。

常见检测类别

并非所有检测都需要立即处理。评估结果时请考虑以下因素：

  • 真实阳性：应该轮换和移除的有效机密信息。例如：

    • 有效 的 API 密钥或令牌
    • 生产数据库凭据
    • 私有加密密钥
    • 任何可能授予未授权访问的凭据

  • 误报：检测到的模式不是真正的机密信息。例如：

    • 类似机密信息但没有实际价值的测试数据
    • 配置模板中的占位值
    • 文档中的示例凭据
    • 匹配机密信息模式的哈希值或校验和

在组织中记录常见的误报模式，以便简化未来的评估。

优化

在广泛部署推送保护之前，优化配置以减少误报并提高特定环境的准确性。

减少误报

误报会显著影响开发人员的工作效率并导致安全疲劳。

要减少误报：

  • 战略性地配置 排除：
    • 为测试目录、文档和第三方依赖项创建基于路径的排除。
    • 为代码库中特定的已知误报模式创建基于模式的排除。
    • 记录您的排除规则并定期审查。
  • 为占位值和测试凭据制定标准。
  • 监控误报率并相应地调整排除规则。

优化性能

大型仓库或频繁的推送可能会影响性能。

要优化推送保护的性能：

  • 监控推送时间并在部署前建立基准指标。
  • 使用差异扫描来减少每次推送扫描的内容量。
  • 对于包含大型二进制资产的仓库，考虑文件大小限制。
  • 为不太可能包含机密信息的目录实施排除。

与现有工作流程集成

确保推送保护与您现有的开发实践相辅相成：

  • 配置流水线密钥检测和推送保护，确保您有多层防御。
  • 更新开发人员文档，包含推送保护流程。
  • 与安全培训保持一致，教育开发人员安全编码实践，以最小化机密信息泄露。

部署

大规模成功部署推送保护需要仔细规划和分阶段实施：

  1. 选择两三个有活跃开发的不关键项目来测试该功能，并了解其对开发工作流的影响。
  2. 为您选择的测试项目启用推送保护，并监控开发人员的反馈。
  3. 记录处理被阻止推送的流程，并对开发团队进行新工作流程的培训。
  4. 在试点阶段跟踪检测到的机密信息数量、误报率和开发人员体验反馈。

您应该运行 2-4 周的试点阶段，以收集足够的数据并在广泛部署前识别任何需要调整的工作流程。

完成试点后，考虑以下三个阶段进行规模化部署：

  1. 早期采用者（第 3-6 周）
    • 在 10-20% 的活跃项目中启用，优先考虑安全性敏感的仓库。
    • 专注于具有强烈安全意识和认同的团队。
    • 监控性能影响和开发人员体验。
    • 根据实际使用情况优化流程。
  2. 广泛部署（第 7-12 周）
    • 逐步在剩余的项目中分批启用。
    • 为开发团队提供持续的支持和培训。
    • 监控系统性能，并在需要时扩展基础设施。
    • 根据使用模式继续优化排除规则。
  3. 全面覆盖（第 13-16 周）
    • 在所有剩余的项目中启用推送保护。
    • 建立持续的维护和审查流程。
    • 对排除规则和检测到的模式实施定期审计。

解决被阻止的推送

当推送保护阻止推送时，您可以选择：

移除机密信息

移除被阻止的机密信息，以便提交可以推送到 GitLab。移除机密信息的方法取决于提交的时间。以下说明使用 Git CLI 客户端，但您也可以使用其他 Git 客户端实现相同的结果。

如果被阻止的机密信息是通过您分支上的最新提交添加的：

  1. 从文件中移除机密信息。
  2. 使用 git add <文件名> 暂存更改。
  3. 使用 git commit --amend 修改最新提交以包含更改的文件。
  4. 使用 git push 推送您的更改。

如果被阻止的机密信息出现在您的 Git 历史记录中较早的位置：

  1. 可选。观看 从提交中移除机密信息 的简短演示。
  2. 从推送错误消息中识别提交 SHA。如果有多个，使用 git log 找到最早的。
  3. 使用 git switch --create copy-branch 创建一个副本分支进行工作，这样如果变基遇到问题，可以重置到原始分支。
  4. 使用 git rebase -i <提交 SHA>~1 开始交互式变基。
  5. 在编辑器中将 pick 命令更改为 edit，标记有问题的提交进行编辑。
  6. 从文件中移除机密信息。
  7. 使用 git add <文件名> 暂存更改。
  8. 使用 git commit --amend 提交更改的文件。
  9. 使用 git rebase --continue 继续变基，直到所有机密信息都被移除。
  10. 使用 git push --force --set-upstream origin copy-branch:<原始分支> 从副本分支将更改推送到原始远程分支。
  11. 当您对更改满意时，考虑以下可选的清理步骤。
    1. 可选。使用 git branch --delete --force <原始分支> 删除原始分支。
    2. 可选。通过重命名副本分支替换原始分支：git branch --move copy-branch <原始分支>。

跳过推送保护

在某些情况下，可能需要跳过推送保护。例如，开发人员可能需要提交占位机密信息进行测试，或者用户可能因为 Git 操作超时而想要跳过推送保护。

当跳过推送保护时，会记录 审计事件。审计事件详细信息包括：

  • 使用的跳过方法。
  • GitLab 账户名称。
  • 跳过推送保护的日期和时间。
  • 机密信息被推送到其中的项目名称。
  • 目标分支。（GitLab 17.4 引入）
  • 跳过推送保护的提交。（GitLab 17.9 引入）

如果启用了 流水线密钥检测，提交内容在推送到仓库后会被扫描。

要跳过推送中所有提交的推送保护，可以：

使用 Git CLI 客户端时跳过

要在使用 Git CLI 客户端时跳过推送保护：

  • 使用 推送选项。

    例如，您有几个提交因为其中一个包含机密信息而被阻止推送。要跳过推送保护，您可以将推送选项附加到 Git 命令中。

    git push -o secret_push_protection.skip_all

使用任何 Git 客户端时跳过

要在使用任何 Git 客户端时跳过推送保护：

  • 将 [skip secret push protection] 添加到某个提交消息中，可以添加到现有行或新行，然后推送提交。

    例如，您正在使用 GitLab Web IDE，并且有几个提交因为其中一个包含机密信息而被阻止推送。要跳过推送保护，请编辑最新的提交消息并添加 [skip secret push protection]，然后推送提交。

故障排除

在使用推送保护时，您可能会遇到以下情况。

推送被意外阻止

在 GitLab 17.11 之前，推送保护会扫描所有修改文件的内容。如果修改的文件包含机密信息，即使该机密信息不是 diff 的一部分，也可能导致推送被意外阻止。

在 GitLab 17.11 及更早版本中，启用 spp_scan_diffs 功能标志 以确保只扫描新提交的更改。要将 Web IDE 的更改推送到包含机密信息的文件，您还需要启用 secret_checks_for_web_requests 功能标志。

文件未被扫描

某些文件被排除在扫描之外。详细信息请参阅 覆盖范围。