From fa4d05df6a22b7d759e91faa4e3021be3da5f0ae Mon Sep 17 00:00:00 2001 From: nscuro Date: Sun, 7 Jun 2026 18:08:33 +0200 Subject: [PATCH] Update vuln policies concept doc Mentions that application is atomic with findings themselves, and why that is beneficial. Also addresses wording and spelling that doesn't align with the project's style guidelines. Signed-off-by: nscuro --- docs/concepts/vulnerability-policies.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/docs/concepts/vulnerability-policies.md b/docs/concepts/vulnerability-policies.md index be4d6e0..9fe7122 100644 --- a/docs/concepts/vulnerability-policies.md +++ b/docs/concepts/vulnerability-policies.md @@ -1,6 +1,6 @@ # 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. @@ -8,11 +8,11 @@ optionally overrides the vulnerability's ratings, and can suppress the finding a 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? @@ -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* @@ -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/