Add --triage: order findings by exploitation evidence, not just severity

Severity says how bad a vulnerability would be if exploited. It says
nothing about whether anyone is exploiting it, and on real output those
two questions give very different answers. --triage adds the second,
from EPSS (a daily per-CVE forecast of exploitation activity) and
CISA's known-exploited catalog.

The reordering is the point, and it is large. The likeliest-to-be-
exploited finding in debian:12 is CVE-2011-3389 at the 99.4th
percentile, and it is UNKNOWN-severity -- so --severity CRITICAL,HIGH
throws it away. Six of that image's eight CRITICALs sit between the
28th and 40th percentile, below the median.

Nothing is hidden and nothing is rewritten. The flag adds two columns
and changes the order: known-exploited first, then EPSS percentile
descending, then everything unscored in the severity order it had. No
status changes and no severity changes, because whether a vulnerability
is being exploited on someone else's network says nothing about whether
the code is present here -- the only question this tool answers.

There is no blended score. internal/cvss already documents Rank as a
display order and not a comparison order, for this exact reason: a
priority = f(cvss, epss, kev) number would be an opinion dressed as
arithmetic.

Both feeds are keyed by CVE and vexscan's findings often are not. On
rancher/rke2-runtime not one of 865 findings carries a CVE in any of
its own fields; expanding each through the OSV alias list the resolver
already fetched scores 834 of them anyway. The 31 that reach no CVE
cannot ever be scored, and are the case this could most easily have got
wrong: they sort last, which in a list ordered by likelihood reads as
"least likely". So the report says in as many words that they sort last
for lack of data rather than lack of risk, and counts "no CVE at all"
apart from "a CVE the feed has not scored yet" because the two have
different fixes -- nothing, and wait a day.

Absence from KEV means nothing at all. It is 1,660 entries against
EPSS's 355,094 and fired on zero of the 1,026 findings across both test
images. The summary states it as a checked fact rather than leaving a
blank column, and an unreachable feed prints a NOTE without failing the
run -- like --vexhub and unlike an unreadable package database, because
it over-reports rather than under-reports.

Feeds are cached under VEXSCAN_TRIAGE_CACHE. EPSS is served under a
dated filename, so the 302 is a HEAD that costs no bytes and a second
scan the same day downloads nothing; KEV revalidates with an ETag. A
cached copy is used when the network fails, and both the summary and
the caveat mark it (cached) with its date, because a percentile is a
claim about a day and a CI log read next month must not pretend
otherwise.

Measured: debian:12 scores 145 of 161, the 16 misses being exactly the
two ids EPSS has not reached yet; rke2-runtime scores 834 of 865 with
no CVE anywhere in the rows. Without the flag the output is
byte-identical to the previous release, diffed over a full 176-line
scan.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: cwayne18

README.md

@@ -931,6 +931,110 @@ Exit codes are unchanged: `0` the scan completed, `1` it could not read
 something, `2` the command line was wrong. Findings existing — at any severity —
 is not a failure, which is what keeps exit `1` worth acting on.
 
