@intentius/chant 0.124.13 → 0.124.15

package/dist/components/verbs/verify.js

@@ -0,0 +1,112 @@
+/**
+ * `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 human-approval semantics (that is `Gate`, ../component.ts, a
+ * different concept: a fact on the gate ledger). `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 { defaultProcessRunner, q, requireTool } from "./process-runner.js";
+/**
+ * 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(imageRef, check, reason) {
+        super(`verify "${imageRef}": ${check} verification failed — ${reason}`);
+        this.imageRef = imageRef;
+        this.check = check;
+        this.reason = 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, policy) {
+    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) {
+    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) {
+    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 = defaultProcessRunner()) {
+    return {
+        kind: "verify",
+        async run(_ctx, input) {
+            await requireTool(processRunner, "cosign", `verify ${input.imageRef} against the configured identity policy`);
+            const checked = [];
+            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 = createVerifyCapability();

package/dist/components/verbs/vex.js

@@ -0,0 +1,131 @@
+/**
+ * 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.
+ */
+/** True for statuses that suppress a matching finding from gating. */
+export function suppresses(status) {
+    return status === "not_affected" || status === "fixed";
+}
+function vexStatusFrom(raw) {
+    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) {
+    const doc = JSON.parse(bytes);
+    const out = [];
+    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;
+}
+/** Map CycloneDX `analysis.state` to a `VexStatus`. */
+function cdxStateToVex(state) {
+    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) {
+    const doc = JSON.parse(bytes);
+    const out = [];
+    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) {
+    let doc;
+    try {
+        doc = JSON.parse(bytes);
+    }
+    catch {
+        return [];
+    }
+    if (Array.isArray(doc.statements))
+        return parseOpenVex(bytes);
+    if (Array.isArray(doc.vulnerabilities))
+        return parseCycloneDxVex(bytes);
+    return [];
+}
+/**
+ * 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, statements) {
+    const byCve = new Map();
+    for (const s of statements) {
+        const list = byCve.get(s.cveId);
+        if (list)
+            list.push(s);
+        else
+            byCve.set(s.cveId, [s]);
+    }
+    const gating = [];
+    const suppressed = [];
+    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/dist/components/verbs/vuln-gate.js

@@ -0,0 +1,152 @@
+/**
+ * `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 { defaultVulnScanner, SEVERITY_RANK, } from "./vuln-scan.js";
+import { applyVex, parseVexDocument } from "./vex.js";
+import { evaluateLicensePolicy } from "./license-policy.js";
+/** Beginner-safe defaults, also encoded in `resolveVulnPolicy` (../../config.ts). */
+export const DEFAULT_VULN_POLICY = {
+    failSeverity: "critical",
+    fixableOnly: true,
+    warnSeverity: "high",
+    failOnLicense: false,
+    failOnUnknownSeverity: false,
+    failOnKev: false,
+    exploitabilityFixableOnly: true,
+};
+/**
+ * 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(blocking, blockingLicenses) {
+        const licList = blockingLicenses.map((l) => `${l.license} in ${l.package}`).join(", ");
+        const parts = [];
+        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("\n")}\nFix the dependency, or record a VEX statement if it is not exploitable.`);
+        this.blocking = blocking;
+        this.blockingLicenses = blockingLicenses;
+        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) {
+    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) {
+    const out = [];
+    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`, 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, 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 = defaultVulnScanner()) {
+    return {
+        kind: "vuln-gate",
+        async run(_ctx, input) {
+            const policy = { ...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 + 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 = [];
+            const warnings = [];
+            for (const f of gating) {
+                const rank = SEVERITY_RANK[f.severity];
+                // 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
+                    // 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 || 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);
+                }
+            }
+            // 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 = createVulnGateCapability();