@clear-capabilities/agentic-security-scanner 0.184.0 → 0.186.1

package/src/lineage/nix-view.js

@@ -18,6 +18,7 @@ import * as ids from './ids.js';
 import { classifyDataElementName } from './classification.js';
 import { analyzeNixSecrets } from '../language/nix-secrets.js';
 import { analyzeNixPersonalData, destinationOf } from '../language/nix-privacy.js';
+import { analyzeNixScripts } from '../language/nix-script-taint.js';
 
 export const NIX_VIEW_VERSION = 'nix-lineage/1';
 
@@ -196,3 +197,37 @@ export function contributeNixConfigLineage(graph, files, opts = {}) {
   }
   return result;
 }
+
+// ── DAG-08: configuration and generated-script scope carried through links ─────────────────────────────────────────────────
+// A Nix value that reaches a generated script is STATIC CONFIGURATION evidence. It carries both the original Nix location and the
+// generated-script location, and it stays that way when a cross-repo link or a boundary contract refers to it. It does not become
+// an application-runtime value by name, by shared attribute or by being declared: only an explicit binding that a verifier has
+// checked (a named verifier and an application site) lets a record say the value enters application runtime.
+export const NIX_SCOPE = Object.freeze({ language: 'nix', kind: 'configuration', scope: 'static-configuration', runtime: false });
+
+/** Script-level Nix findings as scope records that keep the original and the generated location side by side. */
+export function nixGeneratedScriptScopes(files) {
+  const r = analyzeNixScripts({ files });
+  return (r.findings || []).filter((f) => f.originalLocation).map((f) => ({
+    rule: f.rule, attrPath: f.attrPath || null, file: f.file,
+    originalLocation: { file: f.file, line: f.originalLocation.startLine, column: f.originalLocation.startColumn },
+    generatedLocation: f.generatedLocation ? { generated: true, line: f.generatedLocation.line, column: f.generatedLocation.startColumn } : null,
+    origins: (f.origins || []).map((o) => ({ kind: o.kind, detail: o.detail })),
+    scope: NIX_SCOPE, application: { entersRuntime: false, binding: null, observed: false },
+  }));
+}
+
+/**
+ * Decide whether a Nix scope record may claim to enter application runtime. It may only with an explicit binding that names the
+ * application site (file, function) and a verifier (`verified: true` plus `verifiedBy`). Anything less keeps the static-configuration
+ * scope and says why. A matching name is never a binding, and even a verified binding is a declaration, never an observation.
+ */
+export function bindNixValueToApplication(record, binding) {
+  const base = { ...record, scope: NIX_SCOPE };
+  const ok = binding && binding.verified === true && typeof binding.verifiedBy === 'string' && binding.verifiedBy.length > 0
+    && binding.site && typeof binding.site.file === 'string' && typeof binding.site.function === 'string';
+  if (!ok) {
+    return { ...base, application: { entersRuntime: false, binding: null, observed: false, reason: binding ? 'binding is not explicit and verified (needs verified: true, verifiedBy and an application site)' : 'no binding declared; the value is static configuration only' } };
+  }
+  return { ...base, application: { entersRuntime: true, binding: { site: { file: binding.site.file, function: binding.site.function }, verifiedBy: binding.verifiedBy }, observed: false, reason: 'explicit verified binding; this is a declaration, not an observed runtime flow' } };
+}

package/src/lineage/owned-build.js

