GitLab Secret Scanning for Source Code

GitLab Secret Scanning for Source Code is an alternative analyzer for pipeline secret detection. It runs in the same secret_detection CI/CD job as the default analyzer, but provides additional secret detection, including detection of generic secrets.

How GitLab Secret Scanning for Source Code differs

The analyzer uses a proprietary scan engine developed by GitLab. Instead of relying on pattern matching, it uses heuristics to detect unstructured secrets and passwords beyond the standard GitLab Secret Detection rules. It combines multiple heuristic techniques to reduce false positives.

During beta, the analyzer provides:

• Generic secret detection: Identifies unstructured secrets and passwords, including contextual secrets beyond the standard GitLab Secret Detection rule coverage.
• False positive reduction: Combines multiple heuristic techniques to evaluate both the secret and its surrounding context to reduce noise in scan results.
• Encoded secret detection: Detects secrets that are encoded rather than stored in plain text. Supports base64-encoded strings.

Turn on the analyzer

Prerequisites:

• You have a Linux-based runner with the docker or kubernetes executor. If you use hosted runners for GitLab.com, this is enabled by default.
  • Windows runners are not supported.
  • CPU architectures other than amd64 are not supported.
• You have a .gitlab-ci.yml file that includes the test stage.

To turn on the analyzer, use the latest secret detection template and set the SECRET_DETECTION_ENABLE_GSS CI/CD variable to true:

include:
  - template: Jobs/Secret-Detection.latest.gitlab-ci.yml

secret_detection:
  variables:
    SECRET_DETECTION_ENABLE_GSS: "true"

Run the analyzer for the first time

The first time you run GitLab Secret Scanning for Source Code, you should run a historic scan. The analyzer scans all commits and updates the vulnerability report with the most recent findings, including taking over existing findings from pipeline secret detection.

To run a historic scan:

1. In the top bar, select Search or go to and find your project.
2. In the left sidebar, select Build > Pipelines.
3. Select New pipeline.
4. Add a CI/CD variable:
   1. From the dropdown list, select Variable.
   2. In the Input variable key box, enter SECRET_DETECTION_HISTORIC_SCAN.
   3. In the Input variable value box, enter true.
5. Select New pipeline.

If you set SECRET_DETECTION_HISTORIC_SCAN to true in your .gitlab-ci.yml file instead, remove the variable after the scan completes. Otherwise, every pipeline scans the full repository history.

Default configuration

When you turn on the analyzer, it runs with the following configuration:

Generic secrets

When the analyzer is turned on, generic secret detection is on by default.

To turn off generic secret detection, set the SECRET_DETECTION_GSS_ENABLE_GENERIC_SECRETS CI/CD variable to false:

include:
  - template: Jobs/Secret-Detection.latest.gitlab-ci.yml

secret_detection:
  variables:
    SECRET_DETECTION_ENABLE_GSS: "true"
    SECRET_DETECTION_GSS_ENABLE_GENERIC_SECRETS: "false"

Customize rules

You can apply scan customizations to GitLab Secret Scanning for Source Code with a .gitlab/secret-detection-ruleset.toml file in your repository. To create this file, see create a ruleset configuration file.

You can:

• Disable a rule from the default ruleset.
• Extend the default ruleset with your own rules. New rules must follow the custom rule format.
• Ignore secrets by regular expression or file path with allowlists.

For example, to extend the default ruleset and ignore secrets by regular expression or file path, use a file passthrough that points to an extended configuration file. Add the passthrough to the .gitlab/secret-detection-ruleset.toml file:

# .gitlab/secret-detection-ruleset.toml
[secrets]
  [[secrets.passthrough]]
    type   = "file"
    target = "gss.toml"
    value  = "extended-gss-config.toml"

In the extended configuration file, use [extend] to build on the default ruleset, and one or more [[allowlists]] tables to ignore findings. Each allowlist can match secret values with regexes and file paths with paths:

# extended-gss-config.toml
[extend]
# Extends the default packaged ruleset. Do not change the path.
path = "/gitleaks.toml"

[[allowlists]]
  description = "Ignore known test values and fixture paths"
  regexes = [
    '''glpat-[0-9a-zA-Z_\-]{20}''',
  ]
  paths = [
    '''spec/fixtures/.*''',
  ]

The regexes and paths in an allowlist are combined with a logical OR. A finding is ignored if its secret matches any of the regexes, or its file path matches any of the paths.

Migrate from the default analyzer

GitLab Secret Scanning for Source Code replaces the default analyzer in the secret_detection job. When the SECRET_DETECTION_ENABLE_GSS CI/CD variable is set to true, only GitLab Secret Scanning for Source Code runs.

To migrate from the default analyzer:

1. Turn on GitLab Secret Scanning for Source Code on a feature branch.
2. Run a pipeline and compare the findings against a scan that uses the default analyzer.
3. Review your ruleset customizations. For the available options, see customize rules.
4. When you’re satisfied with the results, turn on the analyzer on your default branch.

Existing findings after migration

When you turn on GitLab Secret Scanning for Source Code on your default branch, secrets that both analyzers detect are taken over by the analyzer. It matches these findings to the vulnerabilities previously reported by the default analyzer. Their existing vulnerability records carry over instead of being reported again as new findings.

Findings that the default analyzer previously reported but GitLab Secret Scanning for Source Code does not detect remain unchanged.

FIPS-enabled images

While GitLab Secret Scanning for Source Code is in beta, no FIPS-enabled image is published for it. If you set the SECRET_DETECTION_IMAGE_SUFFIX CI/CD variable to -fips, the secret_detection job fails because it cannot pull the image.

To scan with a FIPS-enabled image, use the default analyzer for pipeline secret detection.

Related topics

• Customize pipeline secret detection