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

Vulnerability management policy schema