Skip to content

Update vuln policies concept doc #143

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nscuro merged 1 commit into from
Jun 7, 2026
Merged

Update vuln policies concept doc #143

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 14 additions & 5 deletions docs/concepts/vulnerability-policies.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,18 +1,18 @@
# About vulnerability policies

Vulnerability policies let organisations encode how specific vulnerabilities should be triaged across
Vulnerability policies let organizations encode how specific vulnerabilities should be triaged across
the portfolio. Where a [component policy](../reference/policies/component-policies.md) raises violations, a vulnerability policy acts
on the [finding](vulnerability-findings.md) 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 organisational context.
* Centralise triage decisions so that every project benefits from them automatically, including
* 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 analyses a project's vulnerabilities. Analyses that
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?
Expand Down Expand Up @@ -51,6 +51,16 @@ Dependency-Track evaluates each policy once per `(component, vulnerability)` pai
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](notifications.md), 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*
Expand Down Expand Up @@ -78,7 +88,6 @@ to *Apply*.
definitions, condition variables, the bundle YAML schema, and sync rules.
* [Managing vulnerability policies](../guides/user/managing-vulnerability-policies.md)
for step-by-step procedures.

* [About component policies](component-policies.md) for the complementary policy type.

[CycloneDX VEX]: https://cyclonedx.org/capabilities/vex/
Expand Down