About vulnerability policies¶

Vulnerability policies let organizations encode how specific vulnerabilities should be triaged across the portfolio. Where a component 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 doesn't apply to a given component or project.
Downgrade or upgrade a vulnerability's severity based on organizational context.
Centralize triage decisions so that every project benefits from them automatically, including projects imported in the future.

Dependency-Track evaluates policies every time it analyzes a project's vulnerabilities. Analyses that a policy applies 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 moment. 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 sits behind a specific transitive dependency" or "only for projects tagged 3rd-party". VEX cannot do this.
VEX has no built-in expiry or scope change. A policy has a validity window and supports central editing or removal. When it stops matching, Dependency-Track automatically reverts the analyses it applied.

Policy sources¶

A vulnerability policy originates from one of two sources:

User-managed policies live directly in Dependency-Track. Users with the right permission can change or delete them at any time.
Bundle-managed policies sync from a remote ZIP archive of YAML files. They appear with a lock icon and the UI does not allow editing or deletion. 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¶

Dependency-Track evaluates each policy once per (component, vulnerability) pair. When two or more policies match the same finding, the policy with the highest priority value wins, and only its analysis and ratings take effect. When two or more matching policies share the same priority, the oldest policy wins.

Atomic with findings¶

Dependency-Track evaluates and applies policies atomically with the findings themselves. A finding suppressed by a policy never enters an unsuppressed state, not even briefly. As a result, suppressed findings do not trigger NEW_VULNERABILITY or NEW_VULNERABLE_DEPENDENCY notifications, and they do not surface as new findings in dashboards or metrics.

This is a meaningful advantage over post-hoc triage approaches such as VEX ingestion, where a notification fires on first detection and is only retracted once the triage decision lands.

Validity window¶

A policy applies 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 a user removed the policy), Dependency-Track automatically reverts any analyses and rating overrides from it 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.