@clear-capabilities/agentic-security-scanner 0.172.0 → 0.173.0

package/src/context-intelligence/invariants.js

@@ -0,0 +1,197 @@
+// First-class security invariants for Deterministic Context Intelligence (E4-02).
+//
+// An invariant is a rule a team states once, in a versioned file, and the analysis then checks on every entry point it applies to:
+// "every /orders route must be authenticated and owner-scoped", "the health check is public by design". It replaces the reviewer's unwritten
+// expectation with something that can be validated, scoped, expired and audited.
+//
+// FILE      context-intelligence-invariants.json at the project root (or a path the caller passes)
+// SCHEMA    { schema: 'agentic-security/dci-invariants', schemaVersion: '1.0.0', invariants: [ ... ] }
+// RULES     'requires'         the matching entry points must carry every listed control before their first sensitive operation
+//           'public-by-design' the matching entry points are deliberately open on the listed dimensions; this is the only way a missing control
+//                              is accepted, and it needs a reason, an owner and a review date
+// SCOPE     appliesTo.routes / methods choose entry points by label; validity.paths limits the invariant to handlers in those files
+//           (path-scoped validity); validity.from / until bound it in time. An invariant that is out of scope for an entry point says
+//           `not_applicable`, never `satisfied`.
+//
+// VERDICTS  satisfied | violated | unknown (the analysis could not resolve enough to say) | not_applicable | public_by_policy | expired
+// A verdict never rests on a model. It reads the protection states DCI already computed, so it is as strong as that evidence and says so.
+//
+// The validator is closed-world: an unknown field, a duplicate id, an empty control list, a glob that is not a glob, a public-by-design with no
+// reason, or an invariant already past its `until` date is reported with a path and a code, never silently dropped.
+import { existsSync, readFileSync } from 'node:fs';
+import { join as pathJoin } from 'node:path';
+
+export const INVARIANTS_SCHEMA = 'agentic-security/dci-invariants';
+export const INVARIANTS_VERSION = '1.0.0';
+export const INVARIANTS_FILE = 'context-intelligence-invariants.json';
+export const CONTROL_DIMENSIONS = Object.freeze(['authentication', 'authorization-role', 'ownership', 'tenant-scope']);
+export const VERDICTS = Object.freeze(['satisfied', 'violated', 'unknown', 'not_applicable', 'public_by_policy', 'expired']);
+const RULES = ['requires', 'public-by-design'];
+const METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS', 'ANY'];
+const ID_RE = /^[A-Z][A-Z0-9-]{2,63}$/;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const TOP = ['schema', 'schemaVersion', 'invariants'];
+const INV = ['id', 'title', 'rule', 'appliesTo', 'requires', 'waives', 'public', 'validity', 'severity'];
+const APPLIES = ['routes', 'methods'];
+const VALID = ['paths', 'from', 'until'];
+const PUB = ['reason', 'owner', 'reviewBy'];
+const SEVERITIES = ['critical', 'high', 'medium', 'low'];
+
+const isObj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const validGlob = (g) => typeof g === 'string' && g.length > 0 && g.length <= 200 && !/[\0\r\n]/.test(g) && !/\*\*\*/.test(g) && !g.includes('..');
+
+/** Glob to RegExp: `**` any characters, `*` any characters except `/`, everything else literal. */
+export function globToRegExp(glob) {
+  let re = '';
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === '*') { if (glob[i + 1] === '*') { re += '.*'; i++; } else re += '[^/]*'; } else re += c.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+  }
+  return new RegExp(`^${re}$`);
+}
+
+/** @returns {{ok:boolean, errors:{code:string,path:string,message:string}[], warnings:{code:string,path:string,message:string}[]}} */
+export function validateInvariants(doc, { now = new Date() } = {}) {
+  const errors = []; const warnings = [];
+  const err = (code, path, message) => errors.push({ code, path, message });
+  const warn = (code, path, message) => warnings.push({ code, path, message });
+  if (!isObj(doc)) { err('NOT_AN_OBJECT', '', 'the invariants file must be a JSON object'); return { ok: false, errors, warnings }; }
+  for (const k of Object.keys(doc)) if (!TOP.includes(k)) err('UNKNOWN_FIELD', k, `field '${k}' is not part of this schema`);
+  if (doc.schema !== INVARIANTS_SCHEMA) { err('SCHEMA_MISMATCH', 'schema', `expected ${INVARIANTS_SCHEMA}`); return { ok: false, errors, warnings }; }
+  const m = typeof doc.schemaVersion === 'string' ? /^(\d+)\.(\d+)\.(\d+)$/.exec(doc.schemaVersion) : null;
+  if (!m) { err('BAD_VERSION', 'schemaVersion', 'must be a semantic version'); return { ok: false, errors, warnings }; }
+  if (Number(m[1]) !== 1) { err('UNSUPPORTED_MAJOR', 'schemaVersion', `major ${m[1]} is not supported (supported: 1)`); return { ok: false, errors, warnings }; }
+  if (!Array.isArray(doc.invariants)) { err('MISSING_FIELD', 'invariants', 'must be a list'); return { ok: false, errors, warnings }; }
+  if (doc.invariants.length > 500) err('TOO_MANY', 'invariants', 'at most 500 invariants');
+  const today = new Date(now); const iso = (d) => d.toISOString().slice(0, 10);
+  const seen = new Set();
+  doc.invariants.forEach((inv, i) => {
+    const p = `invariants[${i}]`;
+    if (!isObj(inv)) { err('BAD_TYPE', p, 'an invariant is an object'); return; }
+    for (const k of Object.keys(inv)) if (!INV.includes(k)) err('UNKNOWN_FIELD', `${p}.${k}`, `field '${k}' is not part of an invariant`);
+    if (typeof inv.id !== 'string' || !ID_RE.test(inv.id)) err('BAD_ID', `${p}.id`, 'id must look like ORDERS-001: capitals, digits and hyphens, 3 to 64 characters');
+    else if (seen.has(inv.id)) err('DUPLICATE_ID', `${p}.id`, `duplicate id ${inv.id}`); else seen.add(inv.id);
+    if (typeof inv.title !== 'string' || !inv.title.trim()) err('MISSING_FIELD', `${p}.title`, 'a title is required');
+    if (!RULES.includes(inv.rule)) err('UNKNOWN_ENUM', `${p}.rule`, `rule must be one of ${RULES.join(', ')}`);
+    if (inv.severity !== undefined && !SEVERITIES.includes(inv.severity)) err('UNKNOWN_ENUM', `${p}.severity`, `severity must be one of ${SEVERITIES.join(', ')}`);
+    const a = inv.appliesTo;
+    if (!isObj(a)) err('MISSING_FIELD', `${p}.appliesTo`, 'appliesTo is required');
+    else {
+      for (const k of Object.keys(a)) if (!APPLIES.includes(k)) err('UNKNOWN_FIELD', `${p}.appliesTo.${k}`, `field '${k}' is not part of appliesTo`);
+      if (!Array.isArray(a.routes) || !a.routes.length) err('MISSING_FIELD', `${p}.appliesTo.routes`, 'at least one route glob is required');
+      else a.routes.forEach((g, j) => { if (!validGlob(g)) err('BAD_GLOB', `${p}.appliesTo.routes[${j}]`, 'not a usable glob'); else if (g === '**' || g === '/**') warn('BROAD_SCOPE', `${p}.appliesTo.routes[${j}]`, 'matches every route'); });
+      if (a.methods !== undefined && (!Array.isArray(a.methods) || !a.methods.length || a.methods.some((x) => !METHODS.includes(x)))) err('UNKNOWN_ENUM', `${p}.appliesTo.methods`, `methods must be a non-empty list of ${METHODS.join(', ')}`);
+    }
+    const dimList = (field, value) => {
+      if (!Array.isArray(value) || !value.length) { err('MISSING_FIELD', `${p}.${field}`, `${field} must list at least one control`); return; }
+      if (new Set(value).size !== value.length) err('DUPLICATE_ID', `${p}.${field}`, 'a control is listed twice');
+      value.forEach((d, j) => { if (!CONTROL_DIMENSIONS.includes(d)) err('UNKNOWN_ENUM', `${p}.${field}[${j}]`, `control must be one of ${CONTROL_DIMENSIONS.join(', ')}`); });
+    };
+    if (inv.rule === 'requires') {
+      dimList('requires', inv.requires);
+      if (inv.waives !== undefined || inv.public !== undefined) err('RULE_VIOLATION', `${p}`, "'requires' does not take waives or public");
+    } else if (inv.rule === 'public-by-design') {
+      dimList('waives', inv.waives);
+      if (inv.requires !== undefined) err('RULE_VIOLATION', `${p}.requires`, "'public-by-design' does not take requires");
+      const pub = inv.public;
+      if (!isObj(pub)) err('MISSING_FIELD', `${p}.public`, 'a public-by-design invariant needs { reason, owner, reviewBy }');
+      else {
+        for (const k of Object.keys(pub)) if (!PUB.includes(k)) err('UNKNOWN_FIELD', `${p}.public.${k}`, `field '${k}' is not part of public`);
+        if (typeof pub.reason !== 'string' || pub.reason.trim().length < 10) err('MISSING_FIELD', `${p}.public.reason`, 'a reason of at least 10 characters is required: openness must be justified');
+        if (typeof pub.owner !== 'string' || !pub.owner.trim()) err('MISSING_FIELD', `${p}.public.owner`, 'an owner is required');
+        if (typeof pub.reviewBy !== 'string' || !DATE_RE.test(pub.reviewBy) || Number.isNaN(Date.parse(pub.reviewBy))) err('BAD_DATE', `${p}.public.reviewBy`, 'reviewBy must be a YYYY-MM-DD date');
+        else if (pub.reviewBy < iso(today)) err('EXPIRED', `${p}.public.reviewBy`, `the review date ${pub.reviewBy} has passed: public-by-design must be re-approved`);
+      }
+    }
+    const v = inv.validity;
+    if (v !== undefined) {
+      if (!isObj(v)) err('BAD_TYPE', `${p}.validity`, 'validity is an object');
+      else {
+        for (const k of Object.keys(v)) if (!VALID.includes(k)) err('UNKNOWN_FIELD', `${p}.validity.${k}`, `field '${k}' is not part of validity`);
+        if (v.paths !== undefined) { if (!Array.isArray(v.paths) || !v.paths.length) err('BAD_TYPE', `${p}.validity.paths`, 'paths must be a non-empty list of globs'); else v.paths.forEach((g, j) => { if (!validGlob(g)) err('BAD_GLOB', `${p}.validity.paths[${j}]`, 'not a usable glob'); }); }
+        for (const f of ['from', 'until']) if (v[f] !== undefined && (typeof v[f] !== 'string' || !DATE_RE.test(v[f]) || Number.isNaN(Date.parse(v[f])))) err('BAD_DATE', `${p}.validity.${f}`, `${f} must be a YYYY-MM-DD date`);
+        if (v.from && v.until && v.from > v.until) err('RULE_VIOLATION', `${p}.validity`, 'from is after until');
+        if (v.until && v.until < iso(today)) warn('PAST_UNTIL', `${p}.validity.until`, `until ${v.until} has passed: the invariant is reported as expired`);
+      }
+    }
+  });
+  return { ok: errors.length === 0, errors, warnings };
+}
+
+const norm = (s) => String(s || '').trim();
+function routeMatches(a, label, method) {
+  if (Array.isArray(a.methods) && method && !a.methods.includes('ANY') && !a.methods.includes(method) && method !== 'ANY') return false;
+  // the label is `METHOD /path`; route globs name the path
+  const path = norm(label).replace(/^[A-Z]+\s+/, '');
+  return a.routes.some((g) => globToRegExp(g).test(path));
+}
+function handlerFile(ep) { return ep?.rootSpan?.file || ep?.registrationSite?.file || ''; }
+
+/** Control state of one dimension for a bundle: present / absent / unresolved / none-to-protect. */
+function dimensionState(bundle, dim) {
+  const prot = bundle.manifest?.protection || {};
+  if (dim === 'tenant-scope') {
+    const facts = bundle.reach?.facts || [];
+    const sens = facts.filter((f) => f.category === 'sensitive');
+    if (!sens.length) return { state: 'none-to-protect', why: 'no sensitive operation was seen' };
+    const first = Math.min(...sens.map((f) => f.effLine));
+    const ctl = facts.filter((f) => f.category === 'control' && f.kind === 'tenant-scope' && (f.effLine < first || (f.basis === 'query-filter' && f.effLine <= first)));
+    if (ctl.length) return { state: 'present', why: 'a tenant scope precedes the first sensitive operation', evidence: ctl.slice(0, 4).map((f) => ({ file: f.file, line: f.line, basis: f.basis })) };
+    const unresolved = (bundle.manifest?.unknowns || []).some((u) => u.material);
+    return unresolved ? { state: 'unresolved', why: 'an unresolved call could hide a tenant scope' } : { state: 'absent', why: 'the resolved context contains no tenant scope' };
+  }
+  const d = prot[dim];
+  if (!d) return { state: 'unresolved', why: 'the bundle carries no protection verdict for this dimension' };
+  if (d.state === 'present') return { state: 'present', why: d.why, evidence: d.evidence };
+  if (d.state === 'not_seen') return { state: 'none-to-protect', why: d.why };
+  if (d.state === 'not_present' || d.state === 'evaluated_and_ineffective') return { state: 'absent', why: d.why, evidence: d.evidence };
+  return { state: 'unresolved', why: d.why };
+}
+
+/**
+ * @param {object} doc a validated invariants document
+ * @param {{entrypoint:object, manifest:object, reach:object}[]} bundles the bundles buildContext returned (those with a manifest)
+ * @returns {{results:object[], problems:string[]}}
+ */
+export function evaluateInvariants(doc, bundles, { now = new Date() } = {}) {
+  const v = validateInvariants(doc, { now });
+  if (!v.ok) return { results: [], problems: v.errors.map((e) => `${e.path}: ${e.code}`) };
+  const today = now.toISOString().slice(0, 10);
+  const results = [];
+  const publics = doc.invariants.filter((i) => i.rule === 'public-by-design');
+  for (const b of bundles.filter((x) => x.manifest)) {
+    const ep = b.entrypoint; const file = handlerFile(ep);
+    for (const inv of doc.invariants) {
+      if (inv.rule !== 'requires') continue;
+      const base = { invariantId: inv.id, title: inv.title, entrypointId: ep.id, label: ep.label, file, ...(inv.severity ? { severity: inv.severity } : {}) };
+      if (!routeMatches(inv.appliesTo, ep.label, ep.method)) continue;
+      const val = inv.validity || {};
+      if (Array.isArray(val.paths) && !val.paths.some((g) => globToRegExp(g).test(file))) { results.push({ ...base, verdict: 'not_applicable', reasons: [`the handler file ${file} is outside this invariant's validity paths`] }); continue; }
+      if (val.from && today < val.from) { results.push({ ...base, verdict: 'not_applicable', reasons: [`the invariant is valid from ${val.from}`] }); continue; }
+      if (val.until && today > val.until) { results.push({ ...base, verdict: 'expired', reasons: [`the invariant expired on ${val.until}`] }); continue; }
+      const dims = inv.requires.map((d) => ({ dim: d, ...dimensionState(b, d) }));
+      const waivedBy = (dim) => publics.find((p) => p.waives.includes(dim) && routeMatches(p.appliesTo, ep.label, ep.method) && (!p.validity?.paths || p.validity.paths.some((g) => globToRegExp(g).test(file))) && !(p.public.reviewBy < today));
+      const missing = dims.filter((x) => x.state === 'absent');
+      const unresolved = dims.filter((x) => x.state === 'unresolved');
+      const allNone = dims.every((x) => x.state === 'none-to-protect');
+      if (allNone) { results.push({ ...base, verdict: 'not_applicable', reasons: ['no sensitive operation was seen, so there is nothing for a control to protect'], controls: dims }); continue; }
+      const unwaived = missing.filter((x) => !waivedBy(x.dim));
+      const waived = missing.filter((x) => waivedBy(x.dim));
+      if (unwaived.length) results.push({ ...base, verdict: 'violated', reasons: unwaived.map((x) => `${x.dim}: ${x.why}`), controls: dims });
+      else if (waived.length) results.push({ ...base, verdict: 'public_by_policy', reasons: waived.map((x) => `${x.dim} is waived by ${waivedBy(x.dim).id}: ${waivedBy(x.dim).public.reason}`), waivedBy: [...new Set(waived.map((x) => waivedBy(x.dim).id))], controls: dims });
+      else if (unresolved.length) results.push({ ...base, verdict: 'unknown', reasons: unresolved.map((x) => `${x.dim}: ${x.why}`), controls: dims });
+      else results.push({ ...base, verdict: 'satisfied', reasons: dims.filter((x) => x.state === 'present').map((x) => `${x.dim}: ${x.why}`), controls: dims });
+    }
+  }
+  results.sort((a, b) => (a.invariantId + a.entrypointId < b.invariantId + b.entrypointId ? -1 : 1));
+  return { results, problems: [] };
+}
+
+/** Read and validate the invariants file of a project. A missing file is "no invariants", not an error; a malformed one reports every problem. */
+export function loadInvariants(root, { file = INVARIANTS_FILE, now } = {}) {
+  const full = pathJoin(root, file);
+  if (!existsSync(full)) return { present: false, doc: null, validation: { ok: true, errors: [], warnings: [] } };
+  let doc;
+  try { doc = JSON.parse(readFileSync(full, 'utf8')); } catch (e) { return { present: true, doc: null, validation: { ok: false, errors: [{ code: 'BAD_JSON', path: '', message: String(e.message).slice(0, 200) }], warnings: [] } }; }
+  return { present: true, doc, validation: validateInvariants(doc, now ? { now } : undefined) };
+}