@@ -0,0 +1,77 @@
+// owned-build.js: run the lineage graph build under an owned worker with a
+// deadline and a watchdog (DAG-07 R07.7).
+//
+// The in-process build (index.js buildLineageGraph) is unchanged and remains
+// the default. This module is the opt-in path: it sends the file contents to a
+// worker thread this module owns, which rebuilds the IR and call graph and runs
+// the same buildLineageGraph with a cooperative stop signal. Two outcomes:
+//   - the field analysis polls the stop flag, finishes the function it is in and
+//     returns a graph whose scanHealth.status is 'cancelled' (cooperative);
+//   - a worker that never polls (or is stuck in a phase that cannot be stopped,
+//     such as parsing) is terminated by the watchdog `ackGraceMs` after the
+//     deadline, and the result is {status:'cancelled', terminatedByWatchdog}.
+// Either way the caller is released and the worker thread is gone
+// (`exited` resolves when it is).
+//
+// Enabled by opts.deadlineMs or AGENTIC_SECURITY_LINEAGE_DEADLINE_MS. Not set
+// means not used, and nothing about the default path changes.
+
+import { fileURLToPath } from 'node:url';
+import { runOwnedWorker } from './owned-worker.js';
+import { buildLineageGraph } from './index.js';
+import { buildProjectIR, buildProjectIRAsync } from '../ir/index.js';
+
+const SELF = fileURLToPath(import.meta.url);
+
+/** Resolve the configured deadline in ms, or null when the owned path is off. */
+export function resolveLineageDeadlineMs(opts = {}, env = process.env) {
+  const raw = opts.deadlineMs !== undefined ? opts.deadlineMs : env.AGENTIC_SECURITY_LINEAGE_DEADLINE_MS;
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+/**
+ * Worker body. Called as fn(spec, { shouldStop }) by owned-worker-entry.js.
+ * `spec.opts` must be structured-cloneable (no functions).
+ */
+export async function lineageWorkerBody(spec, ctl) {
+  const fc = spec.fileContents || {};
+  const hasJava = Object.keys(fc).some((f) => /\.java$/i.test(f));
+  const { perFile, callGraph } = hasJava ? await buildProjectIRAsync(fc) : buildProjectIR(fc);
+  const signal = { get aborted() { return !!(ctl && ctl.shouldStop && ctl.shouldStop()); } };
+  return buildLineageGraph(callGraph, { ...(spec.opts || {}), perFile, fileContents: fc, signal });
+}
+
+/**
+ * @param {Object<string,string>} fileContents
+ * @param {object} [opts] buildLineageGraph options that survive structured clone,
+ *   plus deadlineMs, ackGraceMs, signal (AbortSignal), and the test seam `worker`
+ *   ({modulePath, exportName}) which replaces the worker body.
+ * @returns {{done:Promise<object>, exited:Promise<void>}} done resolves to the
+ *   buildLineageGraph result shape, plus `cancelled` and, when the watchdog ended
+ *   the worker, `terminatedByWatchdog` with status 'cancelled' and graph null.
+ */
+export function buildLineageGraphOwned(fileContents, opts = {}) {
+  const t0 = Date.now();
+  // onProgress and perFile cannot cross the thread boundary; the worker rebuilds the IR.
+  // eslint-disable-next-line no-unused-vars
+  const { deadlineMs, ackGraceMs, signal, worker, onProgress, perFile, ...rest } = opts;
+  const timeoutMs = resolveLineageDeadlineMs({ deadlineMs });
+  const spec = worker || { modulePath: SELF, exportName: 'lineageWorkerBody' };
+  const run = runOwnedWorker(
+    { ...spec, args: [{ fileContents, opts: rest }] },
+    { signal, timeoutMs: timeoutMs || undefined, ackGraceMs },
+  );
+  const done = run.done.then((r) => {
+    if (r.ok) return { ...r.result, cancelled: !!r.cancelled, elapsedMs: Date.now() - t0 };
+    if (r.status === 'cancelled') {
+      return {
+        status: 'cancelled', graph: null, transitEvidence: new Map(),
+        failure: `lineage build cancelled (${r.reason}); worker terminated by watchdog`,
+        cancelled: true, terminatedByWatchdog: true, ackMs: r.ackMs, elapsedMs: Date.now() - t0,
+      };
+    }
+    return { status: 'failed', graph: null, transitEvidence: new Map(), failure: r.error, cancelled: false, elapsedMs: Date.now() - t0 };
+  });
+  return { done, exited: run.exited };
+}

package/src/lineage/owned-worker-entry.js

@@ -0,0 +1,22 @@
+// Worker entry for owned-worker.js (DAG-07 R07.7). Same shape as
+// pipeline/analyzer-worker.js, plus a shared cancellation flag the work can
+// poll even from inside a synchronous loop (a posted message could not be
+// delivered to a busy thread). The export is called as
+// fn(...args, { shouldStop }).
+import { parentPort, workerData } from 'node:worker_threads';
+
+async function run() {
+  const flag = new Int32Array(workerData.flag);
+  const shouldStop = () => Atomics.load(flag, 0) === 1;
+  try {
+    const { modulePath, exportName, args } = workerData;
+    const mod = await import(modulePath);
+    const fn = mod[exportName];
+    if (typeof fn !== 'function') throw new Error(`export "${exportName}" is not a function in ${modulePath}`);
+    const result = await fn(...(args || []), { shouldStop });
+    parentPort.postMessage({ ok: true, cancelled: shouldStop(), result });
+  } catch (e) {
+    parentPort.postMessage({ ok: false, error: String((e && e.message) || e) });
+  }
+}
+run();

package/src/lineage/owned-worker.js

@@ -0,0 +1,95 @@
+// owned-worker.js: run bounded work in a worker thread this module owns, with
+// cooperative cancellation and a watchdog (DAG-07 R07.7).
+//
+// Follows the existing worker convention (pipeline/analyzer-supervisor.js:
+// worker_threads, Worker.terminate() as the only preemptive tool) and adds
+// the two things that module does not have:
+//   - cancellation on an AbortSignal, acknowledged through a shared flag the
+//     work polls (works from inside a synchronous loop);
+//   - a watchdog: if the worker has not acknowledged within `ackGraceMs` of
+//     the abort, it is terminated, so a worker that never polls cannot hold
+//     the caller past that bound.
+// The returned promise always settles with a structured result, and every
+// resource this function created (worker, timers, abort listener) is released
+// before it settles; `exited` resolves when the worker thread is really gone.
+
+import { Worker } from 'node:worker_threads';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ENTRY = path.join(path.dirname(fileURLToPath(import.meta.url)), 'owned-worker-entry.js');
+
+export const DEFAULT_ACK_GRACE_MS = 500;
+
+/**
+ * @param {{modulePath:string, exportName:string, args?:Array}} spec
+ * @param {{signal?:AbortSignal, timeoutMs?:number, ackGraceMs?:number}} [opts]
+ * @returns {{done:Promise<object>, exited:Promise<void>}}
+ *   done resolves to one of:
+ *     {ok:true, result, cancelled:false}
+ *     {ok:true, result, cancelled:true, ackMs}                 cooperative stop
+ *     {ok:false, status:'cancelled', terminatedByWatchdog:true, ackMs}
+ *     {ok:false, error}
+ */
+export function runOwnedWorker(spec, opts = {}) {
+  const ackGraceMs = Number.isFinite(opts.ackGraceMs) && opts.ackGraceMs > 0 ? opts.ackGraceMs : DEFAULT_ACK_GRACE_MS;
+  let resolveExited;
+  const exited = new Promise((r) => { resolveExited = r; });
+  const done = new Promise((resolve) => {
+    if (!spec || !spec.modulePath || !spec.exportName) {
+      resolveExited();
+      return resolve({ ok: false, error: 'runOwnedWorker requires spec.modulePath and spec.exportName' });
+    }
+    const flag = new Int32Array(new SharedArrayBuffer(4));
+    const worker = new Worker(ENTRY, { workerData: { modulePath: spec.modulePath, exportName: spec.exportName, args: spec.args || [], flag: flag.buffer } });
+    worker.once('exit', () => resolveExited());
+    let settled = false;
+    let cancelAt = null;
+    let reason = null;
+    let watchdog = null;
+    let deadlineTimer = null;
+
+    const release = () => {
+      clearTimeout(watchdog);
+      clearTimeout(deadlineTimer);
+      if (opts.signal) opts.signal.removeEventListener('abort', onAbort);
+      worker.terminate().catch(() => {});
+    };
+    const settle = (value) => {
+      if (settled) return;
+      settled = true;
+      release();
+      resolve(value);
+    };
+    const requestCancel = (why) => {
+      if (settled || cancelAt !== null) return;
+      cancelAt = Date.now();
+      reason = why;
+      Atomics.store(flag, 0, 1);
+      watchdog = setTimeout(() => {
+        settle({ ok: false, status: 'cancelled', reason: why, terminatedByWatchdog: true, ackMs: Date.now() - cancelAt });
+      }, ackGraceMs);
+    };
+    function onAbort() { requestCancel('aborted'); }
+
+    worker.once('message', (msg) => {
+      if (msg && msg.ok) {
+        const wasCancelled = !!msg.cancelled || cancelAt !== null;
+        settle(wasCancelled
+          ? { ok: true, result: msg.result, cancelled: true, reason, ackMs: cancelAt === null ? 0 : Date.now() - cancelAt }
+          : { ok: true, result: msg.result, cancelled: false });
+      } else {
+        settle({ ok: false, error: (msg && msg.error) || 'worker failed' });
+      }
+    });
+    worker.once('error', (e) => settle({ ok: false, error: String((e && e.message) || e) }));
+
+    if (opts.signal) {
+      if (opts.signal.aborted) onAbort(); else opts.signal.addEventListener('abort', onAbort, { once: true });
+    }
+    if (Number.isFinite(opts.timeoutMs) && opts.timeoutMs > 0) {
+      deadlineTimer = setTimeout(() => requestCancel('deadline'), opts.timeoutMs);
+    }
+  });
+  return { done, exited };
+}

package/src/lineage/path-evidence.js

@@ -0,0 +1,123 @@
+//
+// path-evidence.js: the DAG-04 evidence for witnesses, assembled (R04.1 to R04.6).
+//
+// One entry point per use:
+//   * evaluatePathEvidence       one reconstructed path: conditions + feasibility + control state.
+//   * summarizeFlowEvidence      a group of paths that share one graph flow: alternatives stay distinct,
+//                                infeasible-under-model paths are listed (never silently dropped), and the
+//                                all-paths claim goes through assessAllPathsProtectedWithControls.
+//   * buildControlEvidence       the `controlEvidence` slot of a witness bundle (posture/witness-bundle.js).
+//
+// Everything here is opt-in. Nothing runs, and no field is added to any output, unless a caller (or the
+// graph builder with `pathEvidence: true` / AGENTIC_SECURITY_LINEAGE_PATH_PREDICATES=1) asks for it.
+
+import crypto from 'node:crypto';
+import { collectWitnessConditions, evaluateWitnessConditions, PATH_PREDICATE_VERSION, SATISFIABILITY_NOTE } from './path-predicates.js';
+import { evaluateWitnessConditionsAsync } from './smt-orchestrator.js';
+import { creditPath, assessAllPathsProtectedWithControls, CONTROL_CREDIT_VERSION } from './control-credit.js';
+
+export const PATH_EVIDENCE_VERSION = 'path-evidence/1';
+
+export function pathEvidenceEnabled(opts) {
+  if (opts && opts.pathEvidence !== undefined) return Boolean(opts.pathEvidence);
+  return process.env.AGENTIC_SECURITY_LINEAGE_PATH_PREDICATES === '1';
+}
+
+const sha12 = (s) => crypto.createHash('sha256').update(s).digest('hex').slice(0, 12);
+
+function assemble(path, conditions, feasibility, credit) {
+  const refsByEdge = conditions.edgeGuards;
+  return {
+    version: PATH_EVIDENCE_VERSION,
+    pathId: path.id ?? null,
+    conditions, feasibility, credit,
+    controlState: credit.controlState,
+    edgeGuards: refsByEdge,
+    controlRefs: credit.credits.map((c) => ({ edgeId: c.edgeId, ref: `ctl:${sha12(`${c.scope}|${c.nodeId}|${c.callee}|${c.sinkFamily}`)}` })),
+  };
+}
+
+/** Synchronous evidence for one reconstructed path (abstract domains only). */
+export function evaluatePathEvidence({ path, nodeOf, fnOf, sinkFamily = null, predicateOpts } = {}) {
+  const hops = path?.hops ?? [];
+  const conditions = collectWitnessConditions(hops, { fnOf });
+  const feasibility = evaluateWitnessConditions(conditions, predicateOpts);
+  const credit = creditPath({ hops, nodeOf, fnOf, sinkFamily, truncated: path?.complete === false || path?.analysisTruncated === true });
+  return assemble(path ?? {}, conditions, feasibility, credit);
+}
+
+/** As above, but an `unknown` abstract answer may be sent to an optional solver (awaited, time-bounded, cancellable). */
+export async function evaluatePathEvidenceAsync({ path, nodeOf, fnOf, sinkFamily = null, predicateOpts, solverOpts } = {}) {
+  const hops = path?.hops ?? [];
+  const conditions = collectWitnessConditions(hops, { fnOf });
+  const feasibility = await evaluateWitnessConditionsAsync(conditions, { ...(predicateOpts ?? {}), ...(solverOpts ?? {}) });
+  const credit = creditPath({ hops, nodeOf, fnOf, sinkFamily, truncated: path?.complete === false || path?.analysisTruncated === true });
+  return assemble(path ?? {}, conditions, feasibility, credit);
+}
+
+const STATE_RANK = { unprotected: 0, unknown: 1, protected: 2 };
+
+/**
+ * Summarize every path of one flow group. `evidences` is the per-path output of evaluatePathEvidence.
+ * The aggregate control state is the WORST over relevant paths, never the best, and alternatives are
+ * listed one by one with their own conjunction of conditions.
+ */
+export function summarizeFlowEvidence({ result, paths, evidences, proof = null }) {
+  const byId = new Map(evidences.map((e, i) => [paths[i].id, e]));
+  const assessed = assessAllPathsProtectedWithControls({ result, enumerated: paths, evidenceOf: (p) => byId.get(p.id), proof });
+  const relevant = evidences.filter((e) => e.feasibility.status !== 'infeasible-under-model');
+  let worst = null;
+  for (const e of relevant) if (worst === null || STATE_RANK[e.controlState] < STATE_RANK[worst]) worst = e.controlState;
+  const feasCounts = {};
+  for (const e of evidences) feasCounts[e.feasibility.status] = (feasCounts[e.feasibility.status] ?? 0) + 1;
+  return {
+    version: PATH_EVIDENCE_VERSION,
+    semanticsVersion: PATH_PREDICATE_VERSION,
+    controlSemanticsVersion: CONTROL_CREDIT_VERSION,
+    pathCount: paths.length,
+    feasibility: feasCounts,
+    controlState: worst ?? 'unknown',
+    allPathsProtected: assessed,
+    alternatives: evidences.map((e, i) => ({
+      pathId: paths[i].id,
+      feasibility: e.feasibility.status,
+      feasibilityReasons: e.feasibility.reasons,
+      controlState: e.controlState,
+      predicateRefs: e.conditions.clauses.map((c) => ({ ref: c.ref, polarity: c.polarity, branchNodeId: c.branchNodeId, scope: c.scope, text: c.text, versions: c.versions })),
+    })),
+    note: SATISFIABILITY_NOTE,
+  };
+}
+
+/**
+ * The `controlEvidence` slot of a witness bundle (posture/witness-bundle.js validates its shape).
+ * Maps the five-valued feasibility result onto the slot's three statuses and keeps the precise result in
+ * `detail`, so `timeout` and `unsupported` stay visible as `unknown` rather than becoming a clean bill.
+ */
+export function buildControlEvidence(evidence, { pathEdgeIds }) {
+  const f = evidence.feasibility;
+  const status = f.status === 'feasible-model' ? 'feasible' : f.status === 'infeasible-under-model' ? 'infeasible' : 'unknown';
+  const onPath = new Set(pathEdgeIds);
+  const predicateRefs = [];
+  for (const c of evidence.conditions.clauses) for (const edgeId of c.atEdgeIds) if (onPath.has(edgeId)) predicateRefs.push({ edgeId, ref: c.ref });
+  const controlRefs = evidence.controlRefs.filter((r) => onPath.has(r.edgeId));
+  return {
+    status,
+    predicateRefs: predicateRefs.sort((a, b) => (a.edgeId + a.ref < b.edgeId + b.ref ? -1 : 1)),
+    controlRefs,
+    detail: {
+      semanticsVersion: PATH_PREDICATE_VERSION,
+      feasibility: f.status,
+      reasons: f.reasons,
+      contradiction: f.contradiction ?? null,
+      unmodeledPredicates: f.unmodeledPredicates ?? [],
+      solver: f.solver ?? null,
+      limitations: f.limitations,
+      doesNotImply: SATISFIABILITY_NOTE,
+      controlState: evidence.controlState,
+      controlSemanticsVersion: CONTROL_CREDIT_VERSION,
+      controlsRejected: evidence.credit.rejected.map((r) => ({ edgeId: r.edgeId, callee: r.callee, reason: r.reason })),
+      controlLimitations: evidence.credit.limitations,
+    },
+  };
+}