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

package/src/artifact/mismatch.js

@@ -0,0 +1,72 @@
+// PRD 5 P0 §7 — Source vs Artifact Mismatch. This is the PRD's own "Killer
+// Demonstration": a developer fixes a vulnerability in source on Monday, but
+// production is still serving Friday's image.
+//
+// Scenario A — "Git: fixed / Production image: vulnerable": an OSV advisory
+// the DEPLOYED ARTIFACT's own vuln-correlate.js result reports against the
+// version it actually has installed, that the CURRENT source scan does NOT
+// report against the version source has installed/declared — i.e. source
+// has moved past this specific advisory (patched, upgraded) but the
+// artifact's installed version has not.
+//
+// Scenario B — "Git: vulnerable / Built artifact: affected component
+// absent": the current source scan flags an advisory against some package,
+// but that PACKAGE (by ecosystem+name, independent of version) is not
+// present anywhere in the artifact's own component inventory at all — a
+// dev-only/optional dependency that never actually shipped in this build.
+//
+// The matching key for a scenario-A/B pair is the OSV advisory id ALONE
+// (`osvId`) — never the purl, which bakes the VERSION into the key. Keying
+// on purl was tried first and is wrong: source and artifact are, by this
+// comparison's entire premise, usually running DIFFERENT versions of the
+// same package, so a purl-based key would make every version difference
+// look like two independent mismatches instead of comparing "does this
+// specific advisory affect each side's own installed version". An OSV
+// advisory id already uniquely identifies one vulnerability against one
+// package, so comparing by id alone correctly asks "is THIS advisory
+// present on one side and absent on the other", regardless of which exact
+// version is installed on either side.
+//
+// Pure comparison only — no new detection. `sourceVulnerabilities` is the
+// output of a normal source-tree SCA scan (queryOSV-shaped `vulnerable_dep`
+// entries); `artifactVulnerabilities`/`artifactComponents` are
+// vuln-correlate.js's/inventory.js's output for one specific image.
+function advisoryKey(v) {
+  return v.osvId || `no-osv-id:${v.ecosystem}:${v.name}`;
+}
+
+function packageIdentity(c) {
+  return `${c.ecosystem}:${c.name}`;
+}
+
+export function detectSourceArtifactMismatch({ sourceVulnerabilities, artifactVulnerabilities, artifactComponents }) {
+  if (!Array.isArray(sourceVulnerabilities) || !Array.isArray(artifactVulnerabilities) || !Array.isArray(artifactComponents)) {
+    throw new TypeError('detectSourceArtifactMismatch requires sourceVulnerabilities/artifactVulnerabilities/artifactComponents arrays');
+  }
+
+  const sourceKeyed = new Map();
+  for (const v of sourceVulnerabilities) {
+    if (v.type && v.type !== 'vulnerable_dep') continue;
+    sourceKeyed.set(advisoryKey(v), v);
+  }
+  const artifactKeyed = new Map();
+  for (const v of artifactVulnerabilities) {
+    if (v.type && v.type !== 'vulnerable_dep') continue;
+    artifactKeyed.set(advisoryKey(v), v);
+  }
+  const artifactPackageIdentities = new Set(artifactComponents.map(packageIdentity));
+
+  const scenarioA = [...artifactKeyed.entries()]
+    .filter(([key]) => !sourceKeyed.has(key))
+    .map(([, v]) => v);
+
+  const scenarioB = [...sourceKeyed.entries()]
+    .filter(([, v]) => !artifactPackageIdentities.has(packageIdentity(v)))
+    .map(([, v]) => v);
+
+  return {
+    scenarioA,
+    scenarioB,
+    hasMismatch: scenarioA.length > 0 || scenarioB.length > 0,
+  };
+}

package/src/artifact/provenance-graph.js

