@clear-capabilities/agentic-security-scanner 0.168.0 → 0.170.0

package/CHANGELOG.md

@@ -9,6 +9,80 @@
 > make the history less accurate, not more.
 
 
+## 0.170.0 - source-to-artifact security & provenance: a new `src/artifact/` package, `image`/`provenance` CLI, VEX
+
+Binds a finding to the actual **built artifact** (a container image, today) that ships it — closing the gap
+between "this dependency has a CVE" and "this specific image digest actually ships it." A new, isolated
+`scanner/src/artifact/` package reuses the existing SCA pipeline (manifest parsers, OS-package-DB parser,
+OSV/KEV/EPSS correlation) rather than building a parallel one.
+
+**OCI image scanning + inventory.** A hand-rolled, hardened tar/gzip reader (`safe-tar.js`) — hard caps on entry
+count/size/archive size, a native decompression-bomb guard, and a path-safety check that flags (never silently
+normalizes) a `..`/absolute tar entry path. Parses a `docker save`-shaped archive or an OCI-layout archive into
+digest/OS/architecture/base-image/layers/entrypoint/build-labels, with OS and application packages extracted
+through the exact same parsers every other SCA finding in this codebase uses. Never executes the image — no
+`docker run`, no daemon required for the archive path.
+
+**Layer secret analysis.** A secret added in one layer and deleted by a later overlay whiteout is still sitting
+in that earlier layer's raw tar bytes — detected and reported (value always masked/redacted, the detector is
+injected, same shape `posture/secret-history.js` already uses for the git-history analog).
+
+**Signature + attestation verification**, states exactly `verified`/`invalid`/`missing`/`unavailable` — a
+detached-signature check over the image digest, plus REAL DSSE (Pre-Authentication Encoding) verification for
+in-toto/SLSA provenance attestations, so a real cosign-keyed attestation bundle verifies here given the matching
+public key. Never treats missing material as verified.
+
+**The provenance graph** (Git Commit → Build → OCI Digest → SBOM Component → Finding → Deployment) and
+**source-vs-artifact mismatch detection** — the PRD's own "Killer Demonstration": a developer fixes a
+vulnerability in source, but production is still running the old image. `SOURCE: FIXED` / `DEPLOYED ARTIFACT:
+STILL VULNERABLE` / `PRODUCTION EXPOSURE: PRESENT`, proven end-to-end against the real built CLI. **VEX**
+statements (affected/not affected/fixed/under investigation) — `not affected` only ever from positive evidence
+(component absent, or confirmed unreachable), never from absence of information.
+
+**CLI:** `agentic-security image scan/verify`, `agentic-security provenance trace`, `agentic-security supply vex`
+— the PRD's own literal CLI shape. New slash commands `/image`, `/provenance`; `/supply` gained a `--vex` mode.
+
+**Deliberately NOT done, disclosed:** a local Docker daemon image reference and a remote OCI registry reference
+as `image scan` inputs (only local docker-archive/oci-archive tar files); keyless Rekor-transparency-log
+signature verification. See `docs/implementation-status/source-to-artifact-provenance.md`.
+
+## 0.169.0 - runtime-corroborated security twin: 4 new telemetry adapters, honest runtime assurance, a `runtime` CLI
+
+Extends the existing Milestone 5 "Runtime-Corroborated Digital Twin" machinery (closed-world `RuntimeObservation`
+contract, a 3-rung static-to-runtime match ladder, a non-mutating overlay) rather than building a second one —
+closing the real gap that machinery had: only one hand-authored JSONL telemetry format could feed it.
+
+**Four new telemetry adapters.** `otel-json` (OpenTelemetry JSON trace export, one draft per span), `envoy-access-log`
+(Envoy's default JSON access log, including `response_flags` → an allow/deny security decision), `k8s-audit-log`
+(Kubernetes `audit.k8s.io` JSONL — `objectRef`/`responseStatus.code`, deliberately never `user.username`), and a
+generic JSON-lines `http-access-log`. Each is a pure, zero-fs parser reading only approved, non-payload metadata
+(destination host/port/scheme, service name, protocol/TLS, store table, queue topic) and dropping everything else
+(query strings, headers, usernames, bodies) — matching the existing contract's own reject-not-redact discipline.
+One new, narrowly-scoped attribute key, `network.securityDecision` (a closed `allowed|denied` enum, not a free-form
+identifier), carries the one new fact these formats need that the existing vocabulary didn't have a slot for.
+
+**Honest runtime assurance.** A new `runtime-assurance.js` reports `runtimeStatus: complete|partial|unavailable` —
+`unavailable` whenever no observation store was ever consulted, never a silent "no risk." `runtime status`,
+`runtime reconcile` (diagnostic drift detection against the current graph, never auto-rewriting a stored
+observation) and `runtime query` (two real graph-backed queries, plus honest, named disclosure of the three
+PRD-example queries this architecture genuinely cannot answer) round out a new top-level `runtime` CLI dispatcher;
+`runtime ingest` is a thin shim over the already-shipped `dataflow observations import` — zero duplicated logic.
+
+**A real, grounded demonstration, not an asserted-away fixture.** A small app (`scanner/test/fixtures/runtime-twin/`)
+proves all 5 of the PRD's named fixture properties in one scenario against the real built CLI: a database write
+that executes and is observed allowed; an outbound call that never executes and is never observed; an unrecognized
+host that IS observed but matches nothing in the static graph (reported `unmatched`, never dropped); a PII flow
+crossing a trust boundary to a third party whose destination can never be runtime-corroborated by any adapter here
+— a genuine, disclosed architectural limit; and a queue publish observed denied by authorization.
+
+**What this deliberately does not do, disclosed rather than silently dropped.** No Data Flow Explorer UI/HTTP-server
+wiring (`scanner/src/server/CLAUDE.md`'s own deferred list already named `runtime/` among the endpoints the
+read-only local server does not serve — bolting one on here without that file's own scoping-doc-plus-test-suite
+rigor would be a real regression). No authenticated-identity field (the existing contract omits it as a
+payload-smuggling risk). No route/function-symbol match rungs or the 3 additional PRD-named edge states
+(`RUNTIME_BLOCKED`/`RUNTIME_POLICY_VIOLATION`/`RUNTIME_EXPLOIT_CORRELATED`) — real, separately-scoped future work.
+See `docs/implementation-status/runtime-corroborated-twin.md` for the full itemized status.
+
 ## 0.168.0 - fleet: multi-repository scan orchestration and cross-repository dependency blast radius
 
 A real, honestly-scoped slice of the organization-wide security graph recommendation: a new CLI command group,

package/bin/agentic-security.js

@@ -5561,6 +5561,512 @@ async function cmdDataflowTwin(args) {
   return 0;
 }
 
+// ─────────────────────────────────────────────────────────────────────
+// PRD "Runtime-Corroborated Security Twin" — the `runtime` dispatcher.
+//
+// `runtime ingest`/`runtime status`/`runtime reconcile`/`runtime query`
+// is the literal CLI shape that PRD names. It is NOT a parallel command
+// surface: `ingest` is a thin shim over the already-shipped
+// `dataflow observations import` (zero duplicated logic — it reshapes
+// `args._` and delegates); `status`/`reconcile`/`query` are genuinely new
+// (the assurance report and the reconciliation/query reports did not
+// exist before this PRD), but all three are built entirely on the
+// already-shipped `correlateObservations`/`matchObservationToGraph`/
+// `loadObservationImports` — no second correlation engine, no second
+// observation store.
+
+async function cmdRuntimeIngest(args) {
+  // args._ = ['runtime', 'ingest', <path>?]. cmdDataflowObservationsImport
+  // reads args._[3] as its own path slot (its own dispatch assumes
+  // ['dataflow', 'observations', 'import', <path>?]) — reshape rather
+  // than duplicate its ~150 lines of validation/import logic.
+  const target = args._[2] || '.';
+  const shimmed = { ...args, _: ['dataflow', 'observations', 'import', target] };
+  return cmdDataflowObservationsImport(shimmed);
+}
+
+async function _loadRuntimeInputs(targetAbs) {
+  const { loadSignedGraph } = await import('../src/server/graph-loader.js');
+  const loaded = loadSignedGraph(targetAbs);
+  if (!loaded.ok) return { ok: false, message: loaded.message };
+
+  const dir = statePath(targetAbs, 'runtime-observations');
+  let importRecords = null;
+  let observations = null;
+  if (fs.existsSync(dir)) {
+    const store = await import('../src/lineage/observation-store.js');
+    importRecords = store.loadObservationImports(targetAbs);
+    observations = store.loadObservations(targetAbs);
+  }
+  return { ok: true, graph: loaded.graph, importRecords, observations };
+}
+
+async function cmdRuntimeStatus(args) {
+  const target = args._[2] || '.';
+  const targetAbs = path.resolve(target);
+  const format = args.flags.format ?? 'json';
+  if (format !== 'json' && format !== 'markdown') {
+    process.stderr.write(`agentic-security runtime status: --format must be one of json|markdown (got ${JSON.stringify(format)}).\n`);
+    return 2;
+  }
+
+  const loaded = await _loadRuntimeInputs(targetAbs);
+  if (!loaded.ok) {
+    process.stderr.write(`agentic-security runtime status: ${loaded.message}\n`);
+    return 1;
+  }
+
+  const environment = typeof args.flags.environment === 'string' ? args.flags.environment : null;
+  const windowStart = typeof args.flags['window-start'] === 'string' ? args.flags['window-start'] : null;
+  const windowEnd = typeof args.flags['window-end'] === 'string' ? args.flags['window-end'] : null;
+
+  const { correlateObservations } = await import('../src/lineage/observation-correlation.js');
+  const correlation = correlateObservations(loaded.graph, loaded.observations, { environment, windowStart, windowEnd });
+
+  const { computeRuntimeAssurance } = await import('../src/lineage/runtime-assurance.js');
+  const assurance = computeRuntimeAssurance({ importRecords: loaded.importRecords, correlation });
+
+  if (format === 'json') {
+    process.stdout.write(JSON.stringify(assurance, null, 2) + '\n');
+    return 0;
+  }
+
+  const lines = [];
+  lines.push('# Runtime Assurance', '');
+  lines.push(`**runtimeStatus:** \`${assurance.runtimeStatus}\``, '');
+  lines.push(`- Telemetry window: ${assurance.telemetryWindow.start ?? '(none)'} .. ${assurance.telemetryWindow.end ?? '(none)'}`);
+  lines.push(`- Last observed: ${assurance.freshness.lastObservedAt ?? '(none)'}${assurance.freshness.stale ? ' (STALE)' : ''}`);
+  lines.push(`- Mapping: ${assurance.mappingPercentage === null ? '(no observations)' : `${assurance.mappingPercentage}%`} (${assurance.unmatchedObservationCount} of ${assurance.totalObservationCount} unmatched)`);
+  lines.push(`- Parse failures: ${assurance.parseFailures} — ${assurance.parseFailuresNote}`);
+  lines.push('', '## Limitations', '');
+  for (const l of assurance.limitations) lines.push(`- ${l}`);
+  lines.push('');
+  process.stdout.write(lines.join('\n'));
+  return 0;
+}
+
+async function cmdRuntimeReconcile(args) {
+  const target = args._[2] || '.';
+  const targetAbs = path.resolve(target);
+
+  const loaded = await _loadRuntimeInputs(targetAbs);
+  if (!loaded.ok) {
+    process.stderr.write(`agentic-security runtime reconcile: ${loaded.message}\n`);
+    return 1;
+  }
+  if (loaded.observations === null) {
+    process.stdout.write(JSON.stringify({ checked: 0, drifted: [], note: 'No runtime observation store exists for this scan — nothing to reconcile.' }, null, 2) + '\n');
+    return 0;
+  }
+
+  // Deliberately diagnostic-only: `matchObservationToGraph` is re-run here
+  // purely to COMPARE against each record's own already-stored match — it
+  // never rewrites the stored record. `observation-correlation.js`'s own
+  // header explains why `correlateObservations` itself must never re-run
+  // the ladder (a stored observation must stay honest about what it was
+  // actually checked against at import time); `reconcile` exists
+  // precisely to surface drift for an operator to decide on, not to
+  // silently apply it.
+  const { matchObservationToGraph } = await import('../src/lineage/observation-correlation.js');
+  const drifted = [];
+  for (const obs of loaded.observations) {
+    const fresh = matchObservationToGraph(loaded.graph, obs);
+    const same = fresh.matchMethod === obs.matchMethod
+      && fresh.matchConfidence === obs.matchConfidence
+      && JSON.stringify([...fresh.matchedFlowIds].sort()) === JSON.stringify([...obs.matchedFlowIds].sort());
+    if (!same) {
+      drifted.push({
+        observationId: obs.id,
+        stored: { matchMethod: obs.matchMethod, matchConfidence: obs.matchConfidence, matchedFlowIds: obs.matchedFlowIds },
+        currentGraph: { matchMethod: fresh.matchMethod, matchConfidence: fresh.matchConfidence, matchedFlowIds: fresh.matchedFlowIds },
+      });
+    }
+  }
+  process.stdout.write(JSON.stringify({
+    checked: loaded.observations.length,
+    drifted,
+    note: drifted.length > 0
+      ? 'These observations would match differently against the CURRENT graph than what is stored — the graph changed since import. Re-import with `runtime ingest` to update the stored match; nothing was changed automatically.'
+      : 'Every stored observation still matches the current graph identically.',
+  }, null, 2) + '\n');
+  return 0;
+}
+
+const _RUNTIME_SENSITIVE_CLASSES = ['PII', 'PHI', 'PCI', 'FIN', 'CREDENTIALS'];
+
+const _RUNTIME_QUERIES = Object.freeze({
+  'internet-facing-to-sensitive': {
+    description: 'Internet-facing flows observed reaching sensitive data (PRD example: "Show Internet-facing flows observed reaching PCI data").',
+    run(graph, correlation) {
+      const nodesById = new Map(graph.nodes.map((n) => [n.id, n]));
+      const dataElementsById = new Map(graph.dataElements.map((d) => [d.id, d]));
+      return graph.flows.filter((f) => {
+        if (correlation.byFlow[f.id]?.layer !== 'runtime_observed') return false;
+        const sink = nodesById.get(f.sink);
+        if (sink?.externality?.value !== 'external') return false;
+        return f.dataElementIds.some((id) => (dataElementsById.get(id)?.dataClasses ?? []).some((c) => _RUNTIME_SENSITIVE_CLASSES.includes(c)));
+      }).map((f) => f.id);
+    },
+  },
+  'sensitive-crossing-boundary': {
+    description: 'Sensitive-data paths observed crossing a trust boundary (PRD example: "Show sensitive-data paths observed crossing trust boundaries").',
+    run(graph, correlation) {
+      const edgesById = new Map(graph.edges.map((e) => [e.id, e]));
+      const dataElementsById = new Map(graph.dataElements.map((d) => [d.id, d]));
+      return graph.flows.filter((f) => {
+        if (correlation.byFlow[f.id]?.layer !== 'runtime_observed') return false;
+        const crosses = f.edgeIds.some((id) => (edgesById.get(id)?.boundaryCrossings ?? []).length > 0);
+        if (!crosses) return false;
+        return f.dataElementIds.some((id) => (dataElementsById.get(id)?.dataClasses ?? []).some((c) => _RUNTIME_SENSITIVE_CLASSES.includes(c)));
+      }).map((f) => f.id);
+    },
+  },
+});
+
+// PRD-named example queries this architecture cannot honestly answer —
+// disclosed, never silently omitted. "Runtime flows absent from the
+// static graph" needs a config-declared/auto-correlated edge mechanism
+// (M5 7a / M2 F2-F3, both out of scope here — every RuntimeObservation
+// matches an EXISTING static node, it never mints a new one). "Vulnerable
+// functions actually exercised in production" and "identities using
+// risky paths" both need identity/function-level telemetry this
+// contract's closed-world schema deliberately omits (see this PRD's
+// implementation-status doc).
+const _RUNTIME_QUERIES_NOT_SUPPORTED = Object.freeze({
+  'runtime-flows-absent-from-static': 'Needs a config-declared/auto-correlated edge mechanism (not built — see M5 7a / M2 F2-F3 in scanner/src/lineage/CLAUDE.md) — every RuntimeObservation matches an existing static graph node, it never mints a new one.',
+  'vulnerable-functions-in-production': 'Needs function/symbol-level runtime telemetry; this adapter set only matches destinations (route/service/table/topic), never a function symbol.',
+  'identities-using-risky-paths': 'The RuntimeObservation contract deliberately carries no identity field (a payload-smuggling risk) — see this PRD\'s implementation-status doc for why.',
+});
+
+async function cmdRuntimeQuery(args) {
+  const name = args._[2];
+  if (!name || args.flags.list) {
+    process.stdout.write('Supported queries:\n');
+    for (const [k, v] of Object.entries(_RUNTIME_QUERIES)) process.stdout.write(`  ${k} — ${v.description}\n`);
+    process.stdout.write('\nNamed but NOT supported by this architecture (disclosed, not silently omitted):\n');
+    for (const [k, v] of Object.entries(_RUNTIME_QUERIES_NOT_SUPPORTED)) process.stdout.write(`  ${k} — ${v}\n`);
+    // --list is always a successful, intentional operation (exit 0);
+    // calling `runtime query` with neither a name nor --list is the only
+    // real misuse here.
+    return args.flags.list ? 0 : 2;
+  }
+
+  if (Object.prototype.hasOwnProperty.call(_RUNTIME_QUERIES_NOT_SUPPORTED, name)) {
+    process.stdout.write(JSON.stringify({ query: name, supported: false, reason: _RUNTIME_QUERIES_NOT_SUPPORTED[name] }, null, 2) + '\n');
+    return 0;
+  }
+  const query = _RUNTIME_QUERIES[name];
+  if (!query) {
+    process.stderr.write(`agentic-security runtime query: unrecognized query "${name}" — run with --list to see every supported (and disclosed-unsupported) query name.\n`);
+    return 2;
+  }
+
+  const target = args._[3] || '.';
+  const targetAbs = path.resolve(target);
+  const loaded = await _loadRuntimeInputs(targetAbs);
+  if (!loaded.ok) {
+    process.stderr.write(`agentic-security runtime query: ${loaded.message}\n`);
+    return 1;
+  }
+
+  const environment = typeof args.flags.environment === 'string' ? args.flags.environment : null;
+  const { correlateObservations } = await import('../src/lineage/observation-correlation.js');
+  const correlation = correlateObservations(loaded.graph, loaded.observations, { environment, windowStart: null, windowEnd: null });
+
+  const flowIds = query.run(loaded.graph, correlation);
+  process.stdout.write(JSON.stringify({ query: name, supported: true, flowIds }, null, 2) + '\n');
+  return 0;
+}
+
+// ─── PRD 5: Source-to-Artifact Security & Provenance ───────────────────────
+// `image scan/verify`, `provenance trace`, `supply vex`. See
+// docs/implementation-status/source-to-artifact-provenance.md for the full
+// scope, naming-collision discipline (why the graph field below is
+// `artifactProvenanceGraph`, never a bare `.provenance`), and what is
+// deliberately NOT implemented (local-daemon image / remote registry
+// reference inputs; keyless Rekor signature lookup).
+
+function _readFileOrError(target) {
+  const abs = path.resolve(target);
+  if (!fs.existsSync(abs)) return { ok: false, message: `no such file: ${target}` };
+  if (!fs.statSync(abs).isFile()) return { ok: false, message: `${target} is not a file` };
+  try {
+    return { ok: true, buf: fs.readFileSync(abs) };
+  } catch (err) {
+    return { ok: false, message: `failed to read ${target}: ${err.message}` };
+  }
+}
+
+function _artifactScanDigestHex(digestOrTarget) {
+  const s = String(digestOrTarget || '');
+  const hex = s.startsWith('sha256:') ? s.slice(7) : s;
+  return /^[0-9a-f]{64}$/.test(hex) ? hex : null;
+}
+
+// Parses an archive fresh and runs inventory + vuln correlation — the one
+// real analysis path every `image scan`/`provenance trace`/`supply vex`
+// invocation that isn't reading a stored result funnels through.
+async function _scanArchiveFresh(buf) {
+  const { buildImageInventory } = await import('../src/artifact/inventory.js');
+  const { ImageArchiveError } = await import('../src/artifact/image-archive.js');
+  const { TarSafetyError } = await import('../src/artifact/safe-tar.js');
+  const { parseManifests, queryOSV } = await import('../src/sca/index.js');
+  const { correlateImageVulnerabilities } = await import('../src/artifact/vuln-correlate.js');
+  const { analyzeLayerSecrets } = await import('../src/artifact/layer-secrets.js');
+  const { scanCredentials } = await import('../src/secrets/index.js');
+
+  let built;
+  try {
+    built = buildImageInventory(buf, { manifestParser: parseManifests });
+  } catch (err) {
+    if (err instanceof ImageArchiveError || err instanceof TarSafetyError) return { ok: false, message: err.message };
+    throw err;
+  }
+  const { vulnerabilities } = await correlateImageVulnerabilities({
+    inventory: built.inventory, fileContents: built.mergedFilesystem.fileContents, queryOSVFn: queryOSV,
+  });
+  const secrets = analyzeLayerSecrets({
+    readLayersResult: built.readLayersResult, deletedPaths: built.mergedFilesystem.deletedPaths, detectFn: scanCredentials,
+  });
+  return {
+    ok: true,
+    built,
+    record: {
+      inventory: built.inventory,
+      vulnerabilities,
+      secrets: { deletedButRecoverable: secrets.deletedButRecoverable, totalFindings: secrets.findings.length },
+      scannedAt: new Date().toISOString(),
+    },
+  };
+}
+
+async function _persistArtifactScan(record) {
+  const { statePath, safeWriteState } = await import('../src/posture/state-dir.js');
+  const root = process.cwd();
+  const hex = _artifactScanDigestHex(record.inventory.digest);
+  if (!hex) return false; // defensive: digest is always well-formed sha256:<hex> from image-archive.js
+  return safeWriteState(statePath(root, 'artifact-scans', `${hex}.json`), JSON.stringify(record, null, 2), { category: 'artifact-scans' });
+}
+
+// Resolves `target` to a scan record: a digest/sha256:<hex> that matches a
+// PREVIOUSLY `image scan`-ned, persisted record is loaded from state;
+// anything else is treated as an archive file path and parsed fresh. This
+// is what lets `provenance trace <digest>` and `supply vex <digest>` work
+// after an earlier `image scan <path>` without re-reading the archive.
+async function _resolveArtifactScan(target) {
+  const hex = _artifactScanDigestHex(target);
+  if (hex) {
+    const { statePath } = await import('../src/posture/state-dir.js');
+    const storedPath = statePath(process.cwd(), 'artifact-scans', `${hex}.json`);
+    if (fs.existsSync(storedPath)) {
+      try {
+        return { ok: true, record: JSON.parse(fs.readFileSync(storedPath, 'utf8')) };
+      } catch (err) {
+        return { ok: false, message: `stored scan at ${storedPath} is corrupt: ${err.message}` };
+      }
+    }
+    return { ok: false, message: `no stored scan for digest ${target} — run "image scan" on the archive first` };
+  }
+  const read = _readFileOrError(target);
+  if (!read.ok) return read;
+  const scanned = await _scanArchiveFresh(read.buf);
+  if (!scanned.ok) return scanned;
+  return { ok: true, record: scanned.record };
+}
+
+async function cmdImageScan(args) {
+  const target = args._[2];
+  if (!target) {
+    process.stderr.write('agentic-security image scan: provide a path to a docker-archive or oci-archive tar (OCI tar / Docker tar — see commands/image.md for the two supported input shapes).\n');
+    return 2;
+  }
+  const format = args.flags.format ?? 'json';
+  if (format !== 'json' && format !== 'cli') {
+    process.stderr.write('agentic-security image scan: --format must be json|cli.\n');
+    return 2;
+  }
+  const read = _readFileOrError(target);
+  if (!read.ok) { process.stderr.write(`agentic-security image scan: ${read.message}\n`); return 1; }
+
+  const scanned = await _scanArchiveFresh(read.buf);
+  if (!scanned.ok) { process.stderr.write(`agentic-security image scan: ${scanned.message}\n`); return 1; }
+
+  await _persistArtifactScan(scanned.record);
+
+  if (format === 'json') {
+    process.stdout.write(JSON.stringify(scanned.record, null, 2) + '\n');
+    return 0;
+  }
+  const { inventory, vulnerabilities, secrets } = scanned.record;
+  const vulnCount = vulnerabilities.filter((v) => v.type === 'vulnerable_dep').length;
+  process.stdout.write([
+    `Image digest: ${inventory.digest} (${inventory.digestKind})`,
+    `OS/architecture: ${inventory.os}/${inventory.architecture}`,
+    `OS packages: ${inventory.osPackages.length}, application packages: ${inventory.appPackages.length}`,
+    `Vulnerabilities (OSV): ${vulnCount}`,
+    `Secrets deleted-but-recoverable from an earlier layer: ${secrets.deletedButRecoverable.length}`,
+    inventory.materializationTruncated ? 'NOTE: some layer content exceeded the scan size cap and was skipped.' : '',
+  ].filter(Boolean).join('\n') + '\n');
+  return 0;
+}
+
+async function cmdImageVerify(args) {
+  const target = args._[2];
+  if (!target) {
+    process.stderr.write('agentic-security image verify: provide a path to a docker-archive or oci-archive tar, or a previously-scanned digest.\n');
+    return 2;
+  }
+  const resolved = await _resolveArtifactScan(target);
+  if (!resolved.ok) { process.stderr.write(`agentic-security image verify: ${resolved.message}\n`); return 1; }
+  const { inventory } = resolved.record;
+
+  const { verifyImageSignature, verifyProvenanceAttestation } = await import('../src/artifact/signature.js');
+
+  let signature = null;
+  let publicKeyPem = null;
+  let attestation = null;
+  if (typeof args.flags.signature === 'string') {
+    const r = _readFileOrError(args.flags.signature);
+    if (!r.ok) { process.stderr.write(`agentic-security image verify: --signature: ${r.message}\n`); return 1; }
+    signature = r.buf;
+  }
+  if (typeof args.flags['public-key'] === 'string') {
+    const r = _readFileOrError(args.flags['public-key']);
+    if (!r.ok) { process.stderr.write(`agentic-security image verify: --public-key: ${r.message}\n`); return 1; }
+    publicKeyPem = r.buf.toString('utf8');
+  }
+  if (typeof args.flags.attestation === 'string') {
+    const r = _readFileOrError(args.flags.attestation);
+    if (!r.ok) { process.stderr.write(`agentic-security image verify: --attestation: ${r.message}\n`); return 1; }
+    try { attestation = JSON.parse(r.buf.toString('utf8')); } catch (err) {
+      process.stderr.write(`agentic-security image verify: --attestation is not valid JSON: ${err.message}\n`);
+      return 1;
+    }
+  }
+
+  const signatureResult = verifyImageSignature({ digest: inventory.digest, signature, publicKeyPem });
+  const attestationResult = verifyProvenanceAttestation({ digest: inventory.digest, envelope: attestation, publicKeyPem });
+
+  const result = { digest: inventory.digest, signature: signatureResult, attestation: attestationResult };
+  process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  // Exit non-zero only on a definite "invalid" — "missing"/"unavailable" are
+  // honest reports of absent material, not a failed check, and must not be
+  // conflated with a cryptographic failure a CI gate should actually block on.
+  return (signatureResult.state === 'invalid' || attestationResult.state === 'invalid') ? 1 : 0;
+}
+
+async function cmdProvenanceTrace(args) {
+  const target = args._[2];
+  if (!target) {
+    process.stderr.write('agentic-security provenance trace: provide a path to an image archive, or a previously-scanned digest.\n');
+    return 2;
+  }
+  const resolved = await _resolveArtifactScan(target);
+  if (!resolved.ok) { process.stderr.write(`agentic-security provenance trace: ${resolved.message}\n`); return 1; }
+  const { inventory, vulnerabilities } = resolved.record;
+
+  let deployment = null;
+  if (typeof args.flags['deployment-id'] === 'string') {
+    deployment = {
+      id: args.flags['deployment-id'],
+      environment: typeof args.flags['deployment-environment'] === 'string' ? args.flags['deployment-environment'] : null,
+      digest: typeof args.flags['deployment-digest'] === 'string' ? args.flags['deployment-digest'] : null,
+      evidence: 'operator-declared',
+    };
+  }
+
+  const { buildArtifactProvenanceGraph, traceArtifactProvenanceGraph } = await import('../src/artifact/provenance-graph.js');
+  const artifactProvenanceGraph = buildArtifactProvenanceGraph({ inventory, vulnerabilities, deployment });
+  const commitNode = artifactProvenanceGraph.nodes.find((n) => n.kind === 'gitCommit');
+  const trace = traceArtifactProvenanceGraph(artifactProvenanceGraph, commitNode.id);
+
+  let mismatch = null;
+  if (typeof args.flags.source === 'string') {
+    const sourceRoot = path.resolve(args.flags.source);
+    const lastScanPath = path.join(sourceRoot, '.agentic-security', 'last-scan.json');
+    if (!fs.existsSync(lastScanPath)) {
+      process.stderr.write(`agentic-security provenance trace: --source "${args.flags.source}" has no .agentic-security/last-scan.json — run "scan" there first.\n`);
+      return 1;
+    }
+    const sourceScan = JSON.parse(fs.readFileSync(lastScanPath, 'utf8'));
+    const { detectSourceArtifactMismatch } = await import('../src/artifact/mismatch.js');
+    mismatch = detectSourceArtifactMismatch({
+      sourceVulnerabilities: sourceScan.supplyChain || [],
+      artifactVulnerabilities: vulnerabilities,
+      artifactComponents: [...inventory.osPackages, ...inventory.appPackages],
+    });
+  }
+
+  const format = args.flags.format ?? 'json';
+  if (format === 'json') {
+    process.stdout.write(JSON.stringify({ artifactProvenanceGraph, trace, mismatch }, null, 2) + '\n');
+    return 0;
+  }
+
+  const lines = [`Artifact digest: ${inventory.digest}`, `Source commit: ${commitNode.known ? commitNode.sha : '(not declared — no org.opencontainers.image.revision label)'}`];
+  if (mismatch) {
+    lines.push('');
+    if (mismatch.scenarioA.length > 0) {
+      lines.push('SOURCE: FIXED');
+      lines.push('DEPLOYED ARTIFACT: STILL VULNERABLE');
+      lines.push('PRODUCTION EXPOSURE: PRESENT');
+      lines.push(`  ${mismatch.scenarioA.length} vulnerabilit${mismatch.scenarioA.length === 1 ? 'y' : 'ies'} present in this artifact, already fixed in current source: ${mismatch.scenarioA.map((v) => v.osvId).join(', ')}`);
+    }
+    if (mismatch.scenarioB.length > 0) {
+      lines.push(`${mismatch.scenarioA.length > 0 ? '' : 'SOURCE: VULNERABLE\n'}BUILT ARTIFACT: AFFECTED COMPONENT ABSENT`);
+      lines.push(`  ${mismatch.scenarioB.length} vulnerabilit${mismatch.scenarioB.length === 1 ? 'y' : 'ies'} flagged in current source did not actually ship in this artifact: ${mismatch.scenarioB.map((v) => v.osvId).join(', ')}`);
+    }
+    if (!mismatch.hasMismatch) lines.push('No mismatch: current source and this deployed artifact agree.');
+  }
+  process.stdout.write(lines.join('\n') + '\n');
+  return 0;
+}
+
+async function cmdSupplyVex(args) {
+  const target = args._[2];
+  if (!target) {
+    process.stderr.write('agentic-security supply vex: provide a path to an image archive, or a previously-scanned digest.\n');
+    return 2;
+  }
+  const resolved = await _resolveArtifactScan(target);
+  if (!resolved.ok) { process.stderr.write(`agentic-security supply vex: ${resolved.message}\n`); return 1; }
+  const { inventory, vulnerabilities } = resolved.record;
+
+  let reachabilityByKey = new Map();
+  if (typeof args.flags.source === 'string') {
+    const sourceRoot = path.resolve(args.flags.source);
+    const lastScanPath = path.join(sourceRoot, '.agentic-security', 'last-scan.json');
+    if (fs.existsSync(lastScanPath)) {
+      const sourceScan = JSON.parse(fs.readFileSync(lastScanPath, 'utf8'));
+      for (const sc of (sourceScan.supplyChain || [])) {
+        if (sc.type !== 'vulnerable_dep') continue;
+        const key = sc.purl || `${sc.ecosystem}:${sc.name}`;
+        const reachable = sc.functionReachable === 'reachable' ? true : sc.functionReachable === 'unreachable' ? false : null;
+        if (reachable !== null) reachabilityByKey.set(key, { reachable, reason: sc.reachabilityTier || null });
+      }
+    }
+  }
+
+  const { deriveVexStatus } = await import('../src/artifact/vex.js');
+  const artifactComponents = [...inventory.osPackages, ...inventory.appPackages];
+  const statements = vulnerabilities.filter((v) => v.type === 'vulnerable_dep').map((v) => {
+    const key = v.purl || `${v.ecosystem}:${v.name}`;
+    const reachability = reachabilityByKey.get(key) || null;
+    const vex = deriveVexStatus({ vulnerability: v, artifactComponents, reachability });
+    return { purl: v.purl || null, name: v.name, ecosystem: v.ecosystem, osvId: v.osvId, ...vex };
+  });
+
+  const format = args.flags.format ?? 'json';
+  if (format === 'json') {
+    process.stdout.write(JSON.stringify({ digest: inventory.digest, statements }, null, 2) + '\n');
+    return 0;
+  }
+  const lines = [`VEX for ${inventory.digest}:`];
+  for (const s of statements) lines.push(`  ${s.osvId} (${s.name}): ${s.status}${s.justification ? ` [${s.justification}]` : ''}`);
+  process.stdout.write(lines.join('\n') + '\n');
+  return 0;
+}
+
 // Mirrors posture/fix-history.js's own _writeAtomicAndSync (temp file in
 // the same directory, fsync, then rename over the target) — a crash
 // mid-write must never leave recipient-profiles.json as invalid JSON,
@@ -7288,6 +7794,67 @@ async function main() {
         }
         break;
       }
