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

package/src/integrations/index.js

@@ -14,6 +14,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as yaml from '../util/yaml.js';
 import { statePath } from '../posture/state-dir.js';
+import { portfolioAssuranceEnabled, HEADLINE, BLOCKED_HEADLINE } from '../posture/portfolio/wording.js';
 
 function _configPath(scanRoot) {
   return statePath(scanRoot, 'integrations.yml');
@@ -36,12 +37,14 @@ export function buildSlackDigest(findings, summary, options = {}) {
   const project = options.project || 'project';
   const status = (summary.critical || 0) === 0 && (summary.high || 0) === 0
     ? '✅ safe to deploy' : '❌ not safe to deploy';
+  const statusLine = portfolioAssuranceEnabled({ option: options.portfolioAssurance })
+    ? (status.startsWith('✅') ? `✅ ${HEADLINE}` : `❌ ${BLOCKED_HEADLINE}`) + ' (completed supported checks only)' : status;
   const top = (findings || []).slice(0, 3);
 
   const lines = [
     `*🛡 agentic-security daily — ${new Date().toISOString().slice(0,10)}*`,
     `Project: \`${project}\``,
-    `Status: ${status}`,
+    `Status: ${statusLine}`,
     '',
     `*Findings:* ${summary.critical || 0} critical · ${summary.high || 0} high · ${summary.medium || 0} medium`,
   ];
@@ -66,7 +69,7 @@ export function buildDiscordDigest(findings, summary, options = {}) {
     embeds: [{
       title: `🛡 agentic-security — ${project}`,
       color: safe ? 0x2ecc71 : 0xe74c3c,
-      description: safe ? '✅ safe to deploy' : '❌ not safe to deploy',
+      description: portfolioAssuranceEnabled({ option: options.portfolioAssurance }) ? (safe ? `✅ ${HEADLINE} (completed supported checks only)` : `❌ ${BLOCKED_HEADLINE}`) : (safe ? '✅ safe to deploy' : '❌ not safe to deploy'),
       fields: [
         { name: 'Critical', value: String(summary.critical || 0), inline: true },
         { name: 'High',     value: String(summary.high || 0),     inline: true },

package/src/ir/CLAUDE.md

@@ -34,6 +34,20 @@ consumed by `scanner/src/dataflow/` for taint analysis.
 | Rust     | `parser-rust.js`      | Hand-rolled, the `parser-go.js`/`parser-cs.js` pattern (preprocess: comments blanked, `::` paths flattened to dots, turbofish/`?`/`.await` stripped; then statement-split + recursive CFG build). **SARD 80% F1 push, first-class from day one — no prior IR existed for Rust at all** (only the opt-in, WASM-based `tree-sitter-loader.js` long-tail path below, which nothing in the taint engine consumes). Models: `fn` items (free/impl/trait, qualifiers, generics, `impl Type` methods named `Type.method`), `let`/destructuring/compound-assign, method chains (args accumulated innermost-first, so `Command::new("sh").arg("-c").arg(x)` has the literal program name at arg 0 regardless of the chain's terminal method), macros (`format!`/`write!`/etc. lower to a template with inline `{ident}` and positional args; `vec!` to an array; every other macro keeps its own `name!` callee so `sqlx::query!` — the compile-checked, parameterized macro — never collides with the `query` sink); `if`/`if let`/`while`/`while let`/`loop`/`for`/`match` (pattern bindings assigned from the scrutinee) including expression-position control flow (`let x = match … {}` yields a `union` of the branch tails); trailing closures inlined with their parameter bound to the receiver; extractor-typed parameters (`Query(q): Query<P>`) and route-attributed handlers (`#[get("/<x>")]`) emit `fn.paramAnnotations`. **`.unwrap()`/`.expect(msg)` are popped from the chain, not just taint-transparent** — leaving them in shifts the terminal segment away from the real sink name (`sqlx::query(&sql).fetch_all(pool).await.unwrap()` would otherwise end in `.unwrap`, never `.fetch_all`, and no catalog entry could ever match it), the same "terminal segment shift" defect class documented for Go/Java/Kotlin above; a macro-only statement whose sole continuation is a popped `.unwrap()` (`write!(w, "…", x).unwrap();`) still counts as a call, tracked via a separate `_baseIsCall` flag so it doesn't fall through to "no call happened here" once the passthrough is gone. Three self-scan-flagged regexes (`(?:#\[[^\]]*\]\s*)+`, the attribute-skip pattern, appearing at three call sites) match the "optional/quantified group flanked by `\s*`" ReDoS heuristic shape but are linear by construction — each iteration is bounded by the mandatory literal `#[`…`]`, no shared character class exists for the engine to backtrack across — confirmed by direct timing (50 000 back-to-back attributes, 200 000 non-matching whitespace chars: both single-digit milliseconds), not merely asserted; see the comment at `_parseParams` in `parser-rust.js`. Guarded by `test/parser-rust.test.js` (CFG shape) and `test/rust-taint-flow.test.js` (end-to-end taint flow + precision cases). **Measured `bench/layer-recall` impact: 0 → 5/5 (100%) whole-corpus, 0 → 3/3 (100%) deep-tier** on first measurement — the corpus is small and every entry is annotation-sourced (axum/actix/rocket extractor parameters route directly into `paramAnnotations`), so 100% reflects the corpus's own composition, not general Rust ecosystem coverage; see `docs/METRICS.md`'s own disclosure. |
 | Long-tail (solidity/go/swift/dart) | `tree-sitter-loader.js` | **Optional** `web-tree-sitter` + `tree-sitter-wasms` (ABI-pinned 0.20.8 ↔ 0.1.13), lazy + degrades when absent. Powers `sast/tree-sitter-sinks.js` (opt-in via `AGENTIC_SECURITY_TREE_SITTER=1`). Marked `--external` in the build so the committed bundle never embeds WASM. Rust's own tree-sitter grammar remains loadable here too (unaffected by `parser-rust.js` existing), but the hand-rolled parser above is what feeds the taint engine — this path is now redundant for Rust specifically, kept only because removing a language from `tree-sitter-sinks.js`'s opt-in surface is out of scope for this change. |
 
+## Implicit handler parameters and Go line attribution (QA-006)
+
+`implicit-handler-params.js` is the pure decision "is this parameter request-bound without any annotation". `parser-cs.js` emits a
+`paramAnnotations` entry with decorator `ImplicitMvcActionParam` for a string-shaped parameter of a public, non-static, non-`[NonAction]` method of a
+controller class (derived from Controller/ControllerBase/ApiController, or named `*Controller`) unless it carries `[FromServices]` or an explicit
+`[From*]`; `parser-java.js` emits `ImplicitSpringMappedParam` for a plain `String` parameter of a method annotated `@GetMapping`/`@PostMapping`/
+`@RequestMapping`/... The catalog turns those two names into sources; the IR states the fact and the catalog decides what is a source. Nothing in the
+module reads a path, label or environment variable.
+
+`parser-go.js` line attribution: `FUNC_RE`'s leading `\s*` swallows blank lines, so the function used to be placed at the first newline of the run above
+it, and `_splitStatements` dropped blank and comment lines so every later statement was pulled upward by their count. Statement lines are now start-offset
+based (`_splitStatements(...).lineOffsets`, `_buildCfg` takes the line the body BEGINS on), a `//` comment no longer swallows the newline that ends its
+line, and nested if/for/closure bodies take their base from the real brace position. Tests: `test/evaluation/engine-mechanisms.test.js`.
+
 ## Python parser — dual-path with auto fallback
 
 The Python pipeline has two implementations. The dispatcher in `index.js`

package/src/ir/implicit-handler-params.js

@@ -0,0 +1,74 @@
+// Implicit request-bound handler parameters (QA-006, mechanism "framework entry points").
+//
+// A web framework binds the parameters of a request-handler method from the
+// request WITHOUT any annotation on the parameter itself:
+//   - ASP.NET MVC / Core: a public action method of a controller binds `string next`
+//     from the route, query string or form unless it carries `[FromServices]`.
+//   - Spring MVC: a method carrying `@GetMapping` / `@RequestMapping` / ... binds a plain
+//     `String q` parameter from the request parameters (`@RequestParam` is optional).
+//
+// The taint engine's annotation channel (`fn.paramAnnotations`, matched by the catalog's
+// `type: 'annotation'` sources) only ever saw the EXPLICIT forms (`[FromQuery]`,
+// `@RequestParam`), so a handler written in the equally common implicit form had no
+// source at all and the flow was invisible to the taint layer. This module is the pure
+// decision of "is this parameter implicitly request-bound", shared by the C# and Java
+// frontends; each frontend turns a positive answer into a `paramAnnotations` entry whose
+// decorator is one of the two names below, which the catalog binds to a source.
+//
+// Scope, stated so nothing is over-read:
+//   - ONLY string-shaped parameters. A numeric or Guid parameter cannot carry an injection
+//     payload, and a complex model parameter's field-level taint is out of scope here.
+//   - ONLY inside a class the framework would treat as a handler (a Controller-derived
+//     class, or any class whose name ends in `Controller`; for Spring, the MAPPING
+//     annotation on the method is what makes it a handler, not the class).
+//   - A DI-injected parameter is not request-bound: `[FromServices]` opts a parameter out.
+//   - Nothing here looks at a file name, path, comment or label.
+
+export const IMPLICIT_MVC_PARAM = 'ImplicitMvcActionParam';
+export const IMPLICIT_SPRING_PARAM = 'ImplicitSpringMappedParam';
+
+const CS_CONTROLLER_BASE = /^(?:Controller|ControllerBase|ApiController|AsyncController)$/;
+const CS_STRINGISH = /^(?:(?:System\.)?[Ss]tring\??(?:\[\])?|(?:List|IList|IEnumerable|ICollection|IReadOnlyList)<\s*(?:System\.)?[Ss]tring\??\s*>)$/;
+const CS_DI_OPT_OUT = new Set(['FromServices', 'FromKeyedServices']);
+
+/** True when a C# class record (`{ name, bases }`) is one the framework treats as a controller. */
+function isCsControllerClass(range) {
+  if (!range) return false;
+  if (/Controller$/.test(range.name || '')) return true;
+  return (range.bases || []).some((b) => CS_CONTROLLER_BASE.test(b));
+}
+
+/**
+ * Should a C# parameter be treated as implicitly request-bound?
+ * @param {object} o
+ * @param {string} o.modifiers   the method's modifier text (the declaration prefix), e.g. 'public async'
+ * @param {string} o.rawType     the parameter's declared type text, e.g. 'string', 'List<string>'
+ * @param {string[]} o.decorators the parameter's attribute names
+ * @param {boolean} o.nonAction  the method carries [NonAction]
+ * @param {object} o.classRange  the enclosing class record
+ */
+export function isImplicitCsActionParam({ modifiers = '', rawType = '', decorators = [], nonAction = false, classRange = null }) {
+  if (nonAction) return false;
+  if (!isCsControllerClass(classRange)) return false;
+  if (!/\bpublic\b/.test(modifiers) || /\bstatic\b/.test(modifiers)) return false;
+  if (decorators.some((d) => CS_DI_OPT_OUT.has(d))) return false;
+  // An explicit binding attribute is handled by the explicit annotation sources.
+  if (decorators.some((d) => /^From/.test(d))) return false;
+  return CS_STRINGISH.test(String(rawType).trim());
+}
+
+const SPRING_MAPPING = /^(?:RequestMapping|GetMapping|PostMapping|PutMapping|DeleteMapping|PatchMapping)$/;
+const SPRING_DI_OR_BINDING = /^(?:RequestParam|PathVariable|RequestBody|RequestHeader|CookieValue|ModelAttribute|RequestAttribute|SessionAttribute|RequestPart|Value|Autowired)$/;
+
+/**
+ * Should a Java parameter be treated as implicitly request-bound?
+ * @param {string[]} o.methodAnnotations annotation simple names on the method
+ * @param {string} o.paramType   the parameter's simple type name ('String')
+ * @param {string[]} o.decorators annotation names already on the parameter
+ */
+export function isImplicitSpringMappedParam({ methodAnnotations = [], paramType = '', decorators = [] }) {
+  if (!methodAnnotations.some((a) => SPRING_MAPPING.test(a))) return false;
+  if (paramType !== 'String') return false;
+  if (decorators.some((d) => SPRING_DI_OR_BINDING.test(d))) return false;
+  return true;
+}

package/src/ir/parser-cs.js

@@ -45,6 +45,7 @@
 // This is a v1. Promoted to a Roslyn-backed CST parser (analogous to
 // parser-py-cst.js) once we have a dotnet capability probe.
 
+import { IMPLICIT_MVC_PARAM, isImplicitCsActionParam } from './implicit-handler-params.js';
 import * as crypto from 'node:crypto';
 import { callSitesFromCfg } from './call-sites.js';
 import { matchBalancedCall } from './balanced-call.js';
@@ -270,6 +271,16 @@ function _extractClassFields(code, range) {
 // Innermost class whose range contains `pos` (a method declaration's match
 // offset), or null when the method sits outside any class (top-level
 // statements — legal but rare).
+function _enclosingClassRange(ranges, pos) {
+  let best = null;
+  for (const r of ranges) {
+    if (pos >= r.start && pos < r.end) {
+      if (!best || (r.end - r.start) < (best.end - best.start)) best = r;
+    }
+  }
+  return best;
+}
+
 function _enclosingClassName(ranges, pos) {
   let best = null;
   for (const r of ranges) {
@@ -1537,7 +1548,12 @@ export function parseCSharpFile(file, code) {
   while ((m = METHOD_RE.exec(code)) !== null) {
     const name = m[2];
     const className = _enclosingClassName(classRanges, m.index);
+    const classRange = _enclosingClassRange(classRanges, m.index);
     const paramsText = m[3] || '';
+    // [NonAction] sits in the attribute region just before the declaration.
+    // Only the attribute region of THIS member counts: cut at the previous statement or block end.
+    const attrRegion = code.slice(Math.max(0, m.index - 300), m.index + 1);
+    const nonAction = /\bNonAction\b/.test(attrRegion.slice(Math.max(attrRegion.lastIndexOf('}'), attrRegion.lastIndexOf(';')) + 1));
     const paramAnnotations = [];
     const paramTypes = {};
     // `keptIdx` tracks the parameter's position in the FILTERED array — the
@@ -1616,6 +1632,10 @@ export function parseCSharpFile(file, code) {
           paramAnnotations.push({ index: keptIdx, name: paramName, decorator });
         }
         if (paramType) paramTypes[paramName] = paramType;
+        // QA-006: a controller action's plain string parameter is bound from the request with no attribute at all.
+        if (isImplicitCsActionParam({ modifiers: m[0], rawType: nameTokens.filter(w => !/^(?:ref|out|params|in|this)$/.test(w)).join(' '), decorators, nonAction, classRange })) {
+          paramAnnotations.push({ index: keptIdx, name: paramName, decorator: IMPLICIT_MVC_PARAM });
+        }
         keptIdx++;
       }
       return paramName;

package/src/ir/parser-go.js

@@ -34,6 +34,10 @@ const FUNC_RE = new RegExp(
 
 function _splitStatements(body) {
   const out = [];
+  // Index (in `body`) of each statement's first character, so a caller can recover its real line. Blank lines and comment-only
+  // lines yield no statement, so counting statements undercounts lines wherever a function body has either.
+  const starts = [];
+  let bufStart = 0;
   let buf = '';
   let depth = 0;
   let inStr = null;
@@ -57,19 +61,24 @@ function _splitStatements(body) {
     if (c === '`') { inRaw = true; buf += c; continue; }
     if (c === '/' && body[i + 1] === '/') {
       while (i < body.length && body[i] !== '\n') i++;
+      // Leave the newline for the loop to see: swallowing it meant a comment line never ended its statement, so the next line was
+      // glued to whatever came before the comment and its line number was counted from the wrong place.
+      i--;
       continue;
     }
     if (c === '{' || c === '(' || c === '[') depth++;
     if (c === '}' || c === ')' || c === ']') depth--;
     if ((c === '\n' || c === ';') && depth === 0) {
       const t = buf.trim();
-      if (t) out.push(t);
+      if (t) { out.push(t); starts.push(bufStart + (buf.length - buf.trimStart().length)); }
       buf = '';
+      bufStart = i + 1;
       continue;
     }
     buf += c;
   }
-  if (buf.trim()) out.push(buf.trim());
+  if (buf.trim()) { out.push(buf.trim()); starts.push(bufStart + (buf.length - buf.trimStart().length)); }
+  out.lineOffsets = starts.map((idx) => _countNewlinesUpTo(body, idx));
   return out;
 }
 
@@ -399,17 +408,21 @@ function _link(nodes, src, dst) {
   if (!nodes[dst].pred.includes(src)) nodes[dst].pred.push(src);
 }
 
+// `startLine` is the line on which `bodyText` BEGINS (the line of its opening brace); each statement's line is that plus the
+// newlines before the statement, so blank lines and comments inside the body no longer pull later statements upward.
 function _buildCfg(bodyText, nodes, prevId, startLine) {
   const stmts = _splitStatements(bodyText);
   let prev = prevId;
   let line = startLine;
-  for (const stmt of stmts) {
+  for (let si = 0; si < stmts.length; si++) {
+    const stmt = stmts[si];
+    line = startLine + (stmts.lineOffsets ? stmts.lineOffsets[si] : 0);
     const s = stmt.trim();
     if (!s || s.startsWith('//')) { line++; continue; }
 
     // if statement with brace body
-    const ifMatch = s.match(/^if\s+([\s\S]+?)\s*\{([\s\S]*)\}(?:\s*else\s*\{([\s\S]*)\})?\s*$/s) ||
-                    s.match(/^if\s+([\s\S]+?)\s*\{([\s\S]*)\}\s*$/s);
+    const ifMatch = s.match(/^if\s+([\s\S]+?)\s*\{([\s\S]*)\}(?:\s*else\s*\{([\s\S]*)\})?\s*$/sd) ||
+                    s.match(/^if\s+([\s\S]+?)\s*\{([\s\S]*)\}\s*$/sd);
     if (ifMatch) {
       const condText = ifMatch[1].replace(/;[^;]*$/, '').trim();
       const thenBody = ifMatch[2];
@@ -417,10 +430,10 @@ function _buildCfg(bodyText, nodes, prevId, startLine) {
       const ifNode = _addNode(nodes, { kind: 'if', cond: _lowerExpr(condText), line });
       _link(nodes, prev, ifNode);
       const join = _addNode(nodes, { kind: 'noop', line });
-      const thenTail = _buildCfg(thenBody, nodes, ifNode, line + 1);
+      const thenTail = _buildCfg(thenBody, nodes, ifNode, line + _countNewlinesUpTo(s, ifMatch.indices[2][0]));
       _link(nodes, thenTail, join);
       if (elseBody) {
-        const elseTail = _buildCfg(elseBody, nodes, ifNode, line + 1);
+        const elseTail = _buildCfg(elseBody, nodes, ifNode, line + _countNewlinesUpTo(s, ifMatch.indices[3][0]));
         _link(nodes, elseTail, join);
       } else {
         _link(nodes, ifNode, join);
@@ -431,7 +444,7 @@ function _buildCfg(bodyText, nodes, prevId, startLine) {
     }
 
     // for loop with brace body
-    const forMatch = s.match(/^for\s+([\s\S]*?)\s*\{([\s\S]*)\}\s*$/s);
+    const forMatch = s.match(/^for\s+([\s\S]*?)\s*\{([\s\S]*)\}\s*$/sd);
     if (forMatch) {
       const header = _addNode(nodes, { kind: 'loop-header', line });
       _link(nodes, prev, header);
@@ -446,7 +459,7 @@ function _buildCfg(bodyText, nodes, prevId, startLine) {
         _link(nodes, header, assignId);
         bodyPrev = assignId;
       }
-      const bodyTail = _buildCfg(loopBody, nodes, bodyPrev, line + 1);
+      const bodyTail = _buildCfg(loopBody, nodes, bodyPrev, line + _countNewlinesUpTo(s, forMatch.indices[2][0]));
       _link(nodes, bodyTail, header);
       const join = _addNode(nodes, { kind: 'noop', line });
       _link(nodes, header, join);
@@ -476,8 +489,9 @@ function _buildCfg(bodyText, nodes, prevId, startLine) {
         const callId = _addNode(nodes, { kind: 'call', line, callee: closureCall.callee, args: outerArgs });
         _link(nodes, prev, callId);
         const closureOffset = s.indexOf(closure.closureText);
-        const bodyStartLine = closureOffset >= 0
-          ? line + _countNewlinesUpTo(s, closureOffset)
+        const closureBodyIdx = closureOffset >= 0 ? s.indexOf(closure.body, closureOffset) : -1;
+        const bodyStartLine = closureBodyIdx >= 0
+          ? line + _countNewlinesUpTo(s, closureBodyIdx)
           : line;
         prev = _buildCfg(closure.body, nodes, callId, bodyStartLine);
         line += (s.match(/\n/g) || []).length + 1;
@@ -517,11 +531,14 @@ export function parseGoFile(file, code) {
     if (braceIdx < 0) continue;
     const extracted = _extractBody(code, braceIdx);
     if (!extracted) continue;
-    const startLine = _lineAt(code, m.index);
+    // FUNC_RE's leading boundary is a newline and its `\s*` then swallows every blank line before `func`, so m.index can sit
+    // several lines ABOVE the declaration (a blank line before a function is the gofmt norm). Every line below, the function's
+    // own and each statement's, is counted from here, so the keyword's offset is what must be measured.
+    const startLine = _lineAt(code, m.index + Math.max(0, m[0].indexOf('func')));
     const nodes = {};
     const entry = _addNode(nodes, { kind: 'entry', line: startLine });
     const exit = _addNode(nodes, { kind: 'exit', line: startLine });
-    const tail = _buildCfg(extracted.body, nodes, entry, startLine + 1);
+    const tail = _buildCfg(extracted.body, nodes, entry, _lineAt(code, braceIdx + 1));
     _link(nodes, tail, exit);
     const cfg = { entry, exit, nodes };
     functions.push({

package/src/ir/parser-java.js

@@ -23,6 +23,7 @@
 
 import { blankComments } from '../sast/_comment-strip.js';
 import { callSitesFromCfg } from './call-sites.js';
+import { IMPLICIT_SPRING_PARAM, isImplicitSpringMappedParam } from './implicit-handler-params.js';
 
 let _nodeIdSeq = 0;
 function nextNodeId() { return 'jn' + (++_nodeIdSeq); }
@@ -1082,6 +1083,11 @@ export async function parseJavaFile(file, raw) {
             || md.children?.methodDeclarator?.[0]?.children?.formalParameterList?.[0];
           const paramAnnotations = [];
           const paramTypes = {};
+          // QA-006: annotation simple names on the METHOD itself (`@GetMapping`), read from its modifiers.
+          const methodAnnotations = (md.children?.methodModifier || []).map((mm) => {
+            const ids = mm.children?.annotation?.[0]?.children?.typeName?.[0]?.children?.Identifier;
+            return ids?.length ? ids[ids.length - 1]?.image : null;
+          }).filter(Boolean);
           const params = (fpl?.children?.formalParameter || []).map((fp, idx) => {
             // Regular parameters nest under `variableParaRegularParameter`.
             // Varargs (`String... args`) instead use a distinct
@@ -1119,6 +1125,7 @@ export async function parseJavaFile(file, raw) {
             // the first, or a stacked annotation is silently dropped (the
             // same class of bug Task 3's C# regex needed a fix round for).
             const variableModifiers = vp?.children?.variableModifier || [];
+            const ownDecorators = [];
             for (const vm of variableModifiers) {
               const ann = vm.children?.annotation?.[0];
               // `typeName.children.Identifier` is an array of ALL
@@ -1133,9 +1140,13 @@ export async function parseJavaFile(file, raw) {
               const identifiers = ann?.children?.typeName?.[0]?.children?.Identifier;
               const decoratorName = identifiers?.length ? identifiers[identifiers.length - 1]?.image : undefined;
               if (decoratorName && paramName) {
+                ownDecorators.push(decoratorName);
                 paramAnnotations.push({ index: idx, name: paramName, decorator: decoratorName });
               }
             }
+            if (paramName && isImplicitSpringMappedParam({ methodAnnotations, paramType, decorators: ownDecorators })) {
+              paramAnnotations.push({ index: idx, name: paramName, decorator: IMPLICIT_SPRING_PARAM });
+            }
             return paramName;
           }).filter(Boolean);
           const body = md.children?.methodBody?.[0]?.children?.block?.[0];

package/src/language/nix-eval-isolation.js

@@ -148,6 +148,15 @@ const un=net.connect(sock);un.on('connect',()=>{r.daemonSocket='CONNECTED';un.de
 setTimeout(()=>{r.timeout=true;console.log(JSON.stringify(r));process.exit(0)},8000);
 `;
 
+/** server.listen that settles: it resolves when listening and rejects on the server's error (a bare callback never fires on failure). */
+function listenOrReject(server, ...args) {
+  return new Promise((resolve, reject) => {
+    const onError = (e) => reject(e);
+    server.once('error', onError);
+    server.listen(...args, () => { server.off('error', onError); resolve(); });
+  });
+}
+
 /**
  * Prove the isolation of a backend with real attempts, independent of any evaluator flag. The result is
  * `verified` only if the one permitted read worked, the scratch write worked and every other attempt was refused.
@@ -160,12 +169,31 @@ export async function probeSandbox(sb, opts = {}) {
   for (const d of [allowed, scratch, outside]) mkdirSync(d);
   writeFileSync(join(allowed, 'a.txt'), 'allowed'); writeFileSync(join(outside, 'secret.txt'), 'secret');
   const script = join(base, 'probe.cjs'); writeFileSync(script, PROBE_SOURCE);
-  const sockPath = join(base, 'daemon.sock');
+  let sockPath = join(base, 'daemon.sock');
+  let sockDir = null;
   let connections = 0;
   const tcp = netServer((s) => { connections++; s.destroy(); });
-  const uds = netServer((s) => { connections++; s.destroy(); });
-  await new Promise((r) => tcp.listen(0, '127.0.0.1', r));
-  await new Promise((r) => uds.listen(sockPath, r));
+  let uds = netServer((s) => { connections++; s.destroy(); });
+  try {
+    await listenOrReject(tcp, 0, '127.0.0.1');
+    try {
+      await listenOrReject(uds, sockPath);
+    } catch (e) {
+      // A unix socket path is limited to about 104 bytes, and a temporary directory can easily be longer than that (macOS, CI runners).
+      // Without an error handler the listen call never completed and the whole evaluation hung. Retry in a short directory; the probe
+      // proves that the sandboxed process is refused, which does not depend on where the socket lives.
+      if (!['EINVAL', 'ENAMETOOLONG'].includes(e && e.code) || !existsSync('/tmp')) throw e;
+      uds.close();
+      uds = netServer((s) => { connections++; s.destroy(); });
+      sockDir = mkdtempSync('/tmp/nep-');
+      sockPath = join(sockDir, 'd.sock');
+      await listenOrReject(uds, sockPath);
+    }
+  } catch (e) {
+    tcp.close(); uds.close(); rmSync(base, { recursive: true, force: true });
+    if (sockDir) rmSync(sockDir, { recursive: true, force: true });
+    return { verified: false, backend: sb.backend, reason: `the probe could not create its listeners (${(e && e.code) || 'error'}): isolation is not verified`, attempts: {} };
+  }
   const port = tcp.address().port;
   try {
     const exe = opts.nodePath || process.execPath;
@@ -186,7 +214,7 @@ export async function probeSandbox(sb, opts = {}) {
     if (attempts.credentialEnv && attempts.credentialEnv !== 'absent') insufficient.push('a credential environment variable was visible');
     if (attempts.timeout) insufficient.push('the probe timed out');
     return { verified: insufficient.length === 0 && connections === 0, backend: sb.backend, reason: insufficient.length ? insufficient.join('; ') : (connections ? 'the probe listeners saw a connection' : null), attempts, listenerConnections: connections, insufficient };
-  } finally { tcp.close(); uds.close(); rmSync(base, { recursive: true, force: true }); }
+  } finally { tcp.close(); uds.close(); rmSync(base, { recursive: true, force: true }); if (sockDir) rmSync(sockDir, { recursive: true, force: true }); }
 }
 
 // ── 3. evaluator feature detection ───────────────────────────────────────────

package/src/lineage/CLAUDE.md

@@ -1182,6 +1182,37 @@ established operator-config trust model this whole package uses
 everywhere else (a hand-edited config file is trusted as declared, the
 way `recipient-profiles.json`/`privacy-policy.json` already are).
 
+## Deployment boundary graph (differentiation PRD, X-301 to X-308)
+
+`deployment/` is a SEPARATE graph from `DataFlowGraph v1`: it answers "what can reach what, as deployed" (repositories,
+services, routes, identities, tenants, resources, environments), not "where does a data element flow". It shares no mutable
+state with the taint or vulnerability engines. It imports only pure helpers (the assurance schema kit, canonical
+serialization and content hashing from `posture/assurance/`) and three assurance enums (provenance, path state,
+observation completeness), so the verification layer and this graph speak one vocabulary. It is gated by the
+`deployment-boundaries` feature (off by default); only the two file-reading entry points are gated, everything else is a
+pure function of text. Suite: `npm run test:deployment`, with fixtures under `test/deployment/fixtures/`.
+
+| Module | Responsibility |
+|---|---|
+| `deployment/boundary-graph.js` | X-301. The versioned, closed-world contract. Seven node kinds, a relation table giving each relation its legal endpoint kinds, the trust boundary it crosses and its meaning (`RELATION_SEMANTICS`), and `validateBoundaryGraph` (ids are recomputed, a tampered digest or id is refused). **Three provenance types are separate**: `static-config`, `runtime-observation`, `inferred` (part of an edge's id, so a configured and an observed edge between the same nodes are two edges). A path is `possible`, `blocked`, `unresolved` or `runtime-supported`; `blocked` requires an explicit deny and a deny is always blocked; absence never blocks. The edge completeness enum has no `complete` value, so no producer can assert complete traffic coverage. Node ids hash (kind, name, environment, tenant), so two environments or tenants are two nodes; the owning repository is NOT in the id, so a reference and its declaration coincide and two repositories claiming one identity collide detectably. `buildBoundaryGraph` normalizes, merges identical declarations, records conflicts as gaps (conflicting allow becomes `unresolved`, deny kept) and never throws; `exportBoundaryGraph`/`importBoundaryGraph` round-trip byte-identically; `findPath` is a bounded, cycle-safe shortest path (shared with the correlation and cross-repository code, and the base for X-305). |
+| `deployment/adapter-kit.js` | Shared adapter context. Every static edge carries `{file, digest, parser, parserVersion}` and the revision; every declared node carries `declaredBy` file references; an unresolved reference becomes an unresolved node plus a typed gap. YAML is read with the scanner's safe loader (unknown tags refused), more than 100 aliases is refused, JSON with `JSON.parse`; nothing is evaluated. |
+| `deployment/adapter-kubernetes.js`, `adapter-compose.js`, `adapter-cloud.js` | X-302 adapters: Kubernetes (workloads, Service, Ingress, Gateway API HTTPRoute, ServiceAccount, Role/ClusterRole bindings, NetworkPolicy), compose files, Terraform plan JSON (`terraform show -json`, with `configuration` references used to join resources and `after_unknown` honoured) and standalone IAM policy documents. Secrets, ConfigMaps, environment values, env files and images are never read. A selector that matches nothing, a missing ServiceAccount/Role/Service, a value known only after apply, `NotAction`/`NotResource`, a YAML merge key and unknown resource types are typed gaps, never edges. A `<<` merge key is reported, not expanded. |
+| `deployment/ingest.js` | `ingestDeploymentConfig` (pure: text in, graph out; an adapter that throws is contained to that file), `ingestDeploymentFiles` (reads named files under one root, refusing traversal, absolute paths, symlinks and oversize files; feature gated), `detectFormat` (HCL, proxy configuration and TOML/XML are typed unsupported syntax) and `invalidateChangedSources` (drops the relations a changed or removed file supported, using the recorded digests; a node only that file declared stops being resolved or is dropped). |
+| `deployment/trace-correlation.js` | X-303. `importTraceLines` keeps an allowlist of topology metadata and removes every other field WITHOUT storing it, even its name (only counts, split credential-shaped, payload-shaped and other); strips query strings; turns opaque path segments into `:id`; rejects a record whose kept value is not identifier-shaped; refuses other-environment records instead of relabelling them; merges duplicates; and is bounded (bytes, line length, lines, distinct observations with oldest-first eviction reported). `correlateObservations` matches with numbered rules R1 to R4 (exact service pair, route chain, identity, naming convention); R4 yields an `inferred` edge, R1 to R3 a `runtime-observation` edge, and static edges are never edited. `coverage.trafficCoverage` is always `not-established`; observed, sampled, stale and missing are separate lists; a static edge with no observation stays `possible`. `applyCorrelation` folds the result into a new validated graph. It does NOT persist anything: callers store `exportObservationSet` output and read it back with `parseObservationSet` (closed world, bounded, digest-checked). This sits beside, not on top of, the existing data-flow `runtime-observation.js` records, whose graph-id oriented contract is unchanged; only `EVENT_COUNT_BANDS` is shared. |
+| `deployment/cross-repo.js` | X-304. `resolveCrossRepoBoundaries` takes graph exports the operator supplies, declared dependencies (each binding an exact 40/64 hex revision for both ends) and an access scope; it has no network or file access (a test pins its import list). A link resolves only when both repositories are in scope and supplied, each graph validates and names the repository it was supplied as, the graph revision equals the bound revision, the declared service exists resolved in its repository and in no other supplied repository, and a declared entry route reaches it. Every failure is a typed gap (`access-denied`, `repository-unavailable`, `version-mismatch`, `revision-unknown`, `identity-collision`, `unresolved-identity`, `graph-integrity`, `malformed-input`) and the dependency is kept as an unresolved edge to an unresolved callee. A resolved link carries evidence (declaration file and digest, both graph digests, the declaring files on each side, the route chain) and transitions (entry route, caller identities, callee identity and its grants, boundary crossings). It extends the idea of `cross-repo-link.js` to this graph; that module and `federation-loader.js` are unchanged. |
+| `deployment/attack-paths.js` | X-305. `computeAttackPaths` walks bounded, cycle-safe simple paths from entry points (resolved public routes and services) to targets (resources an identity is granted, or in the privileged zone) over `routes-to`, `calls`, `depends-on`, `network-allows`, `assumes` and `grants`. A hop is `blocked` only when an explicit deny edge sits between its endpoints; a path is `blocked` if any hop is, `unresolved` if a hop or endpoint is unresolved or a tenant transition makes it CONDITIONAL (a hop whose endpoints carry different tenants, listed as a `tenant-binding` condition), `runtime-supported` only if every network hop was observed (identity hops stay configuration), else `possible`. Each path lists supporting edges (with source file, digest, revision), assumptions, blockers, environments, boundary crossings and a coverage block (observed, sampled, stale, unobserved hops; `trafficCoverage` is always `not-established`; staleness is judged only when the caller passes `now`). Path ids hash the edge ids along the path, not the state, so they survive reordering and state changes. `bindFindingToService` ties a finding to a service ONLY through an explicit path-prefix binding (longest prefix wins; a tie, an absent service or no binding is a typed non-bound status and nothing is guessed). `analyzeFindingBoundaries` builds the per-finding `boundary-context` (exposure paths to the bound service, impact paths onward, verification assessments, uncovered boundaries, warnings). **Exploitability is never derived from reachability**: `assessVerification` accepts a record only if it validates, its outcome is `confirmed`, its confirmation level RECOMPUTED from evidence is `runtime-confirmed`, and its oracle is the one the finding's non-taint class names (an unsupported class has none); the label is `exploitable-confirmed` only then, and a blocked or unresolved path keeps that fact in an `oracle-confirmed-path-*` label. `exposureReach` is the path-free reachability the drift diff compares. |
+| `deployment/drift.js` | X-306. `diffBoundaryGraphs` compares two validated graphs of one repository at stable ids: new exposure (newly reachable from an entry, by reachability not by edge), changed privilege (new or changed grant, new identity assumption), tenant weakening (a dropped tenant binding, found by (kind, name, environment) because the tenant is part of the node id, or a new cross-tenant edge) and removed controls (a removed deny) are `material`; other relation changes are reported but not material. It also diffs the SOURCES and names the edges each moved file supported. `planRescan` maps changes to hypotheses through the bound service: a hypothesis is affected when its service is a seed of a change or can reach or be reached from one (union of both revisions, bounded closure); everything else is `skipped` with a reason and NOT rescanned. A hypothesis that cannot be tied to a service cannot be proven independent, so it makes the plan `incomplete` (only when something changed), as does a graph gap that stands for a missing dependency (`DEPENDENCY_GAP_CODES`). `incrementalAnnotate` recomputes only the planned hypotheses; `compareScoped` checks the result against a complete recomputation on `scopedSignature` (which leaves out graph-wide metadata) and never reports an incomplete result as equivalent. `invalidatePathsForSources` reuses `invalidateChangedSources` and drops exactly the paths whose supporting edges or node declarations cite a changed file. |
+| `deployment/projection.js` | X-307. The ONE projection of a boundary context, modelled on `posture/verification/projection.js`: `projectBoundaryContext` (closed-world validation first: an unknown field, a credential-shaped or payload-shaped string, a control character or an over-long string refuses the whole context), `filterBoundaryView` (service, repository, environment, tenant; keeps scope, uncovered boundaries and every earlier warning and adds a warning saying how many paths it hid), `boundaryFields` (the additive report fields; the context itself is echoed only when it validated), `boundaryCoverage` (run accounting) and `attachBoundaryContext`, the ONLY producer, gated by the `deployment-boundaries` feature (off returns the same findings array untouched). The text states what was and was not established, never says safe, protected or unreachable (a lint-style test sweeps every state), and a context with no path says "not shown to exist". Consumed by `report/index.js` (`normalizeFindings` adds `boundaryContext` and `boundaryView` only when a finding carries a context, a top-level `boundaryCoverage`, a Markdown and a terminal block) and by MCP `explain_finding`. Previous output schemas are pinned in `test/fixtures/boundary-compat/` (captured before the wiring). |
+| `deployment/boundaries-run.js` | X-308 wiring. The one operator entry point: `agentic-security boundaries --from <dir> [--findings <last-scan.json>] [--environment] [--repository] [--revision] [--root] [--out] [--json] [--now]`. `runBoundaries` (gated by `deployment-boundaries`, off by default; off returns a typed `disabled` BEFORE any file is opened) lists configuration files under the directory (bounded walk, symlinks never followed or listed), reads the reserved inputs `service-bindings.json`, `identities.json` and `traces.jsonl`/`traces.ndjson` (never ingested as configuration), ingests through `ingestDeploymentFiles`, correlates sanitized traces, reads findings from a scan result (a sibling `.sig` that exists must verify, else exit 1; an absent one is read and labelled unsigned) or from memory, and attaches contexts with `attachBoundaryContext`. Local files only, no scan, no execution; the only write is `--out`, refused when the target is a symbolic link. Exit codes: 0 report, 1 failed, 2 usage, 3 feature off, blocked or unsupported. `renderBoundariesText` reuses each context's own projected text. Suite: `test/deployment/boundaries-cli.test.js`. |
+
+**Disclosed limits.** Kubernetes `matchExpressions`, namespace-only selectors and ExternalName targets are not evaluated
+(reported as gaps). Terraform modules other than the root are joined only through the plan's flat `resource_changes`.
+IAM conditions are not interpreted (a conditioned statement is recorded at low confidence with `conditioned: true`).
+The digest of an ingested file is over the UTF-8 text that was parsed. Observation persistence is not wired. The presentation (X-307) is consumed by the report and MCP `explain_finding` only when a finding carries a
+`boundaryContext`; nothing in the default scan produces one. `attachBoundaryContext` is a feature-gated helper; its one operator entry point is
+`agentic-security boundaries` (`boundaries-run.js`, explicit, read-only, off by default), so default output is unchanged. The boundary graph attribute grammar admits credential-shaped values such as `password=x` (it only
+restricts characters); the projection refuses them, but the graph contract itself does not.
+
 ## Conventions
 
 - Every enum here is a single source of truth for its concept. If you add