Add --severity to limit the report to the ratings worth acting on

A debian:12 --all scan is 161 findings, and the only way to get the
subset worth waking someone for was jq over --format json. This is
Trivy's spelling: --severity CRITICAL,HIGH, comma-separated or
repeatable, case-insensitive, MODERATE accepted for MEDIUM.

The flag is nearly free -- stringList already splits on commas. All the
work is in what a filter is allowed to hide, because this tool has one
rule it never breaks: a short report must never read as a clean one.

So every filtered run says what it withheld, and glosses the unrated
count. UNKNOWN is a severity you have to name, as in Trivy, and on
debian:12 that hides 36 findings whose only crime is a CVSS v4-only
record -- "36 unknown (no rating was published)" is the line that keeps
that honest. In --repo mode it is worse: govulncheck's OpenVEX carries
no severity, so any --severity that omits UNKNOWN filters out
everything, and that case prints "This is a filtered view, not a clean
result" rather than the ordinary no-findings line.

One exemption: a --cves id that matched no component always survives.
Those rows exist so a hand-typed id cannot vanish; deleting them would
recreate exactly the silence they were written to prevent.

Parsing is strict, via a new cvss.Parse rather than cvss.Normalize --
Normalize("CRITCAL") is UNKNOWN, so the lenient version would read a
typo as a request for precisely the unrated findings. A bad name is
exit 2 before the pull.

The filter runs in the orchestrator, not the renderer, so --format json
shrinks the same way and gains a matching withheld block, and the LLM
overlay is never billed for a row nobody will read. Exit codes are
unchanged: findings existing is still not a failure.

Measured: debian:12 keeps 38 of 161 at CRITICAL,HIGH with the JSON
withheld block agreeing exactly; --repo prints the filtered-view guard
at exit 0; and on rancher/hardened-kubernetes --severity composes with
--vexhub without costing any of its 3 hub matches.

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

Author: cwayne18

README.md

@@ -835,13 +835,62 @@ Two things report `UNKNOWN` that are worth knowing about:
 - **CVSS 4.0-only records are not scored.** A v4 base score is a 270-entry
   MacroVector lookup with interpolation, not a formula. Records carrying only a
   v4 vector report `UNKNOWN` rather than a number this tool made up. Most
-  advisories still publish v3 alongside; on `debian:12` 34 of 159 findings are
+  advisories still publish v3 alongside; on `debian:12` 36 of 161 findings are
   unrated, from a mix of v4-only and pre-CVSS records.
 - **`--repo` Go findings carry no severity at all.** That path resolves
   advisories inside govulncheck, which is run with `-format openvex`, and OpenVEX
   carries no severity field. Image mode goes entirely through the resolver and is
   fully covered — on `debian:12 --all` every finding gets a rating.
 
+### Filtering by severity (`--severity`)
+
+`--severity CRITICAL,HIGH` reports only the findings at those ratings. It is
+comma-separated or repeatable, case-insensitive, accepts `MODERATE` for
+`MEDIUM`, and a name it does not recognize is a command-line error (exit 2)
+rather than a silently empty report.
+
+```console
+$ vexscan --image debian:12 --all --ecosystem os --severity CRITICAL,HIGH
+vexscan report (image) for debian:12
+NOTE: --severity CRITICAL,HIGH withheld 123 of 161 findings:
+      36 unknown (no rating was published), 78 medium, 9 low
+
+  os       Debian:12                  88 components    38 findings
+  affected by severity: 10 critical, 26 high
+```
+
+The filter is applied to the result, not to the rendering, so `--format json`
+shrinks the same way and gains a `withheld` block that matches the banner
+exactly. It also runs before the LLM overlay, so `--severity CRITICAL --llm`
+only pays for criticals.
+
+Three things about it are worth knowing before you put it in CI:
+
+- **`UNKNOWN` is a severity you have to ask for.** As in Trivy, a `--severity`
+  that does not name it drops it — 36 findings on `debian:12` above. Those are
+  unrated, not unimportant ([above](#severity)), so every filtered run prints
+  what it withheld and glosses the unrated count. Name `UNKNOWN` alongside the
+  ratings you want to keep them.
+- **`--repo` mode has no severities at all**, for the reason in the previous
+  section, so any `--severity` that omits `UNKNOWN` filters out *everything*.
+  That does not print as a clean scan:
+
+  ```console
+  $ vexscan --repo https://github.com/cwayne18/vexscan --all --severity HIGH,CRITICAL
+  No findings at these severities.
+  --severity HIGH,CRITICAL withheld all 1 finding(s): 1 unknown (no rating was published).
+  This is a filtered view, not a clean result.
+  ```
+
+- **A `--cves` id that matched nothing is never filtered.** Those rows exist so
+  that an id you named by hand cannot vanish from the report; they carry no
+  severity, and hiding them would recreate exactly the silence they are there to
+  prevent.
+
+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.
+
 ### VEX hubs (`--vexhub`)
 
 Some vendors have already triaged the CVEs in their own images and published the
@@ -931,7 +980,12 @@ The JSON is `schema_version: 2`:
   "findings": [ /* flat, sorted — jq '.findings[]' still works */ ],
   "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
+  "vex_hubs": [ { "url": "...", "author": "...", "products": 1082, "matched": 3 } ],  // only with --vexhub
+  "withheld": {  // only when --severity hid something; findings[] is already the kept set
+    "severities": ["CRITICAL", "HIGH"],
+    "count": 123,
+    "by_severity": { "UNKNOWN": 36, "MEDIUM": 78, "LOW": 9 }
+  }
 }
 ```
 
@@ -995,6 +1049,7 @@ be read, or part of the tree could not be read, `2` the command line was wrong.
 | `--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) |
