Vulnerability management policy schema

The YAML file with vulnerability management policies consists of an array of objects matching the vulnerability management policy schema nested under the vulnerability_management_policy key.

When you save a vulnerability management policy, its content is validated against the vulnerability management policy schema. If you’re not familiar with how to read JSON schemas, the following sections and tables provide an alternative.

Field Type Required Description
vulnerability_management_policy array of vulnerability management policy true List of vulnerability management policies (maximum 5)

Vulnerability management policy

Field Type Required Description
name string true Name of the policy. Maximum of 255 characters.
description string false Description of the policy.
enabled boolean true Flag to enable (true) or disable (false) the policy.
rules array of rules true List of rules that define the policy’s criteria (maximum 5).
policy_scope object of policy_scope false Scope of the policy, based on the projects, groups, or compliance framework labels you specify.
actions array of actions true Action to be taken on vulnerabilities matching the policy.

no_longer_detected rule

This rule defines the criteria for auto-resolve policies.

Field Type Required Possible values Description
type string true no_longer_detected The rule’s type.
scanners array true sast, secret_detection, dependency_scanning, container_scanning, dast, coverage_fuzzing, api_fuzzing Specifies the scanners for which this policy is enforced.
severity_levels array true critical, high, medium, low, info, unknown Specifies the severity levels for which this policy is enforced.

detected rule

This rule defines the criteria for policies with auto_dismiss or severity_override actions.

Field Type Required Possible values Description
type string true detected The rule’s type.
criteria array of criteria objects true List of criteria. Vulnerability must match all criteria for the rule to apply. Maximum of 3 criteria.

Criteria object

Each criteria object must include a type field and either a value field (single value) or a values field (multiple values).

Field Type Required Possible values Description
type string true file_path, directory, identifier The type of criteria the vulnerabilities must match.
value string conditional Single value to match. Required if values is not specified.
values array of strings conditional Multiple values to match (OR logic). Required if value is not specified. Maximum of 1000 values. Requires the security_policies_severity_customize feature flag.
identifier_type string false cve, cwe, owasp For identifier type only. Matches against the identifier’s external type and ID. Requires the security_policies_severity_customize feature flag.

Criteria types:

  • file_path: Matches the file path where the vulnerability was found. Supports glob patterns like test/**/*.
  • directory: Matches the directory containing the vulnerable file. Supports glob patterns like vendor/*.
  • identifier: Matches vulnerability identifiers. Supports wildcard patterns like CVE-2023-*.

When identifier_type is specified, the criteria matches against the identifier’s external type and external ID. Example values by identifier type:

Identifier type Example values
cve CVE-2021-44228, CVE-2023-*
cwe CWE-79, CWE-89, CWE-*
owasp A1, A03:2021, A*

auto_resolve action

This action resolves vulnerabilities matching the policy’s rules and scope.

Field Type Required Possible values Description
type string true auto_resolve The action’s type.

auto_dismiss action

This action dismisses vulnerabilities matching the policy’s rules and scope.

Field Type Required Possible values Description
type string true auto_dismiss The action’s type.
dismissal_reason string true acceptable_risk, false_positive, mitigating_control, used_in_tests, not_applicable The reason for dismissing the vulnerability.

Dismissal reasons:

  • acceptable_risk: The vulnerability is known and accepted as a business risk.
  • false_positive: The vulnerability is incorrectly reported.
  • mitigating_control: Equivalent protection is provided by other controls.
  • used_in_tests: The vulnerability is part of test code or test data.
  • not_applicable: The vulnerability is in code that is no longer updated.

severity_override action

The availability of this feature is controlled by a feature flag. For more information, see the history.

This action overrides (or changes) the severity of vulnerabilities that match the policy’s rules and scope.

Field Type Required Possible values Description
type string true severity_override The action’s type.
severity_override_operation string true set, increase, decrease The operation to perform on the severity.
severity_override_value string conditional info, low, medium, high, critical Target severity. Required when severity_override_operation is set.

Operations:

  • set: Sets the vulnerability severity to the specified severity_override_value.
  • increase: Increases the vulnerability severity by one level (for example, low becomes medium).
  • decrease: Decreases the vulnerability severity by one level (for example, high becomes medium).

Example vulnerability management policy

vulnerability_management_policy:
- name: "Auto-dismiss test vulnerabilities"
  description: "Automatically dismiss vulnerabilities found in test files"
  enabled: true
  rules:
  - type: detected
    criteria:
    - type: file_path
      value: "test/**/*"
    - type: identifier
      value: "CVE-2023-*"
  actions:
  - type: auto_dismiss
    dismissal_reason: used_in_tests
- name: "Auto-resolve no longer detected SAST vulnerabilities"
  description: "Automatically resolve SAST vulnerabilities that are no longer detected"
  enabled: true
  rules:
  - type: no_longer_detected
    scanners:
    - sast
    severity_levels:
    - high
    - critical
  actions:
  - type: auto_resolve
- name: "Increase severity for critical CVEs in production code"
  description: "Increase severity of specific CVEs found outside test directories"
  enabled: true
  rules:
  - type: detected
    criteria:
    - type: identifier
      identifier_type: cve
      values:
      - "CVE-2021-44228"
      - "CVE-2023-*"
    - type: directory
      value: "src/**/*"
  actions:
  - type: severity_override
    severity_override_operation: set
    severity_override_value: critical