- Detected secrets
- Requirements
- Configuration
- Post-processing and revocation
- Full History Secret Detection
- Running Secret Detection in an offline environment
- Troubleshooting
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:
- 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.
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
- 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
andsecret_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.
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
- Introduced in GitLab 13.11, deployed behind a feature flag, enabled by default.
- Feature flag removed in GitLab 14.1.
.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:
- On the top bar, select Menu > Projects and find your project.
- On the left sidebar, select Security & Compliance > Configuration.
- In the Secret Detection row, select Configure with a merge request.
- 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.
only
and except
is no longer supported. When overriding the template, you must use rules
instead.