+### Prioritising by exploitation evidence (`--triage`)
+
+Severity says how bad a vulnerability would be if exploited. It says nothing
+about whether anyone is exploiting it. `--triage` adds the second question, from
+two public feeds: [EPSS](https://www.first.org/epss/), a daily per-CVE forecast
+of exploitation activity, and
+[CISA's known-exploited catalog](https://www.cisa.gov/known-exploited-vulnerabilities-catalog),
+a list of what is being exploited in the wild right now.
+
+```console
+$ vexscan --image debian:12 --all --ecosystem os --triage
+vexscan report (image) for debian:12
+NOTE: --triage could not score 16 of 161 findings, so they sort last for lack of data rather than lack of risk:
+      16 have a CVE the feed has not scored yet, which usually means it was published in the last day or two
+
+  os       Debian:12                  88 components   161 findings
+  affected by severity: 10 critical, 26 high, 34 unknown, 75 medium, 9 low
+  priority: none in CISA's known-exploited catalog, 3 at or above the 90th EPSS percentile, 138 scored, 16 unscored
+  priority data: EPSS 2026-08-04, KEV catalog 2026.08.04
+
+AFFECTED (154) - vulnerable code is present and can be loaded
+SEVERITY  ADVISORY          PACKAGE       VERSION                 EPSS   BASIS
+UNKNOWN   CVE-2011-3389     libgnutls30   3.7.9-2+deb12u7         99.4%  elf-needed-closure
+HIGH      CVE-2018-20796    libc-bin      2.36-9+deb12u14         92.4%  elf-needed-closure
+UNKNOWN   CVE-2005-2541     tar           1.34+dfsg-1.2+deb12u1   89.5%  elf-needed-closure
+CRITICAL  CVE-2019-1010022  libc-bin      2.36-9+deb12u14         87.1%  elf-needed-closure
+```
+
+That reordering is the point, and it is large. The likeliest-to-be-exploited
+finding in `debian:12` is **unrated**, so a `--severity CRITICAL,HIGH` run throws
+it away. Six of the image's eight CRITICALs sit between the 28th and 40th
+percentile — below the median:
+
+| CVE | Severity | EPSS percentile |
+|---|---|---|
+| CVE-2019-1010022 | CRITICAL | 87th |
+| CVE-2023-45853 | CRITICAL | 86th |
+| CVE-2026-5450 | CRITICAL | 40th |
+| CVE-2026-8376 | CRITICAL | 36th |
+| CVE-2026-13221 | CRITICAL | 35th |
+| CVE-2026-42496 | CRITICAL | 35th |
+| CVE-2026-12087 | CRITICAL | 30th |
+| CVE-2026-57433 | CRITICAL | 28th |
+
+**Nothing is hidden and nothing is rewritten.** The flag adds two columns and
+changes the order: known-exploited rows first, then by EPSS percentile
+descending, then everything unscored in the severity order it had before. No
+status changes and no severity changes — whether a vulnerability is being
+exploited on someone else's network says nothing about whether the code is
+present in this image, which is the only question this tool answers. Use
+[`--severity`](#filtering-by-severity---severity) if you want fewer rows;
+`--triage` only decides which of them you read first.
+
+**There is no blended score.** vexscan will not emit a
+`priority = f(cvss, epss, kev)` number, because the two inputs measure different
+things and any weighting would be this tool's opinion dressed as arithmetic. It
+shows the facts and orders by them.
+
+The `EPSS` column is the **percentile**, not the raw probability: `0.03` reads as
+negligible until you know it is the 87th percentile of all 355,094 scored CVEs.
+`--details` prints both, along with the id the score was looked up under:
+
+```
+  epss:     0.03249 (87.1th percentile), as CVE-2019-1010022
+```
+
+Four things are worth knowing before you rely on it:
+
+- **Both feeds are keyed by CVE, and many advisories are not.** On the Rancher
+  image below, *not one* of 865 findings carries a CVE in any of its own fields —
+  they are all `GHSA-` and `GO-` ids. Expanding each through the OSV alias list
+  the resolver already fetched is what scores 834 of them anyway; the remaining
+  31 have no CVE alias anywhere and can never be scored by either feed. Those are
+  counted, named in a `NOTE:`, and sorted last — which in a list ordered by
+  likelihood reads as "least likely", so the note says in as many words that they
+  sort last for lack of data rather than lack of risk.
+- **A CVE published in the last day or two has no score yet.** EPSS lags new
+  CVEs by about a day; the 16 unscored findings on `debian:12` above are two such
+  ids across eight packages each. This is counted separately from "no CVE at
+  all", because the two have different fixes (wait a day; nothing).
+- **Absence from the KEV catalog means nothing at all.** It is 1,660 entries
+  against EPSS's 355,094, and it fired on **zero** of the 1,026 findings across
+  both images here. It is worth carrying because when it does fire it ends the
+  argument, but a report with no KEV rows is the normal case and not a clean bill
+  of health.
+- **EPSS predicts observed exploitation activity anywhere in the next 30 days**,
+  not risk to you. A high percentile on a library your entrypoint never loads is
+  still a finding vexscan has already told you is `not_present`.
+
+`--triage` downloads about 4 MB the first time (2.5 MB gzipped EPSS, 1.5 MB KEV)
+and takes well under a second. Both are cached under `VEXSCAN_TRIAGE_CACHE`, or
+`os.UserCacheDir()/vexscan/triage` by default. EPSS is served under a dated
+filename, so a second scan the same day re-downloads nothing at all; KEV is
+revalidated with an `ETag` and normally answers `304`. A feed that cannot be
+reached falls back to the cached copy, and both the summary and the caveat mark
+it `(cached)` with the date it is from — a percentile is a claim about a day, and
+a CI log read next month must not be able to pretend otherwise.
+
+An unreachable feed with no cache prints a `NOTE:` and **does not fail the run**,
+for the same reason [`--vexhub`](#vex-hubs---vexhub) does not: it leaves the rows
+in the order they were already in, which over-reports rather than under-reports.
+The report says so explicitly, because a table with an empty KEV column must
+never be readable as "nothing here is being exploited".
+
 ### VEX hubs (`--vexhub`)
 
 Some vendors have already triaged the CVEs in their own images and published the
@@ -1021,6 +1125,14 @@ The JSON is `schema_version: 2`:
   "ecosystems": [ { "id": "os", "components": 65, "error": "" } ],
   "unreadable": { "count": 3, "paths": ["/opt/vendor"] },  // omitted when nothing was skipped
   "vex_hubs": [ { "url": "...", "author": "...", "products": 1082, "matched": 3 } ],  // only with --vexhub
+  "triage": {  // only with --triage
+    "epss_date": "2026-08-04", "kev_date": "2026.08.04",  // the feeds' own dates, not today's
+    "epss_stale": true, "kev_stale": true,   // a cached copy was used; omitted when false
+    "epss_error": "...", "kev_error": "...", // a feed failed; set instead of failing the run
+    "not_in_feed": 16, "no_cve": 3,          // unscored, and why; each omitted when zero
+    "catalog_size": 1660,                    // how many CVEs the KEV catalog held
+    "scored": 145, "known_exploited": 0      // always present: "0 known exploited" is a finding
+  },
   "withheld": {  // only when --severity hid something; findings[] is already the kept set
     "severities": ["CRITICAL", "HIGH"],
     "count": 123,
@@ -1037,7 +1149,11 @@ omitted when none was, which is not the same fact as `UNKNOWN`. With
 it was found in) and, when one matched, `vex` — the statement's `status`,
 `justification`, `impact_statement`, `action_statement`, `author`, the product
 purl that matched and the hub it came from, so a consumer can audit the claim
-without re-fetching. The v1 Go
+without re-fetching. With [`--triage`](#prioritising-by-exploitation-evidence---triage)
+it carries `priority`: `{"cve": "...", "scored": true, "epss": 0.03249,
+"percentile": 0.871}` plus `kev` when it is listed. `scored: false` means the
+lookup ran and found nothing, which is not a score of zero; the block is absent
+entirely when the flag was off. The v1 Go
 spellings (`cve`, `module`, `binary`, `go_id`, `packages`,
 `granularity`, `stripped`) are still emitted for Go findings, mirrored from the
 neutral fields so they cannot drift.
@@ -1090,6 +1206,7 @@ be read, or part of the tree could not be read, `2` the command line was wrong.
 | `--roots` | | Extra entrypoints for the closures — shared libraries and language imports; repeatable |
 | `--vexhub` | | VEX Repository to check findings against, e.g. `https://github.com/rancher/vexhub` (also a raw base URL or a local directory); repeatable, earliest wins — see [VEX hubs](#vex-hubs---vexhub) |
 | `--severity` | *(all)* | Only report findings at these severities: `CRITICAL`, `HIGH`, `UNKNOWN`, `MEDIUM`, `LOW`, `NONE`; comma-separated or repeatable. `UNKNOWN` must be named to be shown — see [Filtering by severity](#filtering-by-severity---severity) |
+| `--triage` | `false` | Order findings by exploitation evidence — EPSS scores and CISA's known-exploited catalog. Adds two columns and re-sorts; hides nothing and changes no severity — see [Prioritising by exploitation evidence](#prioritising-by-exploitation-evidence---triage) |
 | `--dlopen-policy` | `taint` | `taint` (block conclusions) or `assume-none` |
 | `--dynamic-import-policy` | `taint` | The same knob for a language import graph's computed imports. These are far more common than `dlopen`, so `assume-none` discards much more |
 | `--trust-import-absence` | `false` | Let a missing dynamic import conclude `not_in_execute_path` (weaker than it looks) |
@@ -1140,6 +1257,7 @@ honored as a fallback so existing CI keeps working.
 | `VEXSCAN_LLM_COMMAND` | | A local CLI to run for `--llm` instead of calling an endpoint |
 | `VEXSCAN_LLM_MIN_INTERVAL` | `GOMODVEX_LLM_MIN_INTERVAL` | Minimum spacing between `--llm` calls (Go duration; default none) |
 | `VEXSCAN_GOVULNCHECK_VERSION` | `GOMODVEX_GOVULNCHECK_VERSION` | Pin the govulncheck version used by `--repo` |
+| `VEXSCAN_TRIAGE_CACHE` | | Directory for the `--triage` feed cache (default `os.UserCacheDir()/vexscan/triage`, e.g. `~/Library/Caches` or `$XDG_CACHE_HOME`) |
 | `VEXSCAN_PAGER` | `GOMODVEX_PAGER` | Pager for terminal output; `$PAGER` is the fallback, `less` the default. Set it **empty** to never page — unlike the variables above, an empty value here is a decision rather than an absence |
 
 `GITHUB_TOKEN` / `GH_TOKEN` are for `--gist` only, and are unchanged.

internal/analyze/analyze.go

@@ -31,6 +31,7 @@ import (
 	"github.com/cwayne18/vexscan/internal/osv"
 	"github.com/cwayne18/vexscan/internal/source"
 	"github.com/cwayne18/vexscan/internal/target"
+	"github.com/cwayne18/vexscan/internal/triage"
 )
 
 // The finding vocabulary lives in internal/ecosystem, which is what the plugins
@@ -113,6 +114,16 @@ type Options struct {
 	// reader still has to look at.
 	VEXHubs []string
 
+	// Triage is the EPSS/KEV loader for --triage, or nil to skip it entirely.
+	// It is the loader rather than a bool so a test can point it at its own
+	// feeds, and so the caller owns the cache location.
+	//
+	// Like VEXHubs it never changes a finding's status. Whether a vulnerability
+	// is being exploited elsewhere says nothing about whether the code is
+	// present here, which is the only question this tool answers; what it
+	// changes is which of the answers a reader looks at first.
+	Triage *triage.Loader
+
 	// GoVersion optionally pins the Go toolchain for repo-mode analysis
 	// (e.g. "1.24.0"). Mainly useful with --module stdlib, whose findings depend
 	// on the toolchain version.
@@ -181,6 +192,10 @@ type Result struct {
 	// flag was not used or hid nothing. See severityFilter: a filtered result
 	// and a clean one are indistinguishable without it.
 	Withheld *Withheld `json:"withheld,omitempty"`
+
+	// Triage records what --triage contributed, and is nil when the flag was
+	// not used. Like VEXHubs it is not part of Failed(): see triageOverlay.
+	Triage *TriageResult `json:"triage,omitempty"`
 }
 
 // Failed reports whether the findings are an incomplete account of the target
@@ -511,6 +526,7 @@ func runTree(ctx context.Context, opts Options) (*Result, error) {
 	// from a directory name would look up an artifact that does not exist.
 	productOverlay(result.Findings, opts.Image)
 	result.VEXHubs = vexOverlay(ctx, opts.VEXHubs, result.Findings, run.resolver.aliases(), logf)
+	result.Triage = triageOverlay(ctx, opts.Triage, result.Findings, run.resolver.aliases(), logf)
 	llmOverlay(ctx, llmClient, result.Findings, "", logf)
 	sortFindings(result.Findings)
 	return result, nil
@@ -657,6 +673,7 @@ func runRepo(ctx context.Context, opts Options) (*Result, error) {
 	// No productOverlay here: repo mode has no image, and the only artifact a
 	// checkout is is its own module, which the Go plugin already recorded.
 	result.VEXHubs = vexOverlay(ctx, opts.VEXHubs, result.Findings, run.resolver.aliases(), logf)
+	result.Triage = triageOverlay(ctx, opts.Triage, result.Findings, run.resolver.aliases(), logf)
 	llmOverlay(ctx, llmClient, result.Findings, "source tree", logf)
 	sortFindings(result.Findings)
 	return result, nil

internal/analyze/triage.go

@@ -0,0 +1,140 @@
+package analyze
+
+import (
+	"context"
+	"regexp"
+	"strings"
+
+	"github.com/cwayne18/vexscan/internal/triage"
+)
+
+// bareCVE matches a CVE id and nothing else. Distro databases publish ids like
+// DEBIAN-CVE-2026-54369 and Go publishes GO-2025-3547; only the plain form is a
+// key into either feed.
+var bareCVE = regexp.MustCompile(`^CVE-[0-9]{4}-[0-9]{4,}$`)
+
+// TriageResult records what --triage contributed, including what it could not.
+//
+// It sits beside VEXHubs in Result and, like VEXHubs, is deliberately not part
+// of Failed(). An unreachable EPSS mirror does not make the report claim a
+// clean image it never examined -- it leaves the findings in the order they
+// were already in. That is a different kind of wrong from an ecosystem that
+// could not be inventoried, and only one of them may pass silently.
+type TriageResult struct {
+	// EPSSDate and KEVDate are the feeds' own dates, read out of the payloads.
+	// A cached percentile is a claim about a day, and a report read next month
+	// must not be able to pretend otherwise.
+	EPSSDate string `json:"epss_date,omitempty"`
+	KEVDate  string `json:"kev_date,omitempty"`
+
+	// Stale means the network could not be reached and a previously downloaded
+	// copy was used.
+	EPSSStale bool `json:"epss_stale,omitempty"`
+	KEVStale  bool `json:"kev_stale,omitempty"`
+
+	EPSSError string `json:"epss_error,omitempty"`
+	KEVError  string `json:"kev_error,omitempty"`
+
+	// Scored is how many findings got a percentile. NoCVE is those whose
+	// advisory carries no CVE id at all, and NotInFeed those that had one the
+	// feed did not know -- almost always a CVE published in the last day or
+	// two. They are counted apart because the report has to explain the two
+	// differently, and because neither of them means "low risk".
+	Scored         int `json:"scored"`
+	NoCVE          int `json:"no_cve,omitempty"`
+	NotInFeed      int `json:"not_in_feed,omitempty"`
+	KnownExploited int `json:"known_exploited"`
+	CatalogSize    int `json:"catalog_size,omitempty"`
+}
+
+// Unscored is how many findings have no percentile, for whichever reason.
+func (t *TriageResult) Unscored() int { return t.NoCVE + t.NotInFeed }
+
+// Usable reports whether either feed produced anything to sort by. When it is
+// false the report keeps its severity ordering and says why.
+func (t *TriageResult) Usable() bool {
+	return t != nil && (t.EPSSError == "" || t.KEVError == "")
+}
+
+// triageOverlay attaches exploitation evidence to every finding, in place.
+//
+// It runs in the orchestrator beside severityOverlay and llmOverlay, and for
+// the same reason: a plugin cannot forget to do something it does not do.
+//
+// A nil loader means --triage was off, and every Priority stays nil, which is
+// what keeps an untriaged report byte-identical to one from before this
+// existed.
+//
+// The join is the interesting part. Both feeds are keyed by CVE and vexscan's
+// findings frequently are not: on a Rancher image not one finding of seventy
+// carries a CVE in any of its three id fields. findingIDs walks the OSV alias
+// list the resolver already fetched, which is what lets GO-2025-3547 be scored
+// as CVE-2024-7598. Advisories that reach no CVE at all are counted and named
+// rather than quietly left at zero.
+func triageOverlay(ctx context.Context, loader *triage.Loader, findings []Finding, aliases map[string][]string, logf func(string, ...any)) *TriageResult {
+	if loader == nil {
+		return nil
+	}
+
+	// Resolve every finding's CVE first, so the feed parser can throw away the
+	// other 355,000 rows as it streams them.
+	cves := make([]string, len(findings))
+	want := map[string]bool{}
+	for i, f := range findings {
+		cves[i] = findingCVE(f, aliases)
+		if cves[i] != "" {
+			want[cves[i]] = true
+		}
+	}
+	logf("Triaging %d findings against EPSS and CISA KEV (%d CVE ids)", len(findings), len(want))
+
+	loader.Logf = logf
+	data := loader.Load(ctx, want)
+
+	res := &TriageResult{
+		EPSSDate:    data.EPSSDate,
+		KEVDate:     data.KEVDate,
+		EPSSStale:   data.EPSSStale,
+		KEVStale:    data.KEVStale,
+		EPSSError:   data.EPSSError,
+		KEVError:    data.KEVError,
+		CatalogSize: len(data.KEV),
+	}
+	for i := range findings {
+		p := data.Lookup(cves[i])
+		findings[i].Priority = &p
+		switch {
+		case p.Scored:
+			res.Scored++
+		case cves[i] == "":
+			res.NoCVE++
+		default:
+			res.NotInFeed++
+		}
+		if p.KEV != nil {
+			res.KnownExploited++
+		}
+	}
+	if res.KnownExploited > 0 {
+		logf("Triage: %d finding(s) are in CISA's known-exploited catalog", res.KnownExploited)
+	}
+	return res
+}
+
+// findingCVE is the bare CVE id to look a finding up by, or "" when its
+// advisory has never been assigned one.
+//
+// Distro prefixes are stripped the way report.go's shortAdvisory strips them
+// for display: DEBIAN-CVE-2026-54369 is CVE-2026-54369 wearing a database's
+// name.
+func findingCVE(f Finding, aliases map[string][]string) string {
+	for _, id := range findingIDs(f, aliases) {
+		if bareCVE.MatchString(id) {
+			return id
+		}
+		if _, rest, found := strings.Cut(id, "-"); found && bareCVE.MatchString(rest) {
+			return rest
+		}
+	}
+	return ""
+}