From 5847964bc3c3f20526901235c5a19a1bdebb315a Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Wed, 6 Dec 2023 11:41:27 +0100
Subject: [PATCH] scout: describe cve severity categorization

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
 content/scout/image-analysis.md | 39 +++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/content/scout/image-analysis.md b/content/scout/image-analysis.md
index c86e6e9236..2b5e8d1e71 100644
--- a/content/scout/image-analysis.md
+++ b/content/scout/image-analysis.md
@@ -202,3 +202,42 @@ reference documentation:
 
 - [`docker scout quickview`](../engine/reference/commandline/scout_quickview.md)
 - [`docker scout cves`](../engine/reference/commandline/scout_cves.md)
+
+## Vulnerability severity assessment
+
+Docker Scout assigns a severity rating to vulnerabilities based on
+vulnerability data from [advisory sources](./advisory-db-sources.md).
+Advisories are ranked and prioritized depending on the type of package that's
+affected by a vulnerability. For example, if a vulnerability affects an OS
+package, the severity level assigned by the distribution maintainer is
+prioritized.
+
+If the preferred advisory source has assigned a severity rating to a CVE, but
+not a CVSS score, Docker Scout falls back to displaying a CVSS score from
+another source. The severity rating from the preferred advisory and the CVSS
+score from the fallback advisory are displayed together. This means a
+vulnerability can have a severity rating of `LOW` with a CVSS score of 9.8, if
+the preferred advisory assigns a `LOW` rating but no CVSS score, and a fallback
+advisory assigns a CVSS score of 9.8.
+
+Vulnerabilities that haven't been assigned a CVSS score in any source are
+categorized as **Unspecified** (U).
+
+Docker Scout doesn't implement a proprietary vulnerability metrics system. All
+metrics are inherited from security advisories that Docker Scout integrates
+with. Advisories may use different thresholds for classifying vulnerabilities,
+but most of them adhere to the CVSS v3.0 specification, which maps CVSS scores
+to severity ratings according to the following table:
+
+| CVSS score | Severity rating  |
+| ---------- | ---------------- |
+| 0.1 – 3.9  | **Low** (L)      |
+| 4.0 – 6.9  | **Medium** (M)   |
+| 7.0 – 8.9  | **High** (H)     |
+| 9.0 – 10.0 | **Critical** (C) |
+
+For more information, see [Vulnerability Metrics (NIST)](https://nvd.nist.gov/vuln-metrics/cvss).
+
+Note that, given the advisory prioritization and fallback mechanism described
+earlier, severity ratings displayed in Docker Scout may deviate from this
+rating system.