@@ -0,0 +1,115 @@
+// PRD 5 P0 §6 — Provenance Graph: Git Commit -> Build -> OCI Digest -> SBOM
+// Component -> Finding -> Deployment.
+//
+// Naming: the exported field is `artifactProvenanceGraph` and the builder is
+// `buildArtifactProvenanceGraph` — never a bare `.provenance`/`*Provenance`,
+// per this repo's own naming discipline (5 unrelated existing uses of
+// "provenance"; see docs/implementation-status/source-to-artifact-provenance.md).
+//
+// This function does no new detection — every node/edge is assembled from
+// evidence `inventory.js`/`vuln-correlate.js` already computed. The one
+// exception is the Git-Commit edge, whose only evidence source is the
+// standard `org.opencontainers.image.revision` build label; when absent the
+// commit node is explicitly `known: false`, never inferred from git history
+// (an image's build label is the only trustworthy claim of "which commit
+// built this" — matching it against local git history by heuristic would be
+// a confident-looking guess, the exact failure mode PRD 5's signature-state
+// discipline exists to prevent elsewhere in this same PRD).
+const REVISION_LABEL = 'org.opencontainers.image.revision';
+
+function componentId(c) {
+  return c.purl || `${c.ecosystem}:${c.name}@${c.version}`;
+}
+
+/**
+ * `inventory` is `inventory.js#buildImageInventory`'s `inventory`.
+ * `vulnerabilities` is `vuln-correlate.js`'s `queryOSVFn` result (only
+ * `type: 'vulnerable_dep'` entries become Finding nodes — the no_lockfile",
+ * "unpinned_dep" structural checks don't bind to a specific component and
+ * are not part of this graph). `deployment`, if supplied, is an
+ * OPERATOR-DECLARED record (`{ id, environment, evidence }`) — this codebase
+ * has no mechanism anywhere that discovers "which digest is running where"
+ * on its own (`lineage/deployment/` models topology, not running digests),
+ * so a missing `deployment` argument means the graph simply stops at the
+ * OCI Digest / SBOM Component / Finding nodes, never a fabricated edge.
+ */
+export function buildArtifactProvenanceGraph({ inventory, vulnerabilities = [], deployment = null }) {
+  if (!inventory || typeof inventory.digest !== 'string') {
+    throw new TypeError('buildArtifactProvenanceGraph requires an inventory with a digest');
+  }
+  const nodes = [];
+  const edges = [];
+
+  const commitSha = inventory.buildLabels ? inventory.buildLabels[REVISION_LABEL] || null : null;
+  const commitId = `commit:${commitSha || 'unknown'}`;
+  const buildId = `build:${inventory.digest}`;
+  const digestId = `digest:${inventory.digest}`;
+
+  nodes.push({ id: commitId, kind: 'gitCommit', sha: commitSha, known: !!commitSha });
+  nodes.push({ id: buildId, kind: 'build', digest: inventory.digest, labels: inventory.buildLabels || {} });
+  nodes.push({ id: digestId, kind: 'ociDigest', digest: inventory.digest, digestKind: inventory.digestKind, repoTags: inventory.repoTags || [] });
+
+  edges.push({
+    from: commitId, to: buildId,
+    evidence: commitSha ? `label:${REVISION_LABEL}` : 'none',
+  });
+  edges.push({ from: buildId, to: digestId, evidence: 'same-archive' });
+
+  const components = [...(inventory.osPackages || []), ...(inventory.appPackages || [])];
+  for (const c of components) {
+    const compId = `component:${componentId(c)}`;
+    nodes.push({ id: compId, kind: 'sbomComponent', purl: c.purl || null, name: c.name, version: c.version, ecosystem: c.ecosystem });
+    edges.push({ from: digestId, to: compId, evidence: 'inventory' });
+  }
+
+  const vulnDeps = (vulnerabilities || []).filter((v) => v.type === 'vulnerable_dep');
+  for (const v of vulnDeps) {
+    const compId = `component:${v.purl || `${v.ecosystem}:${v.name}@${v.version}`}`;
+    const findingId = `finding:${v.osvId}:${v.purl || `${v.ecosystem}:${v.name}@${v.version}`}`;
+    nodes.push({ id: findingId, kind: 'finding', osvId: v.osvId, cveAliases: v.cveAliases || [], severity: v.severity });
+    edges.push({ from: compId, to: findingId, evidence: 'osv' });
+  }
+
+  if (deployment) {
+    if (typeof deployment.id !== 'string') throw new TypeError('a supplied deployment record requires an "id"');
+    const deploymentId = `deployment:${deployment.id}`;
+    nodes.push({ id: deploymentId, kind: 'deployment', environment: deployment.environment || null, declaredDigest: deployment.digest || null });
+    edges.push({
+      from: digestId, to: deploymentId,
+      evidence: deployment.evidence || 'operator-declared',
+      digestMatches: deployment.digest ? deployment.digest === inventory.digest : null,
+    });
+  }
+
+  return { nodes, edges };
+}
+
+/**
+ * Walks the graph from a commit or digest to every reachable Finding/Deployment
+ * node — the `provenance trace` CLI command's query surface.
+ */
+export function traceArtifactProvenanceGraph(graph, fromId) {
+  if (!graph || !Array.isArray(graph.nodes) || !Array.isArray(graph.edges)) {
+    throw new TypeError('traceArtifactProvenanceGraph requires a graph with nodes/edges arrays');
+  }
+  const byId = new Map(graph.nodes.map((n) => [n.id, n]));
+  if (!byId.has(fromId)) return { found: false, path: [] };
+  const adjacency = new Map();
+  for (const e of graph.edges) {
+    if (!adjacency.has(e.from)) adjacency.set(e.from, []);
+    adjacency.get(e.from).push(e);
+  }
+  const visited = new Set([fromId]);
+  const queue = [fromId];
+  const reached = [];
+  while (queue.length) {
+    const cur = queue.shift();
+    for (const e of adjacency.get(cur) || []) {
+      if (visited.has(e.to)) continue;
+      visited.add(e.to);
+      reached.push({ node: byId.get(e.to), via: e });
+      queue.push(e.to);
+    }
+  }
+  return { found: true, root: byId.get(fromId), reached };
+}

