@intentius/chant 0.41.19 → 0.42.1

package/src/components/verbs/exploitability-roundtrip.test.ts

@@ -0,0 +1,190 @@
+/**
+ * Contract test (#1464): exploitability data (KEV/EPSS, from #1462/#1463)
+ * survives the trip from scanner output to the gate's policy evaluation via
+ * BOTH routes a finding can take there:
+ *
+ *   1. `scan-vulnerabilities` step -> `ScanVulnerabilitiesOutput.findings` ->
+ *      `vuln-gate`'s `findings` input (the cross-capability seam where an
+ *      intermediate mapping could drop a field unnoticed), and
+ *   2. `vuln-gate` with no `findings`, scanning the SBOM itself through the
+ *      injected `VulnScanner`.
+ *
+ * All hermetic: real captured scanner stdout from __fixtures__ plus inline
+ * fake scanners — no live scanner, network, or vuln DB. Gate *behavior* on
+ * these fields is #1465; this file only proves the data arrives intact.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, test, expect } from "vitest";
+import {
+  createScanVulnerabilitiesCapability,
+  parseGrypeOutput,
+  parseTrivyOutput,
+  type VulnFinding,
+  type VulnScanner,
+} from "./vuln-scan";
+import { createVulnGateCapability, VulnGateFailedError } from "./vuln-gate";
+import { applyVex } from "./vex";
+import type { SbomDocument } from "./sbom-generator";
+
+const ctx = { env: "prod", component: "search-service" };
+const FIXTURES_DIR = join(import.meta.dirname, "__fixtures__");
+
+const SBOM: SbomDocument = {
+  format: "cyclonedx",
+  mediaType: "application/vnd.cyclonedx+json",
+  bytes: JSON.stringify({ components: [{ name: "log4j-core", version: "2.14.1" }] }),
+  generator: "lockfile",
+};
+
+const EXPLOITABILITY_FIELDS = ["epss", "epssPercentile", "inKev", "kevDateAdded", "kevDueDate", "kevRansomware"] as const;
+
+/** The real grype capture from #1463 — findings with and without exploitability data in one document. */
+const grypeFindings = () => parseGrypeOutput(readFileSync(join(FIXTURES_DIR, "grype-with-kev-epss.json"), "utf8"));
+
+const kevFinding = (findings: VulnFinding[]) => findings.find((f) => f.inKev === true);
+
+describe("exploitability survives scan -> gate (#1464)", () => {
+  test("path 1: scan-vulnerabilities output carries every exploitability field into vuln-gate's findings input", async () => {
+    const scanner: VulnScanner = {
+      async scan() {
+        return grypeFindings();
+      },
+    };
+    const scanned = await createScanVulnerabilitiesCapability(scanner).run(ctx, { sbom: SBOM, digest: "sha256:abc" });
+    const kev = kevFinding(scanned.findings);
+    expect(kev).toBeDefined();
+    expect(kev!.epss).toBeTypeOf("number");
+    expect(kev!.epssPercentile).toBeTypeOf("number");
+    expect(kev!.kevDateAdded).toBeTypeOf("string");
+    expect(kev!.kevDueDate).toBeTypeOf("string");
+    expect(kev!.kevRansomware).toBe(true);
+
+    // Hand the scan step's output to the gate the way a composition wires it,
+    // with VEX suppressing every critical (the capture has two KEV-listed
+    // ones) so the gate passes and reports them — the suppression report is
+    // our window onto what the gate actually saw.
+    const vex = JSON.stringify({
+      statements: scanned.findings
+        .filter((f) => f.severity === "critical")
+        .map((f) => ({ vulnerability: f.cveId, status: "not_affected", justification: "not reachable" })),
+    });
+    const out = await createVulnGateCapability().run(ctx, {
+      sbom: SBOM,
+      findings: scanned.findings,
+      vex: [vex],
+      policy: { failSeverity: "critical", fixableOnly: false },
+    });
+
+    const seen = out.suppressed.find((s) => s.finding.cveId === kev!.cveId)!.finding;
+    for (const field of EXPLOITABILITY_FIELDS) expect(seen[field]).toBe(kev![field]);
+  });
+
+  test("path 1: a KEV finding that BLOCKS reaches the error's blocking list with exploitability intact", async () => {
+    const scanner: VulnScanner = {
+      async scan() {
+        return grypeFindings();
+      },
+    };
+    const scanned = await createScanVulnerabilitiesCapability(scanner).run(ctx, { sbom: SBOM });
+    const kev = kevFinding(scanned.findings)!;
+    let err: unknown;
+    try {
+      await createVulnGateCapability().run(ctx, { sbom: SBOM, findings: scanned.findings });
+    } catch (e) {
+      err = e;
+    }
+    expect(err).toBeInstanceOf(VulnGateFailedError);
+    const blocked = (err as VulnGateFailedError).blocking.find((b) => b.finding.cveId === kev.cveId);
+    expect(blocked).toBeDefined();
+    // Blocked for severity, not KEV — exploitability changes no outcome yet
+    // (#1465) — but the data rode along to the decision point untouched.
+    expect(blocked!.reason).toBe("severity-threshold");
+    for (const field of EXPLOITABILITY_FIELDS) expect(blocked!.finding[field]).toBe(kev[field]);
+  });
+
+  test("path 2: the gate-scans-for-you route delivers the same fields intact", async () => {
+    const kev = kevFinding(grypeFindings())!;
+    const fake: VulnScanner = {
+      async scan() {
+        return [kev];
+      },
+    };
+    const vex = JSON.stringify({ statements: [{ vulnerability: kev.cveId, status: "not_affected" }] });
+    const out = await createVulnGateCapability(fake).run(ctx, { sbom: SBOM, vex: [vex] });
+    const seen = out.suppressed[0].finding;
+    expect(seen).toBe(kev); // same object — nothing rebuilt it on the way through
+    expect(seen.inKev).toBe(true);
+    expect(seen.epss).toBe(kev.epss);
+    expect(seen.epssPercentile).toBe(kev.epssPercentile);
+  });
+
+  test("warnings surface the finding object intact, exploitability included", async () => {
+    const kevHigh: VulnFinding = {
+      cveId: "CVE-2021-45046",
+      severity: "high",
+      package: "log4j-core",
+      installedVersion: "2.14.1",
+      fixedVersion: "2.16.0",
+      fixable: true,
+      epss: 0.99977,
+      epssPercentile: 0.9998,
+      inKev: true,
+      kevDateAdded: "2023-05-01",
+      kevDueDate: "2023-05-22",
+      kevRansomware: true,
+    };
+    const out = await createVulnGateCapability().run(ctx, { sbom: SBOM, findings: [kevHigh] });
+    expect(out.passed).toBe(true);
+    expect(out.warnings).toEqual([kevHigh]);
+    expect(out.warnings[0].inKev).toBe(true);
+    expect(out.warnings[0].epss).toBe(0.99977);
+  });
+
+  test("a scanner reporting no exploitability data reaches the gate with all six fields undefined — not false, not 0", async () => {
+    // The real trivy capture from #1463: same CVEs as the grype fixture, zero
+    // exploitability data — trivy's JSON output has no KEV/EPSS fields at all.
+    const trivyFindings = parseTrivyOutput(readFileSync(join(FIXTURES_DIR, "trivy-with-kev-epss.json"), "utf8"));
+    const scanner: VulnScanner = {
+      async scan() {
+        return trivyFindings;
+      },
+    };
+    const scanned = await createScanVulnerabilitiesCapability(scanner).run(ctx, { sbom: SBOM });
+    let err: unknown;
+    try {
+      await createVulnGateCapability().run(ctx, { sbom: SBOM, findings: scanned.findings });
+    } catch (e) {
+      err = e;
+    }
+    // The capture's fixable criticals block on severity as before; inspect the
+    // findings as the gate saw them at the decision point.
+    expect(err).toBeInstanceOf(VulnGateFailedError);
+    const seen = (err as VulnGateFailedError).blocking.map((b) => b.finding);
+    expect(seen.length).toBeGreaterThan(0);
+    for (const f of seen) {
+      expect(f.inKev).toBeUndefined();
+      expect(f.inKev).not.toBe(false); // undefined !== false: "not reported" is not "reported absent"
+      expect(f.epss).toBeUndefined();
+      expect(f.epss).not.toBe(0);
+      expect(f.epssPercentile).toBeUndefined();
+      expect(f.kevDateAdded).toBeUndefined();
+      expect(f.kevDueDate).toBeUndefined();
+      expect(f.kevRansomware).toBeUndefined();
+    }
+  });
+
+  test("applyVex preserves exploitability on findings it does NOT suppress (no rebuild, no dropped keys)", () => {
+    const findings = grypeFindings();
+    const kev = kevFinding(findings)!;
+    const other = findings.find((f) => f.inKev === undefined && f.cveId !== kev.cveId)!;
+    const { gating, suppressed } = applyVex(findings, [
+      { cveId: other.cveId, status: "not_affected", justification: "not reachable" },
+    ]);
+    expect(suppressed.map((s) => s.finding.cveId)).toEqual([other.cveId]);
+    const survived = gating.find((f) => f.cveId === kev.cveId)!;
+    expect(survived).toBe(kev); // pass-through by reference, not a rebuilt object
+    for (const field of EXPLOITABILITY_FIELDS) expect(survived[field]).toBe(kev[field]);
+  });
+});

