docs: distinguish Severity, Priority Score, and Risk Score (DOCT-2728)

[VeronicaSnyk]

Addresses DOCT-2728. Follow-up to #1735, which fixed the glossary links; this fixes what they lead to.

The reader problem

Support cases keep asking the same question: what is the difference between Priority Score, Severity, and Risk Score, and what score range maps to which priority level? Two cases name the documentation as the root cause in the support engineer's own words:

• 500PU000004QcqbYAC (HUMAN MANAGED) — "The customer's confusion stems from a lack of clear categorization or mapping of Snyk Priority Scores to specific priority levels... The documentation doesn't explicitly define score ranges for different priority levels."
• 500PU00000gmcXcYAI (Export Development Canada, still open) — "The customer lacks clear documentation or understanding regarding Snyk Code's vulnerability scoring mechanisms and the distinction between its various scoring metrics."

Correction to the ticket's evidence: DOCT-2728 claims nine cases and lists ten IDs. On verification, two do not exist (500PU00000XMRcyYAH, and the Flipkart-attributed 500PU00000OBwgGYAT, which appears to be a mangled 500PU00000OBwn7YAD/Securian), one needs manual Salesforce confirmation (500PU00000Xc6r0YAB), and two are about other problems (Paylocity 500PU00000sZgriYAC is an effective_severity_level methodology question; ADP 500PU00000pGCnwYAG is mostly exploit-field mapping). The defensible count is six on-topic cases, and two of those are not in the ticket: 500PU00001AF0RFYA1 (CGS International) and 500PU000007AanlYAC (Trio Advisory). The ticket should be amended.

The answer the docs never gave

The distinction is short, and it was assemblable from four pages but stated on none:

Severity is a band. Scores are ranks. Severity has published score ranges. Priority Score and Risk Score run 0–1,000 and order issues against each other; they have no bands, so a score does not correspond to Critical, High, Medium, or Low.

This is also why the confusion is reasonable rather than careless: Snyk publishes a score-to-level table for severity and shows a 0–1,000 number in the same UI column. Assuming the second also has a table is a fair inference.

Changes

The sentence that was generating tickets

priority-score-vs-risk-score.md read:

"Both scores provide a number between 1 and 1000, where 1 means low severity and 1000 means high severity."

Wrong on both counts, and the outlier: priority-score.md, risk-score.md, breakdown-of-code-analysis.md, enable-automatic-fix-prs.md, and the glossary all say 0–1,000. Replaced with the range plus an explicit rank-not-band statement, including why a Critical issue can rank below a High issue.

Also on that page:

• Added a "Can I map scores to priority levels?" section. The 700 Fix PR default is named as a configurable automation setting rather than a severity band, with a caveat that scores move when their factors move.
• Snyk coverage row omitted Snyk IaC while the same page's body text includes it twice. Added.
• Two table rows were both named Coverage meaning different things. Second renamed to Where it appears.
• Risk Score Integrations read NA → Not supported.
• Style per snyk-docs-writing-rules: contraction and first-person plural removed, analyses → analyzes, sentence-cased list labels, Fixed in available filter-name typo, one ungrammatical sentence.

Glossary — the three entries

None of the three referenced the others, so landing on any one did not distinguish it. Risk score was a single sentence with no release status, no coverage, and no link at all. Each entry now states what it is, its scale, how it differs from the other two, its coverage, and where to read more. Risk score → Risk Score to match the feature name (anchor unchanged).