package/src/artifact/safe-tar.js

@@ -0,0 +1,175 @@
+// Hand-rolled, hardened POSIX/GNU tar reader for OCI/Docker image archives.
+//
+// Why hand-rolled instead of a dependency: this repo has no tar library (see
+// `src/artifact/CLAUDE.md`), and PRD 5's own Safety Requirements ask for exact
+// control over the failure modes a generic tar library treats as implementation
+// detail: malicious entry paths, decompression bombs, giant layers, oversized
+// archives. Rolling it ourselves means every one of those limits is a named,
+// tested constant in this file rather than a library default we'd have to audit.
+//
+// Scope: ustar + GNU longname ('L' typeflag) + base-256 size fields. PAX extended
+// headers ('x'/'g') and GNU longlink ('K') are structurally skipped (their data
+// block is consumed so offsets stay correct, but their content is not applied) —
+// a disclosed limitation, not a silent one. Real docker-save/oci-archive output
+// from Go's archive/tar for images in this size/complexity class essentially
+// never needs them; synthetic fixtures in this codebase never emit them either.
+import zlib from 'node:zlib';
+
+const BLOCK = 512;
+
+export const DEFAULT_LIMITS = Object.freeze({
+  maxEntries: 200_000,
+  maxEntrySize: 512 * 1024 * 1024, // 512MB per tar entry
+  maxTotalSize: 4 * 1024 * 1024 * 1024, // 4GB per archive (sum of entry sizes)
+  maxGunzipOutput: 4 * 1024 * 1024 * 1024, // decompression-bomb guard
+});
+
+export class TarSafetyError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = 'TarSafetyError';
+    this.code = code;
+  }
+}
+
+function parseSizeField(buf) {
+  if (buf[0] & 0x80) {
+    // GNU base-256 extension for sizes that don't fit in octal-ASCII.
+    let n = 0n;
+    for (let i = 1; i < buf.length; i++) n = (n << 8n) | BigInt(buf[i]);
+    return Number(n);
+  }
+  const s = buf.toString('ascii').replace(/\0.*$/, '').trim();
+  if (!s) return 0;
+  const n = parseInt(s, 8);
+  return Number.isFinite(n) ? n : 0;
+}
+
+function cstr(buf) {
+  return buf.toString('utf8').replace(/\0.*$/, '');
+}
+
+// A tar entry name is unsafe when it would escape a virtual extraction root:
+// absolute paths, `..` segments, embedded NULs, or an unreasonable length.
+// Because this module never writes to a real filesystem path (every caller
+// keeps extracted content in an in-memory Map keyed by this string), the
+// classic zip-slip *write* vulnerability cannot occur here — but a hostile
+// name must still never be silently treated as an ordinary path by downstream
+// manifest/package-DB matching, so unsafe entries are flagged, never dropped
+// silently and never accepted as-is.
+export function isSafeEntryName(name) {
+  if (typeof name !== 'string' || name.length === 0 || name.length > 4096) return false;
+  if (name.includes('\0')) return false;
+  const norm = name.replace(/\\/g, '/');
+  if (norm.startsWith('/')) return false;
+  if (norm.split('/').some((p) => p === '..')) return false;
+  return true;
+}
+
+export function isWhiteoutName(name) {
+  return (name.split('/').pop() || '').startsWith('.wh.');
+}
+
+// Resolves a whiteout entry name to what it deletes. `.wh..wh..opq` marks a
+// directory as "opaque" (everything from earlier layers under it is hidden,
+// not individually deleted) — reported distinctly so callers don't conflate
+// it with a single-file deletion.
+export function whiteoutTarget(name) {
+  const parts = name.split('/');
+  const base = parts.pop();
+  if (base === '.wh..wh..opq') return { opaque: true, dir: parts.join('/') };
+  return { opaque: false, path: [...parts, base.slice(4)].join('/') };
+}
+
+// Decompresses a gzip member with a hard output-size cap (Node's native
+// ERR_BUFFER_TOO_LARGE on overflow — no custom streaming counter needed).
+// Returns the input unchanged when it isn't gzip-magic (plain tar).
+export function decompressIfGzip(buf, limits = DEFAULT_LIMITS) {
+  if (buf.length >= 2 && buf[0] === 0x1f && buf[1] === 0x8b) {
+    try {
+      return zlib.gunzipSync(buf, { maxOutputLength: limits.maxGunzipOutput });
+    } catch (err) {
+      if (err && err.code === 'ERR_BUFFER_TOO_LARGE') {
+        throw new TarSafetyError('decompressed layer exceeds the decompression-bomb guard', 'gunzip_too_large');
+      }
+      throw new TarSafetyError(`gzip stream is malformed: ${err.message}`, 'gunzip_malformed');
+    }
+  }
+  return buf;
+}
+
+/**
+ * Reads a decompressed tar buffer and yields one record per entry:
+ *   { name, size, typeflag, linkname, data, unsafe }
+ * `data` is a Buffer view into `buf` (never copied) for safe entries, `null`
+ * for unsafe ones. Throws TarSafetyError (never returns a partial result) the
+ * moment any configured limit is exceeded.
+ */
+export function* readTarEntries(buf, limits = DEFAULT_LIMITS) {
+  if (!Buffer.isBuffer(buf)) throw new TarSafetyError('tar input must be a Buffer', 'bad_input');
+  let offset = 0;
+  let count = 0;
+  let totalSize = 0;
+  let pendingLongName = null;
+
+  while (offset + BLOCK <= buf.length) {
+    const header = buf.subarray(offset, offset + BLOCK);
+    if (header.every((b) => b === 0)) {
+      offset += BLOCK;
+      continue; // end-of-archive zero-fill padding
+    }
+
+    count += 1;
+    if (count > limits.maxEntries) {
+      throw new TarSafetyError(`tar archive has more than ${limits.maxEntries} entries`, 'too_many_entries');
+    }
+
+    let name = cstr(header.subarray(0, 100));
+    const typeflag = String.fromCharCode(header[156] || 0);
+    const linkname = cstr(header.subarray(157, 257));
+    const magic = header.subarray(257, 263).toString('ascii');
+    const prefix = magic.startsWith('ustar') ? cstr(header.subarray(345, 500)) : '';
+    if (prefix) name = `${prefix}/${name}`;
+    const size = parseSizeField(header.subarray(124, 136));
+
+    offset += BLOCK;
+
+    if (size < 0 || !Number.isFinite(size)) {
+      throw new TarSafetyError(`tar entry "${name}" has an invalid size field`, 'bad_size');
+    }
+    if (size > limits.maxEntrySize) {
+      throw new TarSafetyError(`tar entry "${name}" (${size} bytes) exceeds the per-entry size limit`, 'entry_too_large');
+    }
+    totalSize += size;
+    if (totalSize > limits.maxTotalSize) {
+      throw new TarSafetyError('tar archive exceeds the total-size limit', 'archive_too_large');
+    }
+
+    const dataBlocks = Math.ceil(size / BLOCK);
+    if (offset + size > buf.length) {
+      throw new TarSafetyError(`tar entry "${name}" claims more data than the archive contains`, 'truncated');
+    }
+    const data = size > 0 ? buf.subarray(offset, offset + size) : Buffer.alloc(0);
+    offset += dataBlocks * BLOCK;
+
+    const resolvedName = pendingLongName ? pendingLongName : name;
+    pendingLongName = null;
+
+    if (typeflag === 'L') {
+      // GNU longname: this entry's data IS the next entry's real name.
+      pendingLongName = cstr(data);
+      continue;
+    }
+    if (typeflag === 'K' || typeflag === 'x' || typeflag === 'g') {
+      // GNU longlink / PAX extended header — structurally skipped (see header comment).
+      continue;
+    }
+
+    if (!isSafeEntryName(resolvedName)) {
+      yield { name: resolvedName, size, typeflag, linkname, data: null, unsafe: true };
+      continue;
+    }
+
+    yield { name: resolvedName.replace(/\\/g, '/'), size, typeflag, linkname, data, unsafe: false };
+  }
+}

