Add --vexhub: mark findings a vendor has already published a statement for

vexscan re-litigates CVEs that the image's own vendor has already triaged.
--vexhub points at a VEX Repository (rancher/vexhub and friends) and lifts the
findings a published statement already answers into their own section, so
attention goes to the rows nobody has spoken to.

A statement never rewrites status. A --vexhub run and a plain run agree on every
verdict and on the JSON's status field; only the grouping and the affected count
change. Only not_affected and fixed move a row -- a vendor confirming a finding
must not make it quieter.

Two product kinds are looked up: the scanned image (pkg:oci/...) and each Go
binary's own main module (pkg:golang/...), which is how a hub actually files Go
statements. index.json is fetched once and only the documents for products
present in the scan are pulled; the spec's transport is a ~30 MB tarball and
this reads two files out of it.

Three things real data forced:

- Subcomponents match on purl type and name only. The hub writes
  pkg:rpm/suse/libgcrypt20 where vexscan emits
  pkg:rpm/sles/libgcrypt20@...?arch=x86_64, and statements are pinned to the
  version the vendor scanned. Every disagreement the tolerance swallowed is
  written into the evidence line and shown under --details as "matched loosely".

- Findings are expanded through their OSV aliases before matching. Without it
  the first live run matched zero: vexscan's 13 advisories on
  rancher/hardened-kubernetes are GHSA-/GO- ids, the hub's 133 are almost all
  CVE-, and the two sets do not literally intersect. With it, 3 match.

- An unreachable hub warns and does not fail the run, unlike an ecosystem that
  could not be read. An unreadable package database makes the report claim a
  clean image it never examined; an unreachable hub only leaves rows in AFFECTED
  that a vendor had already answered. The first under-reports, which is the way
  this tool must never be wrong.

Verified against rancher/hardened-kubernetes (3 vexed of 70),
longhornio/longhorn-manager and longhorn-instance-manager, with debian:12 as the
control that prints no ALREADY VEXED section at all. The OCI path resolves and
matches on all three Rancher images across the suse/sles spelling gap; no live
OS finding was covered only because each image's one OS advisory is newer than
the hub's document.

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

Author: cwayne18

README.md

@@ -556,12 +556,12 @@ Two more failure modes worth naming:
   than a false clean.
 
 If a whole class of images comes back `linked`, the answer is vendor VEX feeds
