@clear-capabilities/agentic-security-scanner 0.195.28 → 0.195.30

package/src/lineage/deployment/attack-paths.js

@@ -26,9 +26,12 @@ import { indexGraph, validateBoundaryGraph, boundaryCrossings } from './boundary
 import { semanticId, hypothesisIdFromFinding } from '../../posture/assurance/identity.js';
 import { validateVerificationRecord, deriveConfirmationLevel } from '../../posture/assurance/verification-record.js';
 import { nonTaintClassOf, SCENARIO_CLASSES } from '../../posture/oracles/scenario-classes.js';
+import { decideAction, resourceMatches, UNKNOWN_ACTION } from './iam-eval.js';
+import { judgePathPromotion } from './proof-binding.js';
 
 export const BOUNDARY_CONTEXT_SCHEMA = 'agentic-security/boundary-context';
-export const BOUNDARY_CONTEXT_VERSION = '1.0.0';
+// 1.1.0 (threat-model FR-03.3): optional `truncation` (why a search stopped) and `action` (the action a query asked about).
+export const BOUNDARY_CONTEXT_VERSION = '1.1.0';
 
 export const TRAVERSED_RELATIONS = Object.freeze(['routes-to', 'calls', 'depends-on', 'network-allows', 'assumes', 'grants']);
 const TRAVERSED = new Set(TRAVERSED_RELATIONS);
@@ -122,24 +125,61 @@ function hopsFrom(ix, nodeId) {
     else if (TRAVERSED.has(e.relation)) h.edges.push(e);
     hops.set(e.to, h);
   }
+  // threat-model FR-03.1: a deny statement whose resource is a pattern (`*`, `arn:aws:s3:::bucket/*`) is a node of its own, so before
+  // this it never reached the hop to the concrete resource it covers. It now applies to every resource its pattern matches.
+  const patternDenies = [];
+  for (const [to, h] of hops) {
+    const name = ix.nodesById.get(to)?.name ?? '';
+    if (/[*?]/.test(name)) for (const d of h.denies) if (d.relation === 'grants') patternDenies.push({ d, pattern: name });
+  }
+  for (const [to, h] of hops) {
+    const name = ix.nodesById.get(to)?.name ?? '';
+    for (const { d, pattern } of patternDenies) if (d.to !== to && resourceMatches(pattern, name) && !h.denies.includes(d)) h.denies.push(d);
+  }
   for (const [k, h] of [...hops]) if (!h.edges.length) hops.delete(k);
   return hops;
 }
 
