@intentius/chant 0.13.1 → 0.15.0

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

@@ -0,0 +1,170 @@
+/**
+ * `vuln-gate` capability (#626) — the deploy-time gate that closes the
+ * supply-chain loop: scan the SBOM (./vuln-scan.ts) for known CVEs, suppress
+ * the ones VEX says don't matter (./vex.ts), check licenses (./license-policy.ts),
+ * and **throw** on a policy violation so composing it before an apply phase
+ * fails the deploy — the same throw-to-halt mechanism as ./verify.ts and
+ * `policyGate` (../../lint/policy.ts). No new gate plumbing.
+ *
+ * **Beginner-safe default policy:** fail on `severity >= critical AND fixable
+ * AND not VEX-suppressed`; findings at/above the warn severity (default
+ * `high`) that don't reach the fail bar are reported as warnings, not blocked;
+ * license findings are report-only unless `failOnLicense` is set. Everything
+ * is configurable via `chant.config.ts`'s `vulnPolicy` section (see
+ * ../../config.ts `resolveVulnPolicy`). The intent is that a first-timer who
+ * just adds a `vuln-gate` step gets a sensible, non-noisy gate that blocks the
+ * genuinely actionable (critical + fixable) and reports the rest.
+ */
+
+import type { Capability } from "../capability";
+import type { SbomDocument } from "./sbom-generator";
+import {
+  defaultVulnScanner,
+  SEVERITY_RANK,
+  type Severity,
+  type VulnFinding,
+  type VulnScanner,
+} from "./vuln-scan";
+import { applyVex, parseVexDocument, type SuppressedFinding, type VexStatement } from "./vex";
+import { evaluateLicensePolicy, type LicensePolicy, type LicenseViolation } from "./license-policy";
+
+/** The gate's policy. Defaults (per `resolveVulnPolicy`, ../../config.ts) are beginner-safe: fail critical+fixable, warn high, license report-only. */
+export interface VulnPolicy {
+  /** Minimum severity that FAILS the gate. Default `"critical"`. */
+  failSeverity: Severity;
+  /** When true (default), only *fixable* findings at/above `failSeverity` fail the gate — an unfixable finding can't be actioned by upgrading, so it warns instead of blocking. */
+  fixableOnly: boolean;
+  /** Minimum severity reported as a warning (below `failSeverity`). Default `"high"`. */
+  warnSeverity: Severity;
+  /** License allow/deny policy. Evaluated always; only *blocks* when `failOnLicense` is true. */
+  license?: LicensePolicy;
+  /** Block the deploy on a license violation. Default `false` (report-only) — license posture is context-dependent. */
+  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;
+}
+
+/** Beginner-safe defaults, also encoded in `resolveVulnPolicy` (../../config.ts). */
+export const DEFAULT_VULN_POLICY: VulnPolicy = {
+  failSeverity: "critical",
+  fixableOnly: true,
+  warnSeverity: "high",
+  failOnLicense: false,
+  failOnUnknownSeverity: false,
+};
+
+export interface VulnGateInput {
+  /** The artifact's SBOM. Scanned in-place unless `findings` is supplied. */
+  sbom: SbomDocument;
+  /** Pre-scanned findings (e.g. from a prior `scan-vulnerabilities` step). If omitted, the gate scans `sbom` itself via the injected scanner. */
+  findings?: VulnFinding[];
+  /** VEX documents (OpenVEX or CycloneDX-embedded), as serialized JSON, applied to suppress findings. */
+  vex?: string[];
+  /** Policy override; merged over `DEFAULT_VULN_POLICY`. */
+  policy?: Partial<VulnPolicy>;
+  /** Artifact digest, for reporting. */
+  digest?: string;
+}
+
+/** A finding that fails the gate, with why. */
+export interface BlockingFinding {
+  finding: VulnFinding;
+  reason: "severity-threshold" | "unknown-severity";
+}
+
+export interface VulnGateOutput {
+  /** Always `true` when returned — a violation throws instead (mirrors ./verify.ts's `verified`). */
+  passed: true;
+  /** Findings at/above `warnSeverity` that did not reach the fail bar. */
+  warnings: VulnFinding[];
+  /** Findings suppressed by VEX, with justification (never silently dropped). */
+  suppressed: SuppressedFinding[];
+  /** License findings — reported even when `failOnLicense` is false. */
+  licenseFindings: LicenseViolation[];
+}
+
+/**
+ * Thrown when the gate blocks a deploy — carries the blocking findings and any
+ * blocking license violations so a reviewer sees exactly what to fix (or VEX).
+ * Distinct from a scanner-not-installed error (`VulnScannerNotImplementedError`/
+ * `ToolNotAvailableError`) so a caller can tell "policy said no" from "no
+ * scanner."
+ */
+export class VulnGateFailedError extends Error {
+  constructor(
+    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 (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.`);
+    this.name = "VulnGateFailedError";
+  }
+}
+
+/** 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[] = [];
+  for (const bytes of docs ?? []) out.push(...parseVexDocument(bytes));
+  return out;
+}
+
+/**
+ * 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
+ * `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.
+ */
+export function createVulnGateCapability(
+  scanner: VulnScanner = defaultVulnScanner(),
+): Capability<VulnGateInput, VulnGateOutput> {
+  return {
+    kind: "vuln-gate",
+    async run(_ctx, input) {
+      const policy: VulnPolicy = { ...DEFAULT_VULN_POLICY, ...input.policy };
+      const rawFindings = input.findings ?? (await scanner.scan({ sbom: input.sbom, digest: input.digest }));
+
+      // 1. VEX suppression.
+      const { gating, suppressed } = applyVex(rawFindings, collectVex(input.vex));
+
+      // 2. Classify gating findings against the severity policy.
+      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)) {
+          blocking.push({ finding: f, reason: "severity-threshold" });
+        } else if (f.severity === "unknown") {
+          // Never silently pass an unclassifiable finding — a real critical
+          // could arrive mislabeled from a broken/compromised scanner. Surface
+          // 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) {
+          warnings.push(f);
+        }
+      }
+
+      // 3. License policy (always evaluated; blocks only when opted in).
+      const licenseFindings = policy.license ? evaluateLicensePolicy(input.sbom, policy.license) : [];
+      const blockingLicenses = policy.failOnLicense ? licenseFindings : [];
+
+      if (blocking.length > 0 || blockingLicenses.length > 0) {
+        throw new VulnGateFailedError(blocking, blockingLicenses);
+      }
+
+      return { passed: true, warnings, suppressed, licenseFindings };
+    },
+  };
+}
+
+/** Default `vuln-gate` capability (inject a real/mock scanner, or supply `findings`). */
+export const vulnGateCapability: Capability<VulnGateInput, VulnGateOutput> = createVulnGateCapability();

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