+      case 'runtime': {
+        // NOT a `dataflow` subcommand — PRD "Runtime-Corroborated Security
+        // Twin" names this literal CLI shape (`runtime ingest/status/
+        // reconcile/query`). `ingest` is a thin shim over the already-
+        // shipped `dataflow observations import`; `status`/`reconcile`/
+        // `query` are new, built entirely on the already-shipped
+        // correlation/match/store functions. See cmdRuntimeStatus's own
+        // header comment above.
+        const sub = args._[1];
+        if (sub === 'ingest') { process.exit(await cmdRuntimeIngest(args)); }
+        else if (sub === 'status') { process.exit(await cmdRuntimeStatus(args)); }
+        else if (sub === 'reconcile') { process.exit(await cmdRuntimeReconcile(args)); }
+        else if (sub === 'query') { process.exit(await cmdRuntimeQuery(args)); }
+        else {
+          process.stderr.write(`agentic-security runtime: unrecognized sub-command "${sub}" — must be "ingest", "status", "reconcile", or "query".\n`);
+          process.exit(2);
+        }
+        break;
+      }
+      case 'image': {
+        // PRD 5 (Source-to-Artifact Security & Provenance) names this
+        // literal CLI shape. `scan` parses + correlates; `verify` checks
+        // signature/attestation material only (never re-runs correlation).
+        const sub = args._[1];
+        if (sub === 'scan') { process.exit(await cmdImageScan(args)); }
+        else if (sub === 'verify') { process.exit(await cmdImageVerify(args)); }
+        else {
+          process.stderr.write(`agentic-security image: unrecognized sub-command "${sub}" — must be "scan" or "verify".\n`);
+          process.exit(2);
+        }
+        break;
+      }
+      case 'provenance': {
+        // NOT `posture/provenance/`'s git-commit finding provenance, NOT
+        // `sca/sigstore-verify.js`'s package-build provenance — this is PRD
+        // 5's own artifact provenance graph (Git Commit -> Build -> OCI
+        // Digest -> SBOM Component -> Finding -> Deployment). See
+        // docs/implementation-status/source-to-artifact-provenance.md's
+        // naming-discipline section.
+        const sub = args._[1];
+        if (sub === 'trace') { process.exit(await cmdProvenanceTrace(args)); }
+        else {
+          process.stderr.write(`agentic-security provenance: unrecognized sub-command "${sub}" — must be "trace".\n`);
+          process.exit(2);
+        }
+        break;
+      }
+      case 'supply': {
+        // The `/supply` SLASH COMMAND (commands/supply.md) is a different
+        // layer entirely — Claude Code UI sugar that shells out to `scan
+        // --only sca`/`cve-watch`. This is PRD 5's own literal CLI shape,
+        // `agentic-security supply vex`, operating on an IMAGE ARTIFACT
+        // rather than a source directory.
+        const sub = args._[1];
+        if (sub === 'vex') { process.exit(await cmdSupplyVex(args)); }
+        else {
+          process.stderr.write(`agentic-security supply: unrecognized sub-command "${sub}" — must be "vex".\n`);
+          process.exit(2);
+        }
+        break;
+      }
       case 'remediation': {
         // NOT a `dataflow` subcommand — this writes operator/incident
         // state (the append-only remediation ledger), never the scanned