Per the reference-page template in snyk-docs-writing-rules, the "how these relate" content (ask #4 on the ticket) lives on the comparison page, with all three glossary entries pointing to it, rather than as a conceptual section wedged into an A–Z list.

Severity levels

The Severity levels and Priority Score section named only Priority Score — so the page most readers land on first sent them to two of the three concepts. Now covers Risk Score and states the band-versus-rank distinction.

Corrections found while editing (not in the ticket)

• priority-score.md was stale on CVSS. It said the severity factor is "calculated using CVSS framework v3.1"; severity-levels.md states Snyk adopted v4.0 as its primary framework in 2024. Now scoped: v4.0 where a v4.0 vector exists, v3.1 for older vulnerabilities.
• risk-score.md Exploit maturity table sits under Objective likelihood risk factors but all four rows described an effect on the Impact subscore. Corrected to Likelihood.
• risk-score.md "Risk Score replaces the Priority Score directly" was unscoped, though the same page says two paragraphs later that the swap is Open Source and Container only, and only after retest. Now scoped.
• prioritize-issues-for-fixing/README.md repeated the conflation — "rank the severity of an issue" — on the hub page, which is the first framing many readers get. Fixed.
• A truncated sentence on the same page: "This helps you asse are calculated as part of the priority score." Repaired.
• Removed a self-referential link, an orphaned "An example follows" with no example, a duplicated business-criticality statement, a semicolon, and a singular/plural disagreement.

Deliberately not in this PR

Each needs an owner's answer before docs can state it. Raised as open questions on the ticket:

Question	Owner
Provider urgency is documented twice in risk-score.md with conflicting values for Medium, both tables describe Impact effects while one sits under Likelihood, and the two callouts contradict each other	Xujia Zhou
The Likelihood summary list names Scope; the drill-down documents Attack complexity instead	Xujia Zhou
Assessment model row says Priority Score is Impact + Actionability; priority-score.md lists seven factors	Xujia Zhou
Does the Temporal Score affect the Priority Score, as severity-levels.md claims? Not in the factor list	Xujia Zhou
Should CLI and IDE now be listed as Risk Score surfaces? risk-score.md says "not available in the CLI", but reachability-in-CLI material says the CLI returns a Risk Score, and IDE Closed Beta shipped 2026‑01‑19	Steve Winton
Are 700 and the Enterprise Implementation Guide's "Priority Score (900+)" operational defaults rather than bands? Should the unqualified 900+ be scoped?	Steve Winton
Does the 700 threshold apply to Open Source issues only, as internal enablement material states?	Steve Winton
Risk Score release status — docs say Early Access; an internal one-pager gives a GA-planned date of 2025‑11‑03	Steve Winton

Also left alone: the Low = 0.0–3.9 band in both the CVSS and CCSS tables. CVSS defines 0.0 as None, and Snyk's own opa-rules/scoring/severity.py maps 0.0 to none — but the same 0.0 figure ships in four app-ui report templates, so changing docs alone would create a new inconsistency. Needs a docs + app-ui change.

nav_context across this cluster is inconsistent (agnostic on two pages, classic on two) — same defect class #1735 routed to the consistency ticket, so added there rather than here.

Verification

• All six files were edited from blobs verified byte-identical to main, and each pushed blob SHA was checked against a locally computed git hash-object — all six match, so no unintended change slipped in.
• Every relative link target added or changed resolves to a file that exists in the repo; both anchors (#severity-levels-and-cvss, #calculation-of-priority-score) exist on their target pages.
• Factual claims validated against Snyk internal sources, including the CVSS v4.0 adoption announcement (18 June 2024), the Fix PR 700 default, Snyk Code's absence of Critical, license severity values, and Priority Score coverage of Snyk IaC.

One claim worth a reviewer's eye: Priority Score applying to Snyk IaC. priority-score-vs-risk-score.md states it twice, but an SME notes the IaC issue card shows a severity level rather than a score, with the score visible in Reports and the API. Stated as coverage here; flag if that is wrong.

---

Note

Low Risk
Documentation-only edits to prioritization terminology and factual corrections; no application or API behavior changes.

Overview
Clarifies a recurring support confusion: severity is a labeled band (Critical–Low with published CVSS/CCSS ranges); Priority Score and Risk Score are 0–1,000 ranks that order issues but do not map to those bands.

Glossary — Rewrites Priority Score, Risk Score (heading casing), and Severity so each cross-links the others, states coverage (including when Risk Score replaces Priority Score), and points to the comparison page.

Hub and severity page — prioritize-issues-for-fixing/README.md stops conflating scores with “ranking severity,” fixes a broken reachability sentence, and severity-levels.md now ties both scores to severity in one section with the band-vs-rank distinction.

Priority Score vs Risk Score — Replaces incorrect “1–1000 = low/high severity” wording with 0–1,000 urgency ranks; adds “Can I map scores to priority levels?” (no mapping; default 700 fix-PR threshold as automation, not a band); comparison table adds Snyk IaC, renames duplicate Coverage to Where it appears, and minor style/filter fixes.

Reference fixes — priority-score.md updates severity factor text to CVSS v4.0 / v3.1; risk-score.md scopes Priority Score replacement to Open Source/Container, and corrects exploit-maturity table effects from Impact to Likelihood subscores.

^{Reviewed by Cursor Bugbot for commit ec68fce. Bugbot is set up for automated code reviews on this repo. Configure here.}

[snyk-io]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues
✅	Code Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[cursor]

AI review

No style or structural issues found.

Verified: all 6 changed files pass link validation · terminology aligns across Severity, Priority Score, and Risk Score · score ranges (0–1,000 ranks vs CVSS/CCSS bands) and product coverage are consistent across glossary entries and prioritization pages · no invalid contractions or banned modals.

  

_{Sent by Cursor Automation: PR review for User Docs}

[cursor]

The current head commit 12504ef is reviewed.

  

_{Sent by Cursor Automation: PR review for User Docs}