package/src/components/verbs/sbom.ts

@@ -148,5 +148,5 @@ export function createGenerateSbomCapability(
   };
 }
 
-/** Default `generate-sbom` capability, backed by the process-wide default `SbomGenerator` (throws until a real backend is injected — see ./sbom-generator.ts's `notImplementedSbomGenerator`). */
+/** Default `generate-sbom` capability, backed by the process-wide default `SbomGenerator` — the hermetic lockfile backend (#630), so `dir`/`zip`/`jar` work with no tool installed; only `forImage` throws until `toolSbomGenerator` is injected. See ./sbom-generator.ts's `defaultSbomGenerator`. */
 export const generateSbomCapability: Capability<GenerateSbomInput, GenerateSbomOutput> = createGenerateSbomCapability();

package/src/components/verbs/vuln-gate.test.ts

@@ -9,7 +9,7 @@
 import { describe, test, expect } from "vitest";
 import { parseOpenVex, parseCycloneDxVex, parseVexDocument, applyVex } from "./vex";
 import { extractLicenses, evaluateLicensePolicy } from "./license-policy";
-import { createVulnGateCapability, VulnGateFailedError, type VulnGateInput } from "./vuln-gate";
+import { createVulnGateCapability, DEFAULT_VULN_POLICY, VulnGateFailedError, type VulnGateInput } from "./vuln-gate";
 import type { VulnFinding, VulnScanner } from "./vuln-scan";
 import type { SbomDocument } from "./sbom-generator";
 import { resolveVulnPolicy } from "../../config";
