Levels and lanes
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
| Case | Scope | KEV | Malicious | CVSS | Source says | EPSS | Level | Labels |
|---|---|---|---|---|---|---|---|---|
| exploited now in production | production | yes | 10 | 97% | Severe | exploited now | ||
| exploited now with a low CVSS is still severe | production | yes | 5.3 | 2% | Severe | exploited now | ||
| exploited now with no severity at all is severe | production | yes | none yet | Severe | exploited now | |||
| exploited now in development drops to high | development | yes | 10 | 97% | High | exploited now, development only | ||
| malicious in production | production | yes | none yet | Severe | malicious | |||
| malicious in development scope is still severe | development | yes | none yet | Severe | malicious | |||
| malicious with a low source label is still severe | production | yes | low | none yet | Severe | malicious | ||
| critical with EPSS at the threshold | production | 9.8 | 10% | Severe | ||||
| critical with EPSS above the threshold | production | 9.8 | 55% | Severe | ||||
| critical with no EPSS score is severe and provisional | production | 9.8 | none yet | Severe | provisional | |||
| critical with low EPSS is high | production | 9.8 | 0.4% | High | ||||
| critical with a custom threshold | production | 9.1 | 3% (threshold 2%) | Severe | ||||
| critical just below a custom threshold | production | 9.1 | 2% (threshold 2%) | High | ||||
| critical by source label with no CVSS and no EPSS is severe provisional | production | CRITICAL | none yet | Severe | provisional | |||
| high CVSS is high | production | 7.5 | 1% | High | ||||
| high CVSS with no EPSS is high | production | 8.1 | none yet | High | ||||
| high CVSS with high EPSS stays high | production | 8.8 | 90% | High | ||||
| no CVSS but a source label of high | production | HIGH | 0.1% | High | ||||
| no CVSS and a source label of moderate | production | MODERATE | 0.1% | Medium | ||||
| no severity at all is high | production | none yet | High | unscored | ||||
| no severity at all in development is medium | development | none yet | Medium | unscored, development only | ||||
| medium CVSS is medium | production | 5.3 | 0.1% | Medium | ||||
| medium raised by high EPSS | production | 6.1 | 40% | High | ||||
| low CVSS is low | production | 3.1 | 0.1% | Low | ||||
| low raised by high EPSS | production | 3.7 | 20% | Medium | ||||
| a development-only critical drops one level | development | 9.8 | 60% | High | development only | |||
| a development-only critical with no EPSS drops to high and stays provisional | development | 9.8 | none yet | High | provisional, development only | |||
| a development-only critical with low EPSS drops to medium | development | 9.8 | 0.1% | Medium | development only | |||
| a development-only high drops to medium | development | 7.5 | none yet | Medium | development only | |||
| a development-only medium drops to low | development | 5 | none yet | Low | development only | |||
| a development-only low stays low | development | 2 | none yet | Low | development only | |||
| CVSS takes precedence over the source label | production | 5 | CRITICAL | 0.0% | Medium | |||
| Debian's unimportant label is low | production | unimportant | none yet | Low |