@intentius/chant 0.13.1 → 0.15.0

package/src/components/verbs/verify.ts

@@ -0,0 +1,179 @@
+/**
+ * `verify` capability — the deploy-time signature/provenance gate (#622,
+ * epic #551 follow-up to ./sign.ts's keyless signing + SLSA attestation).
+ * Mirrors `../../lint/policy.ts`'s `policyGate` shape: a step that runs
+ * `cosign verify` (+ `cosign verify-attestation` for provenance) against a
+ * configured identity policy and **throws** on any failure, so composing it
+ * before an apply phase fails the deploy the same way a thrown capability
+ * error already halts `driver.ts`'s step execution — no new failure
+ * mechanism, no gate-signal/human-approval semantics (that is `Gate`,
+ * ../component.ts, a different, durable-runtime-only concept). `verify` is a
+ * synchronous, local-executor-safe capability, exactly like `health-gate`
+ * (./wait-verify.ts).
+ *
+ * **Beginner-safe default policy.** The minimum an identity policy must
+ * declare is `expectedIssuer` + `expectedIdentity` (the OIDC issuer/identity
+ * that must have signed) — "signature present + from the expected identity."
+ * There is no "verify but accept any identity" mode: an identity-less verify
+ * would defeat the point of keyless signing (anyone's Rekor-logged signature
+ * would pass), so `IdentityPolicy` requires both fields, not an optional
+ * pair a beginner could forget to set.
+ *
+ * Routes `cosign verify`/`cosign verify-attestation` through the injectable
+ * `ProcessRunner` (./process-runner.ts), mirroring every other #610/#622
+ * real backend: `requireTool` throws `ToolNotAvailableError` if `cosign` is
+ * absent (a missing verifier is a hard stop, never a silent pass — the
+ * opposite failure mode from ./publish.ts's best-effort referrer attach,
+ * because skipping verification on a missing tool would silently let an
+ * unsigned/wrongly-signed artifact through the gate).
+ */
+
+import type { Capability } from "../capability";
+import { defaultProcessRunner, q, requireTool, type ProcessRunner } from "./process-runner";
+
+// ── identity policy ──────────────────────────────────────────────────────────
+
+/**
+ * The configured identity an artifact's signature/provenance must match —
+ * "beginner-safe default" per #622: signature present + from the expected
+ * identity, nothing more exotic required out of the box. Both fields are
+ * required (see this module's doc comment for why an identity-less verify
+ * is not offered).
+ */
+export interface IdentityPolicy {
+  /** Expected OIDC issuer, e.g. `"https://token.actions.githubusercontent.com"` for GitHub Actions keyless signing. Passed to `cosign verify --certificate-oidc-issuer`. */
+  expectedIssuer: string;
+  /**
+   * Expected signer identity. For keyless CI signing this is typically the
+   * workflow identity URI cosign embeds in the Fulcio cert (e.g.
+   * `"https://github.com/my-org/my-repo/.github/workflows/release.yml@refs/heads/main"`).
+   * Passed to `cosign verify --certificate-identity`. Supports the same
+   * `--certificate-identity-regexp` escape hatch via `identityIsRegexp`
+   * below, for teams whose identity varies by branch/tag and want one policy
+   * to match a pattern rather than enumerating every literal ref.
+   */
+  expectedIdentity: string;
+  /** Treat `expectedIdentity` as a regexp (`cosign verify --certificate-identity-regexp`) instead of a literal match. Default: false. */
+  identityIsRegexp?: boolean;
+  /** Optional key-based override — verify against a public key instead of the keyless identity policy, mirroring ./sign.ts's opt-in key-based override. Not the default. */
+  key?: string;
+}
+
+// ── verify (signature gate) ──────────────────────────────────────────────────
+
+export interface VerifyInput {
+  /** Digest-qualified image reference to verify, e.g. `"@Publish.uri"`/`"@Sign.imageRef"`. */
+  imageRef: string;
+  /** The identity policy the signature must satisfy. */
+  policy: IdentityPolicy;
+  /** Also verify the SLSA provenance attestation (`cosign verify-attestation --type slsaprovenance1`) alongside the signature. Default: true — both #622 outputs are expected present once `sign`+`attest-provenance` have run. */
+  requireProvenance?: boolean;
+}
+
+export interface VerifyOutput {
+  /** True once every requested check (signature, and provenance if requested) passed. Always `true` when returned — a failure throws instead, so a caller never has to remember to check this field; it exists for symmetry with other capability outputs and for logging. */
+  verified: true;
+  /** Which checks actually ran and passed. */
+  checked: Array<"signature" | "provenance">;
+}
+
+/**
+ * Thrown when `cosign verify`/`cosign verify-attestation` rejects — wrong
+ * identity, missing signature, tampered artifact, or any other verification
+ * failure `cosign` itself reports. Distinct from `ToolNotAvailableError` so a
+ * caller (and a test) can tell "cosign said no" apart from "cosign isn't
+ * installed." Carries `reason` (cosign's own stderr/message) for whoever is
+ * debugging a failed gate.
+ */
+export class VerificationFailedError extends Error {
+  constructor(
+    public readonly imageRef: string,
+    public readonly check: "signature" | "provenance",
+    public readonly reason: string,
+  ) {
+    super(`verify "${imageRef}": ${check} verification failed — ${reason}`);
+    this.name = "VerificationFailedError";
+  }
+}
+
+/** Append the shared identity-policy flags to a `cosign verify`/`verify-attestation` argv, mutating `args` in place — kept in one place so `verify`'s two checks can never drift apart on how the policy is expressed. */
+function appendPolicyFlags(args: string[], policy: IdentityPolicy): void {
+  if (policy.key) {
+    args.push("--key", q(policy.key));
+    return;
+  }
+  args.push("--certificate-oidc-issuer", q(policy.expectedIssuer));
+  args.push(policy.identityIsRegexp ? "--certificate-identity-regexp" : "--certificate-identity", q(policy.expectedIdentity));
+}
+
+/** Build the `cosign verify` argv (as a shell command string) for `input` — factored out so tests can assert on the exact invocation. */
+export function buildVerifySignatureArgs(input: VerifyInput): string {
+  const args = ["cosign", "verify"];
+  appendPolicyFlags(args, input.policy);
+  args.push(q(input.imageRef));
+  return args.join(" ");
+}
+
+/** Build the `cosign verify-attestation` argv (as a shell command string) for `input`. */
+export function buildVerifyAttestationArgs(input: VerifyInput): string {
+  const args = ["cosign", "verify-attestation", "--type", "slsaprovenance1"];
+  appendPolicyFlags(args, input.policy);
+  args.push(q(input.imageRef));
+  return args.join(" ");
+}
+
+/**
+ * Gate a deploy on `cosign verify` (signature) + `cosign verify-attestation`
+ * (SLSA provenance, unless `requireProvenance: false`) against `input.policy`
+ * — the digest-anchored counterpart to `../../lint/policy.ts`'s
+ * organizational-policy `policyGate`. Throws `VerificationFailedError` on any
+ * failed check, which halts the composition the same way any other thrown
+ * capability error does (see ../driver.ts) — no separate "gate" plumbing
+ * needed; a `verify` step composed before an `Apply` phase blocks that phase
+ * from ever running on verification failure.
+ *
+ * No rollback: verification is read-only observation of already-published
+ * evidence, nothing to compensate — same reasoning as `health-gate`/`wait-*`
+ * (./wait-verify.ts).
+ */
+export function createVerifyCapability(
+  processRunner: ProcessRunner = defaultProcessRunner(),
+): Capability<VerifyInput, VerifyOutput> {
+  return {
+    kind: "verify",
+    async run(_ctx, input) {
+      await requireTool(processRunner, "cosign", `verify ${input.imageRef} against the configured identity policy`);
+
+      const checked: Array<"signature" | "provenance"> = [];
+
+      try {
+        await processRunner.run(buildVerifySignatureArgs(input));
+      } catch (err) {
+        throw new VerificationFailedError(
+          input.imageRef,
+          "signature",
+          err instanceof Error ? err.message : String(err),
+        );
+      }
+      checked.push("signature");
+
+      if (input.requireProvenance !== false) {
+        try {
+          await processRunner.run(buildVerifyAttestationArgs(input));
+        } catch (err) {
+          throw new VerificationFailedError(
+            input.imageRef,
+            "provenance",
+            err instanceof Error ? err.message : String(err),
+          );
+        }
+        checked.push("provenance");
+      }
+
+      return { verified: true, checked };
+    },
+  };
+}
+
+/** Default `verify` capability, backed by the real `ProcessRunner`. */
+export const verifyCapability: Capability<VerifyInput, VerifyOutput> = createVerifyCapability();

