@clear-capabilities/agentic-security-scanner 0.175.0 → 0.177.0

package/src/artifact/registry.js

@@ -0,0 +1,213 @@
+// A minimal OCI Distribution (v2) client for ONE purpose: fetching a single image the operator named explicitly
+// (`image scan --registry <ref>`), so it can be scanned like a local archive (PRD 5, requirement 1: "explicit remote OCI reference").
+//
+// It is deliberately small and deliberately strict. It is hostile-input handling first:
+//   * a reference is parsed, not interpolated: no scheme, no userinfo, no whitespace, no path tricks;
+//   * transport is HTTPS. Plain HTTP is accepted only for a loopback registry (a local test or a local mirror); anything else is refused;
+//   * every redirect is followed by hand, at most 5 hops, to an HTTPS (or loopback) target, and the credential is NOT sent to a host
+//     other than the registry's own, which is what keeps a blob redirected to a CDN from receiving it;
+//   * every body is digest-verified against what the manifest said, and size-capped while it streams, so a registry that lies about
+//     a size or sends endless bytes is cut off, not buffered;
+//   * the manifest a registry returns for a tag is hashed and checked against `Docker-Content-Digest` when one is sent, and for a
+//     digest reference against the reference itself;
+//   * credentials come from the environment or the Docker config for that registry only, are never logged, never put in an error,
+//     and live in an object that refuses to serialize.
+// Nothing is executed and nothing is extracted to disk; the result is an OCI-layout archive in memory for `image-archive.js`.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { sha256Hex, buildOciArchive } from './oci-layout.js';
+
+export class RegistryError extends Error {
+  constructor(message, code) { super(message); this.name = 'RegistryError'; this.code = code; }
+}
+
+export const REGISTRY_LIMITS = Object.freeze({ maxManifestBytes: 1024 * 1024, maxConfigBytes: 4 * 1024 * 1024, maxLayerBytes: 512 * 1024 * 1024, maxTotalBytes: 1024 * 1024 * 1024, maxLayers: 128, maxRedirects: 5, requestTimeoutMs: 60_000, totalTimeoutMs: 15 * 60_000 });
+
+const MANIFEST_ACCEPT = [
+  'application/vnd.oci.image.index.v1+json', 'application/vnd.docker.distribution.manifest.list.v2+json',
+  'application/vnd.oci.image.manifest.v1+json', 'application/vnd.docker.distribution.manifest.v2+json',
+].join(', ');
+const INDEX_TYPES = new Set(['application/vnd.oci.image.index.v1+json', 'application/vnd.docker.distribution.manifest.list.v2+json']);
+const MANIFEST_TYPES = new Set(['application/vnd.oci.image.manifest.v1+json', 'application/vnd.docker.distribution.manifest.v2+json']);
+const LOOPBACK_HOST = /^(?:localhost|127(?:\.\d{1,3}){3}|\[::1\])$/i;
+const DIGEST_RE = /^sha256:[0-9a-f]{64}$/;
+
+/** Credentials that cannot be printed: `JSON.stringify`, `String()` and `util.inspect` all give a placeholder. */
+class Credentials {
+  #basic = null; #bearer = null;
+  constructor({ user, password, token }) { if (token) this.#bearer = token; else if (user && password) this.#basic = Buffer.from(`${user}:${password}`).toString('base64'); }
+  get present() { return !!(this.#basic || this.#bearer); }
+  basicHeader() { return this.#basic ? `Basic ${this.#basic}` : null; }
+  bearerHeader() { return this.#bearer ? `Bearer ${this.#bearer}` : null; }
+  toJSON() { return '[credentials]'; }
+  toString() { return '[credentials]'; }
+  [Symbol.for('nodejs.util.inspect.custom')]() { return '[credentials]'; }
+}
+
+/** The registry's own credentials: environment first, then the Docker config entry for exactly this registry. Never another host's. */
+export function resolveCredentials(registry, { env = process.env, dockerConfig = path.join(os.homedir(), '.docker', 'config.json') } = {}) {
+  if (env.AGENTIC_SECURITY_REGISTRY_TOKEN) return new Credentials({ token: env.AGENTIC_SECURITY_REGISTRY_TOKEN });
+  if (env.AGENTIC_SECURITY_REGISTRY_USER && env.AGENTIC_SECURITY_REGISTRY_PASSWORD) return new Credentials({ user: env.AGENTIC_SECURITY_REGISTRY_USER, password: env.AGENTIC_SECURITY_REGISTRY_PASSWORD });
+  try {
+    const cfg = JSON.parse(fs.readFileSync(dockerConfig, 'utf8'));
+    const keys = [registry, `https://${registry}`, ...(registry === 'registry-1.docker.io' ? ['https://index.docker.io/v1/', 'docker.io'] : [])];
+    for (const k of keys) {
+      const auth = cfg.auths?.[k]?.auth;
+      if (typeof auth === 'string') { const [user, ...rest] = Buffer.from(auth, 'base64').toString('utf8').split(':'); if (user && rest.length) return new Credentials({ user, password: rest.join(':') }); }
+    }
+  } catch { /* no usable Docker config */ }
+  return new Credentials({});
+}
+
+/** @returns {{registry: string, repository: string, reference: string, isDigest: boolean, loopback: boolean}} */
+export function parseReference(input) {
+  const raw = String(input ?? '');
+  if (!raw || raw.length > 300 || /[\s\0\\]/.test(raw) || /^[a-z][a-z0-9+.-]*:\/\//i.test(raw) || raw.includes('@') && !/@sha256:[0-9a-f]{64}$/.test(raw) || raw.includes('..') || raw.startsWith('-')) throw new RegistryError('not a valid image reference', 'bad_reference');
+  let rest = raw; let reference = 'latest'; let isDigest = false;
+  const at = rest.indexOf('@');
+  if (at !== -1) { reference = rest.slice(at + 1); rest = rest.slice(0, at); isDigest = true; }
+  const parts = rest.split('/');
+  let registry = 'registry-1.docker.io';
+  if (parts.length > 1 && (parts[0].includes('.') || parts[0].includes(':') || parts[0] === 'localhost')) registry = parts.shift();
+  let repo = parts.join('/');
+  if (!isDigest) { const colon = repo.lastIndexOf(':'); if (colon !== -1) { reference = repo.slice(colon + 1); repo = repo.slice(0, colon); } }
+  if (registry === 'registry-1.docker.io' && !repo.includes('/')) repo = `library/${repo}`;
+  if (registry === 'docker.io' || registry === 'index.docker.io') registry = 'registry-1.docker.io';
+  if (!/^[a-z0-9]+(?:(?:[._]|__|-+)[a-z0-9]+)*(?:\/[a-z0-9]+(?:(?:[._]|__|-+)[a-z0-9]+)*)*$/.test(repo)) throw new RegistryError('not a valid repository name', 'bad_reference');
+  if (!isDigest && !/^[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}$/.test(reference)) throw new RegistryError('not a valid tag', 'bad_reference');
+  if (isDigest && !DIGEST_RE.test(reference)) throw new RegistryError('only sha256 digests are supported', 'bad_reference');
+  if (!/^(?:\[::1\]|[A-Za-z0-9](?:[A-Za-z0-9.-]{0,251}[A-Za-z0-9])?)(?::\d{1,5})?$/.test(registry)) throw new RegistryError('not a valid registry host', 'bad_reference');
+  const host = registry.replace(/:\d+$/, '');
+  return { registry, repository: repo, reference, isDigest, loopback: LOOPBACK_HOST.test(host) };
+}
+
+const scrubUrl = (u) => { try { const x = new URL(u); return `${x.protocol}//${x.host}${x.pathname}`; } catch { return '[url]'; } };
+
+export async function fetchImage(input, { platform = 'linux/amd64', credentials = null, fetchImpl = globalThis.fetch, limits = REGISTRY_LIMITS, signal = null, env = process.env, allowLoopbackHttp = false } = {}) {
+  const ref = parseReference(input);
+  const L = { ...REGISTRY_LIMITS, ...limits };
+  const creds = credentials ?? resolveCredentials(ref.registry, { env });
+  const scheme = ref.loopback && allowLoopbackHttp ? 'http' : 'https';
+  const origin = `${scheme}://${ref.registry}`;
+  const deadline = Date.now() + L.totalTimeoutMs;
+  let authHeader = null; let total = 0;
+  const allowedUrl = (u) => { try { const x = new URL(u); return x.protocol === 'https:' || (x.protocol === 'http:' && LOOPBACK_HOST.test(x.hostname)); } catch { return false; } };
+
+  async function request(url, { accept, auth = true, maxBytes, expectDigest = null } = {}) {
+    let current = url; let sendAuth = auth;
+    for (let hop = 0; hop <= L.maxRedirects; hop++) {
+      if (!allowedUrl(current)) throw new RegistryError(`refusing a non-HTTPS target: ${scrubUrl(current)}`, 'insecure_transport');
+      if (Date.now() > deadline) throw new RegistryError('the total time budget was exhausted', 'timeout');
+      if (signal?.aborted) throw new RegistryError('the request was cancelled', 'network');
+      const sameOrigin = new URL(current).origin === new URL(origin).origin;
+      const headers = { 'user-agent': 'agentic-security-image-scan', ...(accept ? { accept } : {}) };
+      if (sendAuth && sameOrigin) { const h = authHeader ?? creds.bearerHeader(); if (h) headers.authorization = h; }
+      const ctl = new AbortController();
+      const t = setTimeout(() => ctl.abort(), L.requestTimeoutMs);
+      const onAbort = () => ctl.abort(); signal?.addEventListener('abort', onAbort, { once: true });
+      let res;
+      try { res = await fetchImpl(current, { headers, redirect: 'manual', signal: ctl.signal }); }
+      catch (e) { throw new RegistryError(ctl.signal.aborted ? 'the request timed out or was cancelled' : `request failed: ${String(e.cause?.code ?? e.code ?? e.message).slice(0, 80)}`, 'network'); }
+      finally { clearTimeout(t); signal?.removeEventListener('abort', onAbort); }
+      if (res.status >= 300 && res.status < 400 && res.headers.get('location')) {
+        const next = new URL(res.headers.get('location'), current).toString();
+        if (new URL(next).origin !== new URL(origin).origin) sendAuth = false; // never carry the registry credential to another host
+        current = next; continue;
+      }
+      if (res.status === 401 && sameOrigin && !authHeader) return { status: 401, challenge: res.headers.get('www-authenticate') ?? '' };
+      if (res.status === 404) throw new RegistryError('not found in the registry', 'not_found');
+      if (res.status === 401 || res.status === 403) throw new RegistryError('the registry refused access (authentication required or not permitted)', 'unauthorized');
+      if (!res.ok) throw new RegistryError(`the registry answered ${res.status}`, 'registry_error');
+      const declared = Number(res.headers.get('content-length'));
+      if (Number.isFinite(declared) && declared > maxBytes) throw new RegistryError(`a response larger than the ${maxBytes}-byte limit`, 'too_large');
+      const chunks = []; let got = 0;
+      for await (const c of res.body) {
+        got += c.length; total += c.length;
+        if (got > maxBytes || total > L.maxTotalBytes) { try { await res.body.cancel(); } catch { /* closing */ } throw new RegistryError('the response exceeded its size limit', 'too_large'); }
+        chunks.push(c);
+      }
+      const body = Buffer.concat(chunks);
+      if (expectDigest && `sha256:${sha256Hex(body)}` !== expectDigest) throw new RegistryError('a downloaded blob does not match its digest', 'digest_mismatch');
+      return { status: res.status, body, headers: res.headers };
+    }
+    throw new RegistryError('too many redirects', 'redirect_loop');
+  }
+
+  async function authed(url, opts) {
+    let r = await request(url, opts);
+    if (r.status !== 401) return r;
+    const basic = creds.basicHeader();
+    if (/^Basic\b/i.test(r.challenge)) {
+      if (!basic) throw new RegistryError('the registry requires authentication and none is configured', 'unauthorized');
+      authHeader = basic;
+      r = await request(url, opts);
+      if (r.status === 401) throw new RegistryError('the registry rejected the credentials', 'unauthorized');
+      return r;
+    }
+    const m = /^Bearer\s+(.*)$/i.exec(r.challenge);
+    if (!m) throw new RegistryError(basic ? 'the registry asked for a scheme this client does not support' : 'the registry requires authentication and none is configured', 'unauthorized');
+    const params = Object.fromEntries([...m[1].matchAll(/(\w+)="([^"]*)"/g)].map((x) => [x[1], x[2]]));
+    if (!params.realm) throw new RegistryError('the authentication challenge named no token endpoint', 'unauthorized');
+    const tokenUrl = new URL(params.realm);
+    if (params.service) tokenUrl.searchParams.set('service', params.service);
+    tokenUrl.searchParams.set('scope', params.scope || `repository:${ref.repository}:pull`);
+    if (!allowedUrl(tokenUrl.toString())) throw new RegistryError('refusing a non-HTTPS token endpoint', 'insecure_transport');
+    // the token endpoint may be a different host (Docker Hub's is); the registry credential goes only to the host the challenge named, over HTTPS
+    const headers = { 'user-agent': 'agentic-security-image-scan', ...(basic ? { authorization: basic } : {}) };
+    let tr;
+    try { tr = await fetchImpl(tokenUrl.toString(), { headers, redirect: 'error' }); } catch { throw new RegistryError('the token request failed', 'network'); }
+    if (!tr.ok) throw new RegistryError(`the token endpoint answered ${tr.status}`, 'unauthorized');
+    let tj; try { tj = JSON.parse((await tr.text()).slice(0, 65536)); } catch { throw new RegistryError('the token endpoint returned something that is not JSON', 'unauthorized'); }
+    const token = tj.token ?? tj.access_token;
+    if (typeof token !== 'string' || !token) throw new RegistryError('the token endpoint returned no token', 'unauthorized');
+    authHeader = `Bearer ${token}`;
+    r = await request(url, opts);
+    if (r.status === 401) throw new RegistryError('the registry rejected the token', 'unauthorized');
+    return r;
+  }
+
+  const base = `${origin}/v2/${ref.repository}`;
+  let m = await authed(`${base}/manifests/${ref.reference}`, { accept: MANIFEST_ACCEPT, maxBytes: L.maxManifestBytes, ...(ref.isDigest ? { expectDigest: ref.reference } : {}) });
+  let manifestBytes = m.body;
+  const topDigest = `sha256:${sha256Hex(m.body)}`;
+  const headerDigest = m.headers.get('docker-content-digest');
+  if (headerDigest && headerDigest !== `sha256:${sha256Hex(manifestBytes)}`) throw new RegistryError('the manifest does not match the digest the registry reported for it', 'digest_mismatch');
+  let doc = parseJson(manifestBytes, 'manifest');
+  let mediaType = doc.mediaType ?? m.headers.get('content-type')?.split(';')[0];
+  let selected = null;
+  if (INDEX_TYPES.has(mediaType) || Array.isArray(doc.manifests)) {
+    const [os_, arch] = platform.split('/');
+    const entries = (doc.manifests ?? []).filter((e) => e?.platform && e.platform.os === os_ && e.platform.architecture === arch && DIGEST_RE.test(String(e.digest)));
+    if (!entries.length) throw new RegistryError(`the image has no ${platform} variant (available: ${(doc.manifests ?? []).map((e) => `${e?.platform?.os}/${e?.platform?.architecture}`).filter((x) => !x.includes('undefined')).slice(0, 12).join(', ') || 'none'})`, 'platform_not_found');
+    selected = entries[0];
+    m = await authed(`${base}/manifests/${selected.digest}`, { accept: MANIFEST_ACCEPT, maxBytes: L.maxManifestBytes, expectDigest: selected.digest });
+    manifestBytes = m.body; doc = parseJson(manifestBytes, 'platform manifest'); mediaType = doc.mediaType ?? selected.mediaType;
+  }
+  if (!MANIFEST_TYPES.has(mediaType) && !(Array.isArray(doc.layers) && doc.config)) throw new RegistryError('the registry returned a manifest of a kind this client does not read', 'unsupported_manifest');
+  if (!doc.config || !DIGEST_RE.test(String(doc.config.digest)) || !Array.isArray(doc.layers)) throw new RegistryError('the manifest is malformed', 'malformed_manifest');
+  if (doc.layers.length > L.maxLayers) throw new RegistryError(`the image has more than ${L.maxLayers} layers`, 'too_large');
+  for (const l of doc.layers) {
+    if (!DIGEST_RE.test(String(l.digest))) throw new RegistryError('a layer has no sha256 digest', 'malformed_manifest');
+    if (/foreign|nondistributable/i.test(String(l.mediaType)) || Array.isArray(l.urls)) throw new RegistryError('the image has a foreign (externally hosted) layer, which is not fetched', 'unsupported_manifest');
+    if (!Number.isInteger(l.size) || l.size < 0 || l.size > L.maxLayerBytes) throw new RegistryError(`a layer is larger than the ${L.maxLayerBytes}-byte limit`, 'too_large');
+  }
+  const blob = async (desc, cap) => {
+    if (Number.isInteger(desc.size) && desc.size > cap) throw new RegistryError('a blob is larger than its limit', 'too_large');
+    const r = await authed(`${base}/blobs/${desc.digest}`, { maxBytes: cap, expectDigest: desc.digest });
+    if (Number.isInteger(desc.size) && r.body.length !== desc.size) throw new RegistryError('a blob is not the size its manifest declared', 'digest_mismatch');
+    return r.body;
+  };
+  const config = await blob(doc.config, L.maxConfigBytes);
+  const layers = [];
+  for (const l of doc.layers) layers.push(await blob(l, L.maxLayerBytes));
+  const built = buildOciArchive({ manifest: manifestBytes, config, layers, mediaType: MANIFEST_TYPES.has(mediaType) ? mediaType : 'application/vnd.oci.image.manifest.v1+json' });
+  return {
+    tar: built.tar, manifestDigest: built.manifestDigest,
+    source: { kind: 'registry', registry: ref.registry, repository: ref.repository, reference: ref.reference, platform: selected ? `${selected.platform.os}/${selected.platform.architecture}` : null, indexDigest: selected ? topDigest : null, bytes: total, authenticated: creds.present },
+  };
+}
+
+function parseJson(buf, what) {
+  try { const j = JSON.parse(buf.toString('utf8')); if (!j || typeof j !== 'object' || Array.isArray(j)) throw new Error('not an object'); return j; } catch { throw new RegistryError(`the ${what} is not valid JSON`, 'malformed_manifest'); }
+}

package/src/capabilities/tool-registry.js

@@ -43,6 +43,8 @@ export const TOOL_CAPABILITIES = Object.freeze({
   portfolio_progress: read('builds a read-only progress view from a portfolio store, ledger and optional inputs, confined to the session root'),
   apply_fix: mutating('writes verified patches into the project'),
   verify_fix: mutating('runs the project linter and tests and appends fix metrics'),
+  prove_finding: mutating('runs a reproducer in the confined proof environment and writes a proof record'),
+  prove_fix: mutating('replays the original exploit against a copy of the patched sources and runs the project tests; writes nothing to the project'),
   append_scratchpad: mutating('writes under the agent scratchpad'),
   append_agents_memory: mutating('appends to the continual-learning file'),
   synthesize_sca_upgrade: external('runs a package manager dry-run, which may reach a registry'),

package/src/lineage/CLAUDE.md

@@ -1259,3 +1259,7 @@ synthetic root `$hs`, seeds record-parameter sources, and treats `length`/`null`
 field-to-store flows from `language/nix-privacy.js` (a personal-data `config.<module>.<field>` interpolated into another option;
 hashed, measured or compared references are protected and make no flow). Coverage reports `unknown` for both languages: no
 taint-recall tier is borrowed. See `scanner/src/language/CLAUDE.md`.
+
+## Runtime twin additions (PRD 2 gap closure)
+
+`runtime-edge-states.js` derives the six edge states and the identity / absent-from-static queries from the existing correlation, as a pure read: nothing is written into the static graph. `RUNTIME_EXPLOIT_CORRELATED` is never inferred from observation; it needs validated operator evidence. `identity-token.js` supplies a keyed-hash tokenizer injected into the adapters through `context.tokenizeIdentity`; the adapters stay zero-import and drop identity when no tokenizer is given. The attribute allowlist test pins `identity.token`; widen it deliberately, never by loosening the grammar.

package/src/lineage/identity-token.js

@@ -0,0 +1,11 @@
+// A keyed-hash token for an authenticated identity (PRD 2 section 1, "authenticated identity"). The observation contract is closed-world
+// and refuses raw identities, so what is stored is `idt_` + 16 hex of an HMAC under the per-install key:
+//   * the same identity always yields the same token on this install, so "the same identity used these paths" can be answered;
+//   * without the install key the token cannot be reversed or confirmed by guessing usernames (an unkeyed hash could);
+//   * tokens from two installs do not match, which is deliberate: they are not a portable identifier.
+// It is a pseudonym, not anonymity: someone who holds the install key and a candidate username can confirm a match.
+import { signLastScan } from '../posture/integrity.js';
+
+export function makeIdentityTokenizer() {
+  return (raw) => (typeof raw === 'string' && raw.length > 0 ? `idt_${signLastScan(`identity-token:v1:${raw}`).slice(0, 16)}` : null);
+}

package/src/lineage/observation-adapters.js

@@ -305,6 +305,16 @@ function _splitHostPort(v) {
   return { host: _safeIdentifierOrNull(host), port };
 }
 
+// Identity is recorded ONLY as a keyed-hash token, and only when the importer supplied the tokenizer (`context.tokenizeIdentity`).
+// This module stays zero-import and holds no key: with no tokenizer, identity is dropped, never stored raw and never hashed without a
+// key (an unkeyed hash of a username is reversible by guessing). A raw value that is not a plausible identity string is dropped too.
+function _identityToken(context, raw) {
+  if (typeof context?.tokenizeIdentity !== 'function') return null;
+  if (typeof raw !== 'string' || raw.length === 0 || raw.length > 256 || /[\u0000-\u001f]/.test(raw)) return null;
+  const t = context.tokenizeIdentity(raw);
+  return typeof t === 'string' && /^idt_[0-9a-f]{16}$/.test(t) ? t : null;
+}
+
 function _draftBase(context, environmentOverride) {
   const { version, adapter, source, environment, windowStart, windowEnd, importedAt, retention } = context;
   return {
@@ -398,6 +408,7 @@ export function parseOtelJsonObservations(text, context) {
         if (storeService) attributes['destination.service'] = storeService;
 
         if (Object.keys(attributes).length === 0) continue; // nothing safe to report for this span
+        { const idt = _identityToken(context, a['enduser.id']); if (idt) attributes['identity.token'] = idt; }
 
         const at = _isoFromUnixNano(span.startTimeUnixNano) ?? context.windowStart;
         drafts.push({
@@ -547,6 +558,7 @@ export function parseK8sAuditLogObservations(text, context) {
     }
 
     if (Object.keys(attributes).length === 0) continue;
+    { const idt = _identityToken(context, _isPlainObject(record.user) ? record.user.username : undefined); if (idt) attributes['identity.token'] = idt; }
 
     const observedAt = typeof record.requestReceivedTimestamp === 'string' && Number.isFinite(Date.parse(record.requestReceivedTimestamp))
       ? record.requestReceivedTimestamp
@@ -610,6 +622,7 @@ export function parseHttpAccessLogObservations(text, context) {
     if (scheme) attributes['destination.scheme'] = scheme;
 
     if (Object.keys(attributes).length === 0) continue;
+    { const idt = _identityToken(context, record.user ?? record.remote_user ?? record.authenticated_user); if (idt) attributes['identity.token'] = idt; }
 
     const ts = record.timestamp ?? record.time;
     const observedAt = typeof ts === 'string' && Number.isFinite(Date.parse(ts)) ? ts : context.windowStart;

package/src/lineage/runtime-edge-states.js

@@ -0,0 +1,139 @@
+// Edge states and the identity-aware / absent-from-static queries of the Runtime-Corroborated Security Twin (PRD 2: "Edge States",
+// section 6). Pure: no fs, no I/O, never throws, never mutates the graph. It READS what `observation-correlation.js` and the
+// observation store already hold; it adds no second matching engine and writes nothing into the static graph (the overlay stays an
+// overlay).
+//
+// The six states, and when each is ALLOWED to appear:
+//   STATIC_ONLY                no telemetry was consulted at all (not "nothing seen": nothing was looked at)
+//   RUNTIME_NOT_OBSERVED       telemetry was consulted for this environment/window and no trusted observation maps to the edge.
+//                              Never "unreachable": the window may be short, the exporter partial, the mapping weak.
+//   RUNTIME_OBSERVED           at least one high- or medium-confidence observation maps to the edge
+//   RUNTIME_BLOCKED           observations map to the edge and every decision recorded for them was `denied` (the path was
+//                              attempted and refused); an edge with both allowed and denied observations carries OBSERVED and BLOCKED
+//   RUNTIME_POLICY_VIOLATION   the edge was observed (not only denied) AND a flow through it is `prohibited` by the privacy policy
+//   RUNTIME_EXPLOIT_CORRELATED the edge was observed AND the operator supplied explicit evidence naming this edge/flow/node as the
+//                              target of a proven exploit. Never inferred from observation alone: seeing traffic is not seeing an attack.
+// Low-confidence and ambiguous observations (PRD: "low-confidence observations remain unmatched") never create a state; they are
+// counted in `uncertainObservations` so the weakness is visible instead of silently dropped.
+export const EDGE_STATES = Object.freeze(['STATIC_ONLY', 'RUNTIME_NOT_OBSERVED', 'RUNTIME_OBSERVED', 'RUNTIME_BLOCKED', 'RUNTIME_POLICY_VIOLATION', 'RUNTIME_EXPLOIT_CORRELATED']);
+const SEVERITY_ORDER = ['RUNTIME_EXPLOIT_CORRELATED', 'RUNTIME_POLICY_VIOLATION', 'RUNTIME_BLOCKED', 'RUNTIME_OBSERVED', 'RUNTIME_NOT_OBSERVED', 'STATIC_ONLY'];
+const TRUSTED = new Set(['high', 'medium']);
+
+const arr = (v) => (Array.isArray(v) ? v : []);
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+
+/** Operator-supplied exploit evidence: [{ kind, id, edgeId?|flowId?|nodeId? }]. Anything malformed is reported, not trusted. */
+export function validateExploitEvidence(list) {
+  const errors = []; const ok = [];
+  if (list === null || list === undefined) return { evidence: [], errors };
+  if (!Array.isArray(list)) return { evidence: [], errors: ['exploit evidence must be an array'] };
+  list.forEach((e, i) => {
+    if (!isObj(e) || typeof e.id !== 'string' || !e.id || !['proof', 'dnr-hunt', 'incident'].includes(e.kind)) { errors.push(`entry ${i}: needs kind (proof|dnr-hunt|incident) and id`); return; }
+    const targets = ['edgeId', 'flowId', 'nodeId'].filter((k) => typeof e[k] === 'string' && e[k]);
+    if (targets.length !== 1) { errors.push(`entry ${i}: name exactly one of edgeId, flowId, nodeId`); return; }
+    ok.push({ kind: e.kind, id: e.id.slice(0, 120), [targets[0]]: e[targets[0]] });
+  });
+  return { evidence: ok, errors };
+}
+
+/**
+ * @returns {{ evaluated: boolean, byNode: Record<string, {states: string[], observations: number, allowed: number, denied: number}>, byEdge: Record<string, {states: string[], primary: string, observations: number, allowed: number, denied: number, uncertainObservations: number, identityTokens: string[], exploitEvidence: object[], note: string}>, counts: Record<string, number>, limitations: string[] }}
+ */
+export function deriveEdgeStates(graph, correlation, observations, { exploitEvidence = [] } = {}) {
+  const edges = arr(graph?.edges).filter((e) => isObj(e) && typeof e.id === 'string');
+  const flows = arr(graph?.flows).filter((f) => isObj(f) && typeof f.id === 'string');
+  const evaluated = !!correlation?.evaluated;
+  const considered = new Set(arr(correlation?.consideredObservationIds));
+  const byEdge = {}; const counts = Object.fromEntries(EDGE_STATES.map((s) => [s, 0]));
+  const limitations = [
+    'RUNTIME_NOT_OBSERVED means "no trusted observation in this window", never "unreachable" or "safe".',
+    'Only high- and medium-confidence mappings count; low-confidence and ambiguous observations stay unmatched and are counted as uncertain.',
+    'RUNTIME_EXPLOIT_CORRELATED requires explicit operator-supplied evidence naming the edge, flow or node; observation alone never sets it.',
+  ];
+  const flowsByEdge = new Map();
+  for (const f of flows) for (const eid of arr(f.edgeIds)) { const a = flowsByEdge.get(eid) ?? []; a.push(f); flowsByEdge.set(eid, a); }
+  const obsByEdge = new Map();
+  for (const o of arr(observations)) {
+    if (!isObj(o) || (evaluated && considered.size && !considered.has(o.id))) continue;
+    for (const eid of arr(o.matchedEdgeIds)) { const a = obsByEdge.get(eid) ?? []; a.push(o); obsByEdge.set(eid, a); }
+  }
+  for (const e of edges) {
+    if (!evaluated) { byEdge[e.id] = entry(['STATIC_ONLY'], { note: 'no telemetry was consulted' }); counts.STATIC_ONLY++; continue; }
+    const all = obsByEdge.get(e.id) ?? [];
+    const trusted = all.filter((o) => TRUSTED.has(o.matchConfidence));
+    const uncertain = all.length - trusted.length;
+    if (!trusted.length) { byEdge[e.id] = entry(['RUNTIME_NOT_OBSERVED'], { uncertain, note: uncertain ? `${uncertain} low-confidence observation(s) not counted` : 'no observation in this window' }); counts.RUNTIME_NOT_OBSERVED++; continue; }
+    const dec = (o) => o.attributes?.['network.securityDecision'];
+    const allowed = trusted.filter((o) => dec(o) === 'allowed').length; const denied = trusted.filter((o) => dec(o) === 'denied').length;
+    const states = [];
+    const onlyDenied = denied > 0 && allowed === 0 && trusted.every((o) => dec(o) === 'denied');
+    if (!onlyDenied) states.push('RUNTIME_OBSERVED');
+    if (denied > 0) states.push('RUNTIME_BLOCKED');
+    const prohibited = flowsByEdge.get(e.id)?.some((f) => f.policyVerdict === 'prohibited');
+    if (!onlyDenied && prohibited) states.push('RUNTIME_POLICY_VIOLATION');
+    const flowIds = new Set((flowsByEdge.get(e.id) ?? []).map((f) => f.id));
+    const nodeIds = new Set([e.source, e.target, e.from, e.to].filter(Boolean));
+    const ev = arr(exploitEvidence).filter((x) => x.edgeId === e.id || (x.flowId && flowIds.has(x.flowId)) || (x.nodeId && nodeIds.has(x.nodeId)));
+    if (!onlyDenied && ev.length) states.push('RUNTIME_EXPLOIT_CORRELATED');
+    const tokens = [...new Set(trusted.map((o) => o.attributes?.['identity.token']).filter(Boolean))].sort();
+    byEdge[e.id] = entry(states, { observations: trusted.length, allowed, denied, uncertain, tokens, ev, note: '' });
+    for (const s of states) counts[s]++;
+  }
+  // Observations the matcher placed on a NODE but on no edge or flow (a queue publish, a store write with no modelled path into it).
+  // They still carry the allow/deny fact, so the refused queue publish is visible instead of vanishing between edge and node.
+  const byNode = {};
+  if (evaluated) {
+    const perNode = new Map();
+    for (const o of arr(observations)) {
+      if (!isObj(o) || (considered.size && !considered.has(o.id)) || !TRUSTED.has(o.matchConfidence) || arr(o.matchedEdgeIds).length) continue;
+      for (const nid of arr(o.matchedNodeIds)) { const a = perNode.get(nid) ?? []; a.push(o); perNode.set(nid, a); }
+    }
+    for (const [nid, list] of perNode) {
+      const dec = (o) => o.attributes?.['network.securityDecision'];
+      const denied = list.filter((o) => dec(o) === 'denied').length; const allowed = list.filter((o) => dec(o) === 'allowed').length;
+      const onlyDenied = denied > 0 && denied === list.length;
+      byNode[nid] = { states: [...(onlyDenied ? [] : ['RUNTIME_OBSERVED']), ...(denied ? ['RUNTIME_BLOCKED'] : [])], observations: list.length, allowed, denied };
+    }
+  }
+  return { evaluated, byEdge, byNode, counts, limitations };
+
+  function entry(states, { observations = 0, allowed = 0, denied = 0, uncertain = 0, tokens = [], ev = [], note = '' } = {}) {
+    const primary = SEVERITY_ORDER.find((s) => states.includes(s));
+    return { states, primary, observations, allowed, denied, uncertainObservations: uncertain, identityTokens: tokens, exploitEvidence: ev, note };
+  }
+}
+
+/**
+ * "Show runtime flows absent from the static graph": the observations the matcher could NOT place on any static node, reduced to the
+ * destination identifiers the closed-world schema already allows. These are CANDIDATES. The matcher failing to place an observation
+ * can mean a path the static analysis missed, or a mapping the matcher is too weak to make; this lists them, it does not decide.
+ */
+export function runtimeFlowsAbsentFromStatic(observations, correlation) {
+  const unmatched = new Set(arr(correlation?.unmatchedObservationIds));
+  const rows = [];
+  for (const o of arr(observations)) {
+    if (!isObj(o) || !unmatched.has(o.id)) continue;
+    // an observation the matcher placed on a static NODE is not absent from the static graph; it only lacks a modelled flow
+    if (arr(o.matchedNodeIds).length || arr(o.matchedEdgeIds).length) continue;
+    const a = isObj(o.attributes) ? o.attributes : {};
+    const dest = ['destination.host', 'destination.service', 'destination.port', 'destination.scheme'].filter((k) => a[k] !== undefined).map((k) => `${k.split('.')[1]}=${a[k]}`).join(' ');
+    if (!dest) continue;
+    rows.push({ observationId: o.id, destination: dest, service: a['service.name'] ?? null, environment: o.environment ?? null, firstObservedAt: o.firstObservedAt ?? null, lastObservedAt: o.lastObservedAt ?? null, eventCountBand: o.eventCountBand ?? null });
+  }
+  rows.sort((x, y) => (x.destination < y.destination ? -1 : x.destination > y.destination ? 1 : 0));
+  return { candidates: rows, note: 'Unmatched observations are candidates, not proof that static analysis missed a path: the matcher may be too weak to place them.' };
+}
+
+/** "Show identities using risky paths": identity TOKENS (never identities) seen on edges in the risky states, with a band, never an exact count. */
+export function identitiesUsingRiskyPaths(edgeStates) {
+  const risky = new Set(['RUNTIME_POLICY_VIOLATION', 'RUNTIME_EXPLOIT_CORRELATED']);
+  const byToken = new Map();
+  for (const [edgeId, e] of Object.entries(edgeStates?.byEdge ?? {})) {
+    if (!e.states.some((s) => risky.has(s))) continue;
+    for (const t of e.identityTokens) { const x = byToken.get(t) ?? { token: t, edges: [], states: new Set() }; x.edges.push(edgeId); e.states.filter((s) => risky.has(s)).forEach((s) => x.states.add(s)); byToken.set(t, x); }
+  }
+  return {
+    identities: [...byToken.values()].map((x) => ({ token: x.token, edgeIds: x.edges.sort(), states: [...x.states].sort() })).sort((a, b) => (a.token < b.token ? -1 : 1)),
+    note: 'Tokens are keyed hashes under this install\'s key; they identify "the same identity" but never reveal who. Edges with no identity telemetry contribute nothing, which is not evidence that no identity used them.',
+  };
+}

package/src/lineage/runtime-explorer-view.js

@@ -0,0 +1,82 @@
+// The runtime half of the Data Flow Explorer as ONE static, script-free HTML page (PRD 2 section 5). Pure: it renders what
+// `runtime-edge-states.js` and the correlation already computed, writes nothing, and runs nothing in the browser. It exists as a page
+// rather than a route on the local explore server because that server's contract (`server/CLAUDE.md`) deliberately serves only the
+// signed static graph; widening it is a security decision of its own. A page needs no server, no token and no script.
+//
+// Five views, in the order the PRD names them: Static, Runtime, Static vs Runtime, Observed High-Risk Paths, Unexpected Runtime Paths.
+// Clicking (expanding) an edge shows BOTH its static evidence and its runtime evidence. Every flow is also shown as a path
+// ("source -> ... -> sink") with the state of each hop, which is the PRD's "credit-card field -> API -> payments service -> DB" view.
+//
+// Everything interpolated into the page is escaped. Attribute values (hosts, services) came from telemetry the operator supplied and
+// are treated as hostile text. The page states, at the top, what absence of observation does and does not mean.
+const esc = (v) => String(v ?? '').replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+const arr = (v) => (Array.isArray(v) ? v : []);
+const SENSITIVE = new Set(['PII', 'PHI', 'PCI', 'FIN', 'CREDENTIALS']);
+const CSS = 'body{font:14px/1.45 system-ui,sans-serif;margin:24px auto;max-width:1100px;padding:0 16px;color:#1b1f24;background:#fff}'
+  + '@media(prefers-color-scheme:dark){body{background:#14171a;color:#e6e8ea}}'
+  + 'table{border-collapse:collapse;width:100%;margin:8px 0}td,th{border:1px solid #8886;padding:4px 8px;text-align:left;vertical-align:top}'
+  + 'summary{cursor:pointer}.s{display:inline-block;padding:0 6px;border-radius:4px;border:1px solid #8888;font-size:12px;margin-right:4px}'
+  + '.RUNTIME_BLOCKED,.RUNTIME_POLICY_VIOLATION,.RUNTIME_EXPLOIT_CORRELATED{border-color:#c0392b;color:#c0392b}.RUNTIME_OBSERVED{border-color:#1e8449;color:#1e8449}'
+  + '.note{border-left:4px solid #8888;padding:4px 12px;margin:12px 0}nav a{margin-right:12px}code{font-size:12px}';
+
+export function renderRuntimeExplorer({ graph, edgeStates, correlation, observations = [], absent = { candidates: [] }, title = 'Runtime twin' }) {
+  const nodes = new Map(arr(graph?.nodes).map((n) => [n.id, n]));
+  const edges = arr(graph?.edges); const flows = arr(graph?.flows);
+  const dataEls = new Map(arr(graph?.dataElements).map((d) => [d.id, d]));
+  const label = (id) => esc(nodes.get(id)?.label ?? id);
+  const stateOf = (eid) => edgeStates?.byEdge?.[eid];
+  const obsByEdge = new Map();
+  for (const o of arr(observations)) for (const eid of arr(o.matchedEdgeIds)) { const a = obsByEdge.get(eid) ?? []; a.push(o); obsByEdge.set(eid, a); }
+  const chips = (states) => arr(states).map((s) => `<span class="s ${esc(s)}">${esc(s)}</span>`).join('');
+  const flowClasses = (f) => arr(f.dataElementIds).flatMap((id) => arr(dataEls.get(id)?.dataClasses));
+  const observedEdge = (eid) => stateOf(eid)?.states?.includes('RUNTIME_OBSERVED');
+
+  const staticRows = edges.map((e) => `<tr><td>${label(e.from)} &rarr; ${label(e.to)}</td><td><code>${esc(e.id)}</code></td><td>${esc(e.protocol?.name ?? e.protocol?.kind ?? '')}</td><td>${esc(arr(e.boundaryCrossings).join(', '))}</td></tr>`).join('');
+  const runtimeRows = edges.map((e) => { const s = stateOf(e.id); return `<tr><td>${label(e.from)} &rarr; ${label(e.to)}</td><td>${chips(s?.states)}</td><td>${s?.observations ?? 0}</td><td>${esc(s?.identityTokens?.length ?? 0)}</td></tr>`; }).join('');
+  const bothRows = edges.map((e) => { const s = stateOf(e.id); return `<tr><td>${label(e.from)} &rarr; ${label(e.to)}</td><td>${esc(arr(e.boundaryCrossings).length ? 'crosses a boundary' : 'internal')}, ${esc(e.provenance ?? '')}</td><td>${chips(s?.states)}${s?.uncertainObservations ? ` <small>(${s.uncertainObservations} uncertain, not counted)</small>` : ''}</td></tr>`; }).join('');
+
+  const detail = (e) => {
+    const s = stateOf(e.id); const obs = obsByEdge.get(e.id) ?? [];
+    const o = obs.map((x) => `<li>${esc(x.adapter)} / ${esc(x.environment ?? 'no environment')}: ${esc(x.firstObservedAt)} to ${esc(x.lastObservedAt)}, count band ${esc(x.eventCountBand)}, match ${esc(x.matchMethod)} (${esc(x.matchConfidence)})${x.attributes?.['network.securityDecision'] ? `, decision ${esc(x.attributes['network.securityDecision'])}` : ''}${x.attributes?.['identity.token'] ? `, identity <code>${esc(x.attributes['identity.token'])}</code>` : ''}</li>`).join('');
+    return `<details><summary>${label(e.from)} &rarr; ${label(e.to)} ${chips(s?.states)}</summary>`
+      + `<h4>Static evidence</h4><p><code>${esc(e.id)}</code>, provenance ${esc(e.provenance)}, coverage ${esc(e.coverageStatus)}; boundaries: ${esc(arr(e.boundaryCrossings).join(', ') || 'none')}; evidence: ${esc(arr(e.evidenceRefs).join(', ') || 'none')}</p>`
+      + `<h4>Runtime evidence</h4>${obs.length ? `<ul>${o}</ul>` : `<p>${esc(s?.note || 'none')}</p>`}</details>`;
+  };
+
+  const pathRow = (f) => {
+    const hops = arr(f.edgeIds).map((eid) => { const e = edges.find((x) => x.id === eid); return e ? `${label(e.from)} &rarr; ${label(e.to)} ${chips(stateOf(eid)?.states)}` : esc(eid); });
+    return `<tr><td>${esc(arr(f.dataElementIds).map((id) => dataEls.get(id)?.label ?? id).join(', '))}<br><small>${esc(flowClasses(f).join(', '))}</small></td><td>${hops.join('<br>') || '(no modelled hops)'}</td><td>${esc(f.policyVerdict)}</td></tr>`;
+  };
+  const highRisk = flows.filter((f) => arr(f.edgeIds).some(observedEdge) && (flowClasses(f).some((c) => SENSITIVE.has(c)) || f.policyVerdict === 'prohibited' || arr(f.edgeIds).some((eid) => arr(edges.find((e) => e.id === eid)?.boundaryCrossings).length)));
+  const blockedNodes = Object.entries(edgeStates?.byNode ?? {});
+  const unexpected = [
+    ...arr(absent.candidates).map((c) => `<tr><td>${esc(c.destination)}</td><td>observed, not placed on any static node</td><td>${esc(c.firstObservedAt)} to ${esc(c.lastObservedAt)}</td></tr>`),
+    ...blockedNodes.filter(([, n]) => n.states.includes('RUNTIME_BLOCKED')).map(([id, n]) => `<tr><td>${label(id)}</td><td>attempted and refused (${n.denied} denied)</td><td></td></tr>`),
+  ];
+  const section = (id, h, body) => `<section id="${id}"><h2>${h}</h2>${body}</section>`;
+  const table = (head, rows, empty) => (rows.length ? `<table><tr>${head.map((h) => `<th>${h}</th>`).join('')}</tr>${rows.join('')}</table>` : `<p>${esc(empty)}</p>`);
+  const body = [
+    `<h1>${esc(title)}</h1>`,
+    `<div class="note">${edgeStates?.evaluated ? 'Telemetry was consulted.' : '<strong>No telemetry was consulted:</strong> every edge is STATIC_ONLY. That is not evidence that nothing happens at runtime.'} <strong>Not observed does not mean unreachable or safe.</strong> Only high- and medium-confidence mappings are counted. Telemetry values shown are metadata only; identities appear only as keyed-hash tokens.</div>`,
+    '<nav><a href="#static">Static</a><a href="#runtime">Runtime</a><a href="#both">Static vs Runtime</a><a href="#risk">Observed high-risk paths</a><a href="#unexpected">Unexpected runtime paths</a><a href="#paths">Flow paths</a><a href="#edges">Edge detail</a></nav>',
+    section('static', 'Static', table(['Edge', 'Id', 'Protocol', 'Boundaries'], staticRows ? [staticRows] : [], 'No static edges.')),
+    section('runtime', 'Runtime', table(['Edge', 'State', 'Trusted observations', 'Identity tokens'], runtimeRows ? [runtimeRows] : [], 'No edges.')),
+    section('both', 'Static vs Runtime', table(['Edge', 'Static', 'Runtime'], bothRows ? [bothRows] : [], 'No edges.')),
+    section('risk', 'Observed high-risk paths', table(['Data', 'Path and state per hop', 'Policy'], highRisk.map(pathRow), 'No observed flow is sensitive, policy-prohibited or boundary-crossing. This is a statement about the telemetry window, not about the system.')),
+    section('unexpected', 'Unexpected runtime paths', table(['Destination or node', 'What was seen', 'When'], unexpected, 'Nothing unplaced or refused. Unplaced observations are candidates, not proof static analysis missed a path.')),
+    section('paths', 'Flow paths', table(['Data', 'Path and state per hop', 'Policy'], flows.map(pathRow), 'No flows.')),
+    section('edges', 'Edge detail (expand an edge for its static and runtime evidence)', edges.map(detail).join('') || '<p>No edges.</p>'),
+  ].join('\n');
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'"><title>${esc(title)}</title><style>${CSS}</style></head><body>${body}</body></html>\n`;
+}
+
+/** "Show vulnerable functions actually exercised in production": scan findings whose own path appears in the runtime trace. Expects findings already
+ * annotated by `posture/runtime-correlation.js`; it adds no matching of its own. */
+export function vulnerableFunctionsInProduction(findings) {
+  const list = arr(findings).filter((f) => f && typeof f === 'object');
+  const withEvidence = list.filter((f) => f.runtimeEvidence);
+  if (!withEvidence.some((f) => f.runtimeEvidence.state !== 'unknown')) return { evaluated: false, reason: 'no runtime trace could be evaluated (none present, or it says nothing about any finding): put one at .agentic-security/runtime-trace.jsonl (or set AGENTIC_SECURITY_RUNTIME_TRACE_PATH). This is not "no vulnerable function ran".' };
+  const observed = withEvidence.filter((f) => f.runtimeEvidence.state === 'observed').map((f) => ({ id: f.id, severity: f.severity, vuln: f.vuln, file: f.file, line: f.line, cwe: f.cwe, basis: f.runtimeEvidence.basis, sampling: f.runtimeEvidence.sampling?.state ?? null }));
+  const counts = { observed: observed.length, notObservedInWindow: withEvidence.filter((f) => f.runtimeEvidence.state === 'not_observed_in_window').length, unknown: withEvidence.filter((f) => f.runtimeEvidence.state === 'unknown').length };
+  return { evaluated: true, findings: observed, counts, note: 'A finding listed here has a function, line or route on its path in the trace. A finding not listed may still run: counts show how many were not observed or unknown. Absence of observation is a statement about the window and the instrumentation, not about reachability.' };
+}

package/src/lineage/runtime-observation.js

@@ -173,8 +173,13 @@ export const RUNTIME_ATTRIBUTE_KEYS = Object.freeze([
   // RUNTIME_SECURITY_DECISION_VALUES below and its own dedicated check in
   // validateObservationAttributes.
   'network.securityDecision',
+  // authenticated identity (PRD 2 section 1) as a KEYED-HASH TOKEN only, never the identity itself: `idt_` + 16 hex. The importer
+  // computes it (HMAC under the per-install key) and hands the adapters a tokenizer; no raw username/email can pass this grammar.
+  'identity.token',
 ]);
 
+export const IDENTITY_TOKEN_RE = /^idt_[0-9a-f]{16}$/;
+
 // The closed enum for 'network.securityDecision' — deliberately narrower
 // than the generic identifier-value check every other scalar attribute
 // gets, since this field has exactly two legitimate values and nothing
@@ -305,6 +310,12 @@ export function validateObservationAttributes(attributes) {
       }
       continue;
     }
+    if (key === 'identity.token') {
+      if (typeof value !== 'string' || !IDENTITY_TOKEN_RE.test(value)) {
+        err(`$.attributes["${key}"]`, 'must be an identity token (idt_ followed by 16 hex characters) — a raw identity is never accepted');
+      }
+      continue;
+    }
     const t = typeof value;
     if (t === 'string') {
       if (!_isIdentifierValue(value)) {

package/src/mcp/CLAUDE.md

@@ -29,10 +29,12 @@ MCP server. JSON-RPC 2.0 over NDJSON on stdin/stdout. Bin entry `../../bin/agent
 | `dataflow_get_flow` | ✓ | as above, ID-scoped flow lookup (`handleFlow`), includes contributing node/edge canonical ids |
 | `invariant_scenario_export` | ✓ | X-407: the bounded stateful scenarios for one executable business-logic contract as a reproducible package (digests, pinned fixture digest, replay manifests when a commit is given, the bounds applied, what could not be built). Reads a contract JSON, a fixture directory and an optional ledger from inside the session root (confined by `tools.js::_confine`, passed in to `invariant-tools.js` as a factory argument so the two files do not import each other); runs nothing, writes nothing. The fixture source is never returned, a scenario holding a secret-looking value is withheld (named by path, never by value), the serialized result is re-checked with `redact.js::redactSecretShapes` and BLOCKED if anything would be redacted (an edited scenario is a different scenario), and every export carries the bounded-sample, not-exhaustive statement. Gated by the `invariant-scenarios` feature (off by default, operator-only): with it off the tool is still listed and answers `status: 'disabled'`. Same function as the CLI's `invariants export` (`posture/invariants/export.js::exportFromFiles`) |
 | `portfolio_progress` | ✓ | X-707: the coverage-aware progress view of a durable portfolio store (verified units, blocked/failed/canceled/stale units with reasons, per-repository coverage, remaining budget, pending human review, worker liveness with stale workers kept visible, and, when a findings file is given, aggregate findings deduplicated by stable identity with per-repository/environment evidence and separate affected releases). Reads a store, its scheduler ledger and optional budgets and findings files from inside the session root (confined by `tools.js::_confine`, passed to `portfolio-tools.js` as a factory argument); writes nothing; a corrupt store is an error, never a reset. A finished controller is reported as finished, never as passed. The serialized view is re-checked with `redact.js::redactSecretShapes` and BLOCKED if anything would be redacted. Gated by the `portfolio-assurance` feature (off by default): with it off the tool is still listed and answers `status: 'disabled'`. Same function as the CLI's `portfolio progress` (`posture/portfolio/progress.js::buildProgressView`) |
+| `prove_finding` | ✗ | PRD 1: runs a reproducer (supplied, stored or generated from the finding) in the confined proof environment; requires `confirm:true`; returns evidence state and counts, never the target's output; writes a proof record under `.agentic-security/proofs/` |
+| `prove_fix` | ✗ | PRD 1: replays the original exploit against a COPY of the patched sources, runs the static verification and a sibling-exposure search; requires `confirm:true`; writes nothing to the project |
 
 **Dataflow-tools redaction scope (found by a post-Task-2 whole-branch security review, fixed same day):** the initial cut only redacted `evidence[].location.note`, which turned out to be fixture-only — the real graph-builder emitter never populates `.note` (it uses `{file,line}`). The real source-derived surfaces are `node.destination.raw`/`.literalValue` (lifted verbatim from a scanned call-site argument by `lineage/resolve-destination.js`) and `evidence[].claim`/`.snippet`. `dataflow-tools.js`'s `_redactNode`/`_redactEvidence`/`_redactGraph` now cover all of them, applied on `dataflow_get_graph` (full graph) and `dataflow_get_node` (single node); edges and flows carry only `evidenceRefs` (id strings), never embedded evidence or destination-shaped fields, so they need no redaction pass. `dataflow-tools.js` was also missing from `server.js`'s `CODE_FINGERPRINT` file list (OWASP MCP04/MCP09) — added.
 
-**23 tools, not 12** — this table previously stopped at 12 and the count quoted elsewhere (root `CLAUDE.md`, the non-Claude plugin manifests) said "Six." Re-derive with `grep -c "name: '" scanner/src/mcp/tools.js scanner/src/mcp/dataflow-tools.js | awk -F: '{s+=$2} END{print s}'` — **not** `tools.js` alone, which now undercounts by 5: the 4 `dataflow_*` tools are defined in `dataflow-tools.js`, `invariant_scenario_export` in `invariant-tools.js` and `portfolio_progress` in `portfolio-tools.js`, and only imported/constructed into `tools.js`'s `ALL_TOOLS` (re-derive with `grep -c "name: '" scanner/src/mcp/tools.js scanner/src/mcp/dataflow-tools.js scanner/src/mcp/invariant-tools.js scanner/src/mcp/portfolio-tools.js`). If a future tool file follows this same reused-adapter-module pattern, extend the file list rather than trusting a single-file grep again; `server.js`'s `CODE_FINGERPRINT` list must name it too.
+**25 tools, not 12** — this table previously stopped at 12 and the count quoted elsewhere (root `CLAUDE.md`, the non-Claude plugin manifests) said "Six." Re-derive with `grep -c "name: '" scanner/src/mcp/tools.js scanner/src/mcp/dataflow-tools.js | awk -F: '{s+=$2} END{print s}'` — **not** `tools.js` alone, which now undercounts by 5: the 4 `dataflow_*` tools are defined in `dataflow-tools.js`, `invariant_scenario_export` in `invariant-tools.js` and `portfolio_progress` in `portfolio-tools.js`, and only imported/constructed into `tools.js`'s `ALL_TOOLS` (re-derive with `grep -c "name: '" scanner/src/mcp/tools.js scanner/src/mcp/dataflow-tools.js scanner/src/mcp/invariant-tools.js scanner/src/mcp/portfolio-tools.js`). If a future tool file follows this same reused-adapter-module pattern, extend the file list rather than trusting a single-file grep again; `server.js`'s `CODE_FINGERPRINT` list must name it too.
 
 **Two write tools, not one.** `apply_fix` and `apply_sca_upgrade` both write; `verify_fix` also writes (see its row above) though not to the target project's own files. `apply_fix` additionally requires `confirm:true` AND the last-scan HMAC to verify AND the target path not on the reserved-write list; `apply_sca_upgrade` requires `confirm:true` and gates on its own test-restore cycle.