package/src/context-intelligence/queue.js

@@ -143,6 +143,8 @@ export async function runQueue(jobs, ctx) {
     maxCalls: Math.min(HARD_LIMITS.maxCalls, Math.max(1, ctx.limits.maxCalls || 100)),
     maxWallMs: Math.min(HARD_LIMITS.maxWallSeconds, Math.max(1, ctx.limits.maxWallSeconds || 900)) * 1000,
     maxTokensPerJob: ctx.limits.maxTokensPerJob || 40000,
+    maxTokensPerRepo: Number.isFinite(ctx.limits.maxTokensPerRepo) ? ctx.limits.maxTokensPerRepo : null,
+    anonymizePrompts: ctx.limits.anonymizePrompts === true,
     maxRetries: Math.min(HARD_LIMITS.maxRetries, Math.max(0, ctx.limits.maxRetries ?? 3)),
     jobTimeoutMs: ctx.limits.jobTimeoutMs || 120000,
     maxCostUsd: Number.isFinite(ctx.limits.maxCostUsd) ? ctx.limits.maxCostUsd : null,
@@ -156,6 +158,7 @@ export async function runQueue(jobs, ctx) {
   const results = new Map();
   let calls = 0;
   let estCost = 0;
+  let tokensUsed = 0;
   let cooldownUntil = 0;
   let budgetStop = null;
   let persistChain = Promise.resolve();
@@ -205,6 +208,7 @@ export async function runQueue(jobs, ctx) {
     if (ctx.signal && ctx.signal.aborted) return 'cancelled';
     if (now() - started >= L.maxWallMs) return 'budget-exhausted:wall-time';
     if (calls >= L.maxCalls) return 'budget-exhausted:max-calls';
+    if (L.maxTokensPerRepo !== null && tokensUsed >= L.maxTokensPerRepo) return 'budget-exhausted:max-tokens-per-repo';
     if (L.maxCostUsd !== null && L.costPerCallUsd !== null && estCost + L.costPerCallUsd > L.maxCostUsd) return 'budget-exhausted:max-cost';
     return null;
   };
@@ -228,8 +232,9 @@ export async function runQueue(jobs, ctx) {
       state.jobs[job.key] = { state: 'running', reason: null, attempts, label: job.label };
       const out = await runReviewOnce({
         pack: loadedJob.pack, entrypoints: loadedJob.entrypoints, manifests: loadedJob.manifests, packageIndexes: job.packageIndexes, packageTexts: loadedJob.packageTexts,
-        fileContents: ctx.fileContents, scanRoot: ctx.root, invoker: ctx.invoker, model: ctx.model, limits: { maxTokensPerJob: L.maxTokensPerJob, jobTimeoutMs: L.jobTimeoutMs },
+        fileContents: ctx.fileContents, scanRoot: ctx.root, invoker: ctx.invoker, model: ctx.model, limits: { maxTokensPerJob: L.maxTokensPerJob, jobTimeoutMs: L.jobTimeoutMs, anonymizePrompts: L.anonymizePrompts },
       });
+      if (out.usage) tokensUsed += (out.usage.inputTokensEstimated || 0) + (out.usage.outputTokensEstimated || 0);
       if (out.state === 'skipped_by_policy') calls--; // nothing was sent
       if (out.state === 'failed' && out.retryable && attempts <= L.maxRetries) {
         // exponential backoff with jitter; the shared cooldown slows every worker, which is what a 429 storm needs

package/src/context-intelligence/reachability.js

@@ -11,7 +11,8 @@
 //   * hide a limit. Hitting the symbol or depth cap marks the walk `capped` and lists what was left unvisited.
 //   * lose a control. Middleware and every callee are walked, and each visited symbol's controls are collected by the
 //     same classifier the packer uses to refuse pruning.
-import { analyzeSymbolText } from './controls.js';
+import { analyzeSymbolText, blankComments } from './controls.js';
+import { cmpCodeUnit } from './canonical.js';
 import { MATERIAL_REASONS } from './graph-schema.js';
 
 export const DEFAULT_LIMITS = Object.freeze({ maxSymbols: 60, maxDepth: 12 });
@@ -35,7 +36,7 @@ export function reachFrom({ graph, fileContents, entrypoint, limits = {} }) {
   const lim = { ...DEFAULT_LIMITS, ...limits };
   const { byId, edgesFrom } = indexGraph(graph);
   const linesCache = new Map();
-  const linesOf = (f) => { if (!linesCache.has(f)) linesCache.set(f, (fileContents[f] || '').split('\n')); return linesCache.get(f); };
+  const linesOf = (f) => { if (!linesCache.has(f)) linesCache.set(f, blankComments(fileContents[f] || '', f).split('\n')); return linesCache.get(f); };
 
   const visited = [];
   const seen = new Set();
@@ -70,7 +71,7 @@ export function reachFrom({ graph, fileContents, entrypoint, limits = {} }) {
   }
 
   // middleware runs before the handler: it is enqueued first and ordered at line -1
-  for (const mw of [...entrypoint.middleware].sort((a, b) => (a.line - b.line) || String(a.name).localeCompare(String(b.name)))) {
+  for (const mw of [...entrypoint.middleware].sort((a, b) => (a.line - b.line) || cmpCodeUnit(a.name, b.name))) {
     if (mw.symbolId && byId.has(mw.symbolId)) enqueue(mw.symbolId, 0, mw.inherited ? 'inherited-middleware' : 'middleware', -1, [mw.symbolId], mw.resolution === 'resolved' ? 'exact' : 'name-match');
   }
   if (root.symbolId) {
@@ -163,11 +164,14 @@ export function evaluateProtection({ facts, unknowns, omittedWithControls = fals
   for (const dim of PROTECTION_DIMENSIONS) {
     const kinds = dim === 'ownership' ? ['ownership', 'tenant-scope'] : [dim];
     const ctl = facts.filter(f => f.category === 'control' && kinds.includes(f.kind));
-    const before = ctl.filter(f => firstSens === null || f.effLine < firstSens || (f.basis === 'query-filter' && f.effLine <= firstSens));
+    // A control whose answer is visibly thrown away (a predicate called as a bare statement) guards nothing.
+    const effective = (f) => f.rejectionSeen !== false;
+    const before = ctl.filter(f => effective(f) && (firstSens === null || f.effLine < firstSens || (f.basis === 'query-filter' && f.effLine <= firstSens)));
     const after = ctl.filter(f => firstSens !== null && f.effLine > firstSens);
     let state; let why;
     if (before.length) { state = 'present'; why = 'a control precedes the first sensitive operation'; }
     else if (after.length) { state = 'evaluated_and_ineffective'; why = 'every control of this kind runs after the first sensitive operation'; }
+    else if (ctl.length && ctl.every(f => !effective(f))) { state = 'evaluated_and_ineffective'; why = 'a check is called but nothing in view acts on its answer'; }
     else if (ctl.length) { state = 'evaluated_and_ineffective'; why = 'a control is present but is not ordered before the sensitive operation'; }
     else if (omittedWithControls) { state = 'omitted_due_to_budget'; why = 'a symbol holding a control was left out for size'; }
     else if (unknowns.some(u => u.material) || capped) { state = 'not_resolved'; why = 'an unresolved call or a traversal limit could hide a control'; }
@@ -175,6 +179,8 @@ export function evaluateProtection({ facts, unknowns, omittedWithControls = fals
     else { state = 'not_present'; why = 'the resolved context is complete and contains no control of this kind'; }
     dims[dim] = {
       state, why, firstSensitiveLine: firstSens,
+      // How the control was established: 'observed' = the text shows it, 'inferred' = only a name suggests it. Only meaningful for `present`.
+      strength: state === 'present' ? (before.some(f => f.evidence === 'observed') ? 'observed' : 'inferred') : null,
       evidence: ctl.slice(0, 6).map(f => ({ file: f.file, line: f.line, kind: f.kind, evidence: f.evidence, basis: f.basis, order: firstSens === null ? 'no-sensitive-op' : f.effLine < firstSens ? 'before-sensitive' : f.effLine > firstSens ? 'after-sensitive' : 'same-step', rejectionSeen: f.rejectionSeen })),
     };
   }

package/src/context-intelligence/review.js

@@ -20,14 +20,14 @@ import { redactPayload } from '../egress/redact.js';
 import { evaluateEgress } from '../egress/policy.js';
 import { resolveProvider } from '../llm-validator/providers.js';
 import { resolveLlmInvokeWithDecision } from '../discovery/llm-invoke.js';
-import { hashOf, safeRelPath, sha256 } from './canonical.js';
+import { hashOf, safeLabel, safeRelPath, sha256 } from './canonical.js';
 import { estimateTokens } from './packer.js';
 import { REVIEW_SCHEMA_VERSION, packRef } from './prompts/packs.js';
 
 export const CONCLUSIONS = Object.freeze(['potential_issue', 'no_issue_observed', 'insufficient_evidence']);
 export const LIKELIHOODS = Object.freeze(['low', 'medium', 'high']);
 const FORBIDDEN_MODEL_FIELDS = Object.freeze(['severity', 'proofTier', 'proof_tier', 'confirmation', 'confirmed', 'status', 'verdict', 'shipVerdict', 'ship_verdict', 'exploitability', 'cvss', 'exploit_confirmed', 'EXPLOIT_CONFIRMED']);
-const MAX_CITATION_SPAN = 200;
+const MAX_CITATION_SPAN = 60;
 const MAX_STR = 1200;
 const MAX_ITEMS = 24;
 
@@ -65,8 +65,10 @@ export function buildReviewPrompt({ pack, entrypoints, packageTexts, contextHash
   for (const g of pack.guidance) lines.push(`- ${g}`);
   lines.push('', 'OUTPUT (JSON, evidence listed first):', JSON.stringify(OUTPUT_SHAPE, null, 2), '');
   entrypoints.forEach((ep, i) => {
-    const fenced = fenceUntrusted(packageTexts[i], `context-${i + 1}`);
-    lines.push(`ENTRY POINT ${i + 1}: ${ep.label} (id ${ep.id})`);
+    // The label comes from a route string in the repository, so it is DATA: it goes inside the fence, sanitised, and never
+    // into the instruction text around it.
+    const fenced = fenceUntrusted(`ENTRY POINT LABEL (data): ${safeLabel(ep.label, 120)}\n${packageTexts[i]}`, `context-${i + 1}`);
+    lines.push(`ENTRY POINT ${i + 1} (id ${ep.id})`);
     lines.push(fenced.text, '');
   });
   const prompt = lines.join('\n');
@@ -102,25 +104,103 @@ export function redactPackageText(text, { scanRoot }) {
 }
 
 /** Provider/model identity used in the job key, from the same resolver the rest of the discovery layer uses. */
-export function describeModel() {
+export function isLoopbackEndpoint(endpoint) {
+  if (!endpoint) return false;
+  const parts = String(endpoint).split(',').map(x => x.trim()).filter(Boolean);
+  if (!parts.length) return false;
+  return parts.every(u => {
+    try {
+      const h = new URL(u).hostname.toLowerCase().replace(/^\[|\]$/g, '');
+      return h === 'localhost' || h === '::1' || /^127\.\d+\.\d+\.\d+$/.test(h);
+    } catch { return false; }
+  });
+}
+
+export function describeModel({ allowRemote = false } = {}) {
+  let m;
   try {
     const r = resolveProvider({ role: 'hunt' });
-    if (r.ok) return { provider: r.config.provider, model: r.config.model || process.env.AGENTIC_SECURITY_LLM_MODEL || 'endpoint-default', endpoint: r.config.endpoint || null };
+    if (r.ok) m = { provider: r.config.provider, model: r.config.model || process.env.AGENTIC_SECURITY_LLM_MODEL || 'endpoint-default', endpoint: r.config.endpoint || null };
   } catch { /* fall through */ }
-  const ep = process.env.AGENTIC_SECURITY_LLM_ENDPOINT || null;
-  return { provider: ep ? 'byo' : null, model: process.env.AGENTIC_SECURITY_LLM_MODEL || (ep ? 'endpoint-default' : null), endpoint: ep };
+  if (!m) {
+    const ep = process.env.AGENTIC_SECURITY_LLM_ENDPOINT || null;
+    m = { provider: ep ? 'byo' : null, model: process.env.AGENTIC_SECURITY_LLM_MODEL || (ep ? 'endpoint-default' : null), endpoint: ep };
+  }
+  // `remote` is true for any endpoint that is not loopback; an endpoint-less provider is judged remote too, since its host is not visible here.
+  const remote = m.provider ? !(m.provider === 'local' || isLoopbackEndpoint(m.endpoint)) : false;
+  return { ...m, remote, remoteApproved: allowRemote === true };
 }
 
 /** Evaluate the egress policy for every file that would appear in the prompt. Returns { allowed, reason }. */
 export function checkEgressForFiles(files, { scanRoot, model }) {
   if (!model.endpoint) return { allowed: true, evaluated: false };
+  // Source bundles leave the machine only when the operator has said so. A loopback endpoint needs no approval; any
+  // other endpoint needs --allow-remote (or review.allowRemote), on top of the egress policy below, never instead of it.
+  if (model.remote && !model.remoteApproved) return { allowed: false, reason: 'remote-endpoint-not-approved (pass --allow-remote or set review.allowRemote after reviewing the egress policy)', file: files[0] || null, evaluated: false };
   for (const file of files) {
-    const d = evaluateEgress({ scanRoot, purpose: 'context-review', endpoint: model.endpoint, provider: model.provider, model: model.model, path: file });
-    if (!d.allowed) return { allowed: false, reason: d.reason, file, evaluated: true };
+    // Fail closed. A policy check that throws (a corrupt policy file, an unreadable path, a bug) is not an allow: the answer is "deny", with the
+    // reason, and nothing is sent. This is the only place that decides whether a prompt may leave the machine.
+    let d;
+    try { d = evaluateEgress({ scanRoot, purpose: 'context-review', endpoint: model.endpoint, provider: model.provider, model: model.model, path: file }); }
+    catch (err) { return { allowed: false, reason: `egress-policy-error: ${String((err && err.message) || err).slice(0, 120)}`, file, evaluated: true, failedClosed: true }; }
+    if (!d || d.allowed !== true) return { allowed: false, reason: (d && d.reason) || 'egress-policy-returned-no-decision', file, evaluated: true, ...(d ? {} : { failedClosed: true }) };
   }
   return { allowed: true, evaluated: true };
 }
 
+// ---- model output hygiene -------------------------------------------------------------------------------------
+
+/**
+ * A model's text is untrusted. It can carry a command for a human or a script to run ("run curl ... | sh to confirm"). Nothing here executes model text, but
+ * these strings reach reports, tickets and fix suggestions that people copy from, so shell-looking content is removed and counted, never passed on.
+ */
+const FENCE = /```[\s\S]*?```|~~~[\s\S]*?~~~/g;
+const CMD_WORD = '(?:curl|wget|bash|sh|zsh|sudo|su|rm|chmod|chown|nc|ncat|netcat|python3?|node|perl|ruby|php|powershell|pwsh|cmd(?:\\.exe)?|eval|exec|scp|ssh|dd|mkfs|kill|pkill|git\\s+push|npm\\s+(?:i|install|publish)|pip3?\\s+install|docker\\s+run)';
+const INLINE_CMD = new RegExp('`[^`\\n]*\\b' + CMD_WORD + '\\b[^`\\n]*`|\\$\\([^)]*\\)|\\b(?:curl|wget)\\s+[^\\s]+[^\\n]*\\|\\s*(?:sh|bash)\\b|(?:^|\\n)\\s*(?:\\$|#)\\s+' + CMD_WORD + '\\b[^\\n]*', 'gi');
+export function stripUntrustedCommands(text) {
+  if (typeof text !== 'string' || !text) return { text: text ?? '', stripped: 0 };
+  let n = 0;
+  let out = text.replace(FENCE, () => { n++; return '[command block removed]'; });
+  out = out.replace(INLINE_CMD, () => { n++; return '[command removed]'; });
+  return { text: out, stripped: n };
+}
+function sanitizeReviewStrings(review) {
+  let total = 0;
+  const walk = (v, key) => {
+    if (typeof v === 'string') {
+      if (['promptHash', 'responseHash', 'contextHash', 'entrypointId', 'file', 'role', 'kind', 'conclusion', 'likelihood', 'questionPack', 'status'].includes(key)) return v;
+      const r = stripUntrustedCommands(v); total += r.stripped; return r.text;
+    }
+    if (Array.isArray(v)) return v.map((x) => walk(x, key));
+    if (v && typeof v === 'object') { const o = {}; for (const [k, x] of Object.entries(v)) o[k] = walk(x, k); return o; }
+    return v;
+  };
+  const out = walk(review, '');
+  if (total) out.untrustedCommandsStripped = total;
+  return out;
+}
+
+/** Where a suggestion came from and what checked it. Attached to every review so a reader never mistakes a model's words for a finding. */
+function provenanceOf(model, promptHash) {
+  let host = null; try { host = model.endpoint ? new URL(model.endpoint).hostname : null; } catch { host = null; }
+  const loopback = host === 'localhost' || host === '127.0.0.1' || host === '::1' || host === '[::1]';
+  return { producer: 'model', provider: model.provider ?? null, model: model.model ?? null, endpointClass: !model.endpoint ? 'none' : loopback ? 'loopback' : 'remote', promptHash, checkedBy: 'deterministic-citation-verifier', promotedToFinding: false };
+}
+
+// ---- prompt anonymization ---------------------------------------------------------------------------------------
+
+/** Replace each real file path with a stable pseudonym (`f_<hash>.<ext>`). The mapping stays in memory; only the pseudonyms leave. */
+export function pseudonymizer(files) {
+  const toPseudo = new Map(); const toReal = new Map();
+  for (const f of [...new Set(files)].sort()) {
+    const ext = (/\.[A-Za-z0-9]{1,6}$/.exec(f) || [''])[0];
+    const p = `f_${sha256(f).slice(0, 10)}${ext}`;
+    toPseudo.set(f, p); toReal.set(p, f);
+  }
+  const swap = (text, map) => { let t = text; for (const [a, b] of [...map].sort((x, y) => y[0].length - x[0].length)) t = t.split(a).join(b); return t; };
+  return { toPseudo: (t) => swap(t, toPseudo), toReal: (t) => swap(t, toReal), size: toPseudo.size };
+}
+
 // ---- response parsing and verification ------------------------------------------------------------------------
 
 function extractJson(raw) {
@@ -149,14 +229,29 @@ function normalizeCitations(list) {
   return { items, malformed };
 }
 
-/** A citation resolves when it is a real, bounded range inside a segment the reviewed package contained. */
+const CLAIM_STOPWORDS = new Set(['this', 'that', 'with', 'from', 'which', 'where', 'when', 'does', 'have', 'been', 'would', 'could', 'should', 'into', 'over', 'only', 'also', 'shows', 'show', 'line', 'lines', 'code', 'file', 'function']);
+
+/**
+ * A claim is grounded when at least one meaningful word in it (or the first five letters of a longer one, so "ownership"
+ * meets `ownerId`) appears in the lines it cites. This does not prove the claim is true; it stops a citation that points at
+ * real lines while describing something else, and an empty claim, from being accepted as evidence.
+ */
+export function claimGrounded(claim, citedText) {
+  const hay = String(citedText).toLowerCase();
+  const words = (String(claim).toLowerCase().match(/[a-z_][a-z0-9_]{3,}/g) || []).filter(w => !CLAIM_STOPWORDS.has(w));
+  return words.some(w => hay.includes(w.length > 5 ? w.slice(0, 5) : w));
+}
+
+/** A citation resolves when it is a real, bounded range inside a segment the reviewed package contained, and its claim is about those lines. */
 export function resolveCitation(c, segments, fileContents) {
   if (c.startLine < 1 || c.endLine < c.startLine || c.endLine - c.startLine > MAX_CITATION_SPAN) return 'range-invalid';
   const text = fileContents[c.file];
   if (typeof text !== 'string') return 'file-not-in-snapshot';
-  if (c.endLine > text.split('\n').length) return 'beyond-end-of-file';
+  const fileLines = text.split('\n');
+  if (c.endLine > fileLines.length) return 'beyond-end-of-file';
   const inside = segments.some(s => s.file === c.file && c.startLine >= s.startLine && c.endLine <= s.endLine);
-  return inside ? null : 'outside-provided-context';
+  if (!inside) return 'outside-provided-context';
+  return claimGrounded(c.claim, fileLines.slice(c.startLine - 1, c.endLine).join('\n')) ? null : 'claim-not-grounded-in-cited-lines';
 }
 
 function decline(base, reasons, extra = {}) {
@@ -245,13 +340,24 @@ export function verifyReview({ raw, pack, entrypoints, manifests, packageIndexes
       out.downgradedFrom = 'no_issue_observed';
       out.conclusion = 'insufficient_evidence';
       out.downgradeReason = 'no-mitigation-cited';
+    } else if (dim) {
+      // The cited mitigation must be a control the deterministic pass also recognised, and one the text actually shows:
+      // a model cannot clear a route by pointing at an arbitrary line or at a control known only from its name.
+      const recognised = mit.items.some(c => manifests.some(m => ((m.protection[dim] || {}).evidence || []).some(e => e.file === c.file && e.line >= c.startLine && e.line <= c.endLine)));
+      const onlyInferred = manifests.every(m => (m.protection[dim] || {}).state === 'present' && (m.protection[dim] || {}).strength === 'inferred');
+      if (!recognised || onlyInferred) {
+        out.downgradedFrom = 'no_issue_observed';
+        out.conclusion = 'insufficient_evidence';
+        out.downgradeReason = !recognised ? 'mitigation-not-a-recognised-control' : 'only-inferred-controls';
+      }
     }
   }
 
   // how the model's reading compares with the deterministic reading (metadata only; neither overrides the other)
   if (dim) {
     const states = manifests.map(m => m.protection[dim]?.state);
-    const present = states.every(s => s === 'present');
+    // `present` counts as agreement only when the control is shown by the text; a control known only from its name is neutral.
+    const present = manifests.every(m => m.protection[dim]?.state === 'present' && m.protection[dim]?.strength !== 'inferred');
     const absent = states.some(s => s === 'not_present' || s === 'evaluated_and_ineffective');
     out.deterministicProtection = { dimension: dim, states };
     out.deterministicAgreement = out.conclusion === 'potential_issue' ? (absent ? 'agrees' : present ? 'conflicts' : 'neutral') : (out.conclusion === 'no_issue_observed' ? (present ? 'agrees' : absent ? 'conflicts' : 'neutral') : 'neutral');
@@ -303,7 +409,12 @@ export async function runReviewOnce({ pack, entrypoints, manifests, packageIndex
   const badRedact = redacted.find(r => !r.ok);
   if (badRedact) return { state: 'skipped_by_policy', reason: `redaction refused: ${badRedact.reason}` };
 
-  const { prompt, promptHash } = buildReviewPrompt({ pack, entrypoints, packageTexts: redacted.map(r => r.text), contextHash: manifests[0].contextHash });
+  // Policy-driven anonymization: file paths are replaced by pseudonyms before the prompt is built, and mapped back in the answer before its citations
+  // are checked against the real snapshot. The model never sees a real path, and what is hashed is what was sent.
+  const anon = limits.anonymizePrompts ? pseudonymizer(files) : null;
+  const sendTexts = anon ? redacted.map(r => anon.toPseudo(r.text)) : redacted.map(r => r.text);
+  const sendEntrypoints = anon ? entrypoints.map(e => JSON.parse(anon.toPseudo(JSON.stringify(e)))) : entrypoints;
+  const { prompt, promptHash } = buildReviewPrompt({ pack, entrypoints: sendEntrypoints, packageTexts: sendTexts, contextHash: manifests[0].contextHash });
   const est = estimateTokens(prompt);
   if (est.tokens > limits.maxTokensPerJob) return { state: 'skipped_by_policy', reason: `prompt is about ${est.tokens} tokens, over the ${limits.maxTokensPerJob} per-job limit` };
 
@@ -315,7 +426,9 @@ export async function runReviewOnce({ pack, entrypoints, manifests, packageIndex
     return { state: 'failed', reason: `model call failed: ${String((err && err.message) || err).slice(0, 160)}`, retryable: isRetryableError(err) };
   }
   const usage = { inputTokensEstimated: est.tokens, outputTokensEstimated: Math.ceil(String(raw || '').length / 4), source: 'estimate', redactions: redacted.reduce((n, r) => n + r.redactions, 0) };
-  const review = verifyReview({ raw, pack, entrypoints, manifests, packageIndexes, fileContents, promptHash });
+  const rawReal = anon && typeof raw === 'string' ? anon.toReal(raw) : raw;
+  const review0 = verifyReview({ raw: rawReal, pack, entrypoints, manifests, packageIndexes, fileContents, promptHash });
+  const review = { ...sanitizeReviewStrings(review0), modelProvenance: provenanceOf(model, promptHash), ...(anon ? { promptAnonymized: true } : {}) };
   if (review.status === 'declined') return { state: 'partial', reason: `answer declined: ${review.declineReasons.join(',')}`, review, usage };
   return { state: 'succeeded', reason: null, review, usage };
 }

package/src/dataflow/access-paths.js

@@ -67,6 +67,17 @@ export function pathIsCoveredByPrefix(path, prefix) {
  * - `set = {"x.z"}` does NOT cover "x.y"  ✗
  * - `set = {"x.y.z"}` does NOT cover "x.y"  ✗ (we don't propagate UP)
  */
+/**
+ * True iff some path in `set` lies STRICTLY BELOW `path` (`o.cmd` is below `o`). Reading `o` as a whole value (passing it to a function, serialising
+ * it) reads every field, so a tainted field taints the whole read; reading `o.safe` does not, because `o.cmd` is not below `o.safe`.
+ */
+export function hasTaintedDescendant(set, path) {
+  if (!set || typeof path !== 'string') return false;
+  const prefix = `${path}.`;
+  for (const p of set) if (typeof p === 'string' && p.startsWith(prefix)) return true;
+  return false;
+}
+
 export function isCoveredBy(set, path) {
   if (!set || typeof path !== 'string') return false;
   if (set.has(path)) return true;

package/src/dataflow/analysis-limits.js

@@ -0,0 +1,66 @@
+// Dynamic features the static analysis cannot resolve, reported instead of silently approximated (E2-03).
+//
+// Where the engine meets one of these it takes the sound direction (a write through an unknown key taints the whole container, a read through
+// an unknown key reads the whole container) and loses precision. That is the right trade, but it must be visible: a result that depended on it is
+// less precise than one that did not, and a reviewer should be able to see which functions contain such constructs.
+//
+// Pure: reads the Layer-1 IR only.
+const LIMIT_KINDS = Object.freeze({
+  'computed-write': 'a write through a key that is not a literal (`o[k] = v`): the engine taints the whole container `o`, so clean sibling fields read afterwards are over-approximated as tainted',
+  'computed-read': 'a read through a key that is not a literal (`o[k]`): the engine cannot tell which field is read, so any tainted field of `o` reaches it',
+  'eval-like': 'code built at run time (`eval`, `new Function`, `setTimeout` with a string): its content is not analysed',
+  'dynamic-require': 'a module name computed at run time (`require(name)`, `import(name)`): the callee is unknown, so the call stays unresolved',
+  'reflective-call': 'a call through reflection (`Reflect.apply`, `fn.call/apply` on a computed target, `obj[name]()`): the callee is unknown',
+  'getter-or-proxy': 'property access that may run user code (`Proxy`, `Object.defineProperty` accessors): reads and writes may have effects the engine does not model',
+});
+
+const expressions = (e, acc = []) => {
+  if (!e || typeof e !== 'object') return acc;
+  acc.push(e);
+  for (const k of ['object', 'callee', 'left', 'right', 'value']) if (e[k] && typeof e[k] === 'object') expressions(e[k], acc);
+  for (const k of ['args', 'parts', 'elements', 'props', 'branches']) if (Array.isArray(e[k])) for (const x of e[k]) expressions(x && x.value && !x.kind ? x.value : x, acc);
+  return acc;
+};
+const nameOf = (c) => (typeof c === 'string' ? c : c && c.kind === 'ident' ? c.name : c && c.kind === 'member' ? `${nameOf(c.object)}.${c.prop}` : '');
+
+/** @returns {{kind:string, line:number, detail:string, effect:string}[]} */
+function limitsOfFunction(fn) {
+  const out = [];
+  const add = (kind, line, detail) => out.push({ kind, line: Number.isInteger(line) ? line : (fn.line || 0), detail, effect: LIMIT_KINDS[kind] });
+  for (const n of Object.values(fn.cfg?.nodes || {})) {
+    if (n.kind === 'assign') {
+      if (typeof n.target === 'string' && /\.\*$/.test(n.target)) add('computed-write', n.line, n.target);
+      for (const x of expressions(n.source)) inspect(x, n.line, add);
+    } else if (n.kind === 'call') {
+      inspect({ kind: 'call', callee: n.callee, args: n.args }, n.line, add);
+      for (const a of n.args || []) for (const x of expressions(a)) inspect(x, n.line, add);
+    } else if (n.kind === 'return' && n.value) for (const x of expressions(n.value)) inspect(x, n.line, add);
+  }
+  return out;
+}
+
+function inspect(x, line, add) {
+  if (x.kind === 'member' && x.prop === '*') add('computed-read', line, `${nameOf(x.object)}[…]`);
+  if (x.kind === 'call') {
+    const c = nameOf(x.callee);
+    if (/^(?:eval|Function|new Function|setTimeout|setInterval)$/.test(c)) { if (c === 'eval' || c === 'Function' || c === 'new Function' || (x.args && x.args[0] && x.args[0].kind !== 'function-value' && x.args[0].kind !== 'ident' && x.args[0].kind !== 'literal')) add('eval-like', line, c); else if ((c === 'setTimeout' || c === 'setInterval') && x.args && x.args[0] && x.args[0].kind === 'literal' && typeof x.args[0].value === 'string') add('eval-like', line, `${c}(string)`); }
+    if (c === 'require' && x.args && x.args[0] && x.args[0].kind !== 'literal') add('dynamic-require', line, 'require(<expression>)');
+    if (/^Reflect\.(?:apply|construct|get|set)$/.test(c)) add('reflective-call', line, c);
+    if (x.callee && x.callee.kind === 'member' && x.callee.prop === '*') add('reflective-call', line, `${nameOf(x.callee.object)}[…](…)`);
+    if (/^(?:Object\.defineProperty|Object\.defineProperties|Object\.setPrototypeOf)$/.test(c) || c === 'Proxy' || c === 'new Proxy') add('getter-or-proxy', line, c);
+  }
+}
+
+/**
+ * @param {{perFile:Record<string,{functions:object[]}>}} projectIR
+ * @returns {{file:string, qid:string, function:string, kind:string, line:number, detail:string, effect:string}[]} sorted, stable
+ */
+export function analysisLimits(projectIR) {
+  const out = [];
+  for (const file of Object.keys(projectIR?.perFile || {}).sort()) {
+    for (const fn of projectIR.perFile[file].functions || []) {
+      for (const l of limitsOfFunction(fn)) out.push({ file, qid: String(fn.qid).replace(/@\d+$/, ''), function: fn.name, ...l });
+    }
+  }
+  return out.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : a.line - b.line || (a.kind < b.kind ? -1 : 1)));
+}