Scan result policies (ULTIMATE ALL)

Group-level scan result policies introduced in GitLab 15.6.

You can use scan result policies to take action based on scan results. For example, one type of scan result policy is a security approval policy that allows approval to be required based on the findings of one or more security scan jobs. Scan result policies are evaluated after a CI scanning job is fully executed.

NOTE: Scan result policies are applicable only to protected target branches.

NOTE: When a protected branch is created or deleted, the policy approval rules synchronize, with a delay of 1 minute.

The following video gives you an overview of GitLab scan result policies:

Merge request with multiple pipelines

• Introduced in GitLab 16.2 with a flag named multi_pipeline_scan_result_policies. Disabled by default.
• Enabled on GitLab.com and self-managed in GitLab 16.3.

FLAG: On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can disable the feature flag named multi_pipeline_scan_result_policies. On GitLab.com, this feature is available.

A project can have multiple pipeline types configured. A single commit can initiate multiple pipelines, each of which may contain a security scan.

• In GitLab 16.3 and later, the results of all completed pipelines for the latest commit in the MR's source and target branch are evaluated and used to enforce the scan result policy. Parent-child pipelines and on-demand DAST pipelines are not considered.
• In GitLab 16.2 and earlier, only the results of the latest completed pipeline were evaluated when enforcing scan result policies.

Scan result policy editor

• Introduced in GitLab 14.8.
• Enabled by default in GitLab 15.6.

NOTE: Only project Owners have the permissions to select Security Policy Project.

Once your policy is complete, save it by selecting Configure with a merge request at the bottom of the editor. This redirects you to the merge request on the project's configured security policy project. If a security policy project doesn't link to your project, GitLab creates such a project for you. Existing policies can also be removed from the editor interface by selecting Delete policy at the bottom of the editor.

Most policy changes take effect as soon as the merge request is merged. Any changes that do not go through a merge request and are committed directly to the default branch may require up to 10 minutes before the policy changes take effect.

The policy editor supports YAML mode and rule mode.

NOTE: Propagating scan result policies created for groups with a large number of projects take a while to complete.

Scan result policies schema

The YAML file with scan result policies consists of an array of objects matching the scan result policy schema nested under the scan_result_policy key. You can configure a maximum of five policies under the scan_result_policy key.

When you save a new policy, GitLab validates its contents against this JSON schema. If you're not familiar with how to read JSON schemas, the following sections and tables provide an alternative.

Scan result policy schema

The approval_settings field was introduced in GitLab 16.4 with a flag named scan_result_policy_settings. Disabled by default.

FLAG: On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to enable the feature flag named scan_result_policy_settings. On GitLab.com, this feature is not available.

scan_finding rule type

• The scan result policy field vulnerability_attributes was introduced in GitLab 16.2 with a flag named enforce_vulnerability_attributes_rules. Disabled by default.
• Enabled on GitLab.com and self-managed in GitLab 16.3.
• The scan result policy field vulnerability_age was introduced in GitLab 16.2.
• The branch_exceptions field was introduced in GitLab 16.3 with a flag named security_policies_branch_exceptions. Enabled by default.

FLAG: On self-managed GitLab, by default the vulnerability_attributes field is available. To hide the feature, an administrator can disable the feature flag named enforce_vulnerability_attributes_rules. On GitLab.com, this feature is available.

FLAG: On self-managed GitLab, by default the branch_exceptions field is available. To hide the feature, an administrator can disable the feature flag named security_policies_branch_exceptions. On GitLab.com, this feature is available.

This rule enforces the defined actions based on security scan findings.

license_finding rule type

• Introduced in GitLab 15.9 with a flag named license_scanning_policies.
• Generally available in GitLab 15.11. Feature flag license_scanning_policies removed.
• The branch_exceptions field was introduced in GitLab 16.3 with a flag named security_policies_branch_exceptions. Enabled by default.

FLAG: On self-managed GitLab, by default the branch_exceptions field is available. To hide the feature, an administrator can disable the feature flag named security_policies_branch_exceptions. On GitLab.com, this feature is available.

This rule enforces the defined actions based on license findings.

any_merge_request rule type

• Introduced in GitLab 16.4.
• The branch_exceptions field was introduced in GitLab 16.3 with a flag named security_policies_branch_exceptions. Enabled by default.

FLAG: On self-managed GitLab, by default the branch_exceptions field is available. To hide the feature, an administrator can disable the feature flag named security_policies_branch_exceptions. On GitLab.com, this feature is available.

This rule enforces the defined actions for any merge request based on the commits signature.

require_approval action type

This action sets an approval rule to be required when conditions are met for at least one rule in the defined policy.

Requirements and limitations:

• You must add the respective security scanning tools. Otherwise, scan result policies do not have any effect.
• The maximum number of policies is five.
• Each policy can have a maximum of five rules.
• All configured scanners must be present in the merge request's latest pipeline. If not, approvals are required even if some vulnerability criteria have not been met.

Example security scan result policies project

You can use this example in a .gitlab/security-policies/policy.yml file stored in a security policy project:

---
scan_result_policy:
- name: critical vulnerability CS approvals
  description: critical severity level only for container scanning
  enabled: true
  rules:
  - type: scan_finding
    branches:
    - main
    scanners:
    - container_scanning
    vulnerabilities_allowed: 0
    severity_levels:
    - critical
    vulnerability_states:
    - newly_detected
    vulnerability_attributes:
      false_positive: true
      fix_available: true
  actions:
  - type: require_approval
    approvals_required: 1
    user_approvers:
    - adalberto.dare
- name: secondary CS approvals
  description: secondary only for container scanning
  enabled: true
  rules:
  - type: scan_finding
    branches:
    - main
    scanners:
    - container_scanning
    vulnerabilities_allowed: 1
    severity_levels:
    - low
    - unknown
    vulnerability_states:
    - detected
    vulnerability_age:
      operator: greater_than
      value: 30
      interval: day
  actions:
  - type: require_approval
    approvals_required: 1
    role_approvers:
    - owner

In this example:

• Every MR that contains new critical vulnerabilities identified by container scanning requires one approval from alberto.dare.
• Every MR that contains more than one preexisting low or unknown vulnerability older than 30 days identified by container scanning requires one approval from a project member with the Owner role.

Example for Scan Result Policy editor

You can use this example in the YAML mode of the Scan Result Policy editor. It corresponds to a single object from the previous example:

- name: critical vulnerability CS approvals
  description: critical severity level only for container scanning
  enabled: true
  rules:
  - type: scan_finding
    branches:
    - main
    scanners:
    - container_scanning
    vulnerabilities_allowed: 1
    severity_levels:
    - critical
    vulnerability_states:
    - newly_detected
  actions:
  - type: require_approval
    approvals_required: 1
    user_approvers:
    - adalberto.dare

Example situations where scan result policies require additional approval

There are several situations where the scan result policy requires an additional approval step. For example:

• The number of security jobs is reduced in the working branch and no longer matches the number of security jobs in the target branch. Users can't skip the Scanning Result Policies by removing scanning jobs from the CI/CD configuration. Only the security scans that are configured in the scan result policy rules are checked for removal.

  For example, consider a situation where the default branch pipeline has four security scans: sast, secret_detection, container_scanning, and dependency_scanning. A scan result policy enforces two scanners: container_scanning and dependency_scanning. If an MR removes a scan that is configured in scan result policy, container_scanning for example, an additional approval is required.

• Someone stops a pipeline security job, and users can't skip the security scan.

• A job in a merge request fails and is configured with allow_failure: false. As a result, the pipeline is in a blocked state.

• A pipeline has a manual job that must run successfully for the entire pipeline to pass.