@clear-capabilities/agentic-security-scanner 0.188.0 → 0.189.0

package/src/language/haskell-reachability.js

@@ -0,0 +1,84 @@
+// Project-reachability adjudication of Haskell taint findings.
+//
+// `haskell-ir.js` `projectReachability` stamps every function with `hs.reachability {status, rootKind, holeReason}`: could any caller exist, judged from
+// the project's entry points over the call graph? This module reads that verdict for the function a taint finding was found in and records it on the
+// finding as `reachability {status, reason, premise, roots, holeReason}`. It is a SEPARATE record from `trustBoundary`: that one answers who controls
+// the input, this one answers whether a caller can exist, and either may be `unknown` independently.
+//
+//   status        entrypoint-reachable | unreachable-in-project | external-api | unknown
+//   premise       what the finding's own claim rests on:
+//                   caller-controlled-parameter   the only origin recorded is the assumption that an untrusted caller supplies a parameter of
+//                                                 an exported function (the weak label, `hs:caller-controlled`)
+//                   recorded-read                 a real environment, command-line, file, standard-input, socket or request read is on the chain
+//
+// What the verdict does to the finding:
+//   unreachable-in-project and premise caller-controlled-parameter   the premise is withdrawn (an entry-point-rooted walk over a hole-free graph says
+//                                                 there is no caller at all): lowered to `info`, never dropped (`lowerFinding`, `_reachLowered`)
+//   unreachable-in-project and premise recorded-read   NOT lowered. "Nothing calls this" is a claim about a call graph in a language where typeclass
+//                                                 dispatch, re-exports and point-free aliasing routinely defeat call graphs; being wrong costs a real
+//                                                 vulnerability, so it may cost rank (`posture/relevance.js` reads `f.reachability`) and not visibility
+//   unknown, external-api, entrypoint-reachable   nothing happens to the severity
+//
+// Nothing here reads a comment, a name or a path: the inputs are the call-graph verdict and the origins the taint engine recorded.
+
+import { lowerFinding, originClasses } from './haskell-trust.js';
+
+const HS_FILE = /\.(?:l?hs|hsc)$/i;
+
+const fnByQid = (perFile, qid) => {
+  if (!qid) return null;
+  const file = String(qid).split('::')[0];
+  const ir = perFile && perFile[file];
+  return ir ? ir.functions.find((x) => x.qid === qid) || null : null;
+};
+
+const REASONS = Object.freeze({
+  'entrypoint-reachable': 'a call path from a project entry point reaches the function',
+  'external-api': 'the function belongs to a module the package exposes, so its callers are outside the analysed code',
+  'unreachable-in-project': 'no entry point of the project reaches the function through the call graph (complete scan, hole-free graph, a main and a manifest present, module not exposed)',
+});
+const HOLE_TEXT = Object.freeze({
+  'partial-scan': 'the scan covered only part of the project',
+  'policy-excluded': 'Haskell sources were kept out of the scan by the path policy',
+  'size-skipped': 'Haskell sources were too large to read',
+  'no-entrypoint': 'the analysed files contain no `main`, so there is no entry point to walk from',
+  'no-manifest': 'no manifest says which modules the package exposes',
+  'parse-failure': 'a declaration could not be read, so its calls are missing from the graph',
+  'function-cap': 'functions past the per-file cap are not in the graph',
+  'opaque-boundary': 'Template Haskell, a quasi-quote, a foreign export, a build step that generates code or a source format the IR does not read can call functions the graph does not show',
+  'unresolved-call': 'a function reachable from an entry point makes a call the IR could not resolve',
+  'instance-method': 'an instance method can be invoked by anything that can see its type',
+  'unresolved-route': 'a route registration could not be resolved',
+});
+
+/** What the finding's own claim rests on (see the header). `null` when the recorded origins do not settle it. */
+function premiseOf(f) {
+  const { roots, classes } = originClasses(f);
+  if (!roots.length) return null;
+  if ([...classes].every((c) => c === 'weak-param')) return 'caller-controlled-parameter';
+  if ([...classes].some((c) => c === 'operator' || c === 'external' || c === 'data')) return 'recorded-read';
+  return null;
+}
+
+/**
+ * Stamps `reachability` on every Haskell IR-TAINT finding that has a verdict for its function, and lowers to `info` the ones whose only premise
+ * (a caller-controlled parameter) the verdict withdraws. Mutates the findings; returns counts.
+ */
+export function applyHaskellReachability(findings, perFile) {
+  const stats = { 'entrypoint-reachable': 0, 'unreachable-in-project': 0, 'external-api': 0, unknown: 0, lowered: 0, rankOnly: 0, unstamped: 0 };
+  for (const f of findings || []) {
+    if (!f || f.parser !== 'IR-TAINT' || !HS_FILE.test(String(f.file || ''))) continue;
+    const fn = fnByQid(perFile, f._funcQid);
+    const r = fn && fn.hs && fn.hs.reachability;
+    if (!r || !r.status) { stats.unstamped++; continue; }
+    const premise = premiseOf(f);
+    const reason = r.status === 'unknown' ? (HOLE_TEXT[r.holeReason] || 'the call graph cannot settle it') : REASONS[r.status];
+    f.reachability = { status: r.status, reason, premise, roots: r.rootKind ? [r.rootKind] : [], holeReason: r.holeReason || null };
+    stats[r.status] = (stats[r.status] || 0) + 1;
+    if (r.status !== 'unreachable-in-project') continue;
+    if (premise === 'caller-controlled-parameter') {
+      if (lowerFinding(f, { kind: 'unreachable-in-project', reason: 'the finding rests on a caller of an exported function supplying a parameter, and nothing in the project can call it', controlKind: 'no-caller-in-project', guard: '_reachLowered', keepNote: true })) stats.lowered++;
+    } else if (premise === 'recorded-read') stats.rankOnly++;
+  }
+  return stats;
+}

