watchdep
Sign inSource
Docs / Concepts / 06

Levels and lanes

Section
Concepts
Page
06 of 16

Every finding gets one of four levels, loudest first: severe, high, medium and low. The level says how soon a person should act, and it is worked out the same way everywhere: the CLI and the server rank with the same rules and test against the same list of cases (shown at the end of this page), so they can never disagree. Labels sit beside the level and say why, and a finding sits in one of two lanes, depending on how sure watchdep is that the version you use is affected.

The four levels

Level Badge What it means
Severe octagon, red Act today: exploited now, a malicious release, or critical and likely to be exploited.
High triangle, deep orange Serious. Plan the fix soon.
Medium ringed dot Worth fixing in the normal course of work.
Low circle Unlikely to matter, kept so nothing is hidden.

Severe is narrow on purpose. Everything else that is serious is high, so a severe finding always means “today”.

How a level is worked out

First comes the severity band. A CVSS score wins where any source states one: critical is 9.0 and above, high 7.0 to 8.9, medium 4.0 to 6.9, low below 4.0. With no score, the source’s own word stands in (critical; high or important; moderate or medium; low, negligible or unimportant). With neither, there is no band.

Then the rules below apply, in this order. EPSS is the probability, published daily, that a CVE is exploited in the next 30 days. CISA KEV is the list of vulnerabilities known to be exploited now.

When Level Label
A malicious release, in any scope severe malicious
Listed in CISA KEV severe exploited now
No severity of any kind from any source high unscored
Critical, no EPSS score yet severe provisional
Critical, EPSS at or above the threshold severe
Critical, EPSS below the threshold high
High high
Medium, EPSS at or above the threshold high
Medium medium
Low, EPSS at or above the threshold medium
Low low
Development only (after the rules above) one level lower: severe to high, high to medium, medium to low, low stays low development only
A runtime, database or framework past the end of security support, or within 90 days of it high (medium for a framework used only in development)

The EPSS threshold is 10 percent by default. On the server it is a workspace setting (Settings, Workspace), and every finding in the workspace is ranked with it. The CLI’s offline gate takes it as --epss-threshold (for example --epss-threshold 0.10).

A few things follow from the rules:

  • EPSS raises levels, and lowers only critical. A medium that is likely to be exploited becomes high. A critical with a low probability of exploitation is high rather than severe. Nothing below critical is ever lowered by a low score, so a quiet score never hides a finding.
  • Development only drops one level, except for a malicious release. A package reached only from development or test groups matters less, so a development-only finding is never severe unless it is malicious. A malicious release stays severe in any scope: its install scripts already ran on a developer’s machine or in CI, and the remedy is to remove the version now.
  • End of life is high, not severe, both near the date and past it. Making every runtime past its end severe and immediate would cry wolf. The date itself carries the colour: red once it has passed, deep orange while it is coming.

Labels

Label Shown as Meaning
exploited now “Exploited now, CISA KEV”, with a pulse CISA KEV lists one of the finding’s CVEs, with the date it was added. The pulse is the only animation watchdep runs by itself.
malicious “Malicious release” The release itself is malicious (a malware report). Remove the version now.
provisional “Critical, provisional” and “No exploit score yet” Critical, and EPSS has no score yet. Severe for now; re-ranked when the score arrives.
unscored “No severity stated” No source states a CVSS score or a severity word. Ranked high until one does.
development only “Development only” Every place the finding appears is reached only from development or test groups.

Why missing data errs louder

watchdep follows two rules that can pull against each other: never miss a severe finding, and never cry wolf. They conflict when data is missing, and then watchdep takes the louder answer and says so with a label, so you can tell a firm level from a provisional one.

  • A new critical CVE is exactly the case where EPSS has not caught up. So a critical finding with no score yet is severe now, labelled provisional. When the score arrives the finding is ranked again: at or above the threshold it stays severe (no longer provisional); below it, it is lowered to high, quietly.
  • No severity at all is high, never low. A finding nobody has scored yet is not a small finding.
  • A failed source never reads as clean. If CISA KEV or EPSS does not answer, findings are still ranked with what is known, and an unknown EPSS score makes a critical severe and provisional. In watchdep gate, an advisory OSV names for a package but whose details cannot be fetched is kept, never dropped: a malware report id (MAL-) alone makes it a severe malicious finding, and any other id makes it a finding with no severity stated (high in production); both are labelled provisional, and OSV’s error makes the run incomplete.

When a level goes up (a CVE is added to KEV, or a medium’s EPSS score crosses the threshold), the server alerts it as an escalation. A level going down never alerts. See Alerts.

Two lanes: confirmed and early warning

  • Confirmed: the exact version you use is listed as affected. Everything ranked by the rules above is in this lane.
  • Early warning: a source names a package, runtime or database you use in production before affected versions are known. Early warnings come from the GitHub Advisory Database’s unreviewed advisories, the Node.js, Rails and PostgreSQL security announcements, and the oss-security list.

