Custom rulesets schema

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

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.

Configuration example:

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

Custom rule format

When creating custom rules, you can use both Gitleaks’ standard rule format and additional GitLab-specific fields. The following settings are available for each rule:

Example of a custom rule with all available fields:

[[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,}'''

When you create a custom rule that shares the same ID as a rule in the extended ruleset, your custom rule takes precedence. All properties of your custom rule replace the corresponding values from the extended rule.

Example of extending default rules with a custom rule:

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}'''

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