• Detected secrets
• Requirements
  • Making Secret Detection available to all GitLab tiers
    • Summary of features per tier
• Configuration
  • Supported distributions
    • FIPS-enabled images
  • Enable Secret Detection via an automatic merge request
  • Customizing settings
    • GIT_DEPTH variable
    • Custom settings example
    • Available CI/CD variables
  • Custom rulesets
    • Disable predefined analyzer rules
      • Example: Disable predefined rules of Secret Detection analyzer
    • Override predefined analyzer rules
      • Example: Override predefined rules of Secret Detection analyzer
    • Synthesize a custom configuration
  • Logging level
• Post-processing and revocation
• Full History Secret Detection
• Running Secret Detection in an offline environment
  • Requirements for offline Secret Detection
  • Make GitLab Secret Detection analyzer image available inside your Docker registry
  • Set Secret Detection CI/CD variables to use the local Secret Detection analyzer container image
    • If support for Custom Certificate Authorities are needed
• Troubleshooting
  • Getting warning message gl-secret-detection-report.json: no matching files
  • Error: Couldn't run the gitleaks command: exit status 2
  • secret-detection job fails with ERR fatal: ambiguous argument message

Secret Detection

A recurring problem when developing applications is that people may accidentally commit secrets to their remote Git repositories. Secrets include keys, passwords, API tokens, and other sensitive information. Anyone with access to the repository could use the secrets for malicious purposes. Secrets exposed in this way must be treated as compromised, and be replaced, which can be costly. It’s important to prevent secrets from being committed to a Git repository.

Secret Detection uses the Gitleaks tool to scan the repository for secrets. All identified secrets are reported in the:

• Merge request widget
• Pipelines’ Security tab
• Security Dashboard

Detected secrets

Secret Detection uses a default ruleset containing more than 90 secret detection patterns. You can also customize the secret detection patterns using custom rulesets. If you want to contribute rulesets for “well-identifiable” secrets, follow the steps detailed in the community contributions guidelines.

Requirements

To run Secret Detection jobs, by default, you need GitLab Runner with the docker or kubernetes executor. If you’re using the shared runners on GitLab.com, this is enabled by default.

Making Secret Detection available to all GitLab tiers

To make Secret Detection available to as many customers as possible, we have enabled it for all GitLab tiers. However not all features are available on every tier. See the breakdown below for more details.

Summary of features per tier

Different features are available in different GitLab tiers, as shown in the following table:

Configuration

Secret Detection is performed by a specific analyzer during the secret-detection job. It runs regardless of your app’s programming language.

The Secret Detection analyzer includes Gitleaks checks.

Note that the Secret Detection analyzer ignores Password-in-URL vulnerabilities if the password begins with a dollar sign ($), as this likely indicates the password is an environment variable. For example, https://username:$password@example.com/path/to/repo isn’t detected, while https://username:password@example.com/path/to/repo is.

To enable Secret Detection for GitLab 13.1 and later, you must include the Secret-Detection.gitlab-ci.yml template that’s provided as a part of your GitLab installation. For GitLab versions earlier than 11.9, you can copy and use the job as defined in that template.

Ensure your .gitlab-ci.yml file has a stage called test, and add the following to your .gitlab-ci.yml file:

include:
  - template: Security/Secret-Detection.gitlab-ci.yml

The included template creates Secret Detection jobs in your CI/CD pipeline and scans your project’s source code for secrets.

The results are saved as a Secret Detection report artifact that you can later download and analyze. Due to implementation limitations, we always take the latest Secret Detection artifact available.

Supported distributions

The default scanner images are build off a base Alpine image for size and maintainability.

FIPS-enabled images

GitLab offers Red Hat UBI versions of the images that are FIPS-enabled. To use the FIPS-enabled images, you can either:

• Set the SAST_IMAGE_SUFFIX to -fips.
• Add the -fips extension to the default image name.

For example:

variables:
  SECRET_DETECTION_IMAGE_SUFFIX: '-fips'

include:
  - template: Security/Secret-Detection.gitlab-ci.yml

Enable Secret Detection via an automatic merge request

To enable Secret Detection in a project, you can create a merge request:

1. On the top bar, select Menu > Projects and find your project.
2. On the left sidebar, select Security & Compliance > Configuration.
3. In the Secret Detection row, select Configure with a merge request.
4. Review and merge the merge request to enable Secret Detection.

Pipelines now include a Secret Detection job.

Customizing settings

The Secret Detection scan settings can be changed through CI/CD variables by using the variables parameter in .gitlab-ci.yml.

To override a job definition, (for example, change properties like variables or dependencies), declare a job with the same name as the secret detection job to override. Place this new job after the template inclusion and specify any additional keys under it.