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

教程：使用流水线秘密检测保护你的项目

如果你的应用程序使用外部资源，通常需要使用秘密（如 token 或 key）来验证应用程序身份。如果秘密被推送到远程仓库，任何有权访问该仓库的人都可以冒充你或你的应用程序。

流水线秘密检测使用 CI/CD 作业来检查你的 GitLab 项目中是否存在秘密。在本教程中，你将创建一个项目、配置流水线秘密检测，并学习如何分析其结果：

  1. 创建项目
  2. 检查作业输出
  3. 启用合并请求流水线
  4. 添加假秘密
  5. 处理秘密
  6. 修复泄露

开始之前

开始本教程前，请确保你具备以下条件：

  • 一个 GitLab.com 账户。要充分利用流水线秘密检测的所有功能，如果你有 Ultimate 账户，应该使用该账户。
  • 对 CI/CD 有一定了解。

创建项目

首先，创建一个项目并启用秘密检测：

  1. 在左侧边栏顶部，选择 Create new（ plus ）> New project/repository。
  2. 选择 Create blank project。
  3. 输入项目详情：
    1. 输入项目名称和项目 slug。
    2. 从 Project deployment target (optional) 下拉列表中选择 No deployment planned。
    3. 勾选 Initialize repository with a README 复选框。这为你之后向项目添加内容提供了一个位置。
    4. 勾选 Enable Secret Detection 复选框。
  4. 选择 Create project。

将创建一个新项目，并使用 README 和 .gitlab-ci.yml 文件进行初始化。 CI/CD 配置包含 Security/Secret-Detection.gitlab-ci.yml 模板， 该模板在项目中启用了流水线秘密检测。

检查作业输出

流水线秘密检测在一个名为 secret_detection 的 CI/CD 作业中运行。 扫描结果写入 CI/CD 作业日志。每次扫描还会生成一份完整的报告作为作业产物。

要检查最近一次扫描的结果：

  1. 在左侧边栏，选择 Build > Jobs。
  2. 选择最近的 secret_detection 作业。如果你没有运行新的流水线，应该只有一个作业。
  3. 检查日志输出中的以下内容：
    • 关于扫描的信息，包括分析器版本和规则集。你的项目使用默认规则集，因为你自动启用了秘密检测。
    • 是否检测到任何秘密。你应该看到 no leaks found。
  4. 要下载完整报告，在 Job artifacts 下，选择 Download。

启用合并请求流水线

到目前为止，我们使用流水线秘密检测来扫描默认分支中的提交。但是要在将合并请求合并到默认分支之前分析其中的提交，你需要启用合并请求流水线。

为此：

  1. 将以下行添加到你的 .gitlab-ci.yml 文件中：

    variables:
  AST_ENABLE_MR_PIPELINES: "true"

  2. 保存更改并将其提交到项目的 main 分支。

添加假秘密

接下来，让我们通过在合并请求中"泄露"一个假秘密来使作业输出变得复杂：

  1. 检出一个新分支：

    git checkout -b pipeline-sd-tutorial

  2. 编辑你的项目 README 并添加以下行。 确保删除 - 前后的空格，以匹配个人访问令牌的确切格式：

    # 为使示例生效，请删除
# 破折号前后的空格：
glpat - 12345678901234567890

  3. 提交并推送你的更改，然后打开一个合并请求将其合并到默认分支。

    将自动运行合并请求流水线。

  4. 等待流水线完成，然后检查作业日志。你应该看到 WRN leaks found: 1。

  5. 下载作业产物并检查，确保它包含以下信息：

    • 秘密类型。在本示例中，类型是 "GitLab personal access token"。

    • 关于秘密用途的描述，以及一些可以采取的修复泄露的步骤。

    • 泄露的严重性。因为个人访问令牌可用于冒充 GitLab.com 上的用户，所以此泄露为 Critical。

    • 秘密的原始文本。

    • 关于秘密位置的一些信息：

      "file": "README.md",
"line_start": 97,
"line_end": 97,

      在本示例中，秘密位于文件 README.md 的第 97 行。

使用合并请求安全小部件

  • Tier: Ultimate

在非默认分支上检测到的秘密称为"发现项"（finding）。 当发现项被合并到默认分支时，它就变成了"漏洞"（vulnerability）。

合并请求安全小部件显示一个发现项列表，如果合并请求被合并，这些发现项可能会变成漏洞。

要查看小部件：

  1. 选择你在上一步中创建的合并请求。
  2. 找到合并请求安全小部件，它以 Security scanning 开头。
  3. 在小部件上，选择 Show details（ chevron-down ）。
  4. 查看显示的信息。你应该看到 Secret detection detected 1 new potential vulnerability。

要查看合并请求中所有发现项的详细视图，选择 View all pipeline findings。

处理秘密

  • Tier: Ultimate

在 GitLab Ultimate 上，作业输出还会写入：

  • 流水线的 Security 选项卡。
  • 如果发现项变成了漏洞，漏洞报告中。

为了演示如何通过 UI 处理秘密，让我们创建一个漏洞并在漏洞报告中更改其状态：

  1. 合并你在上一步中创建的 MR，然后等待流水线完成。

    假秘密被添加到 main，这导致发现项变成漏洞。

  2. 在左侧边栏，选择 Secure > Vulnerability report。

  3. 选择漏洞的 Description 以查看：

    • 关于秘密类型的详细信息。
    • 修复指导。
    • 关于漏洞检测时间和位置的信息。

  4. 选择 Edit vulnerability > Change status。

    1. 从 Status 下拉列表中选择 Dismiss as… Used in tests。
    2. 添加一条注释，解释你为什么向项目添加假秘密。
    3. 选择 Change status。

该漏洞不再出现在漏洞报告的首页上。

修复泄露

如果你将秘密添加到远程仓库，该秘密就不再安全，必须尽快撤销。即使秘密尚未合并到你的默认分支，你也应该撤销并替换它们。

你采取的具体修复步骤将取决于你组织的安全策略，但至少应该：

  1. 撤销秘密。当秘密被撤销后，它就不再有效，不能用于冒充合法活动。
  2. 从你的仓库中删除秘密。

具体的修复指导会写入 secret-detection 作业日志，并在漏洞报告详情页面上提供。