Security configuration

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

You can configure security scanners for projects individually or create a scanner configuration shared by multiple projects. Configuring each project manually gives you maximum flexibility but becomes difficult to maintain at scale. For multiple projects or groups, shared scanner configuration provides easier management while still allowing some customization where needed.

For example, if you have 10 projects with the same security scanning configuration applied manually, a single change must be made 10 times. If instead you create a shared CI/CD configuration, the single change only needs to be made once.

Configure an individual project

To configure security scanning in an individual project, either:

Edit the CI/CD configuration file.
Edit the CI/CD configuration in the UI.

With a CI/CD file

To manually enable security scanning of individual projects, either:

Enable individual security scanners.
Enable all security scanners by using AutoDevOps.

AutoDevOps provides a least-effort path to enabling most of the security scanners. However, customization options are limited, compared with enabling individual security scanners.

Enable individual security scanners

To enable individual security scanning tools with the option of customizing settings, include the security scanner's templates to your .gitlab-ci.yml file.

For instructions on how to enable individual security scanners, see their documentation.

Enable security scanning by using Auto DevOps

To enable the following security scanning tools, with default settings, enable Auto DevOps:

While you cannot directly customize Auto DevOps, you can include the Auto DevOps template in your project's .gitlab-ci.yml file and override its settings as required.

With the UI

Use the Security configuration page to view and configure the security testing and vulnerability management settings of a project.

The Security testing tab reflects the status of each of the security scanners. To determine the status of each security scanner it checks for a CI/CD pipeline in the most recent commit on the default branch.

If no CI/CD pipeline exists, the status of all security scanners is shown as Not enabled.
If a CI/CD pipeline exists, each job is inspected for the artifacts:reports keyword. If the keyword is defined, the security scanner's status is shown as Enabled, otherwise it's shown as Not enabled.

View security configuration page

To view a project's security configuration:

On the left sidebar, select Search or go to and find your project.
Select Secure > Security configuration.

To see a historic view of changes to the CI/CD configuration file, select Configuration history.

Edit a project's security configuration

To edit a project's security configuration:

On the left sidebar, select Search or go to and find your project.
Select Secure > Security configuration.
Select the security scanner you want to enable or configure and follow the instructions.

For more details on how to enable and configure individual security scanners, see their documentation.

Create a shared configuration

Tier: Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

To apply the same security scanning configuration to multiple projects, use one of the following methods:

Each of these methods allow a CI/CD configuration, including security scanning, to be defined once and applied to multiple projects and groups. These methods have several advantages over configuring each project individually, including:

Configuration changes only have to be made once instead of for each project.
Permission to make configuration changes is restricted, providing separation of duties.

Scan execution policy compared to compliance framework

Consider the following when deciding between using a scan execution policy or compliance framework.

Use a compliance framework pipeline when:
- Scan execution enforcement is required for any scanner that uses a GitLab template, such as SAST IaC, DAST, Dependency Scanning, API Fuzzing, or Coverage-guided Fuzzing.
- Scan execution enforcement is required for scanners external to GitLab.
- Scan execution enforcement is required for custom jobs other than security scans.
Use a scan execution policy when:
- Scan execution enforcement is required for DAST which uses a DAST site or scan profile.
- Scan execution enforcement is required for SAST, SAST IaC, Secret Detection, Dependency Scanning, or Container Scanning with project-specific variable customizations. To accomplish this, users must create a separate security policy per project.
- Scans are required to run on a regular, scheduled cadence.
Either solution can be used equally well when:
- Scan execution enforcement is required for Container Scanning with no project-specific variable customizations.

Additional details about the differences between these solutions are outlined below:

	Compliance Framework Pipelines	Scan Execution Policies
Flexibility	Supports anything that can be done in a CI/CD file.	Limited to only the items for which GitLab has explicitly added support. DAST, SAST, SAST IaC, Secret Detection, Dependency Scanning, and Container Scanning scans are supported.
Usability	Requires knowledge of CI YAML.	Follows a `rules` and `actions`-based YAML structure.
Inclusion in CI pipeline	The compliance pipeline is executed instead of the project's `.gitlab-ci.yml` file. To include the project's `.gitlab-ci.yml` file, use an `include` statement. Defined variables aren't allowed to be overwritten by the included project's YAML file.	Forced inclusion of a new job into the CI pipeline. DAST jobs that must be customized on a per-project basis can have project-level Site Profiles and Scan Profiles defined. To ensure separation of duties, these profiles are immutable when referenced in a scan execution policy. All jobs can be customized as part of the security policy itself with the same variables that are usually available to the CI job.
Schedulable	Has to be scheduled through a scheduled pipeline on each project.	Can be scheduled natively through the policy configuration itself.
Separation of Duties	Only group owners can create compliance framework labels. Only project owners can apply compliance framework labels to projects. The ability to make or approve changes to the compliance pipeline definition is limited to individuals who are explicitly given access to the project that contains the compliance pipeline.	Only project owners can define a linked security policy project. The ability to make or approve changes to security policies is limited to individuals who are explicitly given access to the security policy project.
Ability to apply one standard to multiple projects	The same compliance framework label can be applied to multiple projects inside a group.	The same security policy project can be used for multiple projects across GitLab with no requirement of being located in the same group.