+| `--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) |
 | `--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

@@ -74,6 +74,16 @@ type Options struct {
 	// Ecosystems restricts which plugins run (--ecosystem). Empty runs them
 	// all. Naming one nothing handles is an error, not an empty result.
 	Ecosystems []string
+	// Severities restricts the result to findings carrying these severity
+	// labels (--severity), already canonicalized through cvss.Parse by the
+	// caller. Empty keeps everything.
+	//
+	// Unlike Ecosystems this changes what is reported rather than what runs:
+	// every plugin still inventories and every advisory is still resolved,
+	// because a finding's severity is only knowable once its advisory is in
+	// hand. What it does buy is that the LLM overlay is never asked about a row
+	// nobody is going to read.
+	Severities []string
 
 	CVEs    []string // optional filter; empty means "every advisory that applies"
 	Version string   // optional override of the detected module version (image mode)
@@ -166,6 +176,11 @@ type Result struct {
 	// 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"`
+
+	// Withheld is what --severity removed from Findings, and is nil when the
+	// 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"`
 }
 
 // Failed reports whether the findings are an incomplete account of the target
@@ -486,6 +501,11 @@ func runTree(ctx context.Context, opts Options) (*Result, error) {
 	}
 
 	severityOverlay(result.Findings, run.resolver.severities())
+	// Filtering here, rather than in the renderer, is what keeps every count
+	// downstream honest: the LLM is never billed for a row nobody will read,
+	// and a hub's Matched is statements about findings that are actually in the
+	// report rather than ones that had already been dropped.
+	result.Findings, result.Withheld = severityFilter(result.Findings, opts.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.
@@ -628,6 +648,12 @@ 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())
+	// See runTree for why the filter runs before the overlays rather than in
+	// the renderer. Repo mode is the path where it bites hardest: govulncheck's
+	// OpenVEX carries no severity, so every Go finding here is UNKNOWN and a
+	// --severity that does not name UNKNOWN empties the report completely. The
+	// renderer has to say so, which is what Withheld is for.
+	result.Findings, result.Withheld = severityFilter(result.Findings, opts.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)

internal/analyze/severity.go

@@ -0,0 +1,81 @@
+package analyze
+
+import (
+	"github.com/cwayne18/vexscan/internal/cvss"
+	"github.com/cwayne18/vexscan/internal/ecosystem"
+)
+
+// Withheld records what --severity removed from the result.
+//
+// It exists because a filtered report and a clean one look identical, and that
+// is the one confusion this tool must never cause. Every renderer prints this
+// before the findings, so a short list is always accompanied by the reason it
+// is short.
+//
+// It is deliberately not part of Failed(). The scan completed and read
+// everything it meant to; the reader asked for a subset of what it found. That
+// is the opposite of an ecosystem that could not be inventoried, where the tool
+// does not know what it missed.
+type Withheld struct {
+	// Severities is what --severity asked to keep, so the banner can quote the
+	// flag back rather than making the reader remember what they typed.
+	Severities []string `json:"severities"`
+	Count      int      `json:"count"`
+	// BySeverity is what was dropped, keyed by label. UNKNOWN in here is the
+	// entry that matters: those findings are unrated, not unimportant.
+	BySeverity map[string]int `json:"by_severity"`
+}
+
+// severityFilter keeps only the findings whose severity was asked for, and
+// reports what it dropped.
+//
+// An empty keep-list is a no-op returning a nil Withheld, which is how an
+// unfiltered run produces neither a JSON field nor a banner.
+//
+// Matching is on cvss.Display, so a finding no advisory resolved for and one
+// whose advisory published no rating are both UNKNOWN here -- the same fact
+// they already are to a reader. UNKNOWN is therefore a severity you can ask
+// for, and one you have to ask for: --severity CRITICAL,HIGH drops it. That is
+// Trivy's behavior and it is what a reader of the flag expects, but it is worth
+// being clear-eyed that on debian:12 it hides 36 findings whose only crime is
+// that their record is CVSS v4-only, and on --repo it hides every Go finding
+// there is. The banner exists because of that, not in spite of it.
+func severityFilter(findings []Finding, keep []string) ([]Finding, *Withheld) {
+	if len(keep) == 0 {
+		return findings, nil
+	}
+	wanted := make(map[string]bool, len(keep))
+	for _, s := range keep {
+		wanted[cvss.Display(s)] = true
+	}
+
+	kept := make([]Finding, 0, len(findings))
+	w := &Withheld{Severities: keep, BySeverity: map[string]int{}}
+	for _, f := range findings {
+		if wanted[cvss.Display(f.Severity)] || alwaysReport(f) {
+			kept = append(kept, f)
+			continue
+		}
+		w.Count++
+		w.BySeverity[cvss.Display(f.Severity)]++
+	}
+	if w.Count == 0 {
+		// Nothing was hidden, so there is nothing to warn about. A banner
+		// saying "withheld 0 findings" is noise that trains a reader to skip
+		// the line that will one day say something.
+		return kept, nil
+	}
+	return kept, w
+}
+
+// alwaysReport is the one exemption from the filter: a finding that exists to
+// account for an id the user named by hand.
+//
+// unmapped emits these so that a --cves id which matched no component anywhere
+// still appears in the output, on the grounds that "a missing id reads as a
+// clean one". They carry no severity, so a severity filter would delete every
+// one of them and recreate exactly the silence unmapped was written to prevent
+// -- and it would do it to the ids the reader was most explicitly asking about.
+func alwaysReport(f Finding) bool {
+	return f.Reason == "no_component_matched" && f.Status == ecosystem.StatusUndetermined
+}

internal/analyze/severity_test.go

@@ -127,3 +127,149 @@ func TestSeverityOverlayLeavesUnresolvableFindingsAlone(t *testing.T) {
 		t.Errorf("unresolved finding was labelled: %+v", findings[0])
 	}
 }