@@ -186,6 +186,131 @@ describe("audit hardening (#628)", () => {
   });
 });
 
+// ── exploitability shape (#1462, phase 0 of epic #1461) ──────────────────────
+
+describe("exploitability policy shape (#1462)", () => {
+  test("DEFAULT_VULN_POLICY does not gate on KEV — flipping failOnKev is a deliberate release decision (epic #1461), not a drive-by", () => {
+    expect(DEFAULT_VULN_POLICY.failOnKev).toBe(false);
+    expect(DEFAULT_VULN_POLICY.exploitabilityFixableOnly).toBe(true);
+    expect(DEFAULT_VULN_POLICY.failEpssAtOrAbove).toBeUndefined();
+    expect(DEFAULT_VULN_POLICY.warnEpssAtOrAbove).toBeUndefined();
+  });
+
+  test("a finding carrying exploitability fields passes through the gate with today's outcomes (evaluation is #1465)", async () => {
+    const kevHigh: VulnFinding = {
+      ...HIGH_FIXABLE,
+      epss: 0.42,
+      epssPercentile: 0.97,
+      inKev: true,
+      kevDateAdded: "2026-01-15",
+      kevDueDate: "2026-02-05",
+      kevRansomware: true,
+    };
+    // KEV membership changes no outcome in this phase: still a warning under the default policy.
+    const out = await gate({ sbom: SBOM_SPDX, findings: [kevHigh] });
+    expect(out.passed).toBe(true);
+    expect(out.warnings).toEqual([kevHigh]);
+  });
+
+  test("a finding constructed without exploitability fields still typechecks and gates as before", async () => {
+    await expect(gate({ sbom: SBOM_SPDX, findings: [CRIT_FIXABLE], policy: { failOnKev: false, exploitabilityFixableOnly: true } })).rejects.toBeInstanceOf(
+      VulnGateFailedError,
+    );
+  });
+});
+
+// ── exploitability evaluation (#1465, phase 2 of epic #1461) ─────────────────
+
+describe("exploitability evaluation (#1465)", () => {
+  const MEDIUM_KEV_FIXABLE: VulnFinding = {
+    cveId: "CVE-K1", severity: "medium", package: "libfoo", installedVersion: "1", fixedVersion: "2", fixable: true,
+    inKev: true, kevDateAdded: "2024-03-11", kevRansomware: true,
+  };
+  const LOW_HIGH_EPSS: VulnFinding = {
+    cveId: "CVE-E1", severity: "low", package: "libbar", installedVersion: "1", fixedVersion: "2", fixable: true,
+    epss: 0.42, epssPercentile: 0.97,
+  };
+
+  async function blockingOf(input: VulnGateInput) {
+    try {
+      await gate(input);
+    } catch (e) {
+      expect(e).toBeInstanceOf(VulnGateFailedError);
+      return (e as VulnGateFailedError).blocking;
+    }
+    throw new Error("expected the gate to block");
+  }
+
+  test("failOnKev blocks a fixable KEV finding BELOW the fail severity, reason kev — the headline case that passes today", async () => {
+    const blocking = await blockingOf({ sbom: SBOM_SPDX, findings: [MEDIUM_KEV_FIXABLE], policy: { failOnKev: true } });
+    expect(blocking).toEqual([{ finding: MEDIUM_KEV_FIXABLE, reason: "kev" }]);
+  });
+
+  test("an UNFIXABLE KEV finding warns instead of blocking under exploitabilityFixableOnly (default)", async () => {
+    const unfixable: VulnFinding = { ...MEDIUM_KEV_FIXABLE, fixedVersion: undefined, fixable: false };
+    const out = await gate({ sbom: SBOM_SPDX, findings: [unfixable], policy: { failOnKev: true } });
+    expect(out.passed).toBe(true);
+    expect(out.warnings).toEqual([unfixable]);
+  });
+
+  test("exploitabilityFixableOnly: false blocks the unfixable KEV finding too", async () => {
+    const unfixable: VulnFinding = { ...MEDIUM_KEV_FIXABLE, fixedVersion: undefined, fixable: false };
+    const blocking = await blockingOf({ sbom: SBOM_SPDX, findings: [unfixable], policy: { failOnKev: true, exploitabilityFixableOnly: false } });
+    expect(blocking[0].reason).toBe("kev");
+  });
+
+  test("failEpssAtOrAbove blocks a low-severity finding at/above the threshold, reason epss-threshold", async () => {
+    const blocking = await blockingOf({ sbom: SBOM_SPDX, findings: [LOW_HIGH_EPSS], policy: { failEpssAtOrAbove: 0.1 } });
+    expect(blocking).toEqual([{ finding: LOW_HIGH_EPSS, reason: "epss-threshold" }]);
+  });
+
+  test("absent EPSS never matches a threshold — undefined is not zero", async () => {
+    const unscored: VulnFinding = { ...LOW_HIGH_EPSS, epss: undefined, epssPercentile: undefined };
+    const out = await gate({ sbom: SBOM_SPDX, findings: [unscored], policy: { failEpssAtOrAbove: 0, warnEpssAtOrAbove: 0 } });
+    expect(out.passed).toBe(true);
+    expect(out.warnings).toEqual([]);
+  });
+
+  test("warnEpssAtOrAbove warns without blocking", async () => {
+    const out = await gate({ sbom: SBOM_SPDX, findings: [LOW_HIGH_EPSS], policy: { warnEpssAtOrAbove: 0.1 } });
+    expect(out.passed).toBe(true);
+    expect(out.warnings).toEqual([LOW_HIGH_EPSS]);
+  });
+
+  test("VEX suppression outranks KEV — a suppressed KEV finding does not block and lands in suppressed", async () => {
+    const vex = JSON.stringify({ statements: [{ vulnerability: "CVE-K1", status: "not_affected", justification: "vulnerable code not in execute path" }] });
+    const out = await gate({ sbom: SBOM_SPDX, findings: [MEDIUM_KEV_FIXABLE], vex: [vex], policy: { failOnKev: true } });
+    expect(out.passed).toBe(true);
+    expect(out.suppressed.map((s) => s.finding.cveId)).toEqual(["CVE-K1"]);
+  });
+
+  test("exploitability escalates, never de-escalates: a severity block with low EPSS and no KEV still blocks", async () => {
+    const dullCritical: VulnFinding = { ...CRIT_FIXABLE, epss: 0.001, inKev: undefined };
+    const blocking = await blockingOf({ sbom: SBOM_SPDX, findings: [dullCritical], policy: { failOnKev: true, failEpssAtOrAbove: 0.5 } });
+    expect(blocking).toEqual([{ finding: dullCritical, reason: "severity-threshold" }]);
+  });
+
+  test("a finding blocked for several reasons is reported once, under the most specific: kev > epss-threshold > severity-threshold", async () => {
+    const everything: VulnFinding = { ...CRIT_FIXABLE, epss: 0.9, inKev: true, kevDateAdded: "2024-03-11" };
+    const blocking = await blockingOf({ sbom: SBOM_SPDX, findings: [everything], policy: { failOnKev: true, failEpssAtOrAbove: 0.1 } });
+    expect(blocking).toEqual([{ finding: everything, reason: "kev" }]);
+  });
+
+  test("the error message names the rule that fired for each finding", async () => {
+    const err = await gate({
+      sbom: SBOM_SPDX,
+      findings: [MEDIUM_KEV_FIXABLE, LOW_HIGH_EPSS, CRIT_FIXABLE],
+      policy: { failOnKev: true, failEpssAtOrAbove: 0.1 },
+    }).then(
+      () => { throw new Error("expected the gate to block"); },
+      (e) => e as VulnGateFailedError,
+    );
+    expect(err.message).toContain("CVE-K1 (medium, libfoo) — in CISA KEV since 2024-03-11, known ransomware use");
+    expect(err.message).toContain("CVE-E1 (low, libbar) — EPSS 0.42 at/above the fail threshold");
+    expect(err.message).toContain("CVE-1 (critical, a) — severity at/above the fail threshold, fixable");
+  });
+});
+
 // ── config resolver ──────────────────────────────────────────────────────────
 
 describe("resolveVulnPolicy", () => {
@@ -198,4 +323,22 @@ describe("resolveVulnPolicy", () => {
       license: { deny: ["GPL-3.0"] },
     });
   });