-function hopState(h, from, to) {
-  if (h.denies.length) return 'blocked';
+function baseState(h, from, to) {
   if (h.edges.some((e) => e.pathState === 'runtime-supported')) return 'runtime-supported';
   if (!from.resolved || !to.resolved || h.edges.every((e) => e.pathState === 'unresolved' || e.pathState === 'blocked')) return 'unresolved';
   return 'possible';
 }
 
+/**
+ * Decide a hop. A network deny, or a deny on a relation other than an IAM grant, blocks it as before. An IAM hop is decided per
+ * action (threat-model FR-03.1): with a requested action, that action only; without one, every action the allow statements grant, and
+ * the hop is possible when any of them is. A deny blocks only an action it matches, under a condition that holds for the request
+ * context; a condition that cannot be evaluated leaves the action unresolved.
+ * @returns {{state:string, denies:object[], actions:object[]|null}}
+ */
+function hopDecision(h, from, to, q = null) {
+  const other = h.denies.filter((d) => d.relation !== 'grants');
+  if (other.length) return { state: 'blocked', denies: other.map((d) => ({ d, why: null })), actions: null };
+  const allows = h.edges.filter((e) => e.relation === 'grants' && e.effect === 'allow');
+  const iamDenies = h.denies.filter((d) => d.relation === 'grants');
+  const base = baseState(h, from, to);
+  if (!allows.length) return { state: base, denies: [], actions: null };
+  const recorded = [...new Set(allows.flatMap((e) => String(e.attrs?.actions ?? '').split(',').filter(Boolean)))].sort();
+  // with no IAM deny on the hop and no requested action there is nothing to decide per action: the grant stands as before
+  if (!iamDenies.length && !(q && q.action)) return { state: base, denies: [], actions: recorded.length ? recorded.map((action) => ({ action, outcome: base === 'unresolved' ? 'unresolved' : 'possible', blockedBy: [], unresolvedBy: [] })) : null };
+  const wanted = q && q.action ? [q.action] : (recorded.length ? recorded : [UNKNOWN_ACTION]);
+  const decisions = wanted.map((a) => decideAction(allows, iamDenies, a, q && q.context));
+  const pick = (o) => decisions.some((d) => d.outcome === o);
+  const state = pick('possible') ? base : pick('unresolved') ? 'unresolved' : pick('blocked') ? 'blocked' : 'not-granted';
+  const denies = state === 'blocked' ? decisions.flatMap((d) => d.blockers).map((b) => ({ d: iamDenies.find((x) => x.id === b.edgeId), why: b })) : [];
+  return { state, denies, actions: decisions.map(({ action, outcome, blockers, unresolvedBy }) => ({ action, outcome, blockedBy: blockers.map((b) => b.edgeId), unresolvedBy })) };
+}
+
+function hopState(h, from, to, q = null) { return hopDecision(h, from, to, q).state; }
+
 function isStale(e, nowMs, staleAfterMs) {
   if (e.attrs?.stale === true) return true;
   if (nowMs === null || !e.observationInterval) return false;
   return nowMs - Date.parse(e.observationInterval.end) > staleAfterMs;
 }
 
-function buildPath(ix, seq, hopList, nowMs, staleAfterMs) {
+function buildPath(ix, seq, hopList, nowMs, staleAfterMs, q = null) {
   const nodes = seq.map((id) => ix.nodesById.get(id));
   const hops = [];
   const conditions = [];
@@ -151,16 +191,20 @@ function buildPath(ix, seq, hopList, nowMs, staleAfterMs) {
   hopList.forEach((h, i) => {
     from = nodes[i];
     const to = nodes[i + 1];
-    const state = hopState(h, from, to);
+    const dec = hopDecision(h, from, to, q);
+    const state = dec.state;
     const crossing = boundaryCrossings(h.edges[0], ix.nodesById);
     for (const c of crossing) crossings.push({ hop: i, type: c.type, detail: c.detail });
     hops.push({
       index: i, from: nodeSummary(from), to: nodeSummary(to), relations: sortedUnique(h.edges.map((e) => e.relation)), state,
       edges: h.edges.map(edgeSummary).sort((a, b) => (a.id < b.id ? -1 : 1)),
+      ...(dec.actions ? { actions: dec.actions } : {}),
     });
-    for (const d of h.denies) {
+    // each blocker is the rule that actually decided the hop, with the action and the condition it matched
+    for (const { d, why } of dec.denies) {
+      if (!d) continue;
       blockers.push({ hop: i, edgeId: d.id, relation: d.relation, provenance: d.provenance, source: d.source ? { file: d.source.file, digest: d.source.digest } : null,
-        detail: `${d.relation} (deny) from ${from.name} to ${to.name}` });
+        detail: `${d.relation} (deny) from ${from.name} to ${to.name}`, ...(why ? { action: why.action, matchedActions: why.matchedActions, condition: why.condition } : {}) });
     }
     if (from.tenant !== null && to.tenant !== null && from.tenant !== to.tenant) {
       conditions.push({ kind: 'tenant-binding', hop: i, detail: `${from.name} (tenant ${from.tenant}) reaches ${to.name} (tenant ${to.tenant}): reachable only if no tenant binding is enforced on this transition, and the configuration does not establish either` });
@@ -193,6 +237,10 @@ function buildPath(ix, seq, hopList, nowMs, staleAfterMs) {
   else if (networkHops.length && networkHops.every((h) => h.state === 'runtime-supported')) state = 'runtime-supported';
   else state = 'possible';
 
+  // threat-model FR-03.2: a path that carries several actions keeps their separate outcomes; one is the worst over its IAM hops
+  const actionOutcomes = {};
+  const RANK = { possible: 0, unresolved: 1, blocked: 2, 'not-granted': 3 };
+  for (const hp of hops) for (const a of hp.actions || []) if (!(a.action in actionOutcomes) || RANK[a.outcome] > RANK[actionOutcomes[a.action]]) actionOutcomes[a.action] = a.outcome;
   const observedEnds = hops.flatMap((h) => h.edges).filter((e) => e.observationInterval).map((e) => e.observationInterval);
   const supportingEdgeIds = sortedUnique(hops.flatMap((h) => h.edges.map((e) => e.id)));
   const envs = sortedUnique([...hops.flatMap((h) => h.edges.map((e) => e.environment)), ...nodes.map((n) => n.environment)].filter(Boolean));
@@ -202,6 +250,8 @@ function buildPath(ix, seq, hopList, nowMs, staleAfterMs) {
     id: semanticId('bpath', { hops: hops.map((h) => h.edges.map((e) => e.id).sort()) }, ['hops']),
     entry: nodeSummary(nodes[0]), target: nodeSummary(nodes[nodes.length - 1]),
     state, conditional: conditions.length > 0, conditions, blockers, assumptions: [...assumptions].sort(),
+    ...(Object.keys(actionOutcomes).length ? { actionOutcomes: Object.fromEntries(Object.entries(actionOutcomes).sort()) } : {}),
+    ...(q && q.action ? { action: q.action } : {}),
     environments: envs, tenants,
     provenance: sortedUnique(hops.flatMap((h) => h.edges.map((e) => e.provenance))),
     crossings: dedupCross, supportingEdgeIds, hops,
@@ -239,7 +289,7 @@ function defaultTargets(graph) {
  */
 export function computeAttackPaths(graph, o = {}) {
   const v = validateBoundaryGraph(graph);
-  if (!v.ok) return { ok: false, paths: [], entries: [], targets: [], truncated: false, limits: { ...PATH_LIMITS }, statement: 'the graph failed validation, so no path was computed', errors: v.errors };
+  if (!v.ok) return { ok: false, paths: [], entries: [], targets: [], truncated: false, truncation: { reasons: [], depthCutoffs: 0, frontier: [], frontierCapped: false }, limits: { ...PATH_LIMITS }, statement: 'the graph failed validation, so no path was computed', errors: v.errors };
   const limits = {
     maxHops: Math.min(o.maxHops ?? PATH_LIMITS.maxHops, PATH_LIMITS.maxHops), maxPaths: Math.min(o.maxPaths ?? PATH_LIMITS.maxPaths, PATH_LIMITS.maxPaths),
     maxExpansions: Math.min(o.maxExpansions ?? PATH_LIMITS.maxExpansions, PATH_LIMITS.maxExpansions),
@@ -252,25 +302,34 @@ export function computeAttackPaths(graph, o = {}) {
   const staleAfterMs = o.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
   const found = [];
   let expansions = 0;
-  let truncated = false;
+  let stopped = false;
+  const q = o.action ? { action: String(o.action), context: o.context ?? {} } : (o.context ? { action: null, context: o.context } : null);
+  // threat-model FR-03.3 (TM-04): every bound that ended the search is recorded, so "no path" after a depth cutoff is never read as
+  // "no path exists". Reaching the depth bound on a node with no unvisited continuation is not a cutoff.
+  const cut = { depth: 0, results: false, expansions: false, frontier: [] };
+  const next = (seq, here) => [...hopsFrom(ix, here)].sort((a, b) => (a[0] < b[0] ? -1 : 1))
+    .filter(([to, h]) => !seq.includes(to) && !(q && q.action && hopState(h, ix.nodesById.get(here), ix.nodesById.get(to), q) === 'not-granted'));
 
   const walk = (seq, hopList) => {
-    if (truncated) return;
+    if (stopped) return;
     const here = seq[seq.length - 1];
     if (hopList.length && targetSet.has(here)) {
-      found.push(buildPath(ix, seq, hopList, Number.isNaN(nowMs) ? null : nowMs, staleAfterMs));
-      if (found.length >= limits.maxPaths) { truncated = true; return; }
+      found.push(buildPath(ix, seq, hopList, Number.isNaN(nowMs) ? null : nowMs, staleAfterMs, q));
+      if (found.length >= limits.maxPaths) { stopped = true; cut.results = true; return; }
+    }
+    const cont = next(seq, here);
+    if (hopList.length >= limits.maxHops) {
+      if (cont.length) { cut.depth++; if (cut.frontier.length < 20) cut.frontier.push({ node: here, depth: hopList.length, unexplored: cont.length }); }
+      return;
     }
-    if (hopList.length >= limits.maxHops) return;
-    for (const [to, h] of [...hopsFrom(ix, here)].sort((a, b) => (a[0] < b[0] ? -1 : 1))) {
-      if (seq.includes(to)) continue;
-      if (++expansions > limits.maxExpansions) { truncated = true; return; }
+    for (const [to, h] of cont) {
+      if (++expansions > limits.maxExpansions) { stopped = true; cut.expansions = true; return; }
       walk([...seq, to], [...hopList, h]);
     }
   };
   for (const entry of entries) {
     if (o.includeSelf && targetSet.has(entry)) {
-      const p = buildPath(ix, [entry], [], Number.isNaN(nowMs) ? null : nowMs, staleAfterMs);
+      const p = buildPath(ix, [entry], [], Number.isNaN(nowMs) ? null : nowMs, staleAfterMs, q);
       p.assumptions = sortedUnique([...p.assumptions, 'the entry point is itself the target; its public trust zone is declared in configuration']);
       found.push(p);
     }
@@ -278,9 +337,13 @@ export function computeAttackPaths(graph, o = {}) {
   }
   found.sort((a, b) => STATE_RANK[a.state] - STATE_RANK[b.state] || a.hops.length - b.hops.length || (a.id < b.id ? -1 : 1));
   const n = found.length;
+  const reasons = [...(cut.depth ? ['depth'] : []), ...(cut.results ? ['result-count'] : []), ...(cut.expansions ? ['expansion'] : [])];
+  const truncated = reasons.length > 0;
   return {
     ok: true, paths: found, entries, targets, truncated, limits,
-    statement: `${n} path(s) found in the supplied configuration${truncated ? ' (search stopped at a limit; more may exist)' : ''}; a path that is not listed has not been shown to exist or to be absent`,
+    truncation: { reasons, depthCutoffs: cut.depth, frontier: cut.frontier, frontierCapped: cut.depth > cut.frontier.length },
+    ...(q && q.action ? { action: q.action } : {}),
+    statement: `${n} path(s) found in the supplied configuration${truncated ? ` (search stopped at a limit: ${reasons.join(', ')}; more may exist)` : ''}; a path that is not listed has not been shown to exist or to be absent`,
     errors: [],
   };
 }
@@ -306,7 +369,7 @@ export function exposureReach(graph, { entries } = {}) {
     const cur = best.get(id);
     for (const [to, h] of hopsFrom(ix, id)) {
       const st = hopState(h, ix.nodesById.get(id), ix.nodesById.get(to));
-      if (st === 'blocked') continue;
+      if (st === 'blocked' || st === 'not-granted') continue;
       const state = cur.state === 'unresolved' || st === 'unresolved' ? 'unresolved' : 'definite';
       const prev = best.get(to);
       if (prev && (prev.state === 'definite' || state === 'unresolved')) continue;
@@ -324,7 +387,7 @@ export function exposureReach(graph, { entries } = {}) {
  * own claim: the record is validated, its confirmation level is recomputed from its evidence, and its oracle must be the one the
  * finding's class names (a finding of an unsupported class has no applicable oracle).
  */
-export function assessVerification(finding, records, hypothesisId = hypothesisIdFromFinding(finding)) {
+export function assessVerification(finding, records, hypothesisId = hypothesisIdFromFinding(finding), { revision = null } = {}) {
   const out = [];
   const cls = nonTaintClassOf(finding);
   for (const rec of Array.isArray(records) ? records : []) {
@@ -340,12 +403,16 @@ export function assessVerification(finding, records, hypothesisId = hypothesisId
       const adapter = SCENARIO_CLASSES.find((c) => c.id === cls.classId)?.adapterId;
       if (!rec.oracle || rec.oracle.id !== adapter) reasons.push(`the record's oracle is not '${adapter}', the oracle for class '${cls.classId}'`);
     }
-    out.push({ recordId: rec.id, outcome: rec.outcome, applicable: reasons.length === 0, reasons });
+    // threat-model FR-04.1: an exact matching commit is the minimum for a CURRENT component proof; a record for another revision is
+    // kept, with the reason, as historical evidence and never applied to this graph
+    let historical = false;
+    if (revision && rec.commit !== revision) { historical = true; reasons.push(`the record was made at ${String(rec.commit).slice(0, 12)}, not this graph's revision ${String(revision).slice(0, 12)}; it is historical evidence for that revision only`); }
+    out.push({ recordId: rec.id, outcome: rec.outcome, applicable: reasons.length === 0, reasons, ...(historical ? { historical: true, commit: rec.commit } : {}) });
   }
   return out.sort((a, b) => String(a.recordId).localeCompare(String(b.recordId)));
 }
 
-function labelPath(path, assessments) {
+function labelPath(path, assessments, pc = null) {
   const ok = assessments.find((a) => a.applicable);
   if (!ok) {
     const why = assessments.length ? assessments.flatMap((a) => a.reasons).slice(0, 3).join('; ') : 'no verification record for this hypothesis was supplied';
@@ -353,7 +420,12 @@ function labelPath(path, assessments) {
   }
   if (path.state === 'blocked') return { label: 'oracle-confirmed-path-blocked', recordId: ok.recordId, reason: 'the oracle confirmed the effect in its declared scenario, but configuration explicitly denies a hop on this path' };
   if (path.state === 'unresolved') return { label: 'oracle-confirmed-path-unresolved', recordId: ok.recordId, reason: 'the oracle confirmed the effect in its declared scenario, but deployment reachability along this path is unresolved' };
-  return { label: 'exploitable-confirmed', recordId: ok.recordId, reason: 'a trusted oracle confirmed the effect in its declared scenario; deployment reachability comes from configuration or sampled observation, not from a production probe' };
+  // threat-model FR-04.1 (TM-05): promotion to exploitable needs an issued binding of this proof to THIS path; a component proof alone
+  // is reported beside the path and does not promote it
+  const record = pc && pc.records.find((r) => r && r.id === ok.recordId);
+  const j = record ? judgePathPromotion({ path, kind: pc.kind, graph: pc.graph, record, bindings: pc.proofBindings, trustRoot: pc.trustRoot, now: pc.now, expect: pc.expect }) : { promote: false, code: 'component-only', reason: 'no binding was supplied', diagnostics: [] };
+  if (!j.promote) return { label: 'not-established', recordId: null, reason: `a trusted oracle confirmed the component, but it is not shown on this ${pc ? pc.kind : 'deployed'} path: ${j.reason}`, componentProof: { recordId: ok.recordId, code: j.code, diagnostics: j.diagnostics } };
+  return { label: 'exploitable-confirmed', recordId: ok.recordId, reason: 'a trusted oracle confirmed the effect in its declared scenario, and an issued binding ties that proof to this path; deployment reachability comes from configuration or sampled observation, not from a production probe', bindingId: j.bindingId };
 }
 
 // ------------------------------------------------------------ the per-finding context
@@ -384,21 +456,25 @@ function summarizeExposure(paths) {
  * @param {Array} [args.records]   version-1 verification records
  * @param {number|string} [args.now]
  */
-export function analyzeFindingBoundaries({ graph, finding, bindings = [], records = [], now, maxHops, maxPaths } = {}) {
+export function analyzeFindingBoundaries({ graph, finding, bindings = [], records = [], now, maxHops, maxPaths, action, context: requestContext, proofBindings = [], trustRoot = {}, expect = {} } = {}) {
   const v = validateBoundaryGraph(graph);
   if (!v.ok) return { ok: false, context: null, errors: v.errors };
   const hypothesisId = hypothesisIdFromFinding(finding);
   const binding = bindFindingToService(finding, bindings, graph);
-  const assessments = assessVerification(finding, records, hypothesisId);
+  const assessments = assessVerification(finding, records, hypothesisId, { revision: graph.revision ?? null });
+  const clock = now === undefined || now === null ? Date.now() : (typeof now === 'number' ? now : Date.parse(now));
+  const pc = (kind) => ({ kind, graph, records: Array.isArray(records) ? records : [], proofBindings, trustRoot, now: clock, expect });
   const paths = [];
   let truncated = false;
-  const popts = { now, maxHops, maxPaths };
+  const truncationReasons = new Set();
+  const popts = { now, maxHops, maxPaths, ...(action ? { action } : {}), ...(requestContext ? { context: requestContext } : {}) };
   if (binding.status === 'bound') {
     const exposure = computeAttackPaths(graph, { ...popts, targets: [binding.service.id], includeSelf: true });
     const impact = computeAttackPaths(graph, { ...popts, entries: [binding.service.id] });
     truncated = exposure.truncated || impact.truncated;
-    for (const p of exposure.paths) paths.push({ kind: 'exposure', ...p, exploitability: labelPath(p, assessments) });
-    for (const p of impact.paths) paths.push({ kind: 'impact', ...p, exploitability: labelPath(p, assessments) });
+    for (const r of [...exposure.truncation.reasons, ...impact.truncation.reasons]) truncationReasons.add(r);
+    for (const p of exposure.paths) paths.push({ kind: 'exposure', ...p, exploitability: labelPath(p, assessments, pc('exposure')) });
+    for (const p of impact.paths) paths.push({ kind: 'impact', ...p, exploitability: labelPath(p, assessments, pc('impact')) });
   }
   const exposurePaths = paths.filter((p) => p.kind === 'exposure');
   const exposure = binding.status === 'bound' ? summarizeExposure(exposurePaths)
@@ -422,7 +498,7 @@ export function analyzeFindingBoundaries({ graph, finding, bindings = [], record
   const warnings = ['Runtime traffic coverage is not established by any supplied observation; configured relationships were not exercised.'];
   if (binding.status !== 'bound') warnings.push(`This finding is not tied to a deployed service (${binding.status}); no path was computed.`);
   if (graph.gaps.length) warnings.push(`The boundary graph has ${graph.gaps.length} gap(s) (${sortedUnique(graph.gaps.map((g) => g.code)).join(', ')}); relationships behind them are missing, not absent.`);
-  if (truncated) warnings.push('The path search stopped at a limit; more paths may exist.');
+  if (truncated) warnings.push(`The path search stopped at a limit (${[...truncationReasons].sort().join(', ')}); more paths may exist, so no listed absence is a proof of absence.`);
 
   const context = {
     schema: BOUNDARY_CONTEXT_SCHEMA, schemaVersion: BOUNDARY_CONTEXT_VERSION, id: '', hypothesisId,
@@ -435,7 +511,8 @@ export function analyzeFindingBoundaries({ graph, finding, bindings = [], record
       tenants: sortedUnique(graph.nodes.map((n) => n.tenant).filter(Boolean)),
       gapCodes: sortedUnique(graph.gaps.map((g) => g.code)), gapCount: graph.gaps.length,
     },
-    exposure, paths, truncated,
+    exposure, paths, truncated, truncation: { reasons: [...truncationReasons].sort() },
+    ...(action ? { action } : {}),
     verification: assessments, uncovered, warnings,
   };
   context.id = semanticId('bctx', { hypothesisId, graph: graph.digest, binding: binding.binding, service: binding.service?.id ?? null, paths: paths.map((p) => p.id) }, ['hypothesisId', 'graph', 'binding', 'service', 'paths']);

package/src/lineage/deployment/boundaries-run.js

@@ -98,7 +98,7 @@ export function readScanFindings(file, { maxBytes, verify } = {}) {
  * @param {string} [o.now]         ISO time used to judge trace staleness; defaults to the current time
  * @returns {object} typed result; `status` is ok | disabled | blocked | unsupported | error. Never throws.
  */
-export function runBoundaries({ config, from, environment = 'prod', repository = null, revision = null, findingsFile = null, findings: suppliedFindings = null, verifySignature, now } = {}) {
+export function runBoundaries({ config, from, environment = 'prod', repository = null, revision = null, findingsFile = null, findings: suppliedFindings = null, verifySignature, now, action = null } = {}) {
   const gate = featureStatus(config, DEPLOYMENT_FEATURE);
   if (gate.status !== 'ok') return { ...gate, report: null };
   const limits = limitValues(config);
@@ -175,7 +175,7 @@ export function runBoundaries({ config, from, environment = 'prod', repository =
     if (integrity === 'unsigned') notes.push('the scan result carries no signature, so its integrity was not verified');
   }
 
-  const attached = attachBoundaryContext({ config, findings, graph, bindings, now: clock });
+  const attached = attachBoundaryContext({ config, findings, graph, bindings, now: clock, action });
   if (attached.status !== 'ok') return { ...attached, report: null };
   const contexts = attached.findings.map((f) => f.boundaryContext).filter(Boolean);
   const rows = attached.findings.map((f) => ({

package/src/lineage/deployment/iam-eval.js

@@ -0,0 +1,105 @@
+// Action-specific IAM decisions for the boundary graph (threat-model PRD FR-03.1, FR-03.4; TM-03).
+//
+// A deny blocks a requested action only when its action and resource patterns match that action and resource AND its condition holds.
+// Before this, any deny edge on a hop blocked it: an unrelated `s3:DeleteObject` deny closed an `s3:GetObject` path, and a conditional
+// deny whose predicate was never evaluated closed it too.
+//
+// The finite policy subset this module decides, and nothing more:
+//   actions and resources  exact strings and IAM globs (`*`, `?`), case-insensitive for actions, case-sensitive for resources
+//   conditions             StringEquals, StringNotEquals, Bool, ArnEquals; every operator and every key must hold (AND), any listed
+//                          value of a key satisfies it (OR); a key the request context does not supply is UNKNOWN
+//   anything else          (an `...IfExists` or set operator, a policy variable, a value outside the attribute grammar, a clipped
+//                          action list) is recorded as unsupported and leaves the decision UNRESOLVED, never allowed or blocked
+//
+// Network denies are not IAM decisions and are not judged here: they still block the hop they sit on.
+const SUPPORTED_OPERATORS = new Set(['StringEquals', 'StringNotEquals', 'Bool', 'ArnEquals']);
+const MAX_CONDITIONS = 8;
+const VALUE_GRAMMAR = /^[A-Za-z0-9_.:\/*,@ +=-]{0,200}$/;
+
+/** IAM glob to RegExp. */
+function glob(pattern, flags = '') {
+  return new RegExp(`^${String(pattern).replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.')}$`, flags);
+}
+export const actionMatches = (pattern, action) => glob(pattern, 'i').test(String(action));
+export const resourceMatches = (pattern, resource) => glob(pattern).test(String(resource));
+
+/**
+ * The structured attributes a grants edge carries for one statement. Fits the graph's attribute grammar (at most 16 keys; values
+ * limited to a safe character set), so the graph contract and its digests are unchanged for every existing field.
+ */
+export function statementAttrs(actions, condition) {
+  const joined = actions.join(',');
+  const attrs = { actions: joined.slice(0, 250), actionsComplete: joined.length <= 250 };
+  if (!condition || typeof condition !== 'object' || !Object.keys(condition).length) return attrs;
+  attrs.conditioned = true;
+  let n = 0; let supported = true;
+  for (const [op, block] of Object.entries(condition)) {
+    if (!SUPPORTED_OPERATORS.has(op) || !block || typeof block !== 'object') { supported = false; continue; }
+    for (const [key, raw] of Object.entries(block)) {
+      const values = [].concat(raw).map(String);
+      const text = `${op} ${key}=${values.join(',')}`;
+      if (n >= MAX_CONDITIONS || !VALUE_GRAMMAR.test(text) || values.some((v) => v.includes(',') || v.includes('${'))) { supported = false; continue; }
+      attrs[`cond${n++}`] = text;
+    }
+  }
+  attrs.conditionSupported = supported;
+  return attrs;
+}
+
+/** Evaluate an edge's encoded condition against a request context. 'true' | 'false' | 'unknown' (with the reason). */
+export function evaluateCondition(attrs, context = {}) {
+  if (!attrs || !attrs.conditioned) return { result: 'true', reason: 'unconditional' };
+  if (attrs.conditionSupported !== true) return { result: 'unknown', reason: 'the condition uses an operator or value outside the supported subset' };
+  const ctx = context && typeof context === 'object' ? context : {};
+  let unknown = null;
+  for (const [k, text] of Object.entries(attrs)) {
+    if (!/^cond\d+$/.test(k)) continue;
+    const m = /^(\S+) ([^=]+)=(.*)$/.exec(String(text));
+    if (!m) return { result: 'unknown', reason: 'an encoded condition could not be read' };
+    const [, op, key, list] = m;
+    const values = list.split(',');
+    if (!Object.prototype.hasOwnProperty.call(ctx, key)) { unknown = unknown ?? `the request context does not supply ${key}`; continue; }
+    const actual = String(ctx[key]);
+    const holds = op === 'StringNotEquals' ? !values.includes(actual) : op === 'Bool' ? values.map((v) => v.toLowerCase()).includes(actual.toLowerCase()) : values.includes(actual);
+    if (!holds) return { result: 'false', reason: `${op} ${key} does not hold for ${actual}` };
+  }
+  return unknown ? { result: 'unknown', reason: unknown } : { result: 'true', reason: 'every condition holds for the request context' };
+}
+
+const actionsOf = (e) => String(e.attrs?.actions ?? '').split(',').filter(Boolean);
+const clipped = (e) => e.attrs?.actionsComplete === false;
+/** An edge that records no action list (another adapter, a hand-built graph): what it covers is not known. */
+export const opaque = (e) => actionsOf(e).length === 0;
+/** The pseudo-action used when the allow statements record no actions: "whatever was granted". */
+export const UNKNOWN_ACTION = '(unrecorded)';
+
+/**
+ * Decide one action across a hop's allow and deny grants edges.
+ * @returns {{action:string, outcome:'possible'|'blocked'|'unresolved'|'not-granted', blockers:object[], unresolvedBy:string[]}}
+ */
+export function decideAction(allows, denies, action, context) {
+  const unresolvedBy = [];
+  let granted = false;
+  for (const e of allows) {
+    const pats = actionsOf(e);
+    if (opaque(e)) { granted = true; continue; } // an allow with no action list grants something; it is not narrowed here
+    if (!pats.some((p) => actionMatches(p, action))) { if (clipped(e)) unresolvedBy.push(`allow ${e.id}: its action list was clipped, so ${action} may be granted`); continue; }
+    const c = evaluateCondition(e.attrs, context);
+    if (c.result === 'true') granted = true;
+    else if (c.result === 'unknown') { granted = true; unresolvedBy.push(`allow ${e.id}: ${c.reason}`); }
+  }
+  if (!granted && !unresolvedBy.length) return { action, outcome: 'not-granted', blockers: [], unresolvedBy };
+  const blockers = [];
+  for (const d of denies) {
+    const pats = actionsOf(d);
+    // a deny with no action list, or any deny when the granted actions are themselves unrecorded, cannot be matched: unresolved
+    if (opaque(d)) { unresolvedBy.push(`deny ${d.id}: it records no action list, so whether it covers ${action} is unknown`); continue; }
+    if (action === UNKNOWN_ACTION) { unresolvedBy.push(`deny ${d.id}: the granted actions are not recorded, so whether it covers them is unknown`); continue; }
+    if (!pats.some((p) => actionMatches(p, action))) { if (clipped(d)) unresolvedBy.push(`deny ${d.id}: its action list was clipped`); continue; }
+    const c = evaluateCondition(d.attrs, context);
+    if (c.result === 'true') blockers.push({ edgeId: d.id, action, matchedActions: pats.filter((p) => actionMatches(p, action)), condition: c.reason });
+    else if (c.result === 'unknown') unresolvedBy.push(`deny ${d.id}: ${c.reason}`);
+  }
+  if (blockers.length) return { action, outcome: 'blocked', blockers, unresolvedBy };
+  return { action, outcome: unresolvedBy.length ? 'unresolved' : 'possible', blockers, unresolvedBy };
+}

package/src/lineage/deployment/projection.js

@@ -27,6 +27,9 @@ export const COVERAGE_SCHEMA = 'agentic-security/boundary-coverage';
 export const BOUNDARY_FEATURE = 'deployment-boundaries';
 
 const CONTEXT_KEYS = ['schema', 'schemaVersion', 'id', 'hypothesisId', 'finding', 'binding', 'graph', 'exposure', 'paths', 'truncated', 'verification', 'uncovered', 'warnings'];
+// Optional from 1.1.0: a 1.0.0 context stays valid without them, and may not carry them.
+const OPTIONAL_KEYS_1_1 = ['truncation', 'action'];
+const SUPPORTED_VERSIONS = ['1.0.0', '1.1.0'];
 const FILTER_KEYS = ['service', 'repository', 'environment', 'tenant'];
 const MAX_STRING = 600;
 
@@ -72,7 +75,9 @@ export function validateBoundaryContext(ctx) {
   const errors = [];
   if (!ctx || typeof ctx !== 'object' || Array.isArray(ctx)) return { ok: false, errors: [{ code: 'BAD_TYPE', path: '', message: 'a boundary context must be an object' }] };
   if (ctx.schema !== BOUNDARY_CONTEXT_SCHEMA) errors.push({ code: 'BAD_SCHEMA', path: 'schema', message: `schema must be '${BOUNDARY_CONTEXT_SCHEMA}'` });
-  for (const k of Object.keys(ctx)) if (!CONTEXT_KEYS.includes(k)) errors.push({ code: 'UNKNOWN_FIELD', path: k, message: `field '${k}' is not part of a boundary context` });
+  if (!SUPPORTED_VERSIONS.includes(ctx.schemaVersion)) errors.push({ code: 'BAD_SCHEMA', path: 'schemaVersion', message: `schemaVersion must be one of ${SUPPORTED_VERSIONS.join(', ')}` });
+  const allowed = ctx.schemaVersion === '1.0.0' ? CONTEXT_KEYS : [...CONTEXT_KEYS, ...OPTIONAL_KEYS_1_1];
+  for (const k of Object.keys(ctx)) if (!allowed.includes(k)) errors.push({ code: 'UNKNOWN_FIELD', path: k, message: `field '${k}' is not part of a boundary context ${ctx.schemaVersion}` });
   for (const k of CONTEXT_KEYS) if (!(k in ctx)) errors.push({ code: 'MISSING_FIELD', path: k, message: `field '${k}' is required` });
   if (errors.length) return { ok: false, errors };
   if (typeof ctx.id !== 'string' || !ctx.id) errors.push({ code: 'BAD_TYPE', path: 'id', message: 'id must be a non-empty string' });
@@ -95,13 +100,14 @@ function pathView(p) {
     environments: p.environments, tenants: p.tenants, services, repositories, provenance: p.provenance,
     entry: p.entry, target: p.target,
     hops: p.hops.map((h) => ({
-      index: h.index, from: h.from, to: h.to, relations: h.relations, state: h.state,
+      index: h.index, from: h.from, to: h.to, relations: h.relations, state: h.state, ...(h.actions ? { actions: h.actions } : {}),
       edges: h.edges.map((e) => ({
         id: e.id, relation: e.relation, provenance: e.provenance, effect: e.effect, confidence: e.confidence, pathState: e.pathState,
         sourceRevision: e.sourceRevision, source: e.source, observationInterval: e.observationInterval, completeness: e.completeness,
       })),
     })),
     supportingEdgeIds: p.supportingEdgeIds, conditions: p.conditions, blockers: p.blockers, assumptions: p.assumptions,
+    ...(p.actionOutcomes ? { actionOutcomes: p.actionOutcomes } : {}),
     crossings: p.crossings, uncoveredBoundaries: uncovered,
     freshness: {
       observedFrom: p.coverage.observedFrom, observedUntil: p.coverage.observedUntil, staleHops: p.coverage.staleHops,
@@ -231,12 +237,12 @@ export function boundaryCoverage(contexts) {
  *
  * @returns {{ status: string, code?: string, reason?: string, findings: object[], errors: object[] }}
  */
-export function attachBoundaryContext({ config, findings, graph, bindings = [], records = [], now } = {}) {
+export function attachBoundaryContext({ config, findings, graph, bindings = [], records = [], now, action = null } = {}) {
   const gate = featureStatus(config, BOUNDARY_FEATURE);
   if (gate.status !== 'ok') return { ...gate, findings, errors: [] };
   const out = [], errors = [];
   for (const f of Array.isArray(findings) ? findings : []) {
-    const r = analyzeFindingBoundaries({ graph, finding: f, bindings, records, now });
+    const r = analyzeFindingBoundaries({ graph, finding: f, bindings, records, now, ...(action ? { action } : {}) });
     if (!r.ok) { errors.push(...r.errors); out.push(f); continue; }
     out.push({ ...f, boundaryContext: r.context });
   }

package/src/lineage/deployment/proof-binding.js

@@ -0,0 +1,79 @@
+// Scope-bound proof for deployed paths (threat-model PRD FR-04.1, FR-04.2; TM-05).
+//
+// A verification record proves a COMPONENT behaviour at one commit. Before this, a record for revision A promoted both the exposure
+// and the impact paths of a revision B graph to exploitable. Now:
+//
+//   component proof   the record is applicable (validated, trusted runtime proof, the class's oracle) AND its commit is the graph's
+//                     revision. A record for another revision is kept as historical evidence with the mismatch, never applied.
+//   path promotion    additionally needs a proof-binding envelope, version 1, for that record and that exact path: the artifact and
+//                     policy (graph) digests, environment, tenant, actor, route and action, the path id and its kind (exposure or
+//                     impact), the oracle version and the effect the oracle observed, issued and signed by an issuer the operator
+//                     trusts (an Ed25519 public key in the trust root). A matching digest or a caller's label is not authority.
+//
+// Every refusal has its own code, so a reviewer can tell a malformed envelope from a tampered, an expired or a replayed one. An exact
+// duplicate envelope adds nothing.
+import crypto from 'node:crypto';
+
+export const PROOF_BINDING_SCHEMA = 'agentic-security/proof-binding';
+export const PROOF_BINDING_VERSION = 1;
+const FIELDS = ['schema', 'version', 'recordId', 'commit', 'artifactDigest', 'policyDigest', 'environment', 'tenant', 'actor', 'route', 'action', 'pathId', 'claim', 'oracleVersion', 'effect', 'issuer', 'issuedAt', 'expires'];
+const REQUIRED = ['recordId', 'commit', 'artifactDigest', 'policyDigest', 'environment', 'actor', 'pathId', 'claim', 'oracleVersion', 'effect', 'issuer', 'issuedAt', 'expires'];
+const CLAIMS = new Set(['exposure', 'impact']);
+
+const canonical = (e) => JSON.stringify(FIELDS.map((k) => [k, e[k] ?? null]));
+export const bindingDigest = (e) => crypto.createHash('sha256').update(canonical(e)).digest('hex');
+
+/** Sign an envelope with an issuer's Ed25519 private key (used by an issuer and by tests). */
+export function signProofBinding(envelope, privateKeyPem) {
+  const body = { schema: PROOF_BINDING_SCHEMA, version: PROOF_BINDING_VERSION, ...envelope };
+  return { ...body, signature: crypto.sign(null, Buffer.from(canonical(body)), privateKeyPem).toString('base64') };
+}
+
+/** Structural and authority check of one envelope. Returns { ok, code, reason }. */
+export function verifyProofBinding(e, { trustRoot = {}, now = Date.now() } = {}) {
+  if (!e || typeof e !== 'object' || Array.isArray(e)) return { ok: false, code: 'malformed', reason: 'the binding is not an object' };
+  if (e.schema !== PROOF_BINDING_SCHEMA || e.version !== PROOF_BINDING_VERSION) return { ok: false, code: 'unsupported-version', reason: 'the binding schema or version is not supported' };
+  for (const k of Object.keys(e)) if (!FIELDS.includes(k) && k !== 'signature') return { ok: false, code: 'malformed', reason: `unknown binding field ${k}` };
+  for (const k of REQUIRED) if (e[k] === undefined || e[k] === null || e[k] === '') return { ok: false, code: 'missing-binding', reason: `the binding has no ${k}` };
+  if (!CLAIMS.has(e.claim)) return { ok: false, code: 'malformed', reason: 'claim must be exposure or impact' };
+  const key = trustRoot[e.issuer];
+  if (!key) return { ok: false, code: 'untrusted-issuer', reason: `issuer ${String(e.issuer).slice(0, 60)} is not in the operator's trust root` };
+  let good = false;
+  try { good = typeof e.signature === 'string' && crypto.verify(null, Buffer.from(canonical(e)), key, Buffer.from(e.signature, 'base64')); } catch { good = false; }
+  if (!good) return { ok: false, code: 'tampered', reason: 'the signature does not verify against the issuer\'s key' };
+  if (!(Date.parse(e.expires) > now)) return { ok: false, code: 'expired', reason: 'the binding has expired' };
+  return { ok: true, code: 'verified', reason: null };
+}
+
+/**
+ * Decide whether a path may be promoted by a component proof, given the bindings supplied for it.
+ * @param {{path:object, kind:'exposure'|'impact', graph:object, record:object, bindings:object[], trustRoot:object, now:number,
+ *          expect:{artifactDigest?:string, environment?:string, tenant?:string|null, actor?:string, route?:string, action?:string}}} a
+ * @returns {{promote:boolean, code:string, reason:string, bindingId:string|null, diagnostics:object[]}}
+ */
+export function judgePathPromotion({ path, kind, graph, record, bindings = [], trustRoot = {}, now = Date.now(), expect = {} }) {
+  const diagnostics = [];
+  const seen = new Set();
+  const forRecord = bindings.filter((b) => b && b.recordId === record.id);
+  if (!forRecord.length) return { promote: false, code: 'component-only', reason: 'the proof covers the component; no issued binding ties it to this deployed path', bindingId: null, diagnostics };
+  for (const b of forRecord) {
+    const id = bindingDigest(b);
+    if (seen.has(id)) continue; // an exact duplicate adds no authority
+    seen.add(id);
+    const v = verifyProofBinding(b, { trustRoot, now });
+    if (!v.ok) { diagnostics.push({ bindingId: id.slice(0, 16), code: v.code, reason: v.reason }); continue; }
+    const mismatch = [];
+    if (b.commit !== record.commit) mismatch.push('commit');
+    if (graph.revision && b.commit !== graph.revision) mismatch.push('revision');
+    if (b.policyDigest !== graph.digest) mismatch.push('policy');
+    if (b.pathId !== path.id) mismatch.push('path');
+    if (b.claim !== kind) mismatch.push('claim');
+    if (record.oracle && b.oracleVersion !== String(record.oracle.version ?? '')) mismatch.push('oracle');
+    if (!(path.environments || []).includes(b.environment)) mismatch.push('environment');
+    if ((path.tenants || []).length && !(path.tenants || []).includes(b.tenant)) mismatch.push('tenant');
+    for (const k of ['artifactDigest', 'environment', 'tenant', 'actor', 'route', 'action']) if (expect[k] !== undefined && expect[k] !== null && b[k] !== expect[k]) mismatch.push(k);
+    if (mismatch.length) { diagnostics.push({ bindingId: id.slice(0, 16), code: 'context-mismatch', reason: `the binding was issued for another ${[...new Set(mismatch)].join(', ')}` }); continue; }
+    return { promote: true, code: 'bound', reason: `issued binding ${id.slice(0, 16)} by ${b.issuer} ties the proof to this ${kind} path`, bindingId: id.slice(0, 16), diagnostics };
+  }
+  return { promote: false, code: diagnostics.length ? diagnostics[0].code : 'component-only', reason: diagnostics.length ? diagnostics.map((d) => d.reason).join('; ') : 'no binding applies', bindingId: null, diagnostics };
+}