+
+// rated is a linked finding at one severity, which is all severityFilter looks
+// at. An empty label is the real and common case: no advisory was resolved.
+func rated(id, label string) Finding {
+	return Finding{
+		Ecosystem: "os", ID: id, CVE: id,
+		Severity: label, Status: StatusLinked,
+	}
+}
+
+func labels(findings []Finding) []string {
+	out := make([]string, 0, len(findings))
+	for _, f := range findings {
+		out = append(out, f.ID)
+	}
+	return out
+}
+
+func TestNoSeverityFilterIsANoOp(t *testing.T) {
+	in := []Finding{rated("a", cvss.Critical), rated("b", cvss.Low)}
+	got, w := severityFilter(in, nil)
+	if len(got) != 2 {
+		t.Errorf("kept %v, want both", labels(got))
+	}
+	if w != nil {
+		t.Errorf("Withheld = %+v, want nil so no banner prints", w)
+	}
+}
+
+func TestSeverityFilterKeepsOnlyWhatWasNamed(t *testing.T) {
+	in := []Finding{
+		rated("crit", cvss.Critical),
+		rated("high", cvss.High),
+		rated("med", cvss.Medium),
+		rated("low", cvss.Low),
+	}
+	got, w := severityFilter(in, []string{cvss.Critical, cvss.High})
+	if len(got) != 2 || got[0].ID != "crit" || got[1].ID != "high" {
+		t.Errorf("kept %v, want [crit high]", labels(got))
+	}
+	if w == nil || w.Count != 2 {
+		t.Fatalf("Withheld = %+v, want 2 dropped", w)
+	}
+	if w.BySeverity[cvss.Medium] != 1 || w.BySeverity[cvss.Low] != 1 {
+		t.Errorf("BySeverity = %v, want one medium and one low", w.BySeverity)
+	}
+}
+
+// The decision that most surprises a Trivy user, pinned: an unrated finding is
+// dropped by --severity CRITICAL,HIGH, and counted as UNKNOWN so the banner can
+// say the drop happened.
+func TestAnUnratedFindingIsWithheldAsUnknown(t *testing.T) {
+	in := []Finding{rated("crit", cvss.Critical), rated("unrated", "")}
+	got, w := severityFilter(in, []string{cvss.Critical, cvss.High})
+	if len(got) != 1 || got[0].ID != "crit" {
+		t.Errorf("kept %v, want [crit]", labels(got))
+	}
+	if w == nil || w.BySeverity[cvss.Unknown] != 1 {
+		t.Fatalf("Withheld = %+v, want the unrated finding counted as UNKNOWN", w)
+	}
+}
+
+// An empty Severity and an explicit UNKNOWN are the same fact to a reader, so
+// naming UNKNOWN has to reach both.
+func TestNamingUnknownKeepsBothSpellingsOfUnrated(t *testing.T) {
+	in := []Finding{
+		rated("empty", ""),
+		rated("explicit", cvss.Unknown),
+		rated("high", cvss.High),
+	}
+	got, w := severityFilter(in, []string{cvss.Unknown})
+	if len(got) != 2 || got[0].ID != "empty" || got[1].ID != "explicit" {
+		t.Errorf("kept %v, want both unrated spellings", labels(got))
+	}
+	if w == nil || w.Count != 1 || w.BySeverity[cvss.High] != 1 {
+		t.Errorf("Withheld = %+v, want only the high one dropped", w)
+	}
+}
+
+// The exemption. unmapped emits this row so an id the user typed cannot vanish;
+// a severity filter deleting it would recreate exactly the silence that row
+// exists to prevent, and would do it to the id they asked about most directly.
+func TestARequestedIdThatMatchedNothingSurvivesTheFilter(t *testing.T) {
+	in := append(unmapped([]string{"CVE-2024-9999"}, nil), rated("med", cvss.Medium))
+	got, w := severityFilter(in, []string{cvss.Critical})
+	if len(got) != 1 || got[0].CVE != "CVE-2024-9999" {
+		t.Fatalf("kept %v, want the unmatched id to survive", labels(got))
+	}
+	if got[0].Reason != "no_component_matched" {
+		t.Errorf("Reason = %q, want it unchanged", got[0].Reason)
+	}
+	// It survived, so it is not counted as withheld -- the banner would be
+	// claiming to have hidden a row that is printed right below it.
+	if w == nil || w.Count != 1 || w.BySeverity[cvss.Medium] != 1 {
+		t.Errorf("Withheld = %+v, want only the medium finding counted", w)
+	}
+}
+
+// An undetermined finding with no severity is not exempt: only the
+// no_component_matched receipt is.
+func TestTheExemptionIsNarrow(t *testing.T) {
+	f := Finding{ID: "x", CVE: "x", Status: StatusUndetermined, Reason: "dlopen_reachable"}
+	got, w := severityFilter([]Finding{f}, []string{cvss.Critical})
+	if len(got) != 0 {
+		t.Errorf("kept %v, want an ordinary undetermined finding to be filtered", labels(got))
+	}
+	if w == nil || w.Count != 1 {
+		t.Errorf("Withheld = %+v, want it counted", w)
+	}
+}
+
+// A filter that hid nothing produces no banner, so the line that will one day
+// matter is not one a reader has been trained to skip.
+func TestAFilterThatHidNothingReportsNothing(t *testing.T) {
+	in := []Finding{rated("crit", cvss.Critical)}
+	got, w := severityFilter(in, []string{cvss.Critical, cvss.High})
+	if len(got) != 1 {
+		t.Errorf("kept %v, want the critical finding", labels(got))
+	}
+	if w != nil {
+		t.Errorf("Withheld = %+v, want nil when nothing was dropped", w)
+	}
+}
+
+func TestWithheldQuotesTheFlagBack(t *testing.T) {
+	_, w := severityFilter([]Finding{rated("low", cvss.Low)}, []string{cvss.Critical, cvss.High})
+	if w == nil {
+		t.Fatal("want a Withheld")
+	}
+	if len(w.Severities) != 2 || w.Severities[0] != cvss.Critical || w.Severities[1] != cvss.High {
+		t.Errorf("Severities = %v, want what --severity asked for", w.Severities)
+	}
+}
+
+// Filtering everything is legal and is the --repo case: every Go finding there
+// is UNKNOWN. What must not happen is it going unrecorded.
+func TestFilteringEverythingIsStillRecorded(t *testing.T) {
+	in := []Finding{rated("a", ""), rated("b", "")}
+	got, w := severityFilter(in, []string{cvss.High, cvss.Critical})
+	if len(got) != 0 {
+		t.Errorf("kept %v, want nothing", labels(got))
+	}
+	if w == nil || w.Count != 2 || w.BySeverity[cvss.Unknown] != 2 {
+		t.Fatalf("Withheld = %+v, want both counted as unrated", w)
+	}
+}