package/src/artifact/signature.js

@@ -0,0 +1,156 @@
+// PRD 5 P0 §5 — Signature Verification. States are exactly the PRD's own
+// four, deliberately different from `sca/sigstore-verify.js`'s own vocabulary
+// (`verified/unverified/tampered/unknown`) so the two are never confused by
+// shared words — see docs/implementation-status/source-to-artifact-provenance.md's
+// naming-discipline section:
+//
+//   verified    — a real cryptographic check ran and the signature matches.
+//   invalid     — a real cryptographic check ran and the signature does NOT match.
+//   missing     — no signature/attestation material was supplied at all.
+//   unavailable — material was supplied but could not be cryptographically
+//                 checked (no public key given, or the check itself could
+//                 not run) — the PRD's "never treat missing tooling as
+//                 verified" clause means this state, not `verified`, is what
+//                 an incomplete check must report.
+//
+// Two real, independent mechanisms are implemented:
+//   1. A plain detached signature over the image digest string, verified
+//      with an operator-supplied public key. This is this tool's OWN local
+//      convention, not cosign's "simple signing" JSON format — disclosed in
+//      the implementation-status doc, not silently passed off as cosign-
+//      compatible.
+//   2. Real DSSE (Dead Simple Signing Envelope) verification for in-toto/SLSA
+//      provenance attestations — the actual encoding cosign/Sigstore use for
+//      attestations, so a real cosign-keyed attestation bundle DOES verify
+//      here given the matching public key. `dssePae` is the exact PAE
+//      (Pre-Authentication Encoding) from the DSSE spec.
+//
+// Keyless/Rekor-transparency-log verification is NOT implemented — disclosed
+// as a gap, never faked. `sca/sigstore-verify.js`'s Rekor-query pattern is
+// the template a future increment could extend this module with.
+import crypto from 'node:crypto';
+
+export const SIGNATURE_STATES = Object.freeze(['verified', 'invalid', 'missing', 'unavailable']);
+
+function verifyRaw(payload, signature, publicKeyPem) {
+  let publicKey;
+  try {
+    publicKey = crypto.createPublicKey(publicKeyPem);
+  } catch (err) {
+    return { ok: false, error: `public key is not parseable: ${err.message}` };
+  }
+  const keyType = publicKey.asymmetricKeyType;
+  const algorithm = (keyType === 'ed25519' || keyType === 'ed448') ? null : 'sha256';
+  try {
+    const ok = crypto.verify(algorithm, payload, publicKey, signature);
+    return { ok, keyType };
+  } catch (err) {
+    return { ok: false, error: `signature verification failed to run: ${err.message}` };
+  }
+}
+
+/**
+ * Verifies a detached signature over an image's digest string.
+ * `signature`/`publicKeyPem` are Buffer/PEM-string; either missing means
+ * `missing` (nothing was supplied to check).
+ */
+export function verifyImageSignature({ digest, signature, publicKeyPem }) {
+  if (typeof digest !== 'string' || !digest.startsWith('sha256:')) {
+    return { state: 'unavailable', reason: 'no image digest available to verify a signature against' };
+  }
+  if (!signature || !publicKeyPem) {
+    return { state: 'missing', reason: 'no detached signature and public key were supplied for this image' };
+  }
+  const { ok, error, keyType } = verifyRaw(Buffer.from(digest, 'utf8'), signature, publicKeyPem);
+  if (error) return { state: 'invalid', reason: error };
+  return ok
+    ? { state: 'verified', keyType }
+    : { state: 'invalid', reason: 'signature does not match the image digest under the supplied public key' };
+}
+
+// DSSE Pre-Authentication Encoding: "DSSEv1" SP LEN(type) SP type SP LEN(body) SP body.
+function dssePae(payloadType, payloadBytes) {
+  const typeBytes = Buffer.from(payloadType, 'utf8');
+  return Buffer.concat([
+    Buffer.from('DSSEv1 ', 'ascii'),
+    Buffer.from(String(typeBytes.length), 'ascii'),
+    Buffer.from(' ', 'ascii'),
+    typeBytes,
+    Buffer.from(' ', 'ascii'),
+    Buffer.from(String(payloadBytes.length), 'ascii'),
+    Buffer.from(' ', 'ascii'),
+    payloadBytes,
+  ]);
+}
+
+const SLSA_PREDICATE_PREFIX = 'https://slsa.dev/provenance/';
+const INTOTO_STATEMENT_TYPES = new Set(['https://in-toto.io/Statement/v0.1', 'https://in-toto.io/Statement/v1']);
+
+/**
+ * Verifies an in-toto/SLSA provenance attestation for an image.
+ * `envelope` is a DSSE envelope: `{ payloadType, payload (base64 in-toto
+ * Statement JSON), signatures: [{ sig (base64) }] }` — the real shape
+ * cosign/Sigstore attestations use. `publicKeyPem` verifies one of
+ * `signatures` against `dssePae(payloadType, payload)`.
+ *
+ * The subject-digest match is checked FIRST and independently of signature
+ * verification, so a mismatched subject is always `invalid` (never
+ * "unavailable", which would understate a real, checkable problem).
+ */
+export function verifyProvenanceAttestation({ digest, envelope, publicKeyPem }) {
+  if (!envelope) return { state: 'missing', reason: 'no in-toto/SLSA provenance attestation was supplied for this image' };
+
+  let env;
+  try {
+    env = typeof envelope === 'string' ? JSON.parse(envelope) : envelope;
+  } catch (err) {
+    return { state: 'invalid', reason: `attestation envelope is not valid JSON: ${err.message}` };
+  }
+  if (typeof env.payload !== 'string' || typeof env.payloadType !== 'string' || !Array.isArray(env.signatures)) {
+    return { state: 'invalid', reason: 'not a recognized DSSE envelope (missing payload, payloadType, or signatures)' };
+  }
+
+  let payloadBytes;
+  let stmt;
+  try {
+    payloadBytes = Buffer.from(env.payload, 'base64');
+    stmt = JSON.parse(payloadBytes.toString('utf8'));
+  } catch (err) {
+    return { state: 'invalid', reason: `attestation payload is not a valid base64-encoded JSON statement: ${err.message}` };
+  }
+  if (!INTOTO_STATEMENT_TYPES.has(stmt._type)) {
+    return { state: 'invalid', reason: 'statement is missing a recognized in-toto "_type"' };
+  }
+
+  const digestHex = typeof digest === 'string' && digest.startsWith('sha256:') ? digest.slice('sha256:'.length) : digest;
+  const subjects = Array.isArray(stmt.subject) ? stmt.subject : [];
+  const subjectMatches = subjects.some((s) => s && s.digest && s.digest.sha256 === digestHex);
+  if (!subjectMatches) {
+    return { state: 'invalid', reason: 'attestation subject digest does not match this image', predicateType: stmt.predicateType || null };
+  }
+
+  const predicateType = stmt.predicateType || null;
+  const isSlsa = typeof predicateType === 'string' && predicateType.startsWith(SLSA_PREDICATE_PREFIX);
+
+  if (!publicKeyPem || env.signatures.length === 0) {
+    return {
+      state: 'unavailable',
+      reason: 'attestation subject matches this image, but no public key was supplied to verify its signature',
+      predicateType, isSlsa,
+    };
+  }
+
+  const pae = dssePae(env.payloadType, payloadBytes);
+  for (const sigEntry of env.signatures) {
+    if (!sigEntry || typeof sigEntry.sig !== 'string') continue;
+    let sigBytes;
+    try {
+      sigBytes = Buffer.from(sigEntry.sig, 'base64');
+    } catch {
+      continue;
+    }
+    const { ok } = verifyRaw(pae, sigBytes, publicKeyPem);
+    if (ok) return { state: 'verified', predicateType, isSlsa };
+  }
+  return { state: 'invalid', reason: 'no signature in the attestation envelope verifies under the supplied public key', predicateType, isSlsa };
+}

