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/