+
+  test("passes through the exploitability fields (#1466)", () => {
+    expect(resolveVulnPolicy({ vulnPolicy: { failOnKev: true, failEpssAtOrAbove: 0.1, warnEpssAtOrAbove: 0.01, exploitabilityFixableOnly: false } })).toEqual({
+      failOnKev: true,
+      failEpssAtOrAbove: 0.1,
+      warnEpssAtOrAbove: 0.01,
+      exploitabilityFixableOnly: false,
+    });
+  });
+
+  test("failEpssAtOrAbove: 0 survives — a meaningful value, not falsy noise", () => {
+    expect(resolveVulnPolicy({ vulnPolicy: { failEpssAtOrAbove: 0, warnEpssAtOrAbove: 0 } })).toEqual({ failEpssAtOrAbove: 0, warnEpssAtOrAbove: 0 });
+  });
+
+  test("an explicit failOnKev: false is distinguishable from unset", () => {
+    expect(resolveVulnPolicy({ vulnPolicy: { failOnKev: false } })).toEqual({ failOnKev: false });
+    expect(resolveVulnPolicy({ vulnPolicy: {} })).toEqual({});
+  });
 });

package/src/components/verbs/vuln-gate.ts

@@ -42,6 +42,14 @@ export interface VulnPolicy {
   failOnLicense: boolean;
   /** Block on an `unknown`-severity finding (a scanner that didn't report a severity chant could map). Default `false` — but such a finding is ALWAYS at least warned, never silently dropped, regardless of this flag. Set true for a strict shop that won't ship an unclassifiable finding. */
   failOnUnknownSeverity: boolean;
+  /** Block any finding in the CISA KEV catalog, regardless of severity. Default `false` — see epic #1461's open decision before flipping. */
+  failOnKev: boolean;
+  /** Block when EPSS is at or above this (0.0–1.0). Omit to ignore EPSS entirely. */
+  failEpssAtOrAbove?: number;
+  /** Warn (not block) at or above this EPSS. Omit to ignore. */
+  warnEpssAtOrAbove?: number;
+  /** Apply `fixableOnly` to exploitability blocks too — an unfixable KEV finding warns rather than blocks. Default `true`. */
+  exploitabilityFixableOnly: boolean;
 }
 
 /** Beginner-safe defaults, also encoded in `resolveVulnPolicy` (../../config.ts). */
