About vulnerability policies¶

Vulnerability policies let organisations encode how specific vulnerabilities should be triaged across the portfolio. Where a standard policy raises violations, a vulnerability policy acts on the finding itself. It applies an analysis (state, justification, vendor response, details), optionally overrides the vulnerability's ratings, and can suppress the finding altogether.

Typical use cases include:

Suppress a CVE that has been assessed as not applicable to a given component or project.
Downgrade or upgrade a vulnerability's severity based on organisational context.
Centralise triage decisions so that every project benefits from them automatically, including projects imported in the future.

Policies are evaluated every time a project's vulnerabilities are analysed. Analyses applied by a policy populate the finding's audit trail in the same way as a manual analysis.

Why Not VEX?¶

CycloneDX VEX and VDR can also communicate triage decisions. Vulnerability policies complement them rather than replace them. The important differences are:

VEX analyses are static. A VEX statement records a decision for a specific finding at a specific point in time. Vulnerability policies are rules. A single policy can match many findings now and in the future, based on conditions such as component version ranges, project tags, or dependency graph relationships.
VEX cannot express constraints. A policy condition can say "apply this decision only while the affected component is reached through Spring Cloud" or "only for projects tagged 3rd-party". VEX cannot do this.
VEX has no built-in expiration or scope change. A policy has a validity window and can be edited or removed centrally. When it stops matching, the analyses it applied are automatically reverted.

Policy Sources¶

A vulnerability policy originates from one of two sources:

User-managed policies are created and edited directly in Dependency-Track. They can be modified or deleted at any time.
Bundle-managed policies are synchronised from a remote ZIP archive of YAML files. They appear with a lock icon and cannot be edited or deleted in the UI. To change a bundle policy, edit it in its source repository and re-sync the bundle.

Both sources share a single namespace. Policy names are globally unique across user-managed and bundle-managed policies. If a bundle sync encounters a policy whose name is already taken by a user-managed policy, the sync fails rather than silently overwriting either side.

Evaluation¶

Each policy is evaluated once per (component, vulnerability) pair. When multiple policies match the same finding, the policy with the highest priority value wins, and only its analysis and ratings are applied. When two or more matching policies have the same priority, the policy that was created first wins.

Validity Window¶

A policy is evaluated only while the current time falls within its Valid From and Valid Until timestamps. Both bounds are optional. A policy with neither bound is always active.

When a policy leaves its validity window (for example because Valid Until has elapsed, or because the policy is deleted), any analyses and rating overrides that were applied by it are automatically reverted on the next evaluation. The finding returns to whatever state it would have without the policy, or to the decision of the next-highest-priority policy that still matches. This makes it safe to use time-bounded policies for temporary suppressions, embargoes, or phased rollouts.

Operation Modes¶

Every policy has an operation mode that determines what happens when its condition matches. Refer to the operation modes reference for the full list.

Log mode is particularly useful when introducing a new policy. It lets you observe how often a policy would match without risking unintended suppression of real findings. Once confident, switch to Apply.