package/src/artifact/vex.js

@@ -0,0 +1,94 @@
+// PRD 5 P0 §8 — VEX (Vulnerability Exploitability eXchange). Statuses are the
+// PRD's own four. The PRD's one explicit rule — "`not affected` requires
+// positive evidence" — is enforced structurally: `not_affected` is only ever
+// returned from one of two named, checked evidence paths below; there is no
+// code path that reaches it by default or by absence of information.
+// Justification strings follow the CISA VEX vocabulary this repo's other VEX
+// output (`toVex` in `src/posture/sbom.js`'s neighborhood) already uses,
+// where applicable.
+//
+// `affected` likewise requires positive evidence (confirmed reachability),
+// not just "OSV lists this version as vulnerable" — a scanner result alone
+// only tells you the CVE/version pair matches; it doesn't tell you the
+// vulnerable code path is reachable in THIS artifact. Absent that
+// confirmation, the honest status is `under_investigation`, never a
+// confident `affected` the evidence doesn't support.
+export const VEX_STATUSES = Object.freeze(['affected', 'not_affected', 'fixed', 'under_investigation']);
+
+// Loose dotted-numeric version comparison. Returns -1/0/1, or null when
+// either side isn't a clean dotted-numeric form — a "fixed" verdict is only
+// ever returned when this does NOT return null; an unparseable version
+// means that evidence path is skipped, never guessed through.
+function compareVersions(a, b) {
+  const pa = String(a).split(/[.-]/).map((s) => (/^\d+$/.test(s) ? parseInt(s, 10) : null));
+  const pb = String(b).split(/[.-]/).map((s) => (/^\d+$/.test(s) ? parseInt(s, 10) : null));
+  if (pa.some((n) => n === null) || pb.some((n) => n === null)) return null;
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const x = pa[i] ?? 0;
+    const y = pb[i] ?? 0;
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
+function componentKeyOf(c) {
+  return c.purl || (c.ecosystem && c.name && c.version ? `${c.ecosystem}:${c.name}@${c.version}` : null);
+}
+
+/**
+ * `vulnerability` is one `vulnerable_dep`-shaped entry already confirmed
+ * present via `vuln-correlate.js` against THIS artifact. `artifactComponents`
+ * is the artifact's own inventory (`osPackages`/`appPackages` concatenated).
+ * `reachability`, if supplied, is `{ reachable: true|false, reason }` from
+ * this codebase's existing dataflow/reachability evidence (never computed
+ * here — this module does no new analysis, only statuses the evidence it's
+ * handed).
+ */
+export function deriveVexStatus({ vulnerability, artifactComponents, reachability = null }) {
+  if (!vulnerability || typeof vulnerability !== 'object') {
+    throw new TypeError('deriveVexStatus requires a vulnerability object');
+  }
+  if (!Array.isArray(artifactComponents)) {
+    throw new TypeError('deriveVexStatus requires an artifactComponents array');
+  }
+
+  const vulnKey = vulnerability.purl
+    || (vulnerability.ecosystem && vulnerability.name && vulnerability.version ? `${vulnerability.ecosystem}:${vulnerability.name}@${vulnerability.version}` : null);
+  const present = vulnKey != null && artifactComponents.some((c) => componentKeyOf(c) === vulnKey);
+
+  if (!present) {
+    return {
+      status: 'not_affected',
+      justification: 'component_not_present',
+      evidence: 'the affected component (by purl/ecosystem+name+version) is not present in this artifact\'s inventory',
+    };
+  }
+
+  if (reachability && reachability.reachable === false) {
+    return {
+      status: 'not_affected',
+      justification: 'vulnerable_code_not_in_execute_path',
+      evidence: reachability.reason || 'static reachability analysis found no path to the vulnerable function in this artifact',
+    };
+  }
+
+  if (Array.isArray(vulnerability.fixedVersions) && vulnerability.fixedVersions.length && vulnerability.version) {
+    for (const fv of vulnerability.fixedVersions) {
+      const cmp = compareVersions(vulnerability.version, fv);
+      if (cmp !== null && cmp >= 0) {
+        return { status: 'fixed', justification: null, evidence: `installed version ${vulnerability.version} is >= the fixed version ${fv}` };
+      }
+    }
+  }
+
+  if (reachability && reachability.reachable === true) {
+    return { status: 'affected', justification: null, evidence: reachability.reason || 'static reachability analysis confirmed a path to the vulnerable function in this artifact' };
+  }
+
+  return {
+    status: 'under_investigation',
+    justification: null,
+    evidence: 'the affected component is present and not confirmed fixed, but reachability has not been established — not a confident "affected" claim',
+  };
+}

package/src/artifact/vuln-correlate.js

@@ -0,0 +1,17 @@
+// PRD 5 P0 §4 — Container Vulnerability Analysis. "Reuse current SCA
+// semantics where technically valid": this module does nothing but hand an
+// image's OS + application package inventory to the engine's existing
+// OSV/KEV/EPSS query path (`queryOSV`, imported via `src/sca/index.js`),
+// exactly as every other SCA finding in this codebase gets its CVE data.
+// `queryOSVFn` is injected (not imported directly) so this module's own
+// tests never make a real network call and stay independent of engine.js's
+// load cost; the CLI wiring passes the real `queryOSV`.
+export async function correlateImageVulnerabilities({ inventory, fileContents, queryOSVFn }) {
+  if (typeof queryOSVFn !== 'function') throw new TypeError('correlateImageVulnerabilities requires queryOSVFn(components, allFileContents)');
+  if (!inventory || !Array.isArray(inventory.osPackages) || !Array.isArray(inventory.appPackages)) {
+    throw new TypeError('correlateImageVulnerabilities requires an inventory with osPackages/appPackages arrays');
+  }
+  const components = [...inventory.osPackages, ...inventory.appPackages];
+  const vulnerabilities = await queryOSVFn(components, fileContents || {});
+  return { components, vulnerabilities };
+}

package/src/lineage/CLAUDE.md

@@ -946,6 +946,25 @@ layer, without collecting a single payload value.
 | `coverage.js` / `index.js` (extended, additively) | `buildGraphWithCoverage` composes a default `correlateObservations` closure over a **pre-loaded** `opts.runtimeObservations` array (never a raw path); `index.js` performs the ONE read per `buildLineageGraph` call (`fs.existsSync(dir) ? loadObservations(scanRoot) : null` — the `null` is deliberate, see below). |
 | `bin/agentic-security.js` (`dataflow observations import\|list`, `dataflow twin`) | The AC-29 proof surface — see `commands/dataflow.md`'s own `## Runtime observations (FR-505)` / `## Runtime Digital Twin layers (AC-29)` sections for the full CLI reference. `observations import` is dry-run-by-default and refuses the WHOLE import on any rejected record; `observations list` never prints an attribute key or value; `dataflow twin` is read-only and never writes into `.agentic-security/`. |
 
+### PRD "Runtime-Corroborated Security Twin" addendum (2026-10-13) — closes the real telemetry-input gap
+
+`observation-adapters.js` gained four more adapters alongside `native-jsonl`: `otel-json`
+(OpenTelemetry JSON trace export, one draft per span), `envoy-access-log` (Envoy's default JSON
+access log, `response_flags` → the new `network.securityDecision` attribute), `k8s-audit-log`
+(Kubernetes `audit.k8s.io` JSONL — `objectRef`/`responseStatus.code`, deliberately never
+`user.username`), `http-access-log` (generic JSON-lines access log). All four are pure (zero
+imports) and follow the exact same `(text, context) -> {drafts, errors}` contract, dropping every
+field with no safe, approved destination. `runtime-observation.js` gained exactly one new attribute
+key, `network.securityDecision` (a closed `allowed|denied` enum, deliberately narrower than the
+generic identifier-value grammar every other key gets) — no identity field was added; that remains
+a deliberate, disclosed omission. `runtime-assurance.js` (new) reports `runtimeStatus:
+complete|partial|unavailable`, read by the new top-level `runtime` CLI (`runtime ingest/status/
+reconcile/query`, `commands/runtime.md`) — `ingest` shims the existing `dataflow observations
+import`, the rest are new but read-only over the existing correlation/store functions. The 3-rung
+match ladder, the 3-valued `OBSERVATION_LAYERS`, and the server/UI deferral above are ALL
+unchanged — see `docs/implementation-status/runtime-corroborated-twin.md` for the full scope
+decision and what was deliberately left out.
+
 ### The five AC-29 properties a future UI increment inherits, and must not break
 
 A future UI increment (deferred here — see the out-of-scope list below) sits