@clear-capabilities/agentic-security-scanner 0.172.1 → 0.174.0

package/src/dataflow/service-edges.js

@@ -0,0 +1,174 @@
+// Static service relationships (E2-07): which service calls, publishes to, or stores for which other service, read from the code.
+//
+// OPT-IN. Nothing here runs unless a caller passes the service roots; a single-service repository gets nothing, and no relationship is invented
+// from a naming coincidence alone.
+//
+// WHAT AN EDGE CARRIES. Each edge says how it is known:
+//   observed  both ends are literal in the code and agree (an HTTP client calling `http://orders/api/items` and an `orders` route `POST /api/items`;
+//             a producer and a consumer naming the same literal topic; two services naming the same table AND the project declaring one shared database)
+//   inferred  the ends match but one rests on a weaker fact (two services name the same table with no declaration that they share a database;
+//             a client URL whose host comes from a configured base URL)
+//   unknown   one end is dynamic (a computed topic, a URL assembled from user data) or has no counterpart: it is recorded and never connected
+//
+// WHAT IT NEVER SAYS. A chain is `static-observed` only when every hop is observed, `static-inferred` when the weakest hop is inferred, and
+// `unproven` is reserved for a caller that supplies its own edges: this module never connects across an unknown one. No label is ever `proven`: this module reads text, it does not run the services, so ambiguity across
+// a service boundary cannot be described as a demonstrated exploit chain. Traversal is bounded by hop count and a visited set, so a cycle ends.
+//
+// SCOPE. JavaScript, TypeScript and Python sources. HTTP (Express/Koa/Fastify-style routes, Flask/FastAPI decorators; fetch/axios/requests/got
+// clients), messaging (Kafka/AMQP/Redis/NATS style publish and subscribe with a literal topic), persistence (SQL text and common collection calls).
+// Serializer contracts (protobuf/JSON-schema sharing) are not read: recorded as a limit.
+import { createHash } from 'node:crypto';
+
+const EDGE_KINDS = Object.freeze(['http', 'messaging', 'persistence']);
+const EVIDENCE = Object.freeze(['observed', 'inferred', 'unknown']);
+export const MAX_HOPS = 6;
+const RANK = { observed: 0, inferred: 1, unknown: 2 };
+const id = (parts) => `svcedge:${createHash('sha256').update(JSON.stringify(parts)).digest('hex').slice(0, 16)}`;
+const posix = (p) => String(p).replace(/\\/g, '/');
+const lineOf = (code, index) => code.slice(0, index).split('\n').length;
+
+function serviceOf(file, services) {
+  const f = posix(file);
+  let best = null;
+  for (const s of services) { const root = posix(s.root).replace(/\/$/, ''); if ((f === root || f.startsWith(`${root}/`)) && (!best || root.length > posix(best.root).length)) best = s; }
+  return best;
+}
+
+const norm = (p) => `/${String(p).replace(/^https?:\/\/[^/]+/, '').replace(/[?#].*$/, '').split('/').filter(Boolean).join('/')}`;
+// `/items/:id`, `/items/{id}`, `/items/<id>`, `/items/${id}` all name the same shape
+// a concrete segment (`/items/42`) matches a parameter segment of a route; two concrete segments must be equal
+const matchesShape = (routePath, clientPath) => { const r = shape(routePath).split('/'); const c = shape(clientPath).split('/'); return r.length === c.length && r.every((seg, i) => seg === ':p' || seg === c[i]); };
+const shape = (p) => norm(p).split('/').map((seg) => (/^(?::|\{|<|\$\{)/.test(seg) ? ':p' : seg)).join('/');
+
+// ---- extraction -------------------------------------------------------------------------------------------------------------
+
+const ROUTE_JS = /\b(?:app|router|server|fastify|api)\s*\.\s*(get|post|put|patch|delete|all)\s*\(\s*(['"`])(\/[^'"`]*)\2/g;
+const ROUTE_PY = /@\s*(?:app|router|bp|blueprint)\s*\.\s*(get|post|put|patch|delete|route)\s*\(\s*(['"])(\/[^'"]*)\2([^)]*)\)/g;
+const CLIENT_JS = /\b(fetch|axios(?:\s*\.\s*(?:get|post|put|patch|delete))?|got(?:\s*\.\s*(?:get|post|put|patch|delete))?)\s*\(\s*([`'"])([^`'"]*)\2/g;
+const CLIENT_PY = /\brequests\s*\.\s*(get|post|put|patch|delete)\s*\(\s*(['"])([^'"]*)\2/g;
+const CLIENT_DYN = /\b(?:fetch|axios(?:\s*\.\s*(?:get|post|put|patch|delete))?|requests\s*\.\s*(?:get|post|put|patch|delete)|got)\s*\(\s*([A-Za-z_$][\w$.]*)\s*[,)]/g;
+const PRODUCE = /\b(?:producer|channel|publisher|pubsub|nats|client|redis|bus|queue)\s*\.\s*(?:send|publish|emit|produce|sendToQueue|xadd|lpush)\s*\(\s*(?:\{\s*topic\s*:\s*)?(['"`])([^'"`]+)\1/g;
+const PRODUCE_DYN = /\b(?:producer|channel|publisher|pubsub|nats|bus|queue)\s*\.\s*(?:send|publish|emit|produce|sendToQueue)\s*\(\s*(?:\{\s*topic\s*:\s*)?([A-Za-z_$][\w$.]*)\s*[,})]/g;
+const CONSUME = /\b(?:consumer|channel|subscriber|pubsub|nats|bus|queue|client)\s*\.\s*(?:subscribe|consume|on|psubscribe|xread|brpop)\s*\(\s*(?:\{\s*topic\s*:\s*)?(['"`])([^'"`]+)\1/g;
+const SQL_WRITE = /\b(?:INSERT\s+INTO|UPDATE|DELETE\s+FROM)\s+[`"']?([A-Za-z_][\w.]*)/gi;
+const SQL_READ = /\bSELECT\b[^;]{0,300}?\bFROM\s+[`"']?([A-Za-z_][\w.]*)/gi;
+const COLL_WRITE = /\b(?:db|database|mongo)\s*\.\s*(?:collection\s*\(\s*['"`]([\w.-]+)['"`]\s*\)|([A-Za-z_]\w*))\s*\.\s*(?:insertOne|insertMany|updateOne|updateMany|deleteOne|deleteMany|save|create|insert|update|remove)\s*\(/g;
+const COLL_READ = /\b(?:db|database|mongo)\s*\.\s*(?:collection\s*\(\s*['"`]([\w.-]+)['"`]\s*\)|([A-Za-z_]\w*))\s*\.\s*(?:find|findOne|findMany|findById|get|select|aggregate|count)\s*\(/g;
+const DB_URL = /\b(DATABASE_URL|DB_URL|MONGO_URL|MONGODB_URI|POSTGRES_URL|REDIS_URL)\b/g;
+
+function* matches(re, code) { re.lastIndex = 0; let m; while ((m = re.exec(code))) yield m; }
+
+/** @returns {{routes:object[], clients:object[], produces:object[], consumes:object[], writes:object[], reads:object[], dbRefs:string[], unknown:object[]}} */
+export function extractFacts(file, code) {
+  const out = { routes: [], clients: [], produces: [], consumes: [], writes: [], reads: [], dbRefs: [], unknown: [] };
+  const py = /\.py$/.test(file);
+  const at = (m) => lineOf(code, m.index);
+  for (const m of matches(py ? ROUTE_PY : ROUTE_JS, code)) {
+    let method = m[1].toUpperCase();
+    if (py && method === 'ROUTE') { const mm = /methods\s*=\s*\[\s*['"](\w+)['"]/.exec(m[4] || ''); method = mm ? mm[1].toUpperCase() : 'GET'; }
+    out.routes.push({ method, path: m[3], file, line: at(m) });
+  }
+  for (const m of matches(py ? CLIENT_PY : CLIENT_JS, code)) {
+    const target = py ? m[3] : m[3];
+    // `fetch(url, { method: 'POST' })` names its verb in the options object; `axios.post` and `requests.post` in the callee
+    const optionVerb = /\bmethod\s*:\s*['"`](\w+)['"`]/.exec(code.slice(m.index, m.index + 300));
+    const verb = py ? m[1].toUpperCase() : ((/\.\s*(get|post|put|patch|delete)/.exec(m[1]) || [null, optionVerb ? optionVerb[1] : 'GET'])[1]).toUpperCase();
+    if (/^https?:\/\//.test(target) || /^\$\{[^}]+\}\//.test(target)) out.clients.push({ method: verb, url: target, file, line: at(m), literalHost: /^https?:\/\/[^/${]+/.test(target) });
+  }
+  for (const m of matches(CLIENT_DYN, code)) out.unknown.push({ kind: 'http', file, line: at(m), reason: `client URL comes from \`${m[1]}\`, not a literal` });
+  for (const m of matches(PRODUCE, code)) out.produces.push({ topic: m[2], file, line: at(m) });
+  for (const m of matches(PRODUCE_DYN, code)) out.unknown.push({ kind: 'messaging', file, line: at(m), reason: `topic comes from \`${m[1]}\`, not a literal` });
+  for (const m of matches(CONSUME, code)) out.consumes.push({ topic: m[2], file, line: at(m) });
+  for (const m of matches(SQL_WRITE, code)) out.writes.push({ table: m[1].toLowerCase(), file, line: at(m) });
+  for (const m of matches(SQL_READ, code)) out.reads.push({ table: m[1].toLowerCase(), file, line: at(m) });
+  for (const m of matches(COLL_WRITE, code)) out.writes.push({ table: String(m[1] || m[2]).toLowerCase(), file, line: at(m) });
+  for (const m of matches(COLL_READ, code)) out.reads.push({ table: String(m[1] || m[2]).toLowerCase(), file, line: at(m) });
+  for (const m of matches(DB_URL, code)) out.dbRefs.push(m[1]);
+  return out;
+}
+
+/**
+ * @param {Record<string,string>} fileContents repository-relative path -> source
+ * @param {{services:{name:string, root:string, hosts?:string[]}[], sharedDatabases?:{name?:string, services:string[], tables?:string[]}[]}} opts
+ *   `services` is REQUIRED: without it nothing is inferred. `hosts` are the names other services use to reach this one.
+ *   `sharedDatabases` is the declaration that makes a persistence edge observed rather than inferred.
+ */
+export function buildServiceEdges(fileContents, opts = {}) {
+  const services = (opts.services || []).filter((s) => s && s.name && s.root);
+  if (services.length < 2) return { edges: [], unknown: [], services: services.map((s) => s.name), limits: LIMITS, optedIn: false, note: 'fewer than two services declared: no service relationships are inferred' };
+  const facts = new Map(services.map((s) => [s.name, { routes: [], clients: [], produces: [], consumes: [], writes: [], reads: [], dbRefs: new Set(), unknown: [] }]));
+  for (const [file, code] of Object.entries(fileContents || {}).sort(([a], [b]) => (a < b ? -1 : 1))) {
+    if (typeof code !== 'string' || !/\.(?:[cm]?[jt]sx?|py)$/.test(file)) continue;
+    const svc = serviceOf(file, services);
+    if (!svc) continue;
+    const f = extractFacts(posix(file), code);
+    const acc = facts.get(svc.name);
+    for (const k of ['routes', 'clients', 'produces', 'consumes', 'writes', 'reads', 'unknown']) acc[k].push(...f[k].map((x) => ({ ...x, service: svc.name })));
+    for (const d of f.dbRefs) acc.dbRefs.add(d);
+  }
+  const hostsOf = (s) => new Set([s.name, ...(s.hosts || [])].map((h) => h.toLowerCase()));
+  const edges = []; const unknown = [];
+  for (const [name, f] of facts) for (const u of f.unknown) unknown.push({ service: name, ...u, evidence: 'unknown' });
+
+  // HTTP: a client URL names a host and a path; the host picks the service, the method and path shape pick the route
+  for (const [from, f] of facts) for (const c of f.clients) {
+    const hm = /^https?:\/\/([^/:${]+)/.exec(c.url);
+    const host = hm ? hm[1].toLowerCase() : null;
+    const target = host ? services.find((s) => s.name !== from && hostsOf(s).has(host)) : null;
+    if (!target) { unknown.push({ service: from, kind: 'http', file: c.file, line: c.line, reason: host ? `host ${host} is not a declared service` : 'the host is configured at run time', evidence: 'unknown' }); continue; }
+    const route = facts.get(target.name).routes.find((r) => (r.method === c.method || r.method === 'ALL') && matchesShape(r.path, c.url));
+    if (!route) { unknown.push({ service: from, kind: 'http', file: c.file, line: c.line, reason: `${target.name} has no ${c.method} route matching ${norm(c.url)}`, evidence: 'unknown' }); continue; }
+    edges.push({ id: id(['http', from, c.file, c.method, shape(c.url), target.name, route.file]), kind: 'http', from: { service: from, file: c.file, line: c.line }, to: { service: target.name, file: route.file, line: route.line }, via: { method: c.method, path: shape(route.path) }, evidence: 'observed', basis: 'a literal client URL and a route with the same method and path shape' });
+  }
+  // Messaging: the same literal topic on a producer and a consumer in different services
+  for (const [from, f] of facts) for (const p of f.produces) {
+    const consumers = [...facts].filter(([n]) => n !== from).flatMap(([n, g]) => g.consumes.filter((c) => c.topic === p.topic).map((c) => ({ ...c, service: n })));
+    if (!consumers.length) { unknown.push({ service: from, kind: 'messaging', file: p.file, line: p.line, reason: `no other service consumes topic "${p.topic}"`, evidence: 'unknown' }); continue; }
+    for (const c of consumers) edges.push({ id: id(['messaging', from, p.file, p.topic, c.service, c.file]), kind: 'messaging', from: { service: from, file: p.file, line: p.line }, to: { service: c.service, file: c.file, line: c.line }, via: { topic: p.topic }, evidence: 'observed', basis: 'the same literal topic is produced and consumed' });
+  }
+  // Persistence: one service writes a table another reads
+  const shared = (opts.sharedDatabases || []).map((d) => ({ services: new Set(d.services), tables: d.tables ? new Set(d.tables.map((t) => t.toLowerCase())) : null }));
+  for (const [from, f] of facts) for (const w of f.writes) for (const [to, g] of facts) {
+    if (to === from) continue;
+    for (const r of g.reads.filter((x) => x.table === w.table)) {
+      const declared = shared.some((d) => d.services.has(from) && d.services.has(to) && (!d.tables || d.tables.has(w.table)));
+      edges.push({ id: id(['persistence', from, w.file, w.table, to, r.file]), kind: 'persistence', from: { service: from, file: w.file, line: w.line }, to: { service: to, file: r.file, line: r.line }, via: { table: w.table }, evidence: declared ? 'observed' : 'inferred', basis: declared ? 'both services use the table and the project declares them as sharing a database' : 'both services name the table, but nothing declares that they share a database' });
+    }
+  }
+  edges.sort((a, b) => (a.id < b.id ? -1 : 1));
+  unknown.sort((a, b) => (a.service + a.file + a.line < b.service + b.file + b.line ? -1 : 1));
+  return { edges, unknown, services: services.map((s) => s.name), limits: LIMITS, optedIn: true };
+}
+
+const LIMITS = Object.freeze([
+  'only JavaScript, TypeScript and Python sources are read',
+  'a topic, URL host or table assembled at run time is recorded as unknown and never connected',
+  'serializer contracts (protobuf, JSON schema) are not read, so a shared message shape is not an edge',
+  'an edge says two services are related in the code; it does not say attacker data crosses it. That needs a finding on each side',
+  'no chain is ever labelled proven: this module reads text and does not run the services',
+]);
+
+/**
+ * Bounded breadth-first trace from a service. Each path carries the weakest evidence on it. A path through an inferred edge is
+ * `static-inferred`; the label `static-observed` needs every hop observed; nothing is `proven`.
+ */
+export function traceFrom(graph, start, { maxHops = MAX_HOPS, maxPaths = 200 } = {}) {
+  const hops = Math.max(1, Math.min(MAX_HOPS, maxHops));
+  const byFrom = new Map();
+  for (const e of graph.edges) { if (!byFrom.has(e.from.service)) byFrom.set(e.from.service, []); byFrom.get(e.from.service).push(e); }
+  const out = []; let truncated = false;
+  const queue = [{ at: start, path: [], seen: new Set([start]) }];
+  while (queue.length) {
+    const cur = queue.shift();
+    if (cur.path.length >= hops) { if ((byFrom.get(cur.at) || []).length) truncated = true; continue; }
+    for (const e of byFrom.get(cur.at) || []) {
+      if (cur.seen.has(e.to.service)) continue;
+      const path = [...cur.path, e];
+      if (out.length >= maxPaths) { truncated = true; break; }
+      const weakest = path.reduce((w, x) => (RANK[x.evidence] > RANK[w] ? x.evidence : w), 'observed');
+      out.push({ services: [start, ...path.map((x) => x.to.service)], edges: path.map((x) => x.id), kinds: path.map((x) => x.kind), evidence: weakest, label: weakest === 'observed' ? 'static-observed' : weakest === 'inferred' ? 'static-inferred' : 'unproven' });
+      queue.push({ at: e.to.service, path, seen: new Set([...cur.seen, e.to.service]) });
+    }
+  }
+  return { start, paths: out, truncated, maxHops: hops };
+}

package/src/dataflow/summaries.js

@@ -116,9 +116,14 @@ export class SummaryCache {
   }
 
   get(qid, taintedParams, receiverType) {
-    return this._cache.get(this._key(qid, taintedParams, receiverType));
+    const r = this._cache.get(this._key(qid, taintedParams, receiverType));
+    if (r === undefined) this._misses = (this._misses || 0) + 1; else this._hits = (this._hits || 0) + 1;
+    return r;
   }
 
+  /** Lookups that found and did not find a summary (E6-01). */
+  stats() { return { hits: this._hits || 0, misses: this._misses || 0, size: this._cache.size }; }
+
   set(qid, taintedParams, summary, receiverType) {
     const k = this._key(qid, taintedParams, receiverType);
     this._cache.set(k, summary);
@@ -163,6 +168,7 @@ export class SummaryCache {
       return { returnTainted: false, mutatedParams: new Set(), taintedGlobals: new Set(), findings: [], _recursive: true };
     }
     if (++this._iter > this._maxIter) {
+      this._budgetHits = (this._budgetHits || 0) + 1;
       return { returnTainted: false, mutatedParams: new Set(), taintedGlobals: new Set(), findings: [], _budgetExceeded: true };
     }
     this._stack.add(qid);

package/src/discovery/judge.js

@@ -51,7 +51,8 @@ export function toFindingShape(candidate) {
     description: candidate.rationale
       ? `${candidate.rationale} (entry point: ${candidate.entryPoint || 'unstated'}; sink: ${candidate.sink || 'unstated'})`
       : `Proposed by the ${candidate.lens} lens; no rationale supplied.`,
-    remediation: `Review ${candidate.file}:${candidate.line}. Confirm whether ${candidate.entryPoint || 'attacker-controlled input'} can reach ${candidate.sink || 'this operation'}, and constrain it at the boundary if so.`,
+    // a candidate that carries its own concrete remediation (a deterministic finding with a known fix shape) keeps it; every other candidate gets the generic review text
+    remediation: (typeof candidate.remediation === 'string' && candidate.remediation) ? candidate.remediation : `Review ${candidate.file}:${candidate.line}. Confirm whether ${candidate.entryPoint || 'attacker-controlled input'} can reach ${candidate.sink || 'this operation'}, and constrain it at the boundary if so.`,
     parser: 'DISCOVERY',
     family: candidate.family || 'other',
     ruleId: `discovery:${candidate.lens}`,

package/src/engine.js

@@ -58,7 +58,8 @@ import { proofCoverage } from './posture/proof-coverage.js';
 import { computeScanHealth, applyFreshness } from './pipeline/scan-health.js';
 import { computeCoverageLedger, summarizeCoverageForScanHealth } from './pipeline/coverage-ledger.js';
 import { runAnnotatorAsync } from './pipeline/annotator-runner.js';
-import { runDetector } from './pipeline/detector-runner.js';
+import { runDetector, setDetectorTimingSink } from './pipeline/detector-runner.js';
+import { createTelemetry, attributeErrors } from './pipeline/telemetry.js';
 import { registerProducer } from './pipeline/producer-registry.js';
 import { collectProducerResult } from './pipeline/producer-collector.js';
 import { completeEnrichment } from './pipeline/enrichment-completion.js';
@@ -129,6 +130,8 @@ import { scanClientSide } from './sast/client-side.js';
 import { scanPromptFirewall } from './sast/prompt-firewall.js';
 import { scanLlmRedteam } from './posture/llm-redteam.js';
 import { assessPrivacyFramework, persistPrivacyFramework } from './posture/privacy-framework.js';
+import { signLastScan } from './posture/integrity.js';
+import { secretCanaryHit } from './posture/runtime-trace-ingest.js';
 import { safeWriteState as _safeWriteState, statePath, statePath as _statePath } from './posture/state-dir.js';
 import { scanContainer } from './sca/container.js';
 import { detectDepConfusion } from './sca/dep-confusion.js';
@@ -210,6 +213,7 @@ import { applyPathConstraints } from './posture/path-predicates.js';
 import { buildProjectIR, buildProjectIRAsync } from './ir/index.js';
 import _v8 from 'node:v8';
 import _vm from 'node:vm';
+import { createStringMemo } from './util/string-memo.js';
 import { collectIrStats, irStatsTarget, writeIrStats } from './ir/ir-stats.js';
 import { runDeepAnalysis } from './dataflow/index.js';
 import { buildLineageGraph } from './lineage/index.js';
@@ -446,7 +450,11 @@ function _ruleAppliesIn(pat, ctx){
 // comments would put the second pass into a stuck string state, blanking the
 // rest of the file. Backtick `${...}` template expressions are preserved
 // verbatim because they contain real source/sink references.
-function stripNoiseAndStrings(code){
+// Called by several detectors per file with the same text; the result depends only on the text, so it is computed once per distinct text
+// (util/string-memo.js). AGENTIC_SECURITY_NO_STRING_MEMO=1 turns the memo off.
+const _stripNoiseAndStringsMemo = createStringMemo((c) => _stripNoiseAndStringsRaw(c), { version: 'stripNoiseAndStrings@1', disableEnv: 'AGENTIC_SECURITY_NO_STRING_MEMO' });
+function stripNoiseAndStrings(code){ return _stripNoiseAndStringsMemo(code); }
+function _stripNoiseAndStringsRaw(code){
   const out = code.split('');
   const n = code.length;
   let i = 0;
@@ -3134,6 +3142,27 @@ function getProjectConstant(name){
   return hit ? hit.value : null;
 }
 
+// E6-04: a digest of every input OUTSIDE a single file that the per-file detector cascade reads: the project index (constants, properties, the
+// e-commerce flag), the Java tainted-method index, and the operator's rules file with its signature. A cached per-file result is reused only when this
+// is unchanged, so a change to a constant in one file cannot leave another file's cached answer standing.
+const _ANALYSIS_CACHE_NEVER_RE = /(?:^|[\\/])\.?mcp(?:\.[a-z]+)?\.json$|(?:^|[\\/])\.mcp\.json$/i;
+function _analysisContextDigest(scanRoot){
+  const h = crypto.createHash('sha256');
+  const mapEntries = (m) => [...(m || new Map()).entries()].map(([k, v]) => [k, v]).sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+  h.update(JSON.stringify({
+    ecommerce: !!_projectIndex.hasEcommerceModel,
+    byFile: mapEntries(_projectIndex.constantsByFile),
+    byExport: mapEntries(_projectIndex.constantsByExport),
+    props: mapEntries(_projectIndex.javaProperties),
+    javaTainted: [..._GLOBAL_JAVA_TAINTED_METHODS].sort(),
+  }));
+  for (const name of ['rules.yml', 'rules.yaml', 'rules.json', 'rules.yml.sig', 'rules.yaml.sig', 'rules.json.sig']) {
+    h.update(`\n${name}\0`);
+    try { h.update(fs.readFileSync(statePath(scanRoot, name))); } catch { h.update('absent'); }
+  }
+  return h.digest('hex');
+}
+
 const _COUPON_MUTATION_RE = /\b(?:apply|redeem|validate|use|deduct|decrement|increment|update|save|consume|create|destroy|remove|insert)\b/i;
 const _REAUTH_PRESENT_RE  = /\b(?:bcrypt\.compare|crypto\.timingSafeEqual|currentPassword|recentLogin|verifyTotp|verifyMfa|mfaToken|requireRecentLogin|requireFreshSession|step[-_]?up|requireFreshAuth|verifyPassword)\b/;
 
@@ -8859,7 +8888,12 @@ function _gcHint(minHeapMiB) {
   _gcFn();
 }
 
-async function runFullScan({fileContents={}, depFileContents={}, scanRoot=null, resume=undefined, deep=undefined, deepInCi=undefined, provenance=true, completeScan=true, skipAnnotators=false, policyExcluded=[], sizeSkipped=[]}, setProgress=()=>{}){_resetSuppressions();_buildProjectIndex(fileContents);await _loadCustomRules(scanRoot);
+async function runFullScan({fileContents={}, depFileContents={}, scanRoot=null, resume=undefined, deep=undefined, deepInCi=undefined, provenance=true, completeScan=true, skipAnnotators=false, policyExcluded=[], sizeSkipped=[]}, setProgress=()=>{}){
+  // E6-01: local, aggregate telemetry for this scan (see pipeline/telemetry.js). Nothing is sent anywhere; the snapshot is a field of the result.
+  const _tel = createTelemetry({ deterministic: isDeterministic() });
+  setDetectorTimingSink((name, ms) => _tel.detector(name, ms));
+  _tel.sample();
+  _resetSuppressions();_tel.time('index', () => _buildProjectIndex(fileContents));await _tel.timeAsync('custom-rules', () => _loadCustomRules(scanRoot));
   // Pre-pass: build cross-file Java tainted-method index so per-file taint
   // analysis can recognize calls to user-input-returning helper methods
   // defined in OTHER files (Juliet's DataflowThruInnerClass / Vector / Stream
@@ -8885,17 +8919,20 @@ function _deterministicFileTimings(timings) {
 }
 
   const _fileTimings = [];
-  let _filesSkipped = 0, _filesTimedOut = 0, _filesDenseSkipped = 0;
+  let _filesSkipped = 0, _filesTimedOut = 0, _filesDenseSkipped = 0, _filesOversizeSkipped = 0;
   const files=Object.keys(fileContents).filter(f=>(shouldScan(f) || isKubernetesManifest(f, fileContents[f]) || isCloudFormationTemplate(f, fileContents[f]) || isInstructionFile(f)) && !_isPathIgnored(f));const fc={},pfr={};const aR=[],aF=[],aSrc=[],aSink=[],aSan=[],aLogic=[],aSupply=[],aSecrets=[],aCiphersRest=[],aCiphersTransit=[];const _detectorErrors=[];
   // ---- R8: opt-in per-file checkpointing (AGENTIC_SECURITY_RESUME=1, or
   // runScan({resume:true})). Default OFF, so existing behaviour is untouched.
   // Only this loop is checkpointed; every cross-file pass below re-runs, so
   // nothing that depends on the whole tree can be stale on resume.
   const _ckptEnabled = (resume === undefined ? process.env.AGENTIC_SECURITY_RESUME === '1' : !!resume) && !!scanRoot;
+  // E6-04: opt-in cross-scan analysis cache (AGENTIC_SECURITY_ANALYSIS_CACHE=1). Same per-file record format as the resume checkpoint, but it is kept after
+  // a completed scan, its records are authenticated with the install key, and the global key also covers the cross-file inputs a file's cascade reads.
+  const _cacheEnabled = !_ckptEnabled && process.env.AGENTIC_SECURITY_ANALYSIS_CACHE === '1' && !!scanRoot;
   let _ckpt = null; const _ckptPayloads = new Map(); let _ckptDone = new Set(); let _ckptResumed = 0, _ckptWrites = 0;
   const _ckptAbortAfter = parseInt(process.env.AGENTIC_SECURITY_CHECKPOINT_ABORT_AFTER || '0', 10) || 0;
   let _ckptInvalidated = [];
-  if (_ckptEnabled) {
+  if (_ckptEnabled || _cacheEnabled) {
     try {
       const _ckptIdentity = {
         engineVersion: _ENGINE_VERSION,
@@ -8909,8 +8946,9 @@ function _deterministicFileTimings(timings) {
       // instead, so changing one file no longer discards every other file's
       // already-completed work — see scan-checkpoint.js's module header.
       _ckpt = openCheckpoint(scanRoot, {
-        globalKey: computeGlobalKey(_ckptIdentity),
+        globalKey: computeGlobalKey(_cacheEnabled ? { ..._ckptIdentity, extra: _analysisContextDigest(scanRoot) } : _ckptIdentity),
         meta: globalKeyMeta(_ckptIdentity),
+        ...(_cacheEnabled ? { persistent: true, fileName: 'analysis-cache.jsonl', sign: signLastScan } : {}),
         // Haskell/Nix sources hash with their import closure, so an imported
         // module's change invalidates its importers' checkpointed work too.
         fileContents: withLanguageClosure(fileContents, depFileContents),
@@ -8939,6 +8977,17 @@ function _deterministicFileTimings(timings) {
     for (const x of (d.ciphersRest || [])) aCiphersRest.push(x);
     for (const x of (d.ciphersTransit || [])) aCiphersTransit.push(x);
     for (const x of (d.suppressions || [])) _suppressionLog.push(x);
+    // A finding's `source` and `sink` ARE the entries of this file's source and sink lists (one object, two references), and later passes annotate them in
+    // place (flowStatus, riskStatus, ...). Reading a record back from JSON gives each reference its own copy, so the annotation would reach the list entry
+    // and not the finding. Re-pointing the finding at the matching list entry restores the sharing a fresh analysis has.
+    {
+      const srcByJson = new Map(); for (const x of aSrc.slice(s0)) srcByJson.set(JSON.stringify(x), x);
+      const sinkByJson = new Map(); for (const x of aSink.slice(k0)) sinkByJson.set(JSON.stringify(x), x);
+      for (const f of aF.slice(f0)) {
+        if (f && f.source && typeof f.source === 'object') { const m = srcByJson.get(JSON.stringify(f.source)); if (m) f.source = m; }
+        if (f && f.sink && typeof f.sink === 'object') { const m = sinkByJson.get(JSON.stringify(f.sink)); if (m) f.sink = m; }
+      }
+    }
     const ta = Object.assign({}, d.pfr || {});
     ta.findings = aF.slice(f0, f0 + (d.pfrFindings || 0));
     ta.sources = aSrc.slice(s0); ta.sinks = aSink.slice(k0); ta.sanitizers = aSan.slice(n0);
@@ -8947,9 +8996,10 @@ function _deterministicFileTimings(timings) {
     _ckptResumed++;
     return true;
   };
+  let _cacheSecretSkips = 0;
   const _ckptRecord = (p, mk, ms, ta) => {
     if (!_ckpt || !_ckpt.enabled) return;
-    recordFileDone(_ckpt, p, {
+    const _payload = {
       routes: aR.slice(mk.aR), findings: aF.slice(mk.aF),
       sources: aSrc.slice(mk.aSrc), sinks: aSink.slice(mk.aSink), sanitizers: aSan.slice(mk.aSan),
       logic: aLogic.slice(mk.aLogic), secrets: aSecrets.slice(mk.aSecrets),
@@ -8958,7 +9008,10 @@ function _deterministicFileTimings(timings) {
       pfr: _pfrMetaOnly(ta),
       pfrFindings: (ta && Array.isArray(ta.findings)) ? ta.findings.length : 0,
       ms,
-    });
+    };
+    // A cache that outlives the scan must not become a second copy of a secret: a file whose result contains a secret-shaped value is analysed afresh each time.
+    if (_cacheEnabled) { let _txt = ''; try { _txt = JSON.stringify(_payload); } catch { /* not serializable: recordFileDone refuses it too */ } if (secretCanaryHit(_txt)) { _cacheSecretSkips++; return; } }
+    recordFileDone(_ckpt, p, _payload);
     _ckptWrites++;
     // Fault injection for the resume test: a hard exit with no unwinding, which
     // is what the checkpoint format has to survive. Never set in normal use.
@@ -8978,12 +9031,13 @@ function _deterministicFileTimings(timings) {
     });
   }
   let i=0;
+  const _tDet = Date.now();
   try {
   for(const p of files){i++;const _ft0=Date.now();setProgress({current:i,total:files.length,file:p.split("/").pop(),phase:"Scanning"});
     if(_ckptDone.has(p)&&_ckptReplay(p))continue;
     const _mk={aR:aR.length,aF:aF.length,aSrc:aSrc.length,aSink:aSink.length,aSan:aSan.length,aLogic:aLogic.length,aSecrets:aSecrets.length,aCR:aCiphersRest.length,aCT:aCiphersTransit.length,sup:_suppressionLog.length};
-    try{const c=fileContents[p];if(!c||c.length>500000){_filesSkipped++;continue;}const _avgLine=c.length/Math.max(c.split('\n').length,1);if(_avgLine>400&&c.length>10000){_filesDenseSkipped++;continue;}
-      let _delta;
+    try{const c=fileContents[p];if(!c||c.length>500000){_filesSkipped++;if(c&&c.length>500000)_filesOversizeSkipped++;continue;}const _avgLine=c.length/Math.max(c.split('\n').length,1);if(_avgLine>400&&c.length>10000){_filesDenseSkipped++;continue;}
+      let _delta; const _errsBefore = _detectorErrors.length;
       if (_cascadePool) {
         const _res = await _cascadePool.runFile(p, c, scanRoot, _detectorErrors, { timeoutMs: _perFileTimeoutMs });
         if (_res.ok) { _delta = _res.result; }
@@ -8997,7 +9051,9 @@ function _deterministicFileTimings(timings) {
       const _ftElapsed=Date.now()-_ft0;
       if(_ftElapsed>_perFileTimeoutMs){aF.push({id:`file-timeout:${p}`,file:p,line:0,vuln:`File analysis exceeded ${_perFileTimeoutMs}ms (${_ftElapsed}ms)`,severity:'info',parser:'ENGINE',confidence:0.5,_timeout:true});_filesTimedOut++;}
       _fileTimings.push({file:p,ms:_ftElapsed});
-      _ckptRecord(p,_mk,_ftElapsed,_delta.pfr);
+      // The cache only keeps a file whose analysis finished cleanly: a detector that threw, a timeout, or a file whose analysis reads or writes state outside
+      // itself (the MCP rug-pull baseline) is analysed afresh every time so health reporting and side effects stay exactly as they are.
+      if (!_cacheEnabled || (_detectorErrors.length === _errsBefore && _ftElapsed <= _perFileTimeoutMs && !_ANALYSIS_CACHE_NEVER_RE.test(p))) _ckptRecord(p,_mk,_ftElapsed,_delta.pfr);
     }catch(_){_fileTimings.push({file:p,ms:Date.now()-_ft0,error:true});}
     if(i%5===0)await new Promise(r=>setTimeout(r,0));}
   } finally {
@@ -9146,6 +9202,8 @@ function _deterministicFileTimings(timings) {
     };
     filterArr(aF); filterArr(aLogic); filterArr(aSecrets); filterArr(aSupply);
   }
+  _tel.record('detectors-per-file', Date.now() - _tDet);
+  const _tLink = Date.now();
   setProgress({current:i,total:files.length,file:"Cross-file...",phase:"Linking"});const ii=buildImportGraph(fc);const cf=crossFileTaint(pfr,fc,ii);aF.push(...cf);
   setProgress({current:i,total:files.length,file:"Stored taint...",phase:"Linking"});const storedRegistry=buildStoredTaintRegistry(fc);const stf=crossStoredTaint(fc,storedRegistry);aF.push(...stf);
   setProgress({current:i,total:files.length,file:"Session taint...",phase:"Linking"});const sess=crossSessionTaint(fc);aF.push(...sess);
@@ -9153,6 +9211,7 @@ function _deterministicFileTimings(timings) {
   // R19 (PRD §5): cross-route BOLA/BFLA over the aggregated route inventory.
   // Convention deviation is PROJECT-scoped by design: the convention is a
   // property of the codebase, not of one file (see convention-deviation.js).
+  _tel.record('cross-file-linking', Date.now() - _tLink);
   aF.push(...(runDetector(_detectorErrors,'<project>','scanConventionDeviationProject',()=>scanConventionDeviationProject(fc))||[]));
   aF.push(...(runDetector(_detectorErrors,'<project>','scanApiBrokenAuthz',()=>scanApiBrokenAuthz(aR))||[]));
   // R22 (PRD §5): cross-service edges inferred from code (client call → matched route).
@@ -9432,6 +9491,7 @@ function _deterministicFileTimings(timings) {
   const _deepEnabled = _deepRequested && (!_inCi || _deepInCiAllowed);
   let _deepCallGraph = null;
   let _deepFailure = null;
+  let _deepIncomplete = null;
   if (_deepEnabled) {
     const budgetMs = parseInt(process.env.AGENTIC_SECURITY_DEEP_TIMEOUT_MS || '300000', 10);
     const t0 = Date.now();
@@ -9462,6 +9522,8 @@ function _deterministicFileTimings(timings) {
         }),
       });
       const elapsed = Date.now() - t0;
+      _tel.record('deep-analysis', elapsed);
+      if (irFindings.analysisIncomplete && irFindings._summaryCache && typeof irFindings._summaryCache.stats === 'function') { const st = irFindings._summaryCache.stats(); _tel.set('cache.summary.hits', st.hits); _tel.set('cache.summary.misses', st.misses); }
       if (elapsed > budgetMs) {
         // We exceeded budget — surface a single info finding so operators see it.
         aF.push({
@@ -9473,6 +9535,7 @@ function _deterministicFileTimings(timings) {
           confidence: 0.5,
         });
       }
+      if (Array.isArray(irFindings.analysisIncomplete) && irFindings.analysisIncomplete.length) _deepIncomplete = irFindings.analysisIncomplete;
       for (const f of irFindings) {
         f.unvalidated = true;
         f.validator_verdict = 'unvalidated';
@@ -9514,6 +9577,8 @@ function _deterministicFileTimings(timings) {
           ? (_inCi ? 'requested, but running in CI without AGENTIC_SECURITY_DEEP_IN_CI=1' : 'unknown')
           : (_inCi ? 'not requested (deep analysis defaults to off in CI)' : 'not requested')),
     failure: _deepFailure,
+    // E2-05: where the deep analysis stopped short (budget, deadline, function limit, a thrown analysis). Present only when something did.
+    ...(_deepIncomplete ? { incomplete: _deepIncomplete } : {}),
   };
   // Sub-project E, increment 5 — Data Flow Explorer lineage graph.
   // DELIBERATELY INDEPENDENT of AGENTIC_SECURITY_DEEP/_deepEnabled above
@@ -9861,7 +9926,7 @@ function _deterministicFileTimings(timings) {
   let _annotatorIdx = 0;
   const _runAnnotator = (phase, fn) => {
     setProgress({ phase: 'Annotating', current: ++_annotatorIdx, total: _ANNOTATOR_TOTAL_ESTIMATE, file: phase });
-    return runAnnotatorAsync(_annotatorErrors, phase, fn);
+    return _tel.timeAsync(`annotator:${phase}`, () => runAnnotatorAsync(_annotatorErrors, phase, fn));
   };
   await _runAnnotator('annotateStableIds', () => annotateStableIds(finalFindings));
   await _runAnnotator("clusterByRootCause", () => { finalFindings = clusterByRootCause(finalFindings); });
@@ -10740,7 +10805,7 @@ function _deterministicFileTimings(timings) {
   // seen when only N-of-those-candidates were actually analyzed.
   // checkpoint.total intentionally keeps files.length — that field means the
   // full candidate set for resume bookkeeping, a different, correct meaning.
-  _scanMeta={filesScanned:Object.keys(fc).length,filesSkipped:_filesSkipped,filesDenseSkipped:_filesDenseSkipped,filesTimedOut:_filesTimedOut,analysisTier:_analysisTier,unmodeledSinkCandidates:_unmodeledSinks,fileTimings:_deterministicFileTimings(_fileTimings),findingsBySeverity:{critical:finalFindings.filter(f=>f.severity==='critical').length,high:finalFindings.filter(f=>f.severity==='high').length,medium:finalFindings.filter(f=>f.severity==='medium').length,low:finalFindings.filter(f=>f.severity==='low').length,info:finalFindings.filter(f=>f.severity==='info').length},checkpoint:{enabled:!!(_ckpt&&_ckpt.enabled),resumed:_ckptResumed,total:files.length,discarded:!!(_ckpt&&_ckpt.discarded),discardReason:(_ckpt&&_ckpt.discarded)?(_ckpt.reason||null):null,invalidatedFileCount:_ckptInvalidated.length,invalidatedFiles:_ckptInvalidated.slice(0,20),invalidatedFilesTruncated:_ckptInvalidated.length>20}};
+  _scanMeta={filesScanned:Object.keys(fc).length,filesSkipped:_filesSkipped,filesOversizeSkipped:_filesOversizeSkipped,filesDenseSkipped:_filesDenseSkipped,filesTimedOut:_filesTimedOut,analysisTier:_analysisTier,unmodeledSinkCandidates:_unmodeledSinks,fileTimings:_deterministicFileTimings(_fileTimings),findingsBySeverity:{critical:finalFindings.filter(f=>f.severity==='critical').length,high:finalFindings.filter(f=>f.severity==='high').length,medium:finalFindings.filter(f=>f.severity==='medium').length,low:finalFindings.filter(f=>f.severity==='low').length,info:finalFindings.filter(f=>f.severity==='info').length},checkpoint:{enabled:!!(_ckpt&&_ckpt.enabled),...(_cacheEnabled?{kind:'analysis-cache',secretSkips:_cacheSecretSkips}:{}),resumed:_ckptResumed,total:files.length,discarded:!!(_ckpt&&_ckpt.discarded),discardReason:(_ckpt&&_ckpt.discarded)?(_ckpt.reason||null):null,invalidatedFileCount:_ckptInvalidated.length,invalidatedFiles:_ckptInvalidated.slice(0,20),invalidatedFilesTruncated:_ckptInvalidated.length>20}};
   // R8: the scan completed, so the checkpoint has been fully consumed — remove
   // it. Anything that threw before this point leaves it in place to resume from.
   try { closeCheckpoint(_ckpt, { complete: true }); } catch (_) {}
@@ -11163,7 +11228,10 @@ function _deterministicFileTimings(timings) {
     compliance: _complianceReport ? { stale: _complianceReport.summary?.stale || 0 } : null,
   });
   } // end if (!skipAnnotators) — FR-PROV-029
-  return{entrypointInventory:_entrypointInventory,rootCauseSweep:_rootCauseSweep,proofCoverage:_proofCoverage,kevCatalog:kevCatalogMeta(),routes:dd(aR,r=>`${r.method}:${r.path}:${r.file}:${r.line}`),findings:finalFindings,sources:aSrc,sinks:aSink,sanitizers:aSan,filesScanned:files.length,linesScanned:Object.values(fc).reduce((_n,_c)=>_n+(typeof _c==='string'?_c.split("\n").length:0),0),crossFileCount:cf.length,logicVulns:aLogic,supplyChain,components:annotatedComponents,secrets:aSecrets,ciphers:{atRest:aCiphersRest,inTransit:aCiphersTransit},pfr,fc,depFileContents,suppressions:_getSuppressions(),...(_stageEvidenceOn()?{stageEvidence:{dedupe:[..._stageEvidence.dedupe],guard:[..._stageEvidence.guard]}}:{}),_v3,_scanMeta,_engineErrors:{cppDataflowParseErrors:_cppDataflowParseErrors.value},annotatorErrors:_annotatorErrors,detectorErrors:_detectorErrors,executionProof:_executionProofSummary,logicClaims:_logicClaims,vulnHistory:_vulnHistory,threatModel:_threatModel,privacyFramework:_privacyFramework,privacyIrBacked:_privacyIrBacked,privacyTaxonomyVersion:_privacyTaxonomyVersion,sbomDiff:_sbomDiff,complianceReport:_complianceReport,exploitBundles:_exploitBundles,pqcPlan:_pqcPlan,licenseGraph:_licenseGraph,attributions:_attributions,attackTaxonomy:_taxonomySummary,scanHealth:_scanHealth,coverageLedger:_coverageLedger,lineageGraph:_lineageGraph,lineageStatus:_lineageStatus,languageBridges:_languageBridges,languageBom:_languageBom,aiAssistance:_aiAssistance};}
+  setDetectorTimingSink(null);
+  attributeErrors(_tel, { annotatorErrors: _annotatorErrors, detectorErrors: (typeof _detectorErrors !== 'undefined' ? _detectorErrors : []), deepFailure: _deepFailure, filesTimedOut: (_scanMeta && _scanMeta.filesTimedOut) || 0 });
+  _tel.set('files.scanned', (_scanMeta && _scanMeta.filesScanned) || 0); _tel.set('files.skipped', (_scanMeta && _scanMeta.filesSkipped) || 0);
+  return{telemetry:_tel.snapshot(),entrypointInventory:_entrypointInventory,rootCauseSweep:_rootCauseSweep,proofCoverage:_proofCoverage,kevCatalog:kevCatalogMeta(),routes:dd(aR,r=>`${r.method}:${r.path}:${r.file}:${r.line}`),findings:finalFindings,sources:aSrc,sinks:aSink,sanitizers:aSan,filesScanned:files.length,linesScanned:Object.values(fc).reduce((_n,_c)=>_n+(typeof _c==='string'?_c.split("\n").length:0),0),crossFileCount:cf.length,logicVulns:aLogic,supplyChain,components:annotatedComponents,secrets:aSecrets,ciphers:{atRest:aCiphersRest,inTransit:aCiphersTransit},pfr,fc,depFileContents,suppressions:_getSuppressions(),...(_stageEvidenceOn()?{stageEvidence:{dedupe:[..._stageEvidence.dedupe],guard:[..._stageEvidence.guard]}}:{}),_v3,_scanMeta,_engineErrors:{cppDataflowParseErrors:_cppDataflowParseErrors.value},annotatorErrors:_annotatorErrors,detectorErrors:_detectorErrors,executionProof:_executionProofSummary,logicClaims:_logicClaims,vulnHistory:_vulnHistory,threatModel:_threatModel,privacyFramework:_privacyFramework,privacyIrBacked:_privacyIrBacked,privacyTaxonomyVersion:_privacyTaxonomyVersion,sbomDiff:_sbomDiff,complianceReport:_complianceReport,exploitBundles:_exploitBundles,pqcPlan:_pqcPlan,licenseGraph:_licenseGraph,attributions:_attributions,attackTaxonomy:_taxonomySummary,scanHealth:_scanHealth,coverageLedger:_coverageLedger,lineageGraph:_lineageGraph,lineageStatus:_lineageStatus,languageBridges:_languageBridges,languageBom:_languageBom,aiAssistance:_aiAssistance};}
 
 // Post-aggregation classification: every source becomes "unsafe"|"safe"; every sink becomes "confirmed"|"safe".
 // Orphans (no finding linkage) are bucketed by file-local heuristic so the UI shows binary states only.