package/src/components/verbs/vex.ts

@@ -0,0 +1,182 @@
+/**
+ * VEX (Vulnerability Exploitability eXchange) ingestion + suppression (#626).
+ * A scanner (./vuln-scan.ts) flags every known CVE in an SBOM, but most aren't
+ * actually exploitable in context (unreachable code path, already mitigated,
+ * false positive). VEX is where you (or upstream) assert, per CVE, whether it
+ * *actually* affects this artifact. Without it a gate is CVE fatigue — 500
+ * findings, 5 that matter. This module parses VEX and filters findings, and it
+ * **reports** every suppression with its justification — a VEX-suppressed
+ * finding is never silently dropped.
+ *
+ * Two formats: **OpenVEX** (the standalone Sigstore/OpenSSF format) and
+ * **CycloneDX**-embedded VEX (`vulnerabilities[].analysis`). Both reduce to the
+ * same `VexStatement` shape here.
+ */
+
+import type { VulnFinding } from "./vuln-scan";
+
+/** VEX status for a CVE against an artifact. `not_affected`/`fixed` suppress a finding; `affected`/`under_investigation` keep it (conservative — an unresolved status must not hide a real vuln). */
+export type VexStatus = "not_affected" | "affected" | "fixed" | "under_investigation";
+
+/** True for statuses that suppress a matching finding from gating. */
+export function suppresses(status: VexStatus): boolean {
+  return status === "not_affected" || status === "fixed";
+}
+
+/** One VEX assertion: this CVE has this status for this artifact, with an optional human justification. */
+export interface VexStatement {
+  cveId: string;
+  status: VexStatus;
+  /** Why — e.g. `"vulnerable_code_not_in_execute_path"`, `"component_not_present"`. Surfaced on the suppression report so a reviewer sees the reasoning, never a bare "suppressed." */
+  justification?: string;
+}
+
+// ── OpenVEX ──────────────────────────────────────────────────────────────────
+
+interface OpenVexDoc {
+  statements?: Array<{
+    // OpenVEX allows `vulnerability` as either a string or an object with `name`.
+    vulnerability?: string | { name?: string; "@id"?: string };
+    status?: string;
+    justification?: string;
+    impact_statement?: string;
+    action_statement?: string;
+  }>;
+}
+
+function vexStatusFrom(raw: string | undefined): VexStatus | undefined {
+  switch ((raw ?? "").toLowerCase()) {
+    case "not_affected":
+      return "not_affected";
+    case "affected":
+      return "affected";
+    case "fixed":
+      return "fixed";
+    case "under_investigation":
+      return "under_investigation";
+    default:
+      return undefined;
+  }
+}
+
+/** Parse an OpenVEX JSON document into statements. Unknown statuses / statements missing a vulnerability id are skipped. */
+export function parseOpenVex(bytes: string): VexStatement[] {
+  const doc = JSON.parse(bytes) as OpenVexDoc;
+  const out: VexStatement[] = [];
+  for (const s of doc.statements ?? []) {
+    const cveId = typeof s.vulnerability === "string" ? s.vulnerability : (s.vulnerability?.name ?? s.vulnerability?.["@id"]);
+    const status = vexStatusFrom(s.status);
+    if (!cveId || !status) continue;
+    out.push({ cveId, status, justification: s.justification ?? s.impact_statement });
+  }
+  return out;
+}
+
+// ── CycloneDX-embedded VEX ───────────────────────────────────────────────────
+
+interface CycloneDxVexDoc {
+  vulnerabilities?: Array<{
+    id?: string;
+    analysis?: { state?: string; detail?: string; justification?: string };
+  }>;
+}
+
+/** Map CycloneDX `analysis.state` to a `VexStatus`. */
+function cdxStateToVex(state: string | undefined): VexStatus | undefined {
+  switch ((state ?? "").toLowerCase()) {
+    case "not_affected":
+    case "false_positive":
+      return "not_affected";
+    case "resolved":
+    case "resolved_with_pedigree":
+      return "fixed";
+    case "exploitable":
+      return "affected";
+    case "in_triage":
+      return "under_investigation";
+    default:
+      return undefined;
+  }
+}
+
+/** Parse CycloneDX-embedded VEX (`vulnerabilities[].analysis`) into statements. */
+export function parseCycloneDxVex(bytes: string): VexStatement[] {
+  const doc = JSON.parse(bytes) as CycloneDxVexDoc;
+  const out: VexStatement[] = [];
+  for (const v of doc.vulnerabilities ?? []) {
+    const status = cdxStateToVex(v.analysis?.state);
+    if (!v.id || !status) continue;
+    out.push({ cveId: v.id, status, justification: v.analysis?.justification ?? v.analysis?.detail });
+  }
+  return out;
+}
+
+/**
+ * Parse a VEX document of either format — dispatched on shape (`statements` ->
+ * OpenVEX, `vulnerabilities` -> CycloneDX). A malformed/unparseable document
+ * yields NO statements (returns `[]`) rather than throwing: it therefore
+ * suppresses nothing, keeping the gate strict (fail-closed) instead of
+ * crashing on attacker- or typo-supplied input.
+ */
+export function parseVexDocument(bytes: string): VexStatement[] {
+  let doc: OpenVexDoc & CycloneDxVexDoc;
+  try {
+    doc = JSON.parse(bytes) as OpenVexDoc & CycloneDxVexDoc;
+  } catch {
+    return [];
+  }
+  if (Array.isArray(doc.statements)) return parseOpenVex(bytes);
+  if (Array.isArray(doc.vulnerabilities)) return parseCycloneDxVex(bytes);
+  return [];
+}
+
+// ── applying VEX to findings ─────────────────────────────────────────────────
+
+/** A finding removed from gating by a VEX statement, kept for reporting (never silently dropped). */
+export interface SuppressedFinding {
+  finding: VulnFinding;
+  status: VexStatus;
+  justification?: string;
+}
+
+/** The result of filtering findings through VEX: what still gates, and what was suppressed (with reasons). */
+export interface VexResult {
+  /** Findings that survived VEX — the gate evaluates these. */
+  gating: VulnFinding[];
+  /** Findings suppressed by a `not_affected`/`fixed` statement, with the statement's justification. */
+  suppressed: SuppressedFinding[];
+}
+
+/**
+ * Filter `findings` through `statements`. A finding is suppressed only when
+ * some statement for its CVE suppresses it (`not_affected`/`fixed`) AND **no**
+ * statement for that CVE asserts it is `affected`/`under_investigation`.
+ *
+ * This is the conservative merge, deliberately NOT "last statement wins":
+ * when VEX comes from several sources (repo-local files + referrer-attached),
+ * a later `not_affected` must not be able to override an earlier `affected` to
+ * unblock a real vulnerability. Merging VEX can only ever make the gate
+ * *stricter*, never quietly weaker — so an attacker who can append a statement
+ * cannot suppress a finding another source flagged as affected.
+ */
+export function applyVex(findings: VulnFinding[], statements: VexStatement[]): VexResult {
+  const byCve = new Map<string, VexStatement[]>();
+  for (const s of statements) {
+    const list = byCve.get(s.cveId);
+    if (list) list.push(s);
+    else byCve.set(s.cveId, [s]);
+  }
+  const gating: VulnFinding[] = [];
+  const suppressed: SuppressedFinding[] = [];
+  for (const f of findings) {
+    const list = byCve.get(f.cveId) ?? [];
+    const contested = list.some((s) => s.status === "affected" || s.status === "under_investigation");
+    const suppressor = contested ? undefined : list.find((s) => suppresses(s.status));
+    if (suppressor) {
+      suppressed.push({ finding: f, status: suppressor.status, justification: suppressor.justification });
+    } else {
+      gating.push(f);
+    }
+  }
+  return { gating, suppressed };
+}

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