package/src/language/haskell-security-rules.js

@@ -162,6 +162,26 @@ function snippetOf(text, line) {
 // socket or connection handle is filled by the peer. A read of standard input is the operator's in a program's own control flow, and
 // the caller's only in an entry point nothing in the analysed code calls (a library function handing back whatever its caller pipes in).
 const NETWORK_HANDLE_CALL = /(?:^|\.)(?:socketToHandle|connectTo|accept|acceptOn|openTCPConnection)$/;
+
+/**
+ * Are this function's callers outside the analysed code? With no project-reachability verdict, or an `unknown` one, the answer is exactly what it
+ * has always been (nothing in the analysed code calls or references it). A function no caller can reach (`unreachable-in-project`) has none. One
+ * reached from an entry point takes its parameters from that path, EXCEPT a root nothing in the analysed code calls (a framework handler, a foreign
+ * export, code the parser withheld): its caller is outside.
+ *
+ * A function of an exposed module (`external-api`) is DELIBERATELY answered as today: the plan for this change said "a public API's callers are
+ * external, so true", but for an exposed function that something in the project also calls that turns on the partial-function and unbounded-read
+ * rules for every such function, and on the development set it added seven flagged sites and no true positive (precision 35.7% -> 23.8%). The
+ * status is still recorded and still keeps the taint finding at full severity; it just does not widen these two rules. Flipping it is the one line
+ * below, with that measurement as the cost.
+ */
+export function callersUnknown(fn) {
+  const hs = (fn && fn.hs) || {};
+  const r = hs.reachability || null;
+  if (!r || r.status === 'unknown' || r.status === 'external-api') return !hs.reached;
+  if (r.status === 'entrypoint-reachable') return !hs.reached && r.rootKind !== 'main';
+  return false;
+}
 function readsOutsideInput(fn, callee, args, importsNetwork) {
   const h = args && args[0];
   const isStdin = !!h && h.kind === 'ident' && /(?:^|\.)stdin$/.test(h.name || '');
@@ -169,7 +189,7 @@ function readsOutsideInput(fn, callee, args, importsNetwork) {
   // the networking packages are not all in the model registry, so a call keeps its bare name; the module imports say which library it is
   if (handleRead) return !!importsNetwork && (fn.calls || []).some((x) => typeof x.callee === 'string' && NETWORK_HANDLE_CALL.test(x.callee));
   const hs = fn.hs || {};
-  return !hs.reached && !/(?:^|\.)main$/.test(fn.name || '');
+  return callersUnknown(fn) && !/(?:^|\.)main$/.test(fn.name || '');
 }
 
 const EQUALITY_OPS = new Set(['==', '/=', '!=']);
@@ -244,7 +264,7 @@ export function analyzeHaskellRules(files, opts = {}) {
   const notes = [];
   if (!Object.keys(hs).length) return { findings, controls, notes };
 
-  const ir = buildHaskellIR(hs);
+  const ir = buildHaskellIR(hs, opts.reachability || {});
 
   // project-level facts
   let requestLimit = null;
@@ -291,7 +311,7 @@ export function analyzeHaskellRules(files, opts = {}) {
       // calls cannot say the text comes from outside.
       const fnHs = fn.hs || {};
       const strongParam = new Set((fnHs.paramSources || []).filter((p) => /^hs:handler-param:/.test(p.decorator || '')).map((p) => p.name));
-      const entryLike = !fnHs.reached;
+      const entryLike = callersUnknown(fn);
       const derivedText = new Set([...(fnHs.textParams || []).filter((n) => strongParam.has(n) || entryLike), ...(entryLike ? (fnHs.inputParams || []) : [])]);
       if (derivedText.size) {
         for (let round = 0; round < 8; round++) {

package/src/language/haskell-syntax.js

@@ -840,7 +840,8 @@ export function parseSyntax(src, opts = {}) {
           // `foreign import ccall unsafe "string.h strlen" c_strlen :: ...` names the Haskell-side function.
           let fname = null;
           for (let q = a; q < b; q++) if (isRop(T[q], '::')) { if (q > a && T[q - 1].t === 'var') fname = T[q - 1].v; break; }
-          res.boundaries.push({ kind: 'ffi', line: t0.line, detail: 'foreign declaration; the foreign code is not analyzed', ...(fname ? { name: fname } : {}) });
+          const dir = T[a + 1] && (T[a + 1].v === 'import' || T[a + 1].v === 'export') ? T[a + 1].v : null;
+          res.boundaries.push({ kind: 'ffi', line: t0.line, detail: 'foreign declaration; the foreign code is not analyzed', ...(dir ? { direction: dir } : {}), ...(fname ? { name: fname } : {}) });
           continue;
         }
         if (t0.v === 'class' || t0.v === 'instance') {

package/src/language/haskell-trust.js

@@ -217,6 +217,28 @@ function findCallsTo(fn, target) {
   return out;
 }
 
+/**
+ * Lower a finding to `info` and say why, without dropping it: the severity it would have had is kept (`originalSeverity`), a control records the
+ * reason (`controls`), and `guardNote` is set (with `keepNote`, only when no earlier pass set one). Idempotent per `guard` (a finding is lowered once by each reason), and two
+ * reasons compose: the second finds the severity already `info`, keeps the original severity the first recorded, and adds its own control.
+ * Used by the trust-boundary pass (`_trustLowered`) and the reachability pass (`_reachLowered`).
+ */
+export function lowerFinding(f, { kind, reason, controlKind, guard, keepNote = false }) {
+  if (!f || !guard || f[guard]) return false;
+  f[guard] = true;
+  f.originalSeverity = f.originalSeverity || f.severity;
+  f.severity = 'info';
+  f.controls = [...(f.controls || []), { kind: controlKind, evidenceKind: 'source' }];
+  if (!keepNote || !f.guardNote) f.guardNote = { kind, reason };
+  return true;
+}
+
+/** The classes of origin a finding's recorded roots fall in (`operator`, `external`, `data`, `weak-param`, `other`), and the roots themselves. */
+export function originClasses(f) {
+  const roots = rootsOf(f);
+  return { roots, classes: new Set(roots.map(classOf)) };
+}
+
 /**
  * Stamps `trustBoundary` on every Haskell IR-TAINT finding and lowers to `info` the verdicts that name no boundary crossed
  * (`operator-controlled`, `api-contract`). Mutates the findings; returns counts.
@@ -256,12 +278,8 @@ export function applyTrustBoundary(findings, perFile) {
     f.trustBoundary = { verdict, reason, role, ...(inferred ? { inferred: true } : {}), roots: roots.slice(0, 5) };
     const key = verdict.replace(/-(\w)/g, (_, c) => c.toUpperCase());
     stats[key] = (stats[key] || 0) + 1;
-    if ((verdict === 'operator-controlled' || verdict === 'api-contract') && !f._trustLowered) {
-      f._trustLowered = true;
-      f.originalSeverity = f.originalSeverity || f.severity;
-      f.severity = 'info';
-      f.controls = [...(f.controls || []), { kind: verdict === 'operator-controlled' ? 'operator-controlled-input' : 'api-contract-wrapper', evidenceKind: 'source' }];
-      f.guardNote = { kind: verdict, reason };
+    if (verdict === 'operator-controlled' || verdict === 'api-contract') {
+      lowerFinding(f, { kind: verdict, reason, controlKind: verdict === 'operator-controlled' ? 'operator-controlled-input' : 'api-contract-wrapper', guard: '_trustLowered' });
     }
   }
   return stats;

package/src/language/haskell-web.js

@@ -83,9 +83,9 @@ const strLit = (e) => { e = unparen(e); return e && e.t === 'lit' && e.kind ===
 
 // ── analysis context ─────────────────────────────────────────────────────────
 class Ctx {
-  constructor(files) {
+  constructor(files, reachability) {
     this.files = files;
-    this.ir = buildHaskellIR(files);
+    this.ir = buildHaskellIR(files, reachability || {});
     this.project = this.ir.project;
     this.modules = [...this.ir.modules.values()];
     this.fnByQid = new Map();
@@ -837,7 +837,7 @@ export function analyzeHaskellWeb(files, opts = {}) {
   for (const [f, t] of Object.entries(files || {})) if (/\.hs$/i.test(f) && typeof t === 'string') hs[f] = t;
   const result = { routes: [], findings: [], middleware: [], frameworks: [], coverage: {}, gaps: [], modelVersion: HS_WEB_MODEL_VERSION, rulesetVersion: HS_WEB_RULES_VERSION, versionStatus: {} };
   if (!Object.keys(hs).length) return result;
-  const ctx = new Ctx(hs);
+  const ctx = new Ctx(hs, opts.reachability);
   const pending = [];
   const add = (r) => pending.push(r);
 

package/src/posture/proof-fabric/container.js

@@ -11,8 +11,19 @@
 // The container is named, and removed (`rm -f`) on every exit path including timeout and cancellation, because killing the `docker`
 // client does not by itself stop the container.
 //
-// HONEST LIMIT: this has been exercised against a fake engine that records the arguments and runs the command locally, which proves
-// the plumbing and the flags. It has not been run against a real Docker or Podman daemon in this repository's test environment.
+// WHAT HAS AND HAS NOT BEEN RUN. The arguments are pinned flag by flag against a fake engine that records them. Against a REAL engine it has
+// run: bench/proof-fabric/RESULT-linux-container.json records 72 container runs (36 vulnerable reproducers confirmed, 0 false confirmations, the
+// timeouts degraded as designed) on Docker 28.0.4 on a Linux x64 runner, over the gcc, eclipse-temurin:21, node:24-slim and python:3-slim images
+// (the Temurin run is what found the `javac: not found` PATH problem above), and the `proof-container` CI job runs it on every change. The
+// residual limits, none of them closed by that run:
+//   * ONE engine and ONE version on ONE host class. Other Docker versions, rootless Docker and other kernels are unmeasured.
+//   * Podman is not probed: it is a supported engine name, and no run against it exists.
+//   * macOS is unmeasured. Docker Desktop runs containers in a VM, so bind mounts, uids and file ownership behave differently from the Linux
+//     measurement; no macOS container run has been recorded.
+//   * The haskell:9 image is wired (CONTAINER_TOOLS, CONTAINER_PATH) but its toolchain layout for a non-root user was never run against a real
+//     engine; the measurement skips Haskell unless AGENTIC_SECURITY_PROOF_CONTAINER_HASKELL=1 (bench/proof-fabric/measure.mjs). The result file
+//     names no .NET image either, so the dotnet SDK image is unverified in the same way.
+//   * A reproducer that needs the loopback callback listener (SSRF) cannot run with `--network none` and is skipped, not measured.
 import { spawnSync } from 'node:child_process';
 import { superviseSpawn } from '../../sandbox/supervise.js';
 import { scrubEnv } from '../../sandbox/trust-domains.js';

package/src/posture/relevance.js

@@ -262,6 +262,21 @@ function _threatBonus(f, threatModel, factors) {
   return bonus;
 }
 
+// A language that reasons about its own call graph (Haskell: `language/haskell-reachability.js`) states `f.reachability = {status, reason, premise,
+// roots, holeReason}`. That verdict is a statement about the FUNCTION, from the project's entry points, so it outranks this module's file-level
+// import graph, which has no Haskell extraction. Only a POSITIVE verdict moves the tier; `unknown` (and any finding without one) falls through
+// to the file-level logic unchanged. It re-ranks only: severity is never touched here (a lowering, where one is justified, is the language
+// pass's own decision and is recorded on the finding).
+const LANGUAGE_STATUSES = new Set(['entrypoint-reachable', 'unreachable-in-project', 'external-api', 'unknown']);
+function languageVerdict(f) {
+  const r = f && f.reachability;
+  if (!r || typeof r !== 'object' || !LANGUAGE_STATUSES.has(r.status) || !Object.hasOwn(r, 'holeReason')) return null;
+  if (r.status === 'unreachable-in-project') return { tier: 'unreachable', reachable: false, factor: `no call path from any entry point of the project (${r.reason || 'call graph complete'})` };
+  if (r.status === 'entrypoint-reachable') return { tier: 'indirect', reachable: true, factor: 'reachable from a project entry point through the call graph' };
+  if (r.status === 'external-api') return { tier: 'indirect', reachable: true, factor: 'part of the package\'s exposed API: its callers are outside the analysed code' };
+  return null;
+}
+
 /**
  * Pure scorer. Does NOT mutate the finding.
  *
@@ -280,7 +295,12 @@ function scoreRelevance(f, graph, threatModel) {
 
   let tier;
   let reachable;
-  if (!file || entryFiles.size === 0) {
+  const lang = languageVerdict(f);
+  if (lang && !(lang.tier === 'indirect' && file && entryFiles.has(file))) {
+    tier = lang.tier;
+    reachable = lang.reachable;
+    factors.push(lang.factor);
+  } else if (!file || entryFiles.size === 0) {
     tier = 'unknown';
     reachable = null;
     factors.push(entryFiles.size === 0