@clear-capabilities/agentic-security-scanner 0.162.0 → 0.163.1

package/src/lineage/deployment/ingest.js

@@ -0,0 +1,221 @@
+// ingest.js: turn customer-supplied deployment files into a boundary graph
+// (X-302), and invalidate it when a source file changes.
+//
+// What this module will and will not do:
+//  - It reads only files the caller names, under one root, as bounded UTF-8
+//    text. It follows no symlink out of the root, opens no socket, spawns no
+//    process, reads no credential and calls no cloud API. The pure entry point
+//    (`ingestDeploymentConfig`) takes text and cannot touch the file system at
+//    all; the file entry point (`ingestDeploymentFiles`) is gated by the
+//    `deployment-boundaries` feature so it is inert unless an operator turns
+//    it on.
+//  - It does not execute configuration. Terraform HCL, nginx style
+//    configuration and other languages are reported as typed unsupported
+//    syntax, with a hint where a supported equivalent exists, and contribute
+//    no edges.
+//  - An adapter that throws on hostile input is contained: the file becomes a
+//    typed gap and the other files are still ingested.
+//
+// Every edge an adapter emits carries the file, the sha256 of the exact text
+// parsed, the parser name and the parser version. `invalidateChangedSources`
+// uses those digests to drop what a changed or removed file used to support,
+// so a stale relation does not outlive its evidence.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { digestOfBytes } from '../../posture/assurance/identity.js';
+import { featureStatus, limitValues, typed } from '../../posture/assurance/config.js';
+import { readFileBounded } from '../../posture/assurance/bounded-io.js';
+import { buildBoundaryGraph } from './boundary-graph.js';
+import { parseKubernetes, KUBERNETES_PARSER, KUBERNETES_PARSER_VERSION } from './adapter-kubernetes.js';
+import { parseCompose, COMPOSE_PARSER, COMPOSE_PARSER_VERSION } from './adapter-compose.js';
+import { parseTerraformPlan, parseIamPolicy, TERRAFORM_PARSER, TERRAFORM_PARSER_VERSION, IAM_PARSER, IAM_PARSER_VERSION } from './adapter-cloud.js';
+
+export const DEPLOYMENT_FEATURE = 'deployment-boundaries';
+export const MAX_INGEST_FILES = 200;
+
+const ADAPTERS = Object.freeze({
+  kubernetes: { parse: parseKubernetes, parser: KUBERNETES_PARSER, version: KUBERNETES_PARSER_VERSION },
+  compose: { parse: parseCompose, parser: COMPOSE_PARSER, version: COMPOSE_PARSER_VERSION },
+  'terraform-plan': { parse: parseTerraformPlan, parser: TERRAFORM_PARSER, version: TERRAFORM_PARSER_VERSION },
+  'iam-policy': { parse: parseIamPolicy, parser: IAM_PARSER, version: IAM_PARSER_VERSION },
+});
+export const ADAPTER_NAMES = Object.freeze(Object.keys(ADAPTERS));
+
+const UNSUPPORTED_SYNTAX = {
+  '.tf': 'Terraform HCL is not interpreted (it would need evaluation); supply the JSON from `terraform show -json <plan>`',
+  '.hcl': 'HCL is not interpreted; supply a supported JSON or YAML form',
+  '.tfvars': 'Terraform variable files carry values, not topology, and are not read',
+  '.conf': 'proxy and server configuration syntax is not supported by any adapter',
+  '.toml': 'TOML configuration is not supported by any adapter',
+  '.xml': 'XML configuration is not supported by any adapter',
+};
+
+/** Decide which adapter reads a file, or why none does. Pure. */
+export function detectFormat(file, text) {
+  const ext = path.extname(file).toLowerCase();
+  if (UNSUPPORTED_SYNTAX[ext]) return { adapter: null, code: 'unsupported-syntax', reason: UNSUPPORTED_SYNTAX[ext] };
+  if (ext === '.json') {
+    let doc;
+    try { doc = JSON.parse(text); } catch (e) { return { adapter: null, code: 'malformed-input', reason: `not valid JSON (${String(e.message).split('\n')[0]})` }; }
+    if (doc && typeof doc === 'object' && !Array.isArray(doc)) {
+      if (typeof doc.format_version === 'string' && Array.isArray(doc.resource_changes)) return { adapter: 'terraform-plan' };
+      if (Object.hasOwn(doc, 'Statement')) return { adapter: 'iam-policy' };
+    }
+    return { adapter: null, code: 'unsupported-format', reason: 'JSON that is neither a terraform plan nor an IAM policy document' };
+  }
+  if (ext === '.yaml' || ext === '.yml') {
+    if (/^services:\s*(#.*)?$/m.test(text)) return { adapter: 'compose' };
+    if (/^apiVersion:\s*\S/m.test(text) && /^kind:\s*\S/m.test(text)) return { adapter: 'kubernetes' };
+    return { adapter: null, code: 'unsupported-format', reason: 'YAML that is neither a compose file nor a Kubernetes manifest' };
+  }
+  return { adapter: null, code: 'unsupported-format', reason: `no adapter reads '${ext || 'files without an extension'}'` };
+}
+
+const NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const REV = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+
+/**
+ * Ingest already-read files. Pure: no file system, no network, no clock.
+ *
+ * @param {object} p
+ * @param {Array<{path: string, text: string}>} p.files
+ * @param {string} p.environment  the deployment environment these files describe
+ * @param {string|null} [p.repository]
+ * @param {string|null} [p.revision]   exact commit these files were read at, when known
+ * @param {Record<string,string>} [p.identities]  file path -> identity a policy document belongs to
+ * @returns {{status: 'ok'|'invalid-input'|'invalid-graph', graph: object|null, files: object[], errors: object[]}}
+ */
+export function ingestDeploymentConfig({ files, environment, repository = null, revision = null, identities = {} } = {}) {
+  if (typeof environment !== 'string' || !NAME.test(environment)) return { status: 'invalid-input', graph: null, files: [], errors: [{ code: 'BAD_TYPE', path: 'environment', message: 'environment must be a name such as prod or staging' }] };
+  if (repository !== null && (typeof repository !== 'string' || !NAME.test(repository))) return { status: 'invalid-input', graph: null, files: [], errors: [{ code: 'BAD_TYPE', path: 'repository', message: 'repository must be null or a name' }] };
+  if (revision !== null && !(typeof revision === 'string' && REV.test(revision))) return { status: 'invalid-input', graph: null, files: [], errors: [{ code: 'BAD_TYPE', path: 'revision', message: 'revision must be null or an exact 40/64 hex commit' }] };
+  if (!Array.isArray(files)) return { status: 'invalid-input', graph: null, files: [], errors: [{ code: 'BAD_TYPE', path: 'files', message: 'files must be an array' }] };
+
+  const nodes = [], edges = [], gaps = [], sources = [], report = [];
+  const sorted = [...files].filter(f => f && typeof f.path === 'string' && typeof f.text === 'string').sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  if (files.length > MAX_INGEST_FILES) gaps.push({ code: 'limit-exceeded', subject: 'files', file: null, message: `${files.length} files supplied; only the first ${MAX_INGEST_FILES} are read` });
+  for (const f of sorted.slice(0, MAX_INGEST_FILES)) {
+    const bytes = Buffer.from(f.text, 'utf8');
+    const digest = digestOfBytes(bytes);
+    const fmt = detectFormat(f.path, f.text);
+    if (!fmt.adapter) {
+      gaps.push({ code: fmt.code, subject: f.path, file: f.path, message: fmt.reason });
+      report.push({ file: f.path, adapter: null, status: fmt.code });
+      continue;
+    }
+    const a = ADAPTERS[fmt.adapter];
+    let out;
+    try {
+      out = a.parse(f.text, { file: f.path, digest, environment, repository, revision, identity: identities[f.path] ?? null });
+    } catch (e) {
+      gaps.push({ code: 'malformed-input', subject: f.path, file: f.path, message: `the ${fmt.adapter} adapter could not read this file (${String(e?.message ?? e).split('\n')[0]})` });
+      report.push({ file: f.path, adapter: fmt.adapter, status: 'malformed-input' });
+      continue;
+    }
+    nodes.push(...out.nodes); edges.push(...out.edges); gaps.push(...out.gaps);
+    sources.push({ file: f.path, digest, parser: a.parser, parserVersion: a.version, bytes: bytes.length });
+    report.push({ file: f.path, adapter: fmt.adapter, status: out.nodes.length || out.edges.length ? 'ingested' : (out.gaps[0]?.code ?? 'empty') });
+  }
+  const built = buildBoundaryGraph({ repository, revision, nodes, edges, gaps, sources });
+  if (!built.ok) return { status: 'invalid-graph', graph: null, files: report, errors: built.errors };
+  return { status: 'ok', graph: built.graph, files: report, errors: [] };
+}
+
+// ------------------------------------------------------------ file entry point
+
+/** Resolve `rel` under `root`, refusing absolute paths, traversal and symlinks. Returns the real path or null. */
+export function resolveUnderRoot(root, rel) {
+  if (typeof rel !== 'string' || rel === '' || path.isAbsolute(rel) || rel.split(/[\\/]/).includes('..')) return null;
+  let realRoot;
+  try { realRoot = fs.realpathSync(root); } catch { return null; }
+  const full = path.join(realRoot, rel);
+  let st;
+  try { st = fs.lstatSync(full); } catch { return null; }
+  if (st.isSymbolicLink() || !st.isFile()) return null;
+  let real;
+  try { real = fs.realpathSync(full); } catch { return null; }
+  return real === full && (real === realRoot || real.startsWith(realRoot + path.sep)) ? real : null;
+}
+
+/**
+ * Read named files under `root` and ingest them. Gated by the
+ * `deployment-boundaries` feature (off by default; the environment, an explicit
+ * option or the operator's config turn it on). Returns a typed result and never
+ * throws.
+ *
+ * @param {object} p
+ * @param {object} p.config  resolveAssuranceConfig() result
+ * @param {string} p.root
+ * @param {string[]} p.paths  relative paths under root
+ */
+export function ingestDeploymentFiles({ config, root, paths, environment, repository = null, revision = null, identities = {} } = {}) {
+  const gate = featureStatus(config, DEPLOYMENT_FEATURE);
+  if (gate.status !== 'ok') return gate;
+  if (!Array.isArray(paths)) return typed('blocked', 'invalid-config', 'paths must be an array', { feature: DEPLOYMENT_FEATURE });
+  const maxBytes = limitValues(config).maxFileBytes;
+  const files = [];
+  const readGaps = [];
+  for (const rel of paths.slice(0, MAX_INGEST_FILES)) {
+    const real = resolveUnderRoot(root, rel);
+    if (!real) { readGaps.push({ code: 'malformed-input', subject: String(rel), file: null, message: 'path is outside the root, is a symlink, or is not a regular file; it is not read' }); continue; }
+    const r = readFileBounded(real, maxBytes);
+    if (r.status !== 'ok') { readGaps.push({ code: r.code === 'limit-exceeded' ? 'limit-exceeded' : 'malformed-input', subject: String(rel), file: String(rel), message: r.reason }); continue; }
+    files.push({ path: rel.split(path.sep).join('/'), text: r.text });
+  }
+  const out = ingestDeploymentConfig({ files, environment, repository, revision, identities });
+  if (out.status !== 'ok') return typed('blocked', 'invalid-config', out.errors.map(e => e.message).join('; ') || 'invalid ingest input', { feature: DEPLOYMENT_FEATURE, ...out });
+  if (readGaps.length) {
+    // Re-build with the read gaps included so the graph tells the whole story.
+    const again = buildBoundaryGraph({ ...out.graph, repository, revision, gaps: [...out.graph.gaps, ...readGaps] });
+    if (again.ok) out.graph = again.graph;
+  }
+  return typed('ok', null, 'ingested', { feature: DEPLOYMENT_FEATURE, ...out });
+}
+
+// ------------------------------------------------------------ invalidation
+
+/**
+ * Drop what changed or removed source files used to support (X-302.AC03).
+ *
+ * `currentDigests` maps file -> the sha256 of the file as it is NOW (a missing
+ * entry means the file is gone). Static edges sourced from a file whose digest
+ * differs are removed; a node that only a stale file declared stops being
+ * resolved; nodes nothing references any more are dropped; a gap records each
+ * invalidated file. Runtime and inferred edges are untouched because they do
+ * not claim a file as evidence. Returns a rebuilt, validated graph.
+ */
+export function invalidateChangedSources(graph, currentDigests) {
+  const cur = currentDigests instanceof Map ? currentDigests : new Map(Object.entries(currentDigests ?? {}));
+  const stale = new Map(); // file -> 'changed' | 'missing'
+  for (const s of graph.sources) {
+    const now = cur.get(s.file);
+    if (now === undefined) stale.set(s.file, 'missing');
+    else if (now !== s.digest) stale.set(s.file, 'changed');
+  }
+  if (stale.size === 0) return { ok: true, graph, invalidatedEdgeIds: [], staleFiles: [], errors: [] };
+
+  const isStale = (ref) => ref && stale.has(ref.file) && cur.get(ref.file) !== ref.digest;
+  const keptEdges = [], invalidated = [];
+  for (const e of graph.edges) {
+    if (e.source && isStale(e.source)) invalidated.push(e.id); else keptEdges.push(e);
+  }
+  const referenced = new Set();
+  for (const e of keptEdges) { referenced.add(e.from); referenced.add(e.to); }
+  const nodes = [];
+  for (const n of graph.nodes) {
+    const declaredBy = n.declaredBy.filter(d => !isStale(d));
+    const lostDeclaration = declaredBy.length < n.declaredBy.length;
+    if (declaredBy.length === 0 && !referenced.has(n.id)) continue; // nothing supports it any more
+    if (lostDeclaration && declaredBy.length === 0) nodes.push({ ...n, declaredBy, resolved: false, unresolvedReason: 'the file that declared it changed or was removed', repository: null });
+    else nodes.push({ ...n, declaredBy });
+  }
+  const gaps = [...graph.gaps];
+  for (const [file, why] of [...stale].sort()) {
+    gaps.push({ code: why === 'missing' ? 'source-missing' : 'source-changed', subject: file, file, message: `${file} ${why === 'missing' ? 'is no longer present' : 'has changed since it was ingested'}; the relations it supported were dropped and must be re-ingested` });
+  }
+  const sources = graph.sources.filter(s => !stale.has(s.file));
+  const built = buildBoundaryGraph({ repository: graph.repository, revision: graph.revision, nodes, edges: keptEdges, gaps, sources });
+  if (!built.ok) return { ok: false, graph: null, invalidatedEdgeIds: invalidated, staleFiles: [...stale.keys()].sort(), errors: built.errors };
+  return { ok: true, graph: built.graph, invalidatedEdgeIds: invalidated.sort(), staleFiles: [...stale.keys()].sort(), errors: [] };
+}

package/src/lineage/deployment/projection.js

@@ -0,0 +1,244 @@
+// projection.js: the one place a boundary context becomes something a person or another tool reads (X-307).
+//
+// It follows the verification projection (`posture/verification/projection.js`): the JSON report, the Markdown and terminal
+// reports and the MCP finding explanation all call this module, so none of them formats its own boundary text and the
+// surfaces cannot disagree. Rules it keeps:
+//   - It is a VIEW. It reads a context produced by `analyzeFindingBoundaries` and invents nothing; a context that fails
+//     validation yields `{ ok: false, errors }`, never a guessed state.
+//   - Closed world. A context with a field this module does not know, or a string shaped like a credential or carrying control
+//     characters, is refused rather than shown. Imported secrets and raw trace payloads cannot reach a report through here.
+//   - Ids are shared. The view carries the context id, the hypothesis id, path ids, edge ids and verification record ids
+//     unchanged, so a boundary record can be joined to a verification record by id.
+//   - Filtering never hides the caveats. A filter narrows the paths shown; the scope, the uncovered boundaries and every
+//     warning stay, and a warning says how many paths the filter hid.
+//   - The text states what was established and what was not. It never calls a partial result safe or protected, and it does
+//     not call a finding unreachable: no path found is "not shown to exist".
+//   - Deterministic: no clock, no randomness, fixed key order.
+//
+// The presentation is additive and off by default. `attachBoundaryContext` is the only producer and it is gated by the
+// `deployment-boundaries` feature; with the feature off no finding carries a context, so no output changes.
+
+import { featureStatus } from '../../posture/assurance/config.js';
+import { analyzeFindingBoundaries, BOUNDARY_CONTEXT_SCHEMA } from './attack-paths.js';
+
+export const VIEW_SCHEMA = 'agentic-security/boundary-view';
+export const VIEW_VERSION = '1.0.0';
+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'];
+const FILTER_KEYS = ['service', 'repository', 'environment', 'tenant'];
+const MAX_STRING = 600;
+
+const STATE_TEXT = Object.freeze({
+  possible: 'POSSIBLE (configured; not exercised)',
+  blocked: 'BLOCKED (an explicit deny in configuration; the deny was not tested)',
+  unresolved: 'UNRESOLVED (depends on something the configuration does not establish)',
+  'runtime-supported': 'OBSERVED (seen in the supplied traces; traffic coverage is not established)',
+});
+const EXPOSURE_TEXT = Object.freeze({
+  'runtime-supported': 'OBSERVED', possible: 'POSSIBLE', unresolved: 'UNRESOLVED', blocked: 'BLOCKED', 'none-found': 'NO PATH FOUND', 'not-assessed': 'NOT ASSESSED',
+});
+const EXPLOIT_TEXT = Object.freeze({
+  'not-established': 'not established',
+  'exploitable-confirmed': 'confirmed by a trusted oracle in its declared scenario',
+  'oracle-confirmed-path-blocked': 'oracle-confirmed effect, but the path is blocked by configuration',
+  'oracle-confirmed-path-unresolved': 'oracle-confirmed effect, but deployment reachability is unresolved',
+});
+
+// Credential and payload shapes that must never appear in a context.
+const SENSITIVE = [
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----/,
+  /\bAKIA[0-9A-Z]{16}\b/,
+  /\b(?:password|passwd|secret|api[_-]?key|token|authorization)\s*[:=]\s*\S+/i,
+  /\bBearer\s+[A-Za-z0-9._~+/=-]{12,}/i,
+  /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\./,
+];
+// eslint-disable-next-line no-control-regex
+const CONTROL = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/;
+
+function scanStrings(value, path, errors, depth = 0) {
+  if (depth > 12) { errors.push({ code: 'RULE_VIOLATION', path, message: 'context nests deeper than the contract allows' }); return; }
+  if (typeof value === 'string') {
+    if (value.length > MAX_STRING) errors.push({ code: 'RULE_VIOLATION', path, message: `a string is over ${MAX_STRING} characters` });
+    else if (CONTROL.test(value)) errors.push({ code: 'RULE_VIOLATION', path, message: 'a string carries control characters' });
+    else if (SENSITIVE.some((re) => re.test(value))) errors.push({ code: 'RULE_VIOLATION', path, message: 'a string is shaped like a credential or a raw payload and is refused' });
+  } else if (Array.isArray(value)) value.forEach((v, i) => scanStrings(v, `${path}[${i}]`, errors, depth + 1));
+  else if (value && typeof value === 'object') for (const k of Object.keys(value)) scanStrings(value[k], `${path}.${k}`, errors, depth + 1);
+}
+
+/** Closed-world check of a context. Never throws. */
+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` });
+  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' });
+  if (!Array.isArray(ctx.paths)) errors.push({ code: 'BAD_TYPE', path: 'paths', message: 'paths must be an array' });
+  if (!Array.isArray(ctx.warnings) || !Array.isArray(ctx.uncovered) || !Array.isArray(ctx.verification)) errors.push({ code: 'BAD_TYPE', path: '', message: 'warnings, uncovered and verification must be arrays' });
+  if (errors.length) return { ok: false, errors };
+  scanStrings(ctx, '', errors);
+  return { ok: errors.length === 0, errors };
+}
+
+// ------------------------------------------------------------ view
+
+function pathView(p) {
+  const services = [...new Set(p.hops.flatMap((h) => [h.from, h.to]).concat(p.hops.length ? [] : [p.entry]).filter((n) => n.kind === 'service').map((n) => n.name))].sort();
+  const repositories = [...new Set(p.hops.flatMap((h) => [h.from.repository, h.to.repository]).concat([p.entry.repository, p.target.repository]).filter(Boolean))].sort();
+  const unobserved = new Set(p.coverage.unobservedHops);
+  const uncovered = p.crossings.filter((c) => c.type === 'identity' || unobserved.has(c.hop)).map((c) => ({ type: c.type, detail: c.detail, hop: c.hop }));
+  return {
+    id: p.id, kind: p.kind, state: p.state, conditional: p.conditional,
+    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,
+      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,
+    crossings: p.crossings, uncoveredBoundaries: uncovered,
+    freshness: {
+      observedFrom: p.coverage.observedFrom, observedUntil: p.coverage.observedUntil, staleHops: p.coverage.staleHops,
+      sampledHops: p.coverage.sampledHops, staleEvaluated: p.coverage.staleEvaluated,
+      statement: p.coverage.observedHops.length
+        ? `${p.coverage.observedHops.length} network hop(s) were observed${p.coverage.observedUntil ? ` up to ${p.coverage.observedUntil}` : ''}${p.coverage.staleEvaluated ? '' : '; staleness was not evaluated (no clock supplied)'}; the rest are configuration only`
+        : 'no network hop was observed; this path is configuration only',
+    },
+    coverage: p.coverage, exploitability: p.exploitability,
+  };
+}
+
+function textLines(view) {
+  const L = [];
+  L.push(`Deployment boundaries: exposure ${EXPOSURE_TEXT[view.exposure.state] ?? view.exposure.state}. ${view.exposure.statement}`);
+  L.push(view.binding.service
+    ? `  Service: ${view.binding.service.name} (environment ${view.binding.service.environment ?? 'none'}, tenant ${view.binding.service.tenant ?? 'none'})`
+    : `  Service: not bound (${view.binding.reason})`);
+  L.push(`  Graph: repository ${view.graph.repository ?? 'unknown'}, revision ${view.graph.revision ? view.graph.revision.slice(0, 12) : 'unknown'}, digest ${view.graph.digest.slice(0, 12)}`);
+  const f = view.filter;
+  const filterText = f ? ` (filter ${FILTER_KEYS.filter((k) => f[k]).map((k) => `${k}=${f[k]}`).join(', ') || 'none'}; ${view.scope.hiddenPathCount} hidden)` : '';
+  L.push(`  Paths: ${view.paths.length} shown of ${view.scope.totalPathCount}${filterText}`);
+  for (const p of view.paths) {
+    const chain = p.hops.length ? [p.hops[0].from.name, ...p.hops.map((h) => h.to.name)].join(' -> ') : p.entry.name;
+    L.push(`    ${p.id} [${p.kind}] ${STATE_TEXT[p.state]}: ${chain}`);
+    L.push(`      environment: ${p.environments.join(', ') || 'none'}; tenants: ${p.tenants.join(', ') || 'none'}; provenance: ${p.provenance.join(', ') || 'none'}`);
+    const files = [...new Set(p.hops.flatMap((h) => h.edges.map((e) => (e.source ? `${e.source.file}@${e.source.digest.slice(0, 8)}` : null))).filter(Boolean))].sort();
+    L.push(`      supporting edges: ${p.supportingEdgeIds.length}${files.length ? ` from ${files.join(', ')}` : ''}`);
+    L.push(`      freshness: ${p.freshness.statement}`);
+    for (const c of p.conditions) L.push(`      condition: ${c.detail}`);
+    for (const b of p.blockers) L.push(`      blocker: ${b.detail}`);
+    if (p.uncoveredBoundaries.length) L.push(`      not covered by observation: ${p.uncoveredBoundaries.map((u) => `${u.type} (${u.detail})`).join('; ')}`);
+    L.push(`      exploitability: ${EXPLOIT_TEXT[p.exploitability.label] ?? p.exploitability.label}. ${p.exploitability.reason}`);
+  }
+  if (view.verification.length) L.push(`  Verification records: ${view.verification.map((v) => `${v.recordId} (${v.applicable ? 'applicable' : 'not applicable'})`).join(', ')}`);
+  if (view.uncovered.length) {
+    L.push('  Not established:');
+    for (const u of view.uncovered) L.push(`    ${u.type}: ${u.detail}`);
+  }
+  L.push('  Caveats:');
+  for (const w of view.warnings) L.push(`    ${w}`);
+  return L;
+}
+
+/**
+ * Project a boundary context.
+ * @returns {{ ok: boolean, view: object|null, errors: object[] }} never throws
+ */
+export function projectBoundaryContext(ctx) {
+  try {
+    const v = validateBoundaryContext(ctx);
+    if (!v.ok) return { ok: false, view: null, errors: v.errors };
+    const paths = ctx.paths.map(pathView);
+    const view = {
+      schema: VIEW_SCHEMA, schemaVersion: VIEW_VERSION,
+      contextId: ctx.id, hypothesisId: ctx.hypothesisId, finding: ctx.finding, binding: ctx.binding,
+      graph: ctx.graph, exposure: ctx.exposure, paths,
+      verification: ctx.verification.map((r) => ({ recordId: r.recordId, outcome: r.outcome, applicable: r.applicable })),
+      verificationRecordIds: ctx.verification.map((r) => r.recordId).filter(Boolean),
+      uncovered: ctx.uncovered,
+      warnings: [...ctx.warnings],
+      scope: {
+        totalPathCount: paths.length, hiddenPathCount: 0, truncated: ctx.truncated,
+        repositories: ctx.graph.repositories, environments: ctx.graph.environments, tenants: ctx.graph.tenants,
+        services: [...new Set(paths.flatMap((p) => p.services))].sort(),
+      },
+      filter: null,
+    };
+    view.text = textLines(view);
+    return { ok: true, view, errors: [] };
+  } catch (e) {
+    return { ok: false, view: null, errors: [{ code: 'RULE_VIOLATION', path: '', message: `boundary projection failed: ${String(e?.message || e).slice(0, 160)}` }] };
+  }
+}
+
+/**
+ * Narrow a view by service, repository, environment and tenant (all given criteria must match). The scope, the uncovered
+ * boundaries and every warning are kept, and a warning says how many paths were hidden. A filter that matches nothing says so
+ * and does not claim that nothing exists.
+ */
+export function filterBoundaryView(view, filter = {}) {
+  const f = {};
+  for (const k of FILTER_KEYS) f[k] = typeof filter[k] === 'string' && filter[k] ? filter[k] : null;
+  const match = (p) => (!f.service || p.services.includes(f.service))
+    && (!f.repository || p.repositories.includes(f.repository))
+    && (!f.environment || p.environments.includes(f.environment))
+    && (!f.tenant || p.tenants.includes(f.tenant));
+  const total = view.scope.totalPathCount;
+  const shown = view.paths.filter(match);
+  const hidden = total - shown.length;
+  const warnings = [...view.warnings.filter((w) => !w.startsWith('Filter: '))];
+  if (hidden > 0) warnings.push(`Filter: ${hidden} of ${total} path(s) are hidden by the filter; hidden paths are not shown to be absent.`);
+  if (!shown.length && total > 0) warnings.push('Filter: no path matches the filter; that says nothing about paths outside it.');
+  const out = { ...view, paths: shown, warnings, scope: { ...view.scope, hiddenPathCount: hidden }, filter: f };
+  out.text = textLines(out);
+  return out;
+}
+
+/**
+ * The additive report fields for a finding that carries a context. Mirrors `verificationFields`, with one difference: the
+ * context itself is returned only when it validated, so a refused context (a credential-shaped string, a made-up field) is not
+ * echoed into a report by the very surface that refused to show it.
+ */
+export function boundaryFields(ctx, o = {}) {
+  if (!ctx || typeof ctx !== 'object') return {};
+  const p = projectBoundaryContext(ctx);
+  if (!p.ok) return { boundaryView: null, boundaryViewErrors: p.errors };
+  return { boundaryContext: ctx, boundaryView: o.filter ? filterBoundaryView(p.view, o.filter) : p.view };
+}
+
+/** Run-level accounting for the findings that carry a context. */
+export function boundaryCoverage(contexts) {
+  const list = (Array.isArray(contexts) ? contexts : []).filter((c) => c && typeof c === 'object');
+  const valid = list.filter((c) => validateBoundaryContext(c).ok);
+  const bound = valid.filter((c) => c.binding.status === 'bound').length;
+  const byExposure = {};
+  for (const c of valid) byExposure[c.exposure.state] = (byExposure[c.exposure.state] || 0) + 1;
+  const invalid = list.length - valid.length;
+  const why = Object.entries(byExposure).sort(([a], [b]) => a.localeCompare(b)).map(([k, n]) => `${k}: ${n}`).join(', ');
+  const line = `Deployment boundaries: ${list.length} finding(s) with context; ${bound} bound to a service, ${valid.length - bound} not bound${invalid ? `, ${invalid} invalid` : ''}${why ? ` (${why})` : ''}; traffic coverage is not established`;
+  return { schema: COVERAGE_SCHEMA, schemaVersion: VIEW_VERSION, total: list.length, bound, unbound: valid.length - bound, invalid, byExposure, lines: [line] };
+}
+
+/**
+ * Attach a boundary context to each finding. This is the only producer and it is feature gated: with the feature off the
+ * same array is returned untouched, so scan and report output do not change.
+ *
+ * @returns {{ status: string, code?: string, reason?: string, findings: object[], errors: object[] }}
+ */
+export function attachBoundaryContext({ config, findings, graph, bindings = [], records = [], now } = {}) {
+  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 });
+    if (!r.ok) { errors.push(...r.errors); out.push(f); continue; }
+    out.push({ ...f, boundaryContext: r.context });
+  }
+  return { status: 'ok', code: null, reason: gate.reason, findings: out, errors };
+}