@@ -51,6 +59,8 @@ export const DEFAULT_VULN_POLICY: VulnPolicy = {
   warnSeverity: "high",
   failOnLicense: false,
   failOnUnknownSeverity: false,
+  failOnKev: false,
+  exploitabilityFixableOnly: true,
 };
 
 export interface VulnGateInput {
@@ -69,7 +79,7 @@ export interface VulnGateInput {
 /** A finding that fails the gate, with why. */
 export interface BlockingFinding {
   finding: VulnFinding;
-  reason: "severity-threshold" | "unknown-severity";
+  reason: "severity-threshold" | "unknown-severity" | "kev" | "epss-threshold";
 }
 
 export interface VulnGateOutput {
@@ -95,16 +105,35 @@ export class VulnGateFailedError extends Error {
     public readonly blocking: BlockingFinding[],
     public readonly blockingLicenses: LicenseViolation[],
   ) {
-    const cveList = blocking.map((b) => `${b.finding.cveId} (${b.finding.severity}, ${b.finding.package})`).join(", ");
     const licList = blockingLicenses.map((l) => `${l.license} in ${l.package}`).join(", ");
     const parts: string[] = [];
-    if (blocking.length) parts.push(`${blocking.length} vulnerability finding(s): ${cveList}`);
+    if (blocking.length) {
+      const lines = blocking.map((b) => `  ${b.finding.cveId} (${b.finding.severity}, ${b.finding.package}) — ${describeBlockReason(b)}`);
+      parts.push(`${blocking.length} vulnerability finding(s):\n${lines.join("\n")}`);
+    }
     if (blockingLicenses.length) parts.push(`${blockingLicenses.length} license violation(s): ${licList}`);
-    super(`vuln-gate blocked the deploy — ${parts.join("; ")}. Fix the dependency, or record a VEX statement if it is not exploitable.`);
+    super(`vuln-gate blocked the deploy — ${parts.join("\n")}\nFix the dependency, or record a VEX statement if it is not exploitable.`);
     this.name = "VulnGateFailedError";
   }
 }
 
+/** Which rule fired, human-readably — naming the rule is the difference between a gate people tune and a gate people disable. */
+function describeBlockReason(b: BlockingFinding): string {
+  const f = b.finding;
+  switch (b.reason) {
+    case "kev": {
+      const since = f.kevDateAdded ? `in CISA KEV since ${f.kevDateAdded}` : "in CISA KEV";
+      return f.kevRansomware ? `${since}, known ransomware use` : since;
+    }
+    case "epss-threshold":
+      return `EPSS ${f.epss} at/above the fail threshold`;
+    case "unknown-severity":
+      return "severity unreported by the scanner (failOnUnknownSeverity)";
+    case "severity-threshold":
+      return `severity at/above the fail threshold${f.fixable ? ", fixable" : ""}`;
+  }
+}
+
 /** Parse every supplied VEX document into a flat statement list (ignoring any that fail to parse into a known shape). */
 function collectVex(docs: string[] | undefined): VexStatement[] {
   const out: VexStatement[] = [];
@@ -116,10 +145,13 @@ function collectVex(docs: string[] | undefined): VexStatement[] {
  * Build the `vuln-gate` capability. Scans `sbom` (or uses supplied `findings`),
  * applies VEX, evaluates the license policy, and classifies every gating
  * finding: it BLOCKS (throws `VulnGateFailedError`) any finding at/above
- * `failSeverity` that satisfies `fixableOnly`, plus license violations when
+ * `failSeverity` that satisfies `fixableOnly`, any KEV finding when
+ * `failOnKev`, any finding at/above `failEpssAtOrAbove` (exploitability
+ * blocks honor `exploitabilityFixableOnly`), plus license violations when
  * `failOnLicense`; everything at/above `warnSeverity` below the fail bar is a
- * warning. On a clean pass it returns the warnings/suppressed/license report
- * for logging.
+ * warning, as are exploitability hits kept from blocking only by fixability
+ * and findings at/above `warnEpssAtOrAbove`. On a clean pass it returns the
+ * warnings/suppressed/license report for logging.
  */
 export function createVulnGateCapability(
   scanner: VulnScanner = defaultVulnScanner(),
@@ -133,14 +165,30 @@ export function createVulnGateCapability(
       // 1. VEX suppression.
       const { gating, suppressed } = applyVex(rawFindings, collectVex(input.vex));
 
-      // 2. Classify gating findings against the severity policy.
+      // 2. Classify gating findings against the severity + exploitability
+      // policy. Exploitability (KEV, EPSS) can only ESCALATE — the rules are
+      // independent block reasons OR'd together, never a replacement scoring
+      // system that could exempt a severity block. A finding blocked for more
+      // than one reason is reported once, under the most specific reason
+      // (kev > epss-threshold > severity-threshold). VEX suppression (step 1)
+      // outranks all of it, KEV included: a VEX statement is a claim about
+      // this artifact as built, a catalog entry is about the CVE somewhere.
       const failRank = SEVERITY_RANK[policy.failSeverity];
       const warnRank = SEVERITY_RANK[policy.warnSeverity];
       const blocking: BlockingFinding[] = [];
       const warnings: VulnFinding[] = [];
       for (const f of gating) {
         const rank = SEVERITY_RANK[f.severity];
-        if (rank >= failRank && (!policy.fixableOnly || f.fixable)) {
+        // Absent EPSS is "not scored", never zero — it can't match a threshold.
+        const epssFailHit = policy.failEpssAtOrAbove !== undefined && f.epss !== undefined && f.epss >= policy.failEpssAtOrAbove;
+        const epssWarnHit = policy.warnEpssAtOrAbove !== undefined && f.epss !== undefined && f.epss >= policy.warnEpssAtOrAbove;
+        const kevHit = policy.failOnKev && f.inKev === true;
+        const exploitActionable = !policy.exploitabilityFixableOnly || f.fixable;
+        if (kevHit && exploitActionable) {
+          blocking.push({ finding: f, reason: "kev" });
+        } else if (epssFailHit && exploitActionable) {
+          blocking.push({ finding: f, reason: "epss-threshold" });
+        } else if (rank >= failRank && (!policy.fixableOnly || f.fixable)) {
           blocking.push({ finding: f, reason: "severity-threshold" });
         } else if (f.severity === "unknown") {
           // Never silently pass an unclassifiable finding — a real critical
@@ -148,7 +196,10 @@ export function createVulnGateCapability(
           // it always; block it when the policy opts in.
           if (policy.failOnUnknownSeverity) blocking.push({ finding: f, reason: "unknown-severity" });
           else warnings.push(f);
-        } else if (rank >= warnRank) {
+        } else if (rank >= warnRank || kevHit || epssFailHit || epssWarnHit) {
+          // The exploitability hits landing here were kept from blocking by
+          // exploitabilityFixableOnly (or are warn-only EPSS) — an unfixable
+          // KEV finding can't be actioned by upgrading, so it warns.
           warnings.push(f);
         }
       }

package/src/components/verbs/vuln-scan.test.ts

@@ -5,6 +5,8 @@
  * `scan-vulnerabilities` capability over an injected scanner.
  */
 
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
 import { describe, test, expect } from "vitest";
 import {
   normalizeSeverity,
@@ -22,6 +24,8 @@ import { createMockProcessRunner } from "./__tests__/mock-process-runner";
 
 const ctx = { env: "prod", component: "search-service" };
 
+const FIXTURES_DIR = join(import.meta.dirname, "__fixtures__");
+
 const SBOM: SbomDocument = {
   format: "spdx",
   mediaType: "application/spdx+json",
@@ -84,6 +88,96 @@ describe("parseTrivyOutput", () => {
   });
 });
 
+// ── exploitability parsing (#1463, over real captured scanner output) ────────
+// Fixtures are unmodified `grype -o json` (v0.116.1) / `trivy sbom --format
+// json` (v0.73.0) stdout from scanning a CycloneDX SBOM containing
+// log4j-core@2.14.1 — a package with KEV-listed CVEs (Log4Shell).
+
+describe("exploitability parsing (#1463)", () => {
+  const grypeFixture = readFileSync(join(FIXTURES_DIR, "grype-with-kev-epss.json"), "utf8");
+  const trivyFixture = readFileSync(join(FIXTURES_DIR, "trivy-with-kev-epss.json"), "utf8");
+
+  test("parseGrypeOutput carries KEV membership, dates, ransomware use, and EPSS through to the finding", () => {
+    const findings = parseGrypeOutput(grypeFixture);
+    const log4shell = findings.find((f) => f.epssPercentile === 1);
+    expect(log4shell).toBeDefined();
+    expect(log4shell!.inKev).toBe(true);
+    expect(log4shell!.kevDateAdded).toBe("2021-12-10");
+    expect(log4shell!.kevDueDate).toBe("2021-12-24");
+    expect(log4shell!.kevRansomware).toBe(true);
+    expect(log4shell!.epss).toBeCloseTo(0.99999, 5);
+    // The severity-shaped fields still parse as before on the same match.
+    expect(log4shell!.severity).toBe("critical");
+    expect(log4shell!.package).toBe("log4j-core");
+    expect(log4shell!.fixable).toBe(true);
+  });
+
+  test("grype omitting the KEV annotation leaves inKev undefined — reported-absent and not-reported are different states", () => {
+    const findings = parseGrypeOutput(grypeFixture);
+    const nonKev = findings.filter((f) => f.inKev === undefined);
+    expect(nonKev.length).toBeGreaterThan(0);
+    for (const f of nonKev) {
+      // undefined !== false: grype said nothing about KEV for these, which is
+      // not the same conclusion as grype reporting "not in KEV".
+      expect(f.inKev).not.toBe(false);
+      expect(f.kevDateAdded).toBeUndefined();
+      expect(f.kevDueDate).toBeUndefined();
+      expect(f.kevRansomware).toBeUndefined();
+      // EPSS is independent of KEV — grype scores these too.
+      expect(f.epss).toBeTypeOf("number");
+    }
+  });
+
+  test("parseTrivyOutput leaves every exploitability field undefined — trivy reports none of them", () => {
+    const findings = parseTrivyOutput(trivyFixture);
+    expect(findings.length).toBeGreaterThan(0);
+    const log4shell = findings.find((f) => f.cveId === "CVE-2021-44228");
+    expect(log4shell).toBeDefined();
+    expect(log4shell!.severity).toBe("critical");
+    for (const f of findings) {
+      expect(f.epss).toBeUndefined();
+      expect(f.epssPercentile).toBeUndefined();
+      expect(f.inKev).toBeUndefined();
+      expect(f.inKev).not.toBe(false);
+      expect(f.kevDateAdded).toBeUndefined();
+      expect(f.kevDueDate).toBeUndefined();
+      expect(f.kevRansomware).toBeUndefined();
+    }
+  });
+
+  test("a grype document with no exploitability data parses to findings with all six fields undefined", () => {
+    const findings = parseGrypeOutput(GRYPE_JSON);
+    for (const f of findings) {
+      expect(f.epss).toBeUndefined();
+      expect(f.epssPercentile).toBeUndefined();
+      expect(f.inKev).toBeUndefined();
+      expect(f.kevDateAdded).toBeUndefined();
+      expect(f.kevDueDate).toBeUndefined();
+      expect(f.kevRansomware).toBeUndefined();
+    }
+  });
+
+  test("KEV ransomware 'unknown' stays undefined, not false — KEV's tri-state survives", () => {
+    const doc = JSON.stringify({
+      matches: [
+        {
+          vulnerability: {
+            id: "CVE-2024-0004",
+            severity: "High",
+            fix: { versions: ["2.0"], state: "fixed" },
+            epss: [{ cve: "CVE-2024-0004", epss: 0.5, percentile: 0.9, date: "2026-08-01" }],
+            knownExploited: [{ cve: "CVE-2024-0004", dateAdded: "2026-01-01", dueDate: "2026-01-22", knownRansomwareCampaignUse: "unknown" }],
+          },
+          artifact: { name: "widget", version: "1.0" },
+        },
+      ],
+    });
+    const [f] = parseGrypeOutput(doc);
+    expect(f.inKev).toBe(true);
+    expect(f.kevRansomware).toBeUndefined();
+  });
+});
+
 describe("createToolVulnScanner (grype, via MockProcessRunner)", () => {
   test("scans the SBOM with `grype sbom:<file>` and parses the result", async () => {
     const mock = createMockProcessRunner({ tools: { grype: true }, responses: { "grype sbom:": GRYPE_JSON } });