@@ -0,0 +1,145 @@
+/**
+ * Tests for #626's vulnerability scanning (./vuln-scan.ts): scanner output
+ * parsing, the real `ProcessRunner`-backed tool scanner (against a
+ * `MockProcessRunner` — never a live grype/trivy), and the
+ * `scan-vulnerabilities` capability over an injected scanner.
+ */
+
+import { describe, test, expect } from "vitest";
+import {
+  normalizeSeverity,
+  parseGrypeOutput,
+  parseTrivyOutput,
+  createToolVulnScanner,
+  createScanVulnerabilitiesCapability,
+  autoDetectVulnScanner,
+  type VulnFinding,
+  type VulnScanner,
+} from "./vuln-scan";
+import { ToolNotAvailableError } from "./process-runner";
+import type { SbomDocument } from "./sbom-generator";
+import { createMockProcessRunner } from "./__tests__/mock-process-runner";
+
+const ctx = { env: "prod", component: "search-service" };
+
+const SBOM: SbomDocument = {
+  format: "spdx",
+  mediaType: "application/spdx+json",
+  bytes: JSON.stringify({ packages: [{ name: "lodash", licenseConcluded: "MIT" }] }),
+  generator: "lockfile",
+};
+
+const GRYPE_JSON = JSON.stringify({
+  matches: [
+    {
+      vulnerability: { id: "CVE-2024-0001", severity: "Critical", fix: { versions: ["4.17.21"], state: "fixed" } },
+      artifact: { name: "lodash", version: "4.17.20" },
+    },
+    {
+      vulnerability: { id: "CVE-2024-0002", severity: "Low", fix: { versions: [], state: "not-fixed" } },
+      artifact: { name: "left-pad", version: "1.0.0" },
+    },
+  ],
+});
+
+describe("normalizeSeverity", () => {
+  test("normalizes case and maps unknowns to 'unknown'", () => {
+    expect(normalizeSeverity("Critical")).toBe("critical");
+    expect(normalizeSeverity("HIGH")).toBe("high");
+    expect(normalizeSeverity("Negligible")).toBe("negligible");
+    expect(normalizeSeverity("bananas")).toBe("unknown");
+    expect(normalizeSeverity(undefined)).toBe("unknown");
+  });
+});
+
+describe("parseGrypeOutput", () => {
+  test("maps matches to findings, deriving fixability", () => {
+    const findings = parseGrypeOutput(GRYPE_JSON);
+    expect(findings).toHaveLength(2);
+    expect(findings[0]).toEqual<VulnFinding>({
+      cveId: "CVE-2024-0001",
+      severity: "critical",
+      package: "lodash",
+      installedVersion: "4.17.20",
+      fixedVersion: "4.17.21",
+      fixable: true,
+    });
+    expect(findings[1].fixable).toBe(false);
+    expect(findings[1].severity).toBe("low");
+  });
+});
+
+describe("parseTrivyOutput", () => {
+  test("flattens Results[].Vulnerabilities into findings", () => {
+    const trivy = JSON.stringify({
+      Results: [
+        { Vulnerabilities: [{ VulnerabilityID: "CVE-2024-0003", Severity: "HIGH", PkgName: "openssl", InstalledVersion: "1.1.1", FixedVersion: "1.1.1w" }] },
+      ],
+    });
+    const findings = parseTrivyOutput(trivy);
+    expect(findings).toHaveLength(1);
+    expect(findings[0].cveId).toBe("CVE-2024-0003");
+    expect(findings[0].fixable).toBe(true);
+    expect(findings[0].fixedVersion).toBe("1.1.1w");
+  });
+});
+
+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 } });
+    const scanner = createToolVulnScanner("grype", mock.runner);
+    const findings = await scanner.scan({ sbom: SBOM, digest: "sha256:abc" });
+    expect(findings).toHaveLength(2);
+    const scanCall = mock.calls.find((c) => c.command.includes("grype sbom:"));
+    expect(scanCall).toBeDefined();
+    expect(scanCall!.command).toContain("-o json");
+  });
+
+  test("throws ToolNotAvailableError when grype is absent (never a silent empty scan)", async () => {
+    const mock = createMockProcessRunner({ tools: { grype: false }, defaultAvailable: false });
+    const scanner = createToolVulnScanner("grype", mock.runner);
+    await expect(scanner.scan({ sbom: SBOM })).rejects.toBeInstanceOf(ToolNotAvailableError);
+  });
+});
+
+describe("autoDetectVulnScanner — the registered default (#634)", () => {
+  const TRIVY_JSON = JSON.stringify({
+    Results: [{ Vulnerabilities: [{ VulnerabilityID: "CVE-2024-9999", Severity: "HIGH", PkgName: "lodash", InstalledVersion: "4.17.20", FixedVersion: "4.17.21" }] }],
+  });
+
+  test("prefers grype when present", async () => {
+    const mock = createMockProcessRunner({ tools: { grype: true, trivy: true }, responses: { "grype sbom:": GRYPE_JSON } });
+    const findings = await autoDetectVulnScanner(mock.runner).scan({ sbom: SBOM });
+    expect(findings).toHaveLength(2);
+    expect(mock.calls.some((c) => c.command.includes("grype sbom:"))).toBe(true);
+    expect(mock.calls.some((c) => c.command.includes("trivy sbom"))).toBe(false);
+  });
+
+  test("falls back to trivy when grype is absent", async () => {
+    const mock = createMockProcessRunner({ tools: { grype: false, trivy: true }, defaultAvailable: false, responses: { "trivy sbom": TRIVY_JSON } });
+    const findings = await autoDetectVulnScanner(mock.runner).scan({ sbom: SBOM });
+    expect(findings).toHaveLength(1);
+    expect(mock.calls.some((c) => c.command.includes("trivy sbom"))).toBe(true);
+  });
+
+  test("throws ToolNotAvailableError naming both tools when neither is installed (not VulnScannerNotImplementedError)", async () => {
+    const mock = createMockProcessRunner({ tools: { grype: false, trivy: false }, defaultAvailable: false });
+    await expect(autoDetectVulnScanner(mock.runner).scan({ sbom: SBOM })).rejects.toBeInstanceOf(ToolNotAvailableError);
+    await expect(autoDetectVulnScanner(mock.runner).scan({ sbom: SBOM })).rejects.toThrow(/grype or trivy/);
+  });
+});
+
+describe("scan-vulnerabilities capability", () => {
+  test("returns the scanner's findings and echoes the digest", async () => {
+    const fake: VulnScanner = {
+      async scan() {
+        return parseGrypeOutput(GRYPE_JSON);
+      },
+    };
+    const cap = createScanVulnerabilitiesCapability(fake);
+    expect(cap.kind).toBe("scan-vulnerabilities");
+    const out = await cap.run(ctx, { sbom: SBOM, digest: "sha256:xyz" });
+    expect(out.findings).toHaveLength(2);
+    expect(out.digest).toBe("sha256:xyz");
+  });
+});

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

@@ -0,0 +1,266 @@
+/**
+ * Vulnerability scanning of an already-generated SBOM (#626, epic #551
+ * supply-chain follow-up to the SBOM stack #606/#613/#614/#609/#610). An SBOM
+ * says *what's in* an artifact; a scanner says *which of those have known
+ * CVEs*. This module produces findings; ./vex.ts suppresses the ones that
+ * don't matter and ./vuln-gate.ts fails the deploy on the ones that do.
+ *
+ * Prefer scanning the **SBOM** (already generated + persisted, keyed by
+ * digest) over re-scanning the image: deterministic (same SBOM -> same
+ * findings), fast, and reuses work already done. Real backends shell out to
+ * `grype`/`trivy` through the injectable `ProcessRunner` (./process-runner.ts),
+ * exactly like ./tool-sbom-generator.ts's deep-scan backend — tests inject a
+ * `MockVulnScanner` (./__tests__/mock-vuln-scanner.ts) and never invoke a real
+ * scanner, network, or vuln DB. The scanner's vuln DB currency is the tool's
+ * job, not chant's.
+ */
+
+import { writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import type { Capability } from "../capability";
+import type { SbomDocument } from "./sbom-generator";
+import { defaultProcessRunner, q, requireTool, ToolNotAvailableError, type ProcessRunner } from "./process-runner";
+
+// ── findings ─────────────────────────────────────────────────────────────────
+
+/** CVE severity, highest to lowest. `unknown` sorts lowest so it never trips a threshold gate by accident. */
+export type Severity = "critical" | "high" | "medium" | "low" | "negligible" | "unknown";
+
+/** Severity rank (higher = more severe) so a gate can ask "severity >= critical". */
+export const SEVERITY_RANK: Record<Severity, number> = {
+  critical: 5,
+  high: 4,
+  medium: 3,
+  low: 2,
+  negligible: 1,
+  unknown: 0,
+};
+
+/** Normalize a scanner's free-form severity string ("High", "CRITICAL", "Negligible", …) to a `Severity`. Unrecognized -> `unknown`. */
+export function normalizeSeverity(raw: string | undefined): Severity {
+  const s = (raw ?? "").toLowerCase();
+  if (s === "critical" || s === "high" || s === "medium" || s === "low" || s === "negligible") return s;
+  return "unknown";
+}
+
+/** One known vulnerability affecting one package in the scanned artifact. */
+export interface VulnFinding {
+  /** Advisory id, e.g. `"CVE-2024-12345"` or `"GHSA-…"` — the join key with VEX statements (./vex.ts). */
+  cveId: string;
+  severity: Severity;
+  /** Affected package name. */
+  package: string;
+  installedVersion: string;
+  /** First version that fixes it, when the scanner reports one. */
+  fixedVersion?: string;
+  /** True when a fix exists (upgradeable) — the beginner-safe default gate blocks only fixable findings, since an unfixable one can't be actioned by bumping. */
+  fixable: boolean;
+}
+
+// ── injectable scanner boundary ──────────────────────────────────────────────
+
+export interface ScanInput {
+  /** The SBOM to scan (the artifact's already-generated SPDX/CycloneDX doc). */
+  sbom: SbomDocument;
+  /** Artifact digest the SBOM belongs to — informational, for logging/keying. */
+  digest?: string;
+}
+
+/**
+ * Injectable vulnerability-scan boundary — the scan-side analogue of
+ * `SbomGenerator` (./sbom-generator.ts) and `CloudExecutor`
+ * (./cloud-executor.ts). A real implementation shells out to `grype`/`trivy`;
+ * tests substitute `MockVulnScanner` (./__tests__/mock-vuln-scanner.ts) and
+ * never touch a real tool, network, or vuln DB.
+ */
+export interface VulnScanner {
+  /** Scan an SBOM, returning every known vulnerability it surfaces. */
+  scan(input: ScanInput): Promise<VulnFinding[]>;
+}
+
+/** Which real CLI scanner a `ProcessRunner`-backed scanner shells out to. */
+export type ScannerTool = "grype" | "trivy";
+
+/** grype `-o json` output shape (the subset we read). */
+interface GrypeOutput {
+  matches?: Array<{
+    vulnerability?: { id?: string; severity?: string; fix?: { versions?: string[]; state?: string } };
+    artifact?: { name?: string; version?: string };
+  }>;
+}
+
+/** trivy `--format json` output shape (the subset we read). */
+interface TrivyOutput {
+  Results?: Array<{
+    Vulnerabilities?: Array<{
+      VulnerabilityID?: string;
+      Severity?: string;
+      PkgName?: string;
+      InstalledVersion?: string;
+      FixedVersion?: string;
+    }>;
+  }>;
+}
+
+/** Parse `grype -o json` stdout into findings. Exported for tests to assert parsing without a live tool. */
+export function parseGrypeOutput(stdout: string): VulnFinding[] {
+  const doc = JSON.parse(stdout) as GrypeOutput;
+  return (doc.matches ?? []).map((m) => {
+    const fixVersions = m.vulnerability?.fix?.versions ?? [];
+    return {
+      cveId: m.vulnerability?.id ?? "UNKNOWN",
+      severity: normalizeSeverity(m.vulnerability?.severity),
+      package: m.artifact?.name ?? "unknown",
+      installedVersion: m.artifact?.version ?? "",
+      fixedVersion: fixVersions[0],
+      fixable: m.vulnerability?.fix?.state === "fixed" || fixVersions.length > 0,
+    } satisfies VulnFinding;
+  });
+}
+
+/** Parse `trivy sbom --format json` stdout into findings. */
+export function parseTrivyOutput(stdout: string): VulnFinding[] {
+  const doc = JSON.parse(stdout) as TrivyOutput;
+  const out: VulnFinding[] = [];
+  for (const r of doc.Results ?? []) {
+    for (const v of r.Vulnerabilities ?? []) {
+      out.push({
+        cveId: v.VulnerabilityID ?? "UNKNOWN",
+        severity: normalizeSeverity(v.Severity),
+        package: v.PkgName ?? "unknown",
+        installedVersion: v.InstalledVersion ?? "",
+        fixedVersion: v.FixedVersion || undefined,
+        fixable: Boolean(v.FixedVersion),
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * A real `VulnScanner` that writes the SBOM to a temp file and scans it with
+ * `grype` (default) or `trivy`, through the injectable `ProcessRunner`.
+ * `requireTool` throws `ToolNotAvailableError` if the scanner is absent — a
+ * missing scanner is a hard stop (like ./verify.ts's missing `cosign`), never
+ * a silent "no vulns found," because that would let an unscanned artifact
+ * through a gate. Never used in tests.
+ */
+export function createToolVulnScanner(
+  tool: ScannerTool = "grype",
+  processRunner: ProcessRunner = defaultProcessRunner(),
+): VulnScanner {
+  return {
+    async scan(input) {
+      await requireTool(processRunner, tool, `scan the SBOM for known vulnerabilities`);
+      // Content-address the temp file so concurrent scans never collide and we
+      // avoid Date.now()/Math.random() (blocked in some chant runtimes).
+      const hash = createHash("sha256").update(input.sbom.bytes).digest("hex").slice(0, 16);
+      const ext = input.sbom.format === "cyclonedx" ? "cdx.json" : "spdx.json";
+      const path = join(tmpdir(), `chant-scan-${hash}.${ext}`);
+      writeFileSync(path, input.sbom.bytes);
+      if (tool === "trivy") {
+        const { stdout } = await processRunner.run(`trivy sbom --quiet --format json ${q(path)}`);
+        return parseTrivyOutput(stdout);
+      }
+      const { stdout } = await processRunner.run(`grype sbom:${q(path)} -o json`);
+      return parseGrypeOutput(stdout);
+    },
+  };
+}
+
+/**
+ * Thrown by `notImplementedVulnScanner` — the "no real scanner wired yet"
+ * signal, mirroring `SbomGeneratorNotImplementedError` (./sbom-generator.ts).
+ * The default is loud-and-specific rather than a silent empty scan, so a
+ * caller that forgets to inject a scanner (or a mock in tests) fails obviously
+ * instead of appearing to find zero vulnerabilities.
+ */
+export class VulnScannerNotImplementedError extends Error {
+  constructor() {
+    super(
+      `VulnScanner has no real scanner configured — inject a real scanner ` +
+        `(createToolVulnScanner("grype"|"trivy")) or a mock in tests`,
+    );
+    this.name = "VulnScannerNotImplementedError";
+  }
+}
+
+/** Kept for tests and for a caller that wants the old loud "no scanner wired" behavior; no longer the registered default (#634). */
+export const notImplementedVulnScanner: VulnScanner = {
+  async scan() {
+    throw new VulnScannerNotImplementedError();
+  },
+};
+
+/**
+ * A `VulnScanner` that picks a real backend at scan time — `grype` if present,
+ * else `trivy`. Unlike SBOM generation there is no hermetic fallback (a scan
+ * needs a real vuln DB), so when neither tool is on `PATH` this throws a
+ * `ToolNotAvailableError` naming what to install — an error a config-only user
+ * can act on — rather than `VulnScannerNotImplementedError`, which told them to
+ * edit code. This is the vuln-side analog of #630's hermetic-by-default SBOM
+ * generator: the registered `scan-vulnerabilities`/`vuln-gate` capabilities now
+ * work the moment a scanner is installed, with no code wiring.
+ */
+export function autoDetectVulnScanner(processRunner: ProcessRunner = defaultProcessRunner()): VulnScanner {
+  return {
+    async scan(input) {
+      const tool: ScannerTool | undefined = (await processRunner.available("grype"))
+        ? "grype"
+        : (await processRunner.available("trivy"))
+          ? "trivy"
+          : undefined;
+      if (!tool) {
+        throw new ToolNotAvailableError("grype or trivy", "scan the SBOM for known vulnerabilities");
+      }
+      return createToolVulnScanner(tool, processRunner).scan(input);
+    },
+  };
+}
+
+let defaultScanner: VulnScanner | undefined;
+
+/** The default `VulnScanner` the `scan-vulnerabilities`/`vuln-gate` capabilities fall back to when none is supplied: auto-detects `grype`/`trivy` and throws `ToolNotAvailableError` if neither is installed (#634). */
+export function defaultVulnScanner(): VulnScanner {
+  if (!defaultScanner) defaultScanner = autoDetectVulnScanner();
+  return defaultScanner;
+}
+
+// ── scan-vulnerabilities capability ──────────────────────────────────────────
+
+export interface ScanVulnerabilitiesInput {
+  /** The SBOM to scan. */
+  sbom: SbomDocument;
+  /** Artifact digest the SBOM belongs to (recorded on the output). */
+  digest?: string;
+}
+
+export interface ScanVulnerabilitiesOutput {
+  findings: VulnFinding[];
+  /** Echoed back so a downstream `vuln-gate` step can key results to the artifact. */
+  digest?: string;
+}
+
+/**
+ * `scan-vulnerabilities` capability — scan an SBOM for known CVEs via the
+ * injectable `VulnScanner`. Produces findings only; suppression (VEX) and the
+ * pass/fail decision live in ./vuln-gate.ts, so a composition can scan once
+ * and reuse the findings, or run the gate directly (which scans for you).
+ */
+export function createScanVulnerabilitiesCapability(
+  scanner: VulnScanner = defaultVulnScanner(),
+): Capability<ScanVulnerabilitiesInput, ScanVulnerabilitiesOutput> {
+  return {
+    kind: "scan-vulnerabilities",
+    async run(_ctx, input) {
+      const findings = await scanner.scan({ sbom: input.sbom, digest: input.digest });
+      return { findings, digest: input.digest };
+    },
+  };
+}
+
+/** Default `scan-vulnerabilities` capability, backed by the not-implemented scanner (inject a real/mock one). */
+export const scanVulnerabilitiesCapability: Capability<ScanVulnerabilitiesInput, ScanVulnerabilitiesOutput> =
+  createScanVulnerabilitiesCapability();