Early warnings are kept apart so they never read as confirmed. They have their own view (“Early warnings” in the explorer), they are left out of the confirmed finding lists (which link to them with a count), and each is labelled “Early warning, unconfirmed”, with “Not known yet: no affected versions published” as its fix.

  • Matching is exact, never fuzzy. By exact package name, and ecosystem where the source states it, against production inventories. The oss-security list states nothing structured, so its subjects match only exact names of production packages of five characters or more, as whole words.
  • Level comes only from a stated severity. An unreviewed GitHub advisory’s severity gives the level (critical is severe, high is high, moderate is medium, low is low), dropped one level in development scope. Announcements and mailing list items state none, so they have no level and show a “No level” badge.
  • Alerts: a severe early warning is always told immediately. One with no level goes to the daily digest of everyone who gets any alerts, never immediately.
  • Becoming confirmed: when the affected versions are published and the version you use is affected, the early warning becomes a confirmed finding (the same finding, with the same history), logged “Confirmed: the details arrived and the version in use is affected”.
  • Withdrawn: when the advisory is withdrawn; when no details arrive within 30 days; when the affected versions arrive and show your version unaffected (until they settle it, the warning stays, past 30 days too); or when production no longer has the package where watchdep looked. A file watchdep could not read this time keeps the warning open: it is never withdrawn for want of looking.

Incomplete runs

“No findings” never means “did not look”. A result is incomplete when any of these happened, and each is shown with its reason, in deep orange:

What happened Shown as
A dependency file could not be read the file and the reason
An ecosystem is present but no reader supports it the file and the ecosystem
Packages of an ecosystem no advisory source covers the count and the ecosystem
A manifest with no lockfile (version ranges only) the count of packages declared with ranges only
An image could not be pulled or read, or a base image could not be resolved the image and the reason
A symbolic link leads outside the project, or nowhere, and is a folder or a file watchdep would read the link and why it was not followed
A --rootfs folder holds no operating system package database the folder and the reason
The folder holds nothing to check at all, for example a CI job that never checked the code out (watchdep gate) “No dependency files found in this folder. Nothing was checked; this is not a clean result.”
OSV, CISA KEV or EPSS did not answer the source by name and the error
watchdep gate --mirror: the mirror’s last sync of an ecosystem failed, or its last good sync is over 24 hours old the ecosystem and why; the old copy still answers

An incomplete result is never presented as clean. In the CLI it has its own exit code, 2 (a finding that meets the gate’s threshold, exit 1, wins over it); --allow-incomplete turns it into 0 only when nothing meets the threshold. On the server, an incomplete part is shown in deep orange on the part, its application and the overview, and a place in a file that could not be read this time is never marked gone, so an unreadable lockfile can never make a finding look fixed. See the CLI.

Every rule, case by case

Generated from ranking_cases.json, the cases the CLI and the server are both tested against.
CaseScopeKEVMaliciousCVSSSource saysEPSSLevelLabels
exploited now in productionproductionyes1097%Severeexploited now
exploited now with a low CVSS is still severeproductionyes5.32%Severeexploited now
exploited now with no severity at all is severeproductionyesnone yetSevereexploited now
exploited now in development drops to highdevelopmentyes1097%Highexploited now, development only
malicious in productionproductionyesnone yetSeveremalicious
malicious in development scope is still severedevelopmentyesnone yetSeveremalicious
malicious with a low source label is still severeproductionyeslownone yetSeveremalicious
critical with EPSS at the thresholdproduction9.810%Severe
critical with EPSS above the thresholdproduction9.855%Severe
critical with no EPSS score is severe and provisionalproduction9.8none yetSevereprovisional
critical with low EPSS is highproduction9.80.4%High
critical with a custom thresholdproduction9.13% (threshold 2%)Severe
critical just below a custom thresholdproduction9.12% (threshold 2%)High
critical by source label with no CVSS and no EPSS is severe provisionalproductionCRITICALnone yetSevereprovisional
high CVSS is highproduction7.51%High
high CVSS with no EPSS is highproduction8.1none yetHigh
high CVSS with high EPSS stays highproduction8.890%High
no CVSS but a source label of highproductionHIGH0.1%High
no CVSS and a source label of moderateproductionMODERATE0.1%Medium
no severity at all is highproductionnone yetHighunscored
no severity at all in development is mediumdevelopmentnone yetMediumunscored, development only
medium CVSS is mediumproduction5.30.1%Medium
medium raised by high EPSSproduction6.140%High
low CVSS is lowproduction3.10.1%Low
low raised by high EPSSproduction3.720%Medium
a development-only critical drops one leveldevelopment9.860%Highdevelopment only
a development-only critical with no EPSS drops to high and stays provisionaldevelopment9.8none yetHighprovisional, development only
a development-only critical with low EPSS drops to mediumdevelopment9.80.1%Mediumdevelopment only
a development-only high drops to mediumdevelopment7.5none yetMediumdevelopment only
a development-only medium drops to lowdevelopment5none yetLowdevelopment only
a development-only low stays lowdevelopment2none yetLowdevelopment only
CVSS takes precedence over the source labelproduction5CRITICAL0.0%Medium
Debian's unimportant label is lowproductionunimportantnone yetLow