-(Red Hat CSAF, Debian tracker, Alpine secdb) rather than more heuristics. The
-`evidence` array on every finding is the extension point for that: a future
-vendor-feed source contributes `Evidence{Origin: "vendor-vex"}` alongside the
-local evidence, under one policy — local deterministic evidence outranks a
-vendor claim, and a vendor `not_affected` never downgrades a finding below
-`linked` on its own.
+rather than more heuristics. [`--vexhub`](#vex-hubs---vexhub) is the first of
+those: it contributes `Evidence{Origin: "vendor-vex"}` alongside the local
+evidence, under one policy — local deterministic evidence outranks a vendor
+claim, and a vendor `not_affected` never downgrades a finding below `linked` on
+its own. Direct distro feeds (Red Hat CSAF, Debian tracker, Alpine secdb) are
+the same shape and would slot in beside it.
 
 **Java's presence test is sharp and its inventory is the weak part.** The class
 check is the strongest below-package test in this tool after pclntab, and it
@@ -842,6 +842,84 @@ Two things report `UNKNOWN` that are worth knowing about:
   carries no severity field. Image mode goes entirely through the resolver and is
   fully covered — on `debian:12 --all` every finding gets a rating.
 
+### VEX hubs (`--vexhub`)
+
+Some vendors have already triaged the CVEs in their own images and published the
+answers. `--vexhub` points at one of those published sets — a
+[VEX Repository](https://github.com/aquasecurity/vex-repo-spec), such as
+[rancher/vexhub](https://github.com/rancher/vexhub) — and marks the findings a
+statement already covers, so attention goes to the rows nobody has spoken to.
+
+```sh
+vexscan --image rancher/hardened-kubernetes:v1.34.10-rke2r1-build20260724 --all \
+  --vexhub https://github.com/rancher/vexhub
+```
+
+```
+  affected by severity: 6 high, 26 unknown, 28 medium
+  already vexed: 3 by Rancher Security team
+
+AFFECTED (60) - vulnerable code is present and can be loaded
+...
+
+ALREADY VEXED (3) - a published statement answers these; vexscan's own verdict is unchanged
+SEVERITY  ADVISORY             PACKAGE                            VERSION  VEX STATUS    JUSTIFICATION
+HIGH      GHSA-cgrx-mc8f-2prm  github.com/opencontainers/selinux  v1.11.1  not_affected  vulnerable_code_not_in_execute_path
+```
+
+**A statement never rewrites `status`.** A `--vexhub` run and a plain run agree
+on every finding's verdict and on the JSON's `status` field; the hub changes
+only which section the row is printed under, and therefore what the affected
+count draws the eye to. `--details` prints the vendor's own sentence, which is
+usually the most useful thing in the document:
+
+```
+  vendor:   Rancher Security team says not_affected (vulnerable_code_not_in_execute_path)
+            Manually confirmed, only exploitable when running runc directly.
+            product pkg:golang/k8s.io/kubernetes, published 2026-06-19T00:00:00Z
+            matched loosely: statement names pkg:golang/github.com/opencontainers/selinux@v1.11.0; component is pkg:golang/github.com%2Fopencontainers%2Fselinux@v1.11.1
+```
+
+Only `not_affected` and `fixed` move a row. A vendor `affected` or
+`under_investigation` stays in `AFFECTED` and is annotated there — a vendor
+confirming a finding must not make it quieter. The flag is repeatable and the
+earliest hub to speak wins, so an internal hub listed first overrides a
+vendor's.
+
+What is looked up: the scanned image (`pkg:oci/…`) and each Go binary's own main
+module (`pkg:golang/…`), which is how a hub actually files Go statements. The
+hub's `index.json` is fetched once and only the documents for products actually
+present in the scan are pulled — the spec's transport is a ~30 MB tarball, and
+this reads two files out of it. Three caveats, all measured:
+
+- **Coverage is entirely a function of whether the hub has a document for the
+  exact product you scanned.** rancher/vexhub is 1,082 products — Rancher, SUSE,
+  Longhorn, NeuVector, StackState — and nothing else. `debian:12 --vexhub
+  https://github.com/rancher/vexhub` correctly matches nothing and prints no
+  `ALREADY VEXED` section at all.
+- **Subcomponents are matched on purl *type and name only*.** Real data leaves
+  no choice: the hub writes `pkg:rpm/suse/libgcrypt20` where vexscan emits
+  `pkg:rpm/sles/libgcrypt20@…?arch=x86_64`, and statements are pinned to the
+  version the vendor scanned (`selinux@v1.11.0`) rather than the one in your
+  image (`v1.11.1`). Namespace, version and qualifiers are ignored; every
+  disagreement that tolerance swallowed is written out in the evidence line and
+  under `--details` as `matched loosely`, so you can see what was actually
+  compared. A statement about an older version is applied to a newer one —
+  usually right for a "code not reachable" claim, and visible when it is not.
+- **The two sides name advisories differently, and the match depends on OSV
+  aliases to bridge them.** On the Rancher image above, vexscan's 13 advisories
+  are all `GHSA-`/`GO-` ids and the hub's 133 are almost all `CVE-`, with zero
+  literal overlap; expanding each finding through the alias list the resolver
+  already fetched is what makes any of them meet. A finding whose advisory OSV
+  gives no aliases for can only match a hub using the same spelling.
+
+An unreachable hub prints a `NOTE:` and **does not fail the run** — unlike an
+ecosystem that could not be read, which exits 1. The asymmetry is deliberate: an
+unreadable package database makes the report claim a clean image it never
+examined, while an unreachable hub only leaves rows in `AFFECTED` that a vendor
+had already answered. The first under-reports, which is the way this tool must
+never be wrong; the second over-reports, which is merely tiring.
+
 ### JSON
 
 The JSON is `schema_version: 2`:
@@ -852,14 +930,20 @@ The JSON is `schema_version: 2`:
   "target": "...", "mode": "image",          // or "rootfs", or "repo"
   "findings": [ /* flat, sorted — jq '.findings[]' still works */ ],
   "ecosystems": [ { "id": "os", "components": 65, "error": "" } ],
-  "unreadable": { "count": 3, "paths": ["/opt/vendor"] }  // omitted when nothing was skipped
+  "unreadable": { "count": 3, "paths": ["/opt/vendor"] },  // omitted when nothing was skipped
+  "vex_hubs": [ { "url": "...", "author": "...", "products": 1082, "matched": 3 } ]  // only with --vexhub
 }
 ```
 
 Each finding carries ecosystem-neutral identity (`ecosystem`, `id`, `package`,
 `version`, `location`, `purl`) plus `status`, `method`, `justification` and
 `evidence`, and `severity`/`cvss` when an advisory was resolved for it. Both are
-omitted when none was, which is not the same fact as `UNKNOWN`. The v1 Go
+omitted when none was, which is not the same fact as `UNKNOWN`. With
+[`--vexhub`](#vex-hubs---vexhub) a finding also carries `product` (the artifact
+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
 spellings (`cve`, `module`, `binary`, `go_id`, `packages`,
 `granularity`, `stripped`) are still emitted for Go findings, mirrored from the
 neutral fields so they cannot drift.
@@ -910,6 +994,7 @@ be read, or part of the tree could not be read, `2` the command line was wrong.
 | `--go-version` | *(auto)* | Pin the Go toolchain for `--repo`, e.g. `1.24.0` (useful with `golang:stdlib`) |
 | `--osv-ecosystem` | *(auto)* | Override the OSV ecosystem derived from os-release, e.g. `Debian:12` |
 | `--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) |
 | `--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) |

internal/analyze/analyze.go

@@ -94,6 +94,15 @@ type Options struct {
 	// not the same knob as Ecosystems, which chooses which plugins run.
 	OSVEcosystem string
 
+	// VEXHubs are VEX Hub repositories to check findings against (--vexhub),
+	// in priority order: the first hub with a statement about a finding wins,
+	// so an internal hub listed ahead of a vendor's overrides it.
+	//
+	// A statement never changes a finding's status. It records that someone has
+	// already published an answer, which the report uses to decide what a
+	// reader still has to look at.
+	VEXHubs []string
+
 	// 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.
@@ -152,6 +161,11 @@ type Result struct {
 	// looked inside contributes no findings, which is exactly what a directory
 	// full of nothing wrong contributes. Only one of those is good news.
 	Unreadable *target.Unreadable `json:"unreadable,omitempty"`
+
+	// VEXHubs records what each --vexhub contributed, including one that could
+	// not be read. It is not part of Failed(): see vexOverlay for why a hub
+	// failure is not the same kind of incompleteness as an ecosystem failure.
+	VEXHubs []ecosystem.VEXHubResult `json:"vex_hubs,omitempty"`
 }
 
 // Failed reports whether the findings are an incomplete account of the target
@@ -472,6 +486,11 @@ func runTree(ctx context.Context, opts Options) (*Result, error) {
 	}
 
 	severityOverlay(result.Findings, run.resolver.severities())
+	// The image is only a product for a scan that was given one: --rootfs
+	// analyzes a tree whose provenance nobody recorded, and inventing a purl
+	// 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)
 	llmOverlay(ctx, llmClient, result.Findings, "", logf)
 	sortFindings(result.Findings)
 	return result, nil
@@ -609,6 +628,9 @@ func runRepo(ctx context.Context, opts Options) (*Result, error) {
 	result.Findings = append(result.Findings, unmapped(opts.CVEs, result.Findings)...)
 
 	severityOverlay(result.Findings, run.resolver.severities())
+	// 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)
 	llmOverlay(ctx, llmClient, result.Findings, "source tree", logf)
 	sortFindings(result.Findings)
 	return result, nil
@@ -827,6 +849,33 @@ func (r *advisoryResolver) severities() map[string]severity {
 	return out
 }
 
+// aliases maps every id an advisory is known by onto that advisory's whole set
+// of ids.
+//
+// It exists for the VEX overlay. A finding names its advisory by whichever id
+// its plugin was working from -- the Go plugin reports GO-2025-3547 -- while a
+// hub files under whichever its own scanner used, which for every hub seen so
+// far is the CVE. Neither side is wrong and neither carries the other's
+// spelling, so matching them means going through the record that lists both,
+// which the resolver has already fetched.
+func (r *advisoryResolver) aliases() map[string][]string {
+	out := map[string][]string{}
+	for _, set := range r.cache {
+		for _, adv := range set {
+			if adv == nil {
+				continue
+			}
+			ids := append([]string{adv.ID}, adv.Aliases...)
+			for _, key := range ids {
+				if key != "" {
+					out[key] = ids
+				}
+			}
+		}
+	}
+	return out
+}
+
 // severityOverlay labels each finding with its advisory's severity, in place.
 //
 // It runs in the orchestrator beside llmOverlay, and for the same reason: a