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

自定义规则集架构

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

您可以使用不同类型的规则集自定义来定制流水线密钥检测的行为。

架构

流水线密钥检测规则集的自定义必须遵循严格的架构。以下各节描述了每个可用选项及其适用的架构。

顶级部分

顶级部分包含一个或多个配置节，定义为 TOML 表格。

设置 描述
[secrets] 声明分析器的配置节。

配置示例：

[secrets]
...

[secrets] 配置节

[secrets] 节允许您自定义分析器的行为。有效属性根据您正在进行的配置类型而异。

设置 适用范围 描述
[[secrets.ruleset]] 预定义规则 定义对现有规则的修改。
interpolate 全部 如果设置为 true，您可以在配置中使用 $VAR 来评估环境变量。请谨慎使用此功能，以免泄露密钥或令牌。（默认值：false）
description 直通规则 自定义规则集的描述。
targetdir 直通规则 最终配置应持久化的目录。如果为空，则会创建一个随机名称的目录。该目录最多可包含 100 MB 的文件。
validate 直通规则 如果设置为 true，则会验证每个直通规则的内容。验证适用于 yaml、xml、json 和 toml 内容。根据 [[secrets.passthrough]] 节中 target 参数使用的扩展名，识别适当的验证器。（默认值：false）
timeout 直通规则 评估直通链超时前的最长时间。超时时间不能超过 300 秒。（默认值：60）

interpolate

为降低泄露密钥的风险，请谨慎使用此功能。

下面的示例展示了一个使用 $GITURL 环境变量访问私有仓库的配置。该变量包含用户名和令牌 （例如 https://user:token@url），因此它们不会显式存储在配置文件中。

[secrets]
  description = "My private remote ruleset"
  interpolate = true

  [[secrets.passthrough]]
    type  = "git"
    value = "$GITURL"
    ref = "main"

[[secrets.ruleset]] 节

[[secrets.ruleset]] 节用于定位和修改单个预定义规则。您可以为分析器定义一个或多个这样的节。

设置 描述
disable 是否应禁用该规则。（默认值：false）
[secrets.ruleset.identifier] 选择要修改的预定义规则。
[secrets.ruleset.override] 定义规则的覆盖。

配置示例：

[secrets]
  [[secrets.ruleset]]
    disable = true
    ...

[secrets.ruleset.identifier] 节

[secrets.ruleset.identifier] 节定义您希望修改的预定义规则的标识符。

设置 描述
type 预定义规则使用的标识符类型。
value 预定义规则使用的标识符值。

要确定 type 和 value 的正确值，请查看分析器生成的 gl-secret-detection-report.json。 您可以从分析器的 CI/CD 作业中下载此文件作为作业产物。

例如，下面的代码片段显示了一个带有单个标识符的 gitlab_personal_access_token 规则的发现。 JSON 对象中的 type 和 value 键对应于您应在本节中提供的值。

...
  "vulnerabilities": [
    {
      "id": "fccb407005c0fb58ad6cfcae01bea86093953ed1ae9f9623ecc3e4117675c91a",
      "category": "secret_detection",
      "name": "GitLab personal access token",
      "description": "GitLab personal access token has been found in commit 5c124166",
      ...
      "identifiers": [
        {
          "type": "gitleaks_rule_id",
          "name": "Gitleaks rule ID gitlab_personal_access_token",
          "value": "gitlab_personal_access_token"
        }
      ]
    }
    ...
  ]
...

配置示例：

[secrets]
  [[secrets.ruleset]]
    [secrets.ruleset.identifier]
      type = "gitleaks_rule_id"
      value = "gitlab_personal_access_token"
    ...

[secrets.ruleset.override] 节

[secrets.ruleset.override] 节允许您覆盖预定义规则的属性。

设置 描述
description 问题的详细描述。
message （已弃用）问题的描述。
name 规则的名称。
severity 规则的严重性。有效选项包括：Critical、High、Medium、Low、Unknown、Info

尽管分析器仍然会填充 message，但它已被 弃用 并由 name 和 description 替代。

配置示例：

[secrets]
  [[secrets.ruleset]]
    [secrets.ruleset.override]
      severity = "Medium"
      name = "systemd machine-id"
    ...

自定义规则格式

创建自定义规则时，您可以使用 Gitleaks 的标准规则格式 和额外的 GitLab 特定字段。以下规则可用：

设置 必需 描述
title 否 设置规则自定义标题的 GitLab 特定字段。
description 是 规则检测内容的详细描述。
remediation 否 规则触发时提供修复指导的 GitLab 特定字段。
regex 是 用于检测密钥的正则表达式模式。
keywords 否 在应用正则表达式之前用于预过滤内容的关键字列表。
id 是 规则的唯一标识符。

包含所有可用字段的自定义规则示例：

[[rules]]
  title = "API Key Detection Rule"
  description = "Detects potential API keys in the codebase"
  remediation = "Rotate the exposed API key and store it in a secure credential manager"
  id = "custom_api_key"
  keywords = ["apikey", "api_key"]
  regex = '''api[_-]key[_-][a-zA-Z0-9]{16,}'''

当您创建的自定义规则与扩展规则集中的规则共享相同的 ID 时，您的自定义规则将优先。您的自定义规则的所有属性将替换扩展规则中的相应值。

使用自定义规则扩展默认规则的示例：

title = "Extension of GitLab's default Gitleaks config"

[extend]
  path = "/gitleaks.toml"

[[rules]]
  title = "Custom API Key Rule"
  description = "Detects custom API key format"
  remediation = "Rotate the exposed API key"
  id = "custom_api_123"
  keywords = ["testing"]
  regex = '''testing-key-[1-9]{3}'''

[[secrets.passthrough]] 节

[[secrets.passthrough]] 节允许您为分析器合成自定义配置。

每个分析器最多可以定义 20 个这样的节。然后，直通规则组合成一个 直通链，该链会评估为一个完整配置，可用于替换或扩展分析器的预定义规则。

直通规则按顺序评估。链中列出的后续直通规则具有更高的优先级， 并且可以覆盖或附加到先前直通规则提供的数据（取决于 mode）。当您需要使用或修改现有配置时，请使用直通规则。

单个直通规则生成的配置大小限制为 10 MB。

设置 适用范围 描述
type 全部 file、raw、git 或 url 之一。
target 全部 包含直通评估写入数据的目标文件。如果为空，则使用随机文件名。
mode 全部 如果为 overwrite，则覆盖 target 文件。如果为 append，则将新内容附加到 target 文件。git 类型仅支持 overwrite。（默认值：overwrite）
ref type = "git" 包含要拉取的分支、标签或 SHA 的名称。
subdir type = "git" 用于选择 Git 存储库的子目录作为配置源。
auth type = "git" 用于在使用 存储在私有 Git 存储库中的配置 时提供凭据。
value 全部 对于 file、url 和 git 类型，定义文件或 Git 存储库的位置。对于 raw 类型，包含内联配置。
validator 全部 用于在直通评估后显式调用目标文件上的验证器（xml、yaml、json、toml）。

直通规则类型

类型 描述
file 使用存储在同一 Git 存储库中的文件。
raw 提供内联的规则集配置。
git 从远程 Git 存储库拉取配置。
url 使用 HTTP 获取配置。