Scan result policies Ultimate All offerings

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.

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

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.

Merge request with multiple pipelines

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 merge request’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

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.

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

scan_finding rule type

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

license_finding rule type

This rule enforces the defined actions based on license findings.

any_merge_request rule type

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.

approval_settings

The settings set in the policy overwrite settings in the project.

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:

type: 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: 1
  severity_levels:
  - critical
  vulnerability_states:
  - newly_detected
actions:
- type: require_approval
  approvals_required: 1
  user_approvers:
  - adalberto.dare

Understanding scan result policy approvals

Scope of scan result policy comparison

• To determine when approval is required on a merge request, we compare the latest completed pipelines for each supported pipeline source for the source and target branch (for example, feature/main). This ensures the most comprehensive evaluation of scan results.
• We compare findings from the latest completed pipelines that ran on HEAD of the source and target branch.
• Scan result policies considers all supported pipeline sources (based on the CI_PIPELINE_SOURCE variable) when comparing results from both the source and target branches when determining if a merge request requires approval. Pipeline sources webide and parent_pipeline are not supported.

Accepting risk and ignoring vulnerabilities in future merge requests

For scan result policies that are scoped to newly_detected findings, it’s important to understand the implications of this vulnerability state. A finding is considered newly_detected if it exists on the merge request’s branch but not on the default branch. When a merge request whose branch contains newly_detected findings is approved and merged, approvers are “accepting the risk” of those vulnerabilities. If one or more of the same vulnerabilities were detected after this time, their status would be previously_detected and so not be out of scope of a policy aimed at newly_detected findings. For example:

• A scan result policy is created to block critical SAST findings. If a SAST finding for CVE-1234 is approved, future merge requests with the same violation will not require approval in the project.

When using license approval policies, the combination of project, component (dependency), and license are considered in the evaluation. If a license is approved as an exception, future merge requests don’t require approval for the same combination of project, component (dependency), and license. The component’s version is not be considered in this case. If a previously approved package is updated to a new version, approvers will not need to re-approve. For example:

• A license approval policy is created to block merge requests with newly detected licenses matching AGPL-1.0. A change is made in project demo for component osframework that violates the policy. If approved and merged, future merge requests to osframework in project demo with the license AGPL-1.0 don’t require approval.

Multiple approvals

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.

Known issues

We have identified in epic 11020 common areas of confusion in scan result findings that need to be addressed. Below are a few of the known issues:

• When using newly_detected, some findings may require approval when they are not introduced by the merge request (such as a new CVE on a related dependency). We currently use main tip of the target branch for comparison. In the future, we plan to use merge base for newly_detected policies (see issue 428518).
• Findings or errors that cause approval to be required on a scan result policy may not be evident in the Security MR Widget. By using merge base in issue 428518 some cases will be addressed. We will additionally be displaying more granular details about what caused security policy violations.
• Security policy violations are distinct compared to findings displayed in the MR widgets. Some violations may not be present in the MR widget. We are working to harmonize our features in epic 11020 and to display policy violations explicitly in merge requests in epic 11185.

Troubleshooting

Merge request rules widget shows a scan result policy is invalid or duplicated Ultimate Self-managed

On GitLab self-managed from 15.0 to 16.4, the most likely cause is that the project was exported from a group and imported into another, and had scan result policy rules. These rules are stored in a separate project to the one that was exported. As a result, the project contains policy rules that reference entities that don’t exist in the imported project’s group. The result is policy rules that are invalid, duplicated, or both.

To remove all invalid scan result policy rules from a GitLab instance, an administrator can run the following script in the Rails console.

Project.joins(:approval_rules).where(approval_rules: { report_type: %i[scan_finding license_scanning] }).where.not(approval_rules: { security_orchestration_policy_configuration_id: nil }).find_in_batches.flat_map do |batch|
  batch.map do |project|
    # Get projects and their configuration_ids for applicable project rules
    [project, project.approval_rules.where(report_type: %i[scan_finding license_scanning]).pluck(:security_orchestration_policy_configuration_id).uniq]
  end.uniq.map do |project, configuration_ids| # We take only unique combinations of project + configuration_ids
    # If we find more configurations than what is available for the project, we take records with the extra configurations
    [project, configuration_ids - project.all_security_orchestration_policy_configurations.pluck(:id)]
  end.select { |_project, configuration_ids| configuration_ids.any? }
end.each do |project, configuration_ids|
  # For each found pair project + ghost configuration, we remove these rules for a given project
  Security::OrchestrationPolicyConfiguration.where(id: configuration_ids).each do |configuration|
    configuration.delete_scan_finding_rules_for_project(project.id)
  end
  # Ensure we sync any potential rules from new group's policy
  Security::ScanResultPolicies::SyncProjectWorker.perform_async(project.id)
end