Secret Detection

Moved from GitLab Ultimate to GitLab Free in 13.3.

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:

Secret Detection in merge request widget

caution
Secret Detection does not support scanning binary files.

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.

caution
Our Secret Detection jobs expect a Linux/amd64 container type. Windows containers are not supported.
caution
If you use your own runners, make sure the Docker version installed is not 19.03.0. See troubleshooting information for details.

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:

Capability In Free & Premium In Ultimate
Configure Secret Detection scanner
Customize Secret Detection settings
Download JSON Report
See new findings in the merge request widget
View identified secrets in the pipelines’ Security tab
Manage vulnerabilities
Access the Security Dashboard
Customize Secret Detection rulesets

Configuration

Version history
  • In GitLab 13.1, Secret Detection was split from the SAST configuration into its own CI/CD template. If you’re using GitLab 13.0 or earlier and SAST is enabled, then Secret Detection is already enabled.
  • In GitLab 14.0, Secret Detection jobs secret_detection_default_branch and secret_detection were consolidated into one job, secret_detection.

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.

note
You don’t have to configure Secret Detection manually as shown in this section if you’re using Auto Secret Detection, provided by Auto DevOps.

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

Introduced in GitLab 14.10.

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

Version history
note
This method works best with no existing .gitlab-ci.yml file, or with a minimal configuration file. If you have a complex GitLab configuration file it may not be parsed successfully, and an error may occur.

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.

caution
All customization of GitLab security scanning tools should be tested in a merge request before merging these changes to the default branch. Failure to do so can give unexpected results, including a large number of false positives.

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.

caution
Beginning in GitLab 13.0, the use of only and except is no longer supported. When overriding the template, you must use rules instead.