# Advisory severity and CVSS

Describes Keryn 0.5.2 and keryn-rules 0.8.0.

> How Keryn sets the severity of a vulnerable dependency, from the advisory's severity word or its CVSS v4, v3 or v2 vector, how that maps to error, warning and info, and what happens to an advisory with no usable severity.

Source: https://keryn.dev/docs/reference/sca/severity/

> **Caution: Ships in the next release**
> On main; not in Keryn 0.5.2, the latest release.

This applies to the dependency findings Keryn's own matcher produces (`keryn scan --online`, `keryn sca deno`, `keryn sca assess`). Reports imported from other scanners keep the severity their scanner gave.

## Source of the severity, in order

1. **The advisory's severity word.** It is read from the affected package's `ecosystem_specific.severity`, else `database_specific.severity`, else the record's `database_specific.severity`. `critical`, `high`, `medium`/`moderate` and `low` are used. Any other word (for example `UNKNOWN`) falls through to CVSS.
2. **CVSS.** Every vector in the affected entry's and the record's `severity` list is scored. The newest CVSS version present wins (v4 over v3 over v2), and within that version the highest score. A vector that does not parse is skipped.
3. **Unknown.** No usable word and no vector that scores.

| Score | Rating |
|---|---|
| 9.0–10.0 | critical (v3, v4); **high** for CVSS v2, which has no critical band |
| 7.0–8.9 | high |
| 4.0–6.9 | medium |
| 0.1–3.9 | low |
| 0.0 | info |

## Finding severity and the gate

| Rating | Finding severity | Fails the default `--fail-on error` |
|---|---|---|
| critical, high | `ERROR` | yes |
| medium | `WARNING` | no; yes with `--fail-on warning` |
| unknown | `WARNING` | no; yes with `--fail-on warning` |
| low, info | `INFO` | no; yes with `--fail-on info` |

A package with several advisories is one finding, rated at its worst advisory. When the worst is unknown and a scored advisory of the same rating exists, the scored one sets the finding, and the message's *the worst …* names that advisory.

**Unknown is never info.** A finding whose advisories have no usable severity says so in its message: *Severity unknown: the advisory has no severity word and no CVSS v2, v3 or v4 vector; it is gated as a warning.* The coverage statement counts such packages: *N vulnerable dependencies have only advisories with no usable severity … reported as severity unknown and gated as WARNING, so --fail-on warning holds on them.*

## Recorded fields

On each advisory in a dependency finding's `metadata.advisories[]`:

| Field | Meaning |
|---|---|
| `severity` | `critical`, `high`, `medium`, `low` or `info` (an unknown advisory reads `medium`, with `unknown: true`) |
| `severitySource` | `database_specific` (a severity word), `cvss_v4`, `cvss_v3`, `cvss_v2`, or `none` |
| `cvss`, `cvssVersion` | the best vector's base score and `4.0`, `3.x` or `2.0`. These are recorded even when a severity word set the rating |
| `cvssV3` | the v3 base score, when the best vector is v3 |
| `unknown` | true when the advisory had no usable severity |

The finding's own `metadata` repeats `severitySource`, `cvss` and `cvssVersion` for the advisory that set it, and `severity: "unknown"` when that advisory is unknown. SARIF `level` follows the finding severity. SARIF `security-severity` is Keryn's fixed band for that level (error 8.0, warning 5.0, info 2.0), not the CVSS score.