Feedback is welcome on our vision for unifying the user experience for these two features

Customize security scanning

You can customize security scanning to suit your requirements and environment. For details of how to customize individual security scanners, refer to their documentation.

Best practices

When customizing the security scanning configuration:

Test all customization of security scanning tools by using a merge request before merging changes to the default branch. Failure to do so can give unexpected results, including a large number of false positives.
Include the scanning tool's CI/CD template. Don't copy the content of the template.
Override values in the template only as needed. All other values are inherited from the template.
Use the stable edition of each template for production workflows. The stable edition changes less often, and breaking changes are only made between major GitLab versions. The latest version contains the most recent changes, but may have significant changes between minor GitLab versions.

Template editions

GitLab application security tools have up to two template editions:

Stable: The stable template is the default. It offers a reliable and consistent application security experience. You should use the stable template for most users and projects that require stability and predictable behavior in their CI/CD pipelines.
Latest: The latest template is for those who want to access and test cutting-edge features. It is identified by the word latest in the template's name. It is not considered stable and may include breaking changes that are planned for the next major release. This template allows you to try new features and updates before they become part of the stable release.

Don't mix security templates in the same project. Mixing different security template editions can cause both merge request and branch pipelines to run.

Override the default registry base address

By default, GitLab security scanners use registry.gitlab.com/security-products as the base address for Docker images. You can override this for most scanners by setting the CI/CD variable SECURE_ANALYZERS_PREFIX to another location. This affects all scanners at once.

The Container Scanning analyzer is an exception, and it does not use the SECURE_ANALYZERS_PREFIX variable. To override its Docker image, see the instructions for Running container scanning in an offline environment.

Use security scanning tools with merge request pipelines

By default, the application security jobs are configured to run for branch pipelines only. To use them with merge request pipelines, either:

Set the CI/CD variable AST_ENABLE_MR_PIPELINES to "true" (introduced in 18.0) (Recommended)
Use the latest edition template which enables merge request pipelines by default.

For example, to run both SAST and Dependency Scanning with merge request pipelines enabled, the following configuration is used:

include:
  - template: Jobs/Dependency-Scanning.gitlab-ci.yml
  - template: Jobs/SAST.gitlab-ci.yml

variables:
  AST_ENABLE_MR_PIPELINES: "true"

Use a custom scanning stage

Security scanner templates use the predefined test stage by default. To have them instead run in a different stage, add the custom stage's name to the stages: section of the .gitlab-ci.yml file.

For more information about overriding security jobs, see:

Troubleshooting

When configuring security scanning you might encounter the following issues.

Error: `chosen stage test does not exist`

When running a pipeline you might get an error that states chosen stage test does not exist.

This issue occurs when the stage used by the security scanning jobs isn't declared in the .gitlab-ci.yml file.

To resolve this, either:

Add a test stage in your .gitlab-ci.yml:

include:
  - template: Jobs/Dependency-Scanning.gitlab-ci.yml
  - template: Jobs/SAST.gitlab-ci.yml
  - template: Jobs/Secret-Detection.gitlab-ci.yml

stages:
  - test
  - unit-tests

custom job:
  stage: unit-tests
  script:
    - echo "custom job"

Override the default stage of each security job. For example, to use a pre-defined stage named unit-tests:

include:
  - template: Jobs/Dependency-Scanning.gitlab-ci.yml
  - template: Jobs/SAST.gitlab-ci.yml
  - template: Jobs/Secret-Detection.gitlab-ci.yml

stages:
  - unit-tests

dependency_scanning:
  stage: unit-tests

sast:
  stage: unit-tests

.secret-analyzer:
  stage: unit-tests

custom job:
  stage: unit-tests
  script:
    - echo "custom job"