@@ -0,0 +1,201 @@
+/**
+ * Tests for #626's VEX suppression (./vex.ts), license policy
+ * (./license-policy.ts), the `vuln-gate` capability (./vuln-gate.ts), and the
+ * `vulnPolicy` config resolver (../../config.ts). All hermetic: the gate runs
+ * over supplied findings or an inline fake scanner — no live scanner, network,
+ * or vuln DB.
+ */
+
+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 type { VulnFinding, VulnScanner } from "./vuln-scan";
+import type { SbomDocument } from "./sbom-generator";
+import { resolveVulnPolicy } from "../../config";
+
+const ctx = { env: "prod", component: "search-service" };
+
+const CRIT_FIXABLE: VulnFinding = { cveId: "CVE-1", severity: "critical", package: "a", installedVersion: "1", fixedVersion: "2", fixable: true };
+const CRIT_UNFIXABLE: VulnFinding = { cveId: "CVE-2", severity: "critical", package: "b", installedVersion: "1", fixable: false };
+const HIGH_FIXABLE: VulnFinding = { cveId: "CVE-3", severity: "high", package: "c", installedVersion: "1", fixedVersion: "2", fixable: true };
+
+const SBOM_SPDX: SbomDocument = {
+  format: "spdx",
+  mediaType: "application/spdx+json",
+  bytes: JSON.stringify({ packages: [{ name: "gpl-lib", licenseConcluded: "GPL-3.0" }, { name: "mit-lib", licenseConcluded: "MIT" }, { name: "no-lic", licenseConcluded: "NOASSERTION" }] }),
+  generator: "lockfile",
+};
+
+// ── VEX ──────────────────────────────────────────────────────────────────────
+
+describe("VEX parsing", () => {
+  test("parseOpenVex handles vulnerability as string and as object", () => {
+    const doc = JSON.stringify({
+      statements: [
+        { vulnerability: "CVE-1", status: "not_affected", justification: "vulnerable_code_not_in_execute_path" },
+        { vulnerability: { name: "CVE-3" }, status: "affected" },
+      ],
+    });
+    const stmts = parseOpenVex(doc);
+    expect(stmts).toHaveLength(2);
+    expect(stmts[0]).toEqual({ cveId: "CVE-1", status: "not_affected", justification: "vulnerable_code_not_in_execute_path" });
+    expect(stmts[1].status).toBe("affected");
+  });
+
+  test("parseCycloneDxVex maps analysis.state", () => {
+    const doc = JSON.stringify({
+      vulnerabilities: [
+        { id: "CVE-1", analysis: { state: "not_affected", justification: "code_not_reachable" } },
+        { id: "CVE-9", analysis: { state: "resolved" } },
+      ],
+    });
+    const stmts = parseCycloneDxVex(doc);
+    expect(stmts[0].status).toBe("not_affected");
+    expect(stmts[1].status).toBe("fixed");
+  });
+
+  test("parseVexDocument dispatches on shape", () => {
+    expect(parseVexDocument(JSON.stringify({ statements: [{ vulnerability: "CVE-1", status: "fixed" }] }))[0].status).toBe("fixed");
+    expect(parseVexDocument(JSON.stringify({ vulnerabilities: [{ id: "CVE-1", analysis: { state: "exploitable" } }] }))[0].status).toBe("affected");
+  });
+
+  test("applyVex suppresses not_affected/fixed, keeps affected, reports justification", () => {
+    const { gating, suppressed } = applyVex(
+      [CRIT_FIXABLE, HIGH_FIXABLE],
+      [{ cveId: "CVE-1", status: "not_affected", justification: "not reachable" }],
+    );
+    expect(gating.map((f) => f.cveId)).toEqual(["CVE-3"]);
+    expect(suppressed).toHaveLength(1);
+    expect(suppressed[0].justification).toBe("not reachable");
+  });
+});
+
+// ── licenses ─────────────────────────────────────────────────────────────────
+
+describe("license policy", () => {
+  test("extractLicenses reads SPDX and CycloneDX", () => {
+    expect(extractLicenses(SBOM_SPDX).find((l) => l.package === "gpl-lib")?.license).toBe("GPL-3.0");
+    const cdx: SbomDocument = {
+      format: "cyclonedx",
+      mediaType: "application/vnd.cyclonedx+json",
+      bytes: JSON.stringify({ components: [{ name: "x", licenses: [{ license: { id: "Apache-2.0" } }] }] }),
+      generator: "lockfile",
+    };
+    expect(extractLicenses(cdx)[0].license).toBe("Apache-2.0");
+  });
+
+  test("deny flags a denied license; NOASSERTION is skipped", () => {
+    const violations = evaluateLicensePolicy(SBOM_SPDX, { deny: ["GPL-3.0"] });
+    expect(violations).toHaveLength(1);
+    expect(violations[0]).toEqual({ package: "gpl-lib", license: "GPL-3.0", reason: "denied" });
+  });
+
+  test("allowlist flags anything not on it (case-insensitive)", () => {
+    const violations = evaluateLicensePolicy(SBOM_SPDX, { allow: ["mit"] });
+    expect(violations.map((v) => v.package)).toEqual(["gpl-lib"]);
+    expect(violations[0].reason).toBe("not-allowed");
+  });
+});
+
+// ── the gate ─────────────────────────────────────────────────────────────────
+
+function gate(input: VulnGateInput) {
+  return createVulnGateCapability().run(ctx, input);
+}
+
+describe("vuln-gate", () => {
+  test("passes on a clean set, reporting high findings as warnings (default policy)", async () => {
+    const out = await gate({ sbom: SBOM_SPDX, findings: [HIGH_FIXABLE] });
+    expect(out.passed).toBe(true);
+    expect(out.warnings.map((f) => f.cveId)).toEqual(["CVE-3"]);
+  });
+
+  test("FAILS on an unsuppressed critical + fixable finding", async () => {
+    await expect(gate({ sbom: SBOM_SPDX, findings: [CRIT_FIXABLE] })).rejects.toBeInstanceOf(VulnGateFailedError);
+  });
+
+  test("a VEX not_affected statement suppresses the blocking finding (gate passes)", async () => {
+    const vex = JSON.stringify({ statements: [{ vulnerability: "CVE-1", status: "not_affected", justification: "not reachable" }] });
+    const out = await gate({ sbom: SBOM_SPDX, findings: [CRIT_FIXABLE], vex: [vex] });
+    expect(out.passed).toBe(true);
+    expect(out.suppressed[0].finding.cveId).toBe("CVE-1");
+  });
+
+  test("critical but NOT fixable does not block under the default fixableOnly, it warns", async () => {
+    const out = await gate({ sbom: SBOM_SPDX, findings: [CRIT_UNFIXABLE], policy: { warnSeverity: "critical" } });
+    expect(out.passed).toBe(true);
+    expect(out.warnings.map((f) => f.cveId)).toEqual(["CVE-2"]);
+  });
+
+  test("license: report-only by default (no block), blocks when failOnLicense", async () => {
+    const reportOnly = await gate({ sbom: SBOM_SPDX, findings: [], policy: { license: { deny: ["GPL-3.0"] } } });
+    expect(reportOnly.passed).toBe(true);
+    expect(reportOnly.licenseFindings).toHaveLength(1);
+
+    await expect(
+      gate({ sbom: SBOM_SPDX, findings: [], policy: { license: { deny: ["GPL-3.0"] }, failOnLicense: true } }),
+    ).rejects.toBeInstanceOf(VulnGateFailedError);
+  });
+
+  test("scans via the injected scanner when findings are not supplied", async () => {
+    const fake: VulnScanner = { async scan() { return [CRIT_FIXABLE]; } };
+    await expect(createVulnGateCapability(fake).run(ctx, { sbom: SBOM_SPDX })).rejects.toBeInstanceOf(VulnGateFailedError);
+  });
+});
+
+// ── audit hardening (#628) ───────────────────────────────────────────────────
+
+describe("audit hardening (#628)", () => {
+  const CRIT: VulnFinding = { cveId: "CVE-X", severity: "critical", package: "p", installedVersion: "1", fixedVersion: "2", fixable: true };
+  const UNKNOWN: VulnFinding = { cveId: "CVE-U", severity: "unknown", package: "q", installedVersion: "1", fixable: true };
+
+  test("VEX conservative merge: an `affected` statement blocks a later `not_affected` from suppressing", () => {
+    const { gating, suppressed } = applyVex(
+      [CRIT],
+      [
+        { cveId: "CVE-X", status: "affected" },
+        { cveId: "CVE-X", status: "not_affected", justification: "attacker-appended" },
+      ],
+    );
+    expect(gating.map((f) => f.cveId)).toEqual(["CVE-X"]);
+    expect(suppressed).toHaveLength(0);
+  });
+
+  test("malformed VEX does not crash and suppresses nothing (gate stays strict)", async () => {
+    await expect(gate({ sbom: SBOM_SPDX, findings: [CRIT], vex: ['{"bad json'] })).rejects.toBeInstanceOf(VulnGateFailedError);
+  });
+
+  test("SPDX license expression: deny matches a license hidden in an OR expression", () => {
+    const sbom: SbomDocument = {
+      format: "spdx",
+      mediaType: "application/spdx+json",
+      generator: "lockfile",
+      bytes: JSON.stringify({ packages: [{ name: "z", licenseConcluded: "GPL-3.0 OR MIT" }] }),
+    };
+    const v = evaluateLicensePolicy(sbom, { deny: ["GPL-3.0"] });
+    expect(v).toHaveLength(1);
+    expect(v[0].package).toBe("z");
+  });
+
+  test("unknown-severity is warned by default (never silently dropped), and blocks when opted in", async () => {
+    const warned = await gate({ sbom: SBOM_SPDX, findings: [UNKNOWN] });
+    expect(warned.passed).toBe(true);
+    expect(warned.warnings.map((f) => f.cveId)).toEqual(["CVE-U"]);
+    await expect(gate({ sbom: SBOM_SPDX, findings: [UNKNOWN], policy: { failOnUnknownSeverity: true } })).rejects.toBeInstanceOf(VulnGateFailedError);
+  });
+});
+
+// ── config resolver ──────────────────────────────────────────────────────────
+
+describe("resolveVulnPolicy", () => {
+  test("empty for no config; passes through set fields", () => {
+    expect(resolveVulnPolicy({})).toEqual({});
+    expect(resolveVulnPolicy({ vulnPolicy: { failSeverity: "high", fixableOnly: false, failOnLicense: true, license: { deny: ["GPL-3.0"] } } })).toEqual({
+      failSeverity: "high",
+      fixableOnly: false,
+      failOnLicense: true,
+      license: { deny: ["GPL-3.0"] },
+    });
+  });
+});