Custom rulesets schema

DETAILS: Tier: Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

You can use different kinds of ruleset customizations to customize the behavior of pipeline secret detection.

Schema

Customization of pipeline secret detection rulesets must adhere to a strict schema. The following sections describe each of the available options and the schema that applies to that section.

The top-level section

The top-level section contains one or more configuration sections, defined as TOML tables.

Configuration example:

[secrets]
...

The [secrets] configuration section

The [secrets] section lets you customize the behavior of the analyzer. Valid properties differ based on the kind of configuration you're making.

interpolate

WARNING: To reduce the risk of leaking secrets, use this feature with caution.

The example below shows a configuration that uses the $GITURL environment variable to access a private repository. The variable contains a username and token (for example https://user:token@url), so they're not explicitly stored in the configuration file.

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

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

The [[secrets.ruleset]] section

The [[secrets.ruleset]] section targets and modifies a single predefined rule. You can define one to many of these sections for the analyzer.

Configuration example:

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

The [secrets.ruleset.identifier] section

The [secrets.ruleset.identifier] section defines the identifiers of the predefined rule that you wish to modify.

To determine the correct values for type and value, view the gl-secret-detection-report.json produced by the analyzer. You can download this file as a job artifact from the analyzer's CI job.

For example, the snippet below shows a finding from a gitlab_personal_access_token rule with one identifier. The type and value keys in the JSON object correspond to the values you should provide in this section.

...
  "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"
        }
      ]
    }
    ...
  ]
...

Configuration example:

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

The [secrets.ruleset.override] section

The [secrets.ruleset.override] section allows you to override attributes of a predefined rule.

NOTE: Although message is still populated by the analyzers, it has been deprecated and replaced by name and description.

Configuration example:

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

The [[secrets.passthrough]] section

The [[secrets.passthrough]] section allows you to synthesize a custom configuration for an analyzer.

You can define up to 20 of these sections per analyzer. Passthroughs are then composed into a passthrough chain that evaluates into a complete configuration that can be used to replace or extend the predefined rules of the analyzer.

Passthroughs are evaluated in order. Passthroughs listed later in the chain have a higher precedence and can overwrite or append to data yielded by previous passthroughs (depending on the mode). Use passthroughs when you need to use or modify an existing configuration.

The size of the configuration generated by a single passthrough is limited to 10 MB.

Passthrough types