@clear-capabilities/agentic-security-scanner 0.153.2 → 0.154.0

package/src/language/nixos-option-catalog.js

@@ -0,0 +1,96 @@
+// Revision-pinned NixOS / Home Manager option catalog (NIX-002).
+//
+// This is NOT a copy of the option set. It lists the options the scanner reasons
+// about, with a type, a default PER RELEASE, and the renames that must be followed
+// so an old spelling cannot bypass a hardening rule that is written against the new
+// one. Anything absent from here is "uncataloged" and its default is unknown, never
+// guessed. A default is only "proven" when it is recorded for the release in force
+// (or recorded identically for every release in the catalog).
+//
+// The catalog is pinned by NixOS release (the CI-tested set in CATALOG_RELEASES) and
+// by a content hash (`catalogRevision`), so a report can say exactly which table it
+// was judged against. Refresh it, and bump CATALOG_SCHEMA when the shape changes, by
+// editing the tables below: the revision hash changes with them.
+
+import { createHash } from 'node:crypto';
+
+export const CATALOG_SCHEMA = 1;
+export const CATALOG_RELEASES = Object.freeze(['24.11', '25.05', '25.11']);
+
+const same = (v) => Object.freeze(Object.fromEntries(CATALOG_RELEASES.map((r) => [r, v])));
+
+/** option path -> { type, default?: {release: value} }. A missing `default` means "no static default" (unknown). */
+const NIXOS_OPTIONS = {
+  'services.openssh.enable': { type: 'bool', default: same(false) },
+  'services.openssh.openFirewall': { type: 'bool', default: same(true) },
+  'services.openssh.ports': { type: 'listOf', default: same([22]) },
+  'services.openssh.settings.PermitRootLogin': { type: 'enum', default: same('prohibit-password') },
+  'services.openssh.settings.PasswordAuthentication': { type: 'bool', default: same(true) },
+  'services.openssh.settings.KbdInteractiveAuthentication': { type: 'bool', default: same(true) },
+  'services.openssh.settings.X11Forwarding': { type: 'bool', default: same(false) },
+  'networking.firewall.enable': { type: 'bool', default: same(true) },
+  'networking.firewall.allowedTCPPorts': { type: 'listOf', default: same([]) },
+  'networking.firewall.allowedUDPPorts': { type: 'listOf', default: same([]) },
+  'networking.hostName': { type: 'str', default: same('nixos') },
+  'security.sudo.enable': { type: 'bool', default: same(true) },
+  'security.sudo.wheelNeedsPassword': { type: 'bool', default: same(true) },
+  'security.sudo.extraConfig': { type: 'lines', default: same('') },
+  'security.sudo.execWheelOnly': { type: 'bool', default: same(false) },
+  'networking.firewall.allowedTCPPortRanges': { type: 'listOf', default: same([]) },
+  'users.mutableUsers': { type: 'bool', default: same(true) },
+  'nix.settings.sandbox': { type: 'bool', default: same(true) },
+  'nix.settings.trusted-users': { type: 'listOf', default: same(['root']) },
+  'services.nginx.enable': { type: 'bool', default: same(false) },
+  'services.postgresql.enable': { type: 'bool', default: same(false) },
+  'services.postgresql.enableTCPIP': { type: 'bool', default: same(false) },
+  'services.xserver.enable': { type: 'bool', default: same(false) },
+  'system.stateVersion': { type: 'str' },
+};
+
+const HM_OPTIONS = {
+  'programs.git.enable': { type: 'bool', default: same(false) },
+  'programs.bash.enable': { type: 'bool', default: same(false) },
+  'services.gpg-agent.enable': { type: 'bool', default: same(false) },
+  'home.stateVersion': { type: 'str' },
+};
+
+/** old spelling -> current spelling. A definition at the old path is evaluated as the new path. */
+const NIXOS_RENAMES = {
+  'services.openssh.permitRootLogin': 'services.openssh.settings.PermitRootLogin',
+  'services.openssh.passwordAuthentication': 'services.openssh.settings.PasswordAuthentication',
+  'services.openssh.kbdInteractiveAuthentication': 'services.openssh.settings.KbdInteractiveAuthentication',
+  'services.openssh.challengeResponseAuthentication': 'services.openssh.settings.KbdInteractiveAuthentication',
+  'services.openssh.forwardX11': 'services.openssh.settings.X11Forwarding',
+  'nix.useSandbox': 'nix.settings.sandbox',
+  'nix.trustedUsers': 'nix.settings.trusted-users',
+};
+
+/** Prefixes the catalog is authoritative for: an option under one that is neither listed nor renamed is "unknown", not "fine". */
+const AUTHORITATIVE = ['services.openssh', 'networking.firewall', 'security.sudo'];
+/** Freeform attribute sets: any key is valid, but only the listed ones have a known default. */
+const FREEFORM = ['services.openssh.settings', 'nix.settings', 'networking.firewall.interfaces'];
+
+const CATALOG = {
+  schema: CATALOG_SCHEMA,
+  releases: [...CATALOG_RELEASES],
+  nixos: { options: NIXOS_OPTIONS, renames: NIXOS_RENAMES, authoritative: AUTHORITATIVE, freeform: FREEFORM },
+  homeManager: { options: HM_OPTIONS, renames: {}, authoritative: [], freeform: [] },
+};
+
+export function computeCatalogRevision(catalog) {
+  const { revision, ...content } = catalog;
+  void revision;
+  return `nixos-option-catalog/${catalog.schema}+${createHash('sha256').update(JSON.stringify(content)).digest('hex').slice(0, 12)}`;
+}
+
+export const CATALOG_REVISION = computeCatalogRevision(CATALOG);
+
+export function defaultCatalog() {
+  return { ...CATALOG, revision: CATALOG_REVISION };
+}
+
+/** `nixos-24.11`, `release-25.05`, `24.11` -> '24.11'; anything else null. */
+export function normalizeRelease(text) {
+  const m = /(?:^|[^0-9])(\d{2}\.(?:05|11))(?![0-9])/.exec(String(text || ''));
+  return m ? m[1] : null;
+}

package/src/language/pragma.js

@@ -0,0 +1,150 @@
+// Inline suppression pragmas for Haskell and Nix (X-013).
+//
+//   Haskell   `-- agentic-security-ignore: rule-a, rule-b`    and    `{- agentic-security-ignore: rule-a -}`
+//   Nix       `# agentic-security-ignore: rule-a`            and    `/* agentic-security-ignore: rule-a */`
+//
+// A pragma is recognised only INSIDE A COMMENT, so the same words in a string literal, an identifier or an operator
+// (`-->` is an operator in Haskell, not a comment) never suppress anything. Comment boundaries come from a small
+// scanner that knows each language's strings, nesting and interpolation, not from a regular expression over the line.
+//
+// Scope: LINE. A pragma applies to findings reported on the line it sits on, exactly like the pragmas of the other
+// languages. With rule ids it suppresses only a finding whose rule, id, family, CWE or title slug EQUALS one of them
+// (exact token match, never a substring: `cmd` must not silence `cmdi`). A bare pragma suppresses every finding on its
+// line. A pragma whose rule list is malformed (anything other than ids separated by commas or spaces) suppresses
+// nothing and is reported back as `malformed`, so it cannot silence an unrelated finding by accident.
+
+const MARK = /agentic-security-ignore(?![A-Za-z0-9_-])/;
+const RULE_ID = /^[A-Za-z0-9_.:/\-]+$/;
+
+/**
+ * Comment spans of a Haskell source: [{start, end, text}] in source offsets.
+ * Strings ("..." with escapes, string gaps) and character literals are skipped; `--` starts a line comment only when
+ * it is not part of a longer operator symbol; `{- -}` nests.
+ */
+export function haskellComments(src) {
+  const out = []; const n = src.length; let i = 0;
+  const SYM = /[!#$%&*+./<=>?@\\^|~:-]/;
+  while (i < n) {
+    const c = src[i]; const d = src[i + 1];
+    if (c === '"') { i++; while (i < n && src[i] !== '"') { if (src[i] === '\\') i++; if (src[i] === '\n') break; i++; } i++; continue; }
+    if (c === "'" && /^'(?:[^'\\\n]|\\[^\n]{1,8}?)'/.test(src.slice(i, i + 12)) && !/[A-Za-z0-9_']/.test(src[i - 1] || '')) { const m = /^'(?:[^'\\\n]|\\[^\n]{1,8}?)'/.exec(src.slice(i, i + 12)); i += m[0].length; continue; }
+    if (c === '{' && d === '-' && src[i + 2] !== '#') {
+      let depth = 1; let j = i + 2;
+      while (j < n && depth > 0) { if (src[j] === '{' && src[j + 1] === '-') { depth++; j += 2; } else if (src[j] === '-' && src[j + 1] === '}') { depth--; j += 2; } else j++; }
+      out.push({ start: i, end: j, text: src.slice(i, j) }); i = j; continue;
+    }
+    if (c === '-' && d === '-') {
+      let j = i; while (src[j] === '-') j++;
+      const before = src[i - 1]; const after = src[j];
+      if (!(before && SYM.test(before)) && !(after && SYM.test(after)) ) { const e = src.indexOf('\n', i); const end = e < 0 ? n : e; out.push({ start: i, end, text: src.slice(i, end) }); i = end; continue; }
+      i = j; continue;
+    }
+    i++;
+  }
+  return out;
+}
+
+/**
+ * Comment spans of a Nix source: `#` to end of line, and slash-star block comments. Strings `"..."` and indented strings `''...''` are
+ * skipped, including their `${ ... }` interpolations, whose inner code may itself contain comments and strings.
+ */
+export function nixComments(src) {
+  const out = []; const n = src.length;
+  function scan(i, stopAtBrace) {
+    let depth = 0;
+    while (i < n) {
+      const c = src[i]; const d = src[i + 1];
+      if (stopAtBrace) { if (c === '{') depth++; else if (c === '}') { if (depth === 0) return i + 1; depth--; } }
+      if (c === '#') { const e = src.indexOf('\n', i); const end = e < 0 ? n : e; out.push({ start: i, end, text: src.slice(i, end) }); i = end; continue; }
+      if (c === '/' && d === '*') { const e = src.indexOf('*/', i + 2); const end = e < 0 ? n : e + 2; out.push({ start: i, end, text: src.slice(i, end) }); i = end; continue; }
+      if (c === '"') { i = skipString(i + 1, '"'); continue; }
+      if (c === "'" && d === "'") { i = skipString(i + 2, "''"); continue; }
+      i++;
+    }
+    return i;
+  }
+  function skipString(i, close) {
+    while (i < n) {
+      const c = src[i]; const d = src[i + 1];
+      if (close === '"') { if (c === '\\') { i += 2; continue; } if (c === '"') return i + 1; }
+      else {
+        if (c === "'" && d === "'") { const e = src[i + 2]; if (e === "'" || e === '$') { i += 3; continue; } if (e === '\\') { i += 4; continue; } return i + 2; }
+      }
+      if (c === '$' && d === '{') { i = scan(i + 2, true); continue; }
+      i++;
+    }
+    return i;
+  }
+  scan(0, false);
+  return out;
+}
+
+const lineStarts = (src) => { const a = [0]; for (let i = 0; i < src.length; i++) if (src[i] === '\n') a.push(i + 1); return a; };
+const lineOfOffset = (starts, off) => { let lo = 0; let hi = starts.length - 1; while (lo < hi) { const mid = (lo + hi + 1) >> 1; if (starts[mid] <= off) lo = mid; else hi = mid - 1; } return lo + 1; };
+
+/** Strips the comment delimiters from a comment's text. */
+function commentBody(text) {
+  if (text.startsWith('{-')) return text.replace(/^\{-+/, '').replace(/-+\}$/, '');
+  if (text.startsWith('/*')) return text.replace(/^\/\*+/, '').replace(/\*+\/$/, '');
+  if (text.startsWith('#')) return text.replace(/^#+/, '');
+  return text.replace(/^--+/, '');
+}
+
+/**
+ * Parses the pragma inside ONE comment body. Returns null when there is none, else
+ * {bare:boolean, rules:string[], malformed:string|null}.
+ */
+export function parsePragma(body) {
+  const m = MARK.exec(body);
+  if (!m) return null;
+  let rest = body.slice(m.index + m[0].length);
+  // only the first line of a multi-line comment body carries the list
+  rest = rest.split('\n')[0];
+  // a trailing block-comment closer is not part of the list
+  rest = rest.replace(/(?:-\}|\*\/)\s*$/, '');
+  const hasColon = /^\s*:/.test(rest);
+  rest = rest.replace(/^\s*:?/, '').trim();
+  if (!rest) return hasColon ? { bare: false, rules: [], malformed: 'a pragma with a colon needs at least one rule id' } : { bare: true, rules: [], malformed: null };
+  if (!hasColon && /^[A-Za-z0-9_.:/-]/.test(rest) && !/^[,\s]/.test(rest)) return { bare: false, rules: [], malformed: 'rule ids follow a colon: "agentic-security-ignore: <rule>"' };
+  const toks = rest.split(/[\s,]+/).filter(Boolean);
+  const bad = toks.find((t) => !RULE_ID.test(t));
+  if (bad) return { bare: false, rules: [], malformed: `"${bad}" is not a rule id` };
+  return { bare: false, rules: toks, malformed: null };
+}
+
+/**
+ * The pragma a source carries on `line`, or null. `file` selects the comment grammar (.hs/.lhs or .nix); any other
+ * file type returns null (the generic pragma handles those).
+ */
+export function languagePragmaOnLine(file, src, line) {
+  if (typeof src !== 'string' || !Number.isInteger(line) || line < 1) return null;
+  const isHs = /\.l?hs$|\.hs-boot$|\.hsc$/i.test(file || '');
+  const isNix = /\.nix$/i.test(file || '');
+  if (!isHs && !isNix) return null;
+  const comments = isHs ? haskellComments(src) : nixComments(src);
+  const starts = lineStarts(src);
+  const found = [];
+  for (const c of comments) {
+    if (!MARK.test(c.text)) continue;
+    // the line the words sit on (a block comment may span several lines)
+    const off = c.start + c.text.search(MARK);
+    if (lineOfOffset(starts, off) !== line) continue;
+    const p = parsePragma(commentBody(c.text));
+    if (p) found.push(p);
+  }
+  if (!found.length) return null;
+  const rules = []; let bare = false; let malformed = null;
+  for (const p of found) { if (p.bare) bare = true; rules.push(...p.rules); if (p.malformed) malformed = p.malformed; }
+  return { bare, rules, malformed, form: isHs ? 'haskell' : 'nix' };
+}
+
+const slug = (s) => String(s || '').replace(/[^a-zA-Z0-9]+/g, '-').replace(/^-+|-+$/g, '').toLowerCase();
+
+/** Whether a parsed language pragma suppresses finding `f`: bare, or an EXACT match on one of its identifiers. */
+export function languagePragmaSuppresses(p, f) {
+  if (!p || !f) return false;
+  if (p.malformed && !p.bare && !p.rules.length) return false;
+  if (p.bare) return true;
+  const ids = new Set([f.rule, f.id, f.family, f.cwe, f.ruleId, slug(f.vuln), typeof f.id === 'string' ? f.id.split(':')[0] : null].filter(Boolean).map((x) => String(x).toLowerCase()));
+  return p.rules.some((r) => ids.has(String(r).toLowerCase()));
+}

package/src/language/resolved-pass.js

@@ -0,0 +1,146 @@
+// Resolved dependency data in the scan path (QA-005.AC04): explicit exports a user or tool wrote on purpose become part of a normal scan,
+// instead of being reachable only from a unit test.
+//
+//   Haskell   dist-newstyle/cache/plan.json and .stack-work/dependencies.json   -> a resolved graph (transitive packages, exact
+//             versions, scopes) joined to the declared manifests; stale data is used for nothing and disclosed.
+//   Nix       nix-export.json (and .direnv/nix-export.json)                       -> an imported closure, matched against an advisory
+//             snapshot with upstream-identity and patch-evidence rules; no feed means "unknown", never "clean".
+//   Eval      AGENTIC_SECURITY_NIX_EVAL=1 + AGENTIC_SECURITY_NIX_TARGET=<attr>   -> an isolated, opt-in evaluation whose state is its
+//             own scan-health field. A scan that did not select it never runs a Nix evaluator.
+//
+// Nothing here fetches, builds, evaluates or runs a project's code unless the evaluation is selected AND the sandbox proves its isolation.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { statePath } from '../posture/state-dir.js';
+import { analyzeHaskellManifests } from './haskell-manifests.js';
+import { buildResolvedGraph } from './haskell-resolved-graph.js';
+import { importNixClosure } from './nix-closure.js';
+import { NixAdvisoryData, matchNixVulnerabilities, overlayEvidence } from './nix-sca.js';
+import { configuredAdvisoryDb, collectUsage, manifestFiles } from './haskell-supply.js';
+import { runIsolatedEval, mergeEvaluationHealth, _which } from './nix-eval-isolation.js';
+
+export const RESOLVED_PASS_VERSION = 'resolved-pass/1';
+
+const PLAN = /(?:^|\/)dist-newstyle\/cache\/plan\.json$/;
+const STACK_EXPORT = /(?:^|\/)\.stack-work\/dependencies\.json$/;
+const NIX_EXPORT = /(?:^|\/)nix-export\.json$/;
+const ACTIONABLE = new Set(['affected', 'possibly-affected', 'candidate', 'backported-verified']);
+
+const memo = new WeakMap();
+const memoized = (files, key, make) => { let m = memo.get(files); if (!m) { m = new Map(); memo.set(files, m); } if (!m.has(key)) m.set(key, make()); return m.get(key); };
+
+function parseJson(text) { try { return { ok: true, value: JSON.parse(text) }; } catch (e) { return { ok: false, reason: String((e && e.message) || e).slice(0, 120) }; } }
+
+/** The resolved Haskell graph for a file set, or null when no explicit export is present. Cached per file set. */
+export function resolvedHaskellGraph(files) {
+  return memoized(files, 'hs-graph', () => {
+    const planFile = Object.keys(files).find((p) => PLAN.test(p));
+    const stackFile = !planFile ? Object.keys(files).find((p) => STACK_EXPORT.test(p)) : null;
+    const src = planFile || stackFile;
+    if (!src) return null;
+    const mf = manifestFiles(files);
+    const manifests = mf.length ? analyzeHaskellManifests(mf) : null;
+    const parsed = parseJson(files[src]);
+    if (!parsed.ok) return { file: src, graph: { source: planFile ? 'cabal-plan' : 'stack-export', graphAvailable: false, units: null, edges: null, freshness: { status: 'unverified', reasons: [] }, closure: { complete: false, reason: 'malformed_resolved_data' }, gaps: [{ kind: planFile ? 'malformed_plan' : 'malformed_stack_export', detail: `${src} is not valid JSON: ${parsed.reason}` }], declared: [] }, manifests };
+    const graph = buildResolvedGraph({ manifests, ...(planFile ? { plan: parsed.value } : { stackExport: parsed.value }), expected: {} });
+    return { file: src, graph, manifests };
+  });
+}
+
+/**
+ * Components for the resolved graph: every Hackage unit with an exact version, its scope and where it came from. Only a graph that is
+ * not stale contributes; a stale one is returned as a gap (never as components), and a partial one says it is partial.
+ */
+export function resolvedHackageComponents(files) {
+  const r = resolvedHaskellGraph(files);
+  if (!r) return { components: [], gaps: [], summary: null };
+  const g = r.graph;
+  const gaps = (g.gaps || []).map((x) => ({ kind: `resolved-${x.kind}`, detail: x.detail || x.message || x.kind, file: r.file }));
+  const summary = { file: r.file, source: g.source, graphAvailable: g.graphAvailable, freshness: g.freshness, closure: g.closure, units: g.units ? g.units.length : null, edges: g.edges ? g.edges.length : null };
+  if (!g.graphAvailable || g.freshness.status === 'stale') return { components: [], gaps, summary };
+  const SCOPE = { runtime: 'required', test: 'optional', benchmark: 'optional', setup: 'optional', 'build-tool': 'optional' };
+  const direct = new Set((g.declared || []).map((d) => d.name));
+  const components = [];
+  for (const u of g.units) {
+    if (u.origin === 'local' || u.origin === 'compiler' || !u.name || !u.version) continue;   // the project itself and boot libraries are not dependencies to match
+    const scopes = Array.isArray(u.scopes) && u.scopes.length ? u.scopes : ['runtime'];
+    const scope = scopes.includes('runtime') ? 'runtime' : scopes[0];
+    components.push({ ecosystem: 'hackage', name: u.name, version: u.version, declaredRange: null, resolution: 'plan', scope, engineScope: SCOPE[scope] || 'required', target: null, componentKind: u.componentKind || null, manifest: r.file, line: null, ghcComponent: false, direct: direct.has(u.name), unitId: u.id, origin: u.origin, versionSource: { file: r.file, line: null } });
+  }
+  return { components, gaps, summary };
+}
+
+// ── Nix closure ──────────────────────────────────────────────────────────────────
+function loadNixExports(files) {
+  const exports = []; const sources = []; const problems = []; let expected = {};
+  for (const p of Object.keys(files).filter((x) => NIX_EXPORT.test(x)).sort()) {
+    const parsed = parseJson(files[p]);
+    sources.push(p);
+    if (!parsed.ok) { problems.push({ kind: 'malformed-export', file: p, detail: parsed.reason }); continue; }
+    const j = parsed.value;
+    if (j && Array.isArray(j.exports)) { exports.push(...j.exports.filter((e) => e && typeof e === 'object')); if (j.expected && typeof j.expected === 'object') expected = { ...expected, ...j.expected }; }
+    else if (j && typeof j === 'object' && j.schema && (j.data !== undefined || j.text !== undefined)) exports.push(j);
+    else exports.push({ text: files[p] });
+  }
+  return { exports, sources, problems, expected };
+}
+
+/** The imported closure (and each derivation's env block) for a file set, or null when there is no export. Cached per file set. */
+export function nixClosureOf(files, { now = Date.now() } = {}) {
+  return memoized(files, 'nix-closure', () => {
+    const { exports, sources, problems, expected } = loadNixExports(files);
+    if (!sources.length) return null;
+    const closure = importNixClosure({ exports, expected, now });
+    const drvEnv = {};
+    for (const ex of exports) {
+      if (ex.schema !== 'nix-derivation-show-json') continue;
+      let data = ex.data; if (data === undefined && typeof ex.text === 'string') { const p = parseJson(ex.text); data = p.ok ? p.value : null; }
+      for (const [k, v] of Object.entries(data || {})) if (v && v.env) drvEnv[k] = v.env;
+    }
+    return { closure, drvEnv, sources, problems };
+  });
+}
+
+/** Advisory records for Nix: a snapshot named by AGENTIC_SECURITY_NIX_ADVISORIES or kept in the project state directory. */
+export function configuredNixAdvisories(root, env = process.env, hackageDb = null) {
+  const path = env.AGENTIC_SECURITY_NIX_ADVISORIES || (root && existsSync(statePath(root, 'nix-advisories.json')) ? statePath(root, 'nix-advisories.json') : null);
+  if (!path) return { data: null, reason: 'no Nix advisory snapshot is configured (set AGENTIC_SECURITY_NIX_ADVISORIES or provide nix-advisories.json in the project state directory)' };
+  let snap; try { snap = JSON.parse(readFileSync(path, 'utf8')); } catch (e) { return { data: null, reason: `the Nix advisory snapshot is unreadable: ${e.code || e.message}` }; }
+  const records = Array.isArray(snap) ? snap : (Array.isArray(snap.records) ? snap.records : []);
+  return { data: new NixAdvisoryData({ records, hackage: hackageDb, source: 'pinned-snapshot', generatedAt: (snap && snap.generatedAt) || null }), reason: null };
+}
+
+/** Closure statuses and findings, with every disclosure the import and the feed produced. */
+export function analyzeNixClosure(files, opts = {}) {
+  return memoized(files, 'nix-analysis', () => _analyzeNixClosure(files, opts));
+}
+function _analyzeNixClosure(files, { scanRoot = null, env = process.env, now = Date.now() } = {}) {
+  const c = nixClosureOf(files, { now });
+  if (!c) return null;
+  const hackage = configuredAdvisoryDb(scanRoot, env).db;
+  const adv = configuredNixAdvisories(scanRoot, env, hackage);
+  let usage = null; try { usage = collectUsage(files); } catch { usage = null; }
+  let matched = null;
+  try { matched = matchNixVulnerabilities({ closure: c.closure, drvEnv: c.drvEnv, data: adv.data, overlays: overlayEvidence(files), haskellUsage: usage }); } catch (e) { matched = null; c.problems.push({ kind: 'match-failed', detail: String((e && e.message) || e).slice(0, 160) }); }
+  const gaps = [];
+  for (const d of c.closure.disclosures || []) gaps.push({ kind: `closure-${d.kind}`, detail: d.detail });
+  for (const p of c.problems) gaps.push({ kind: `closure-${p.kind}`, detail: p.detail, file: p.file });
+  if (!adv.data) gaps.push({ kind: 'closure-advisory-feed-unavailable', detail: `${adv.reason}. The closure's components were NOT checked against any advisory: the absence of findings is not a clean result.` });
+  else if (adv.data.stale) gaps.push({ kind: 'closure-advisory-feed-stale', detail: `the Nix advisory snapshot is stale or undated (${adv.data.ageDays == null ? 'age unknown' : `${Math.floor(adv.data.ageDays)} day(s) old`})` });
+  const findings = ((matched && matched.findings) || []).filter((f) => ACTIONABLE.has(f.status)).map((f) => ({ ...f, file: c.sources[0], line: 1 }));
+  return { status: c.closure.status, claims: c.closure.claims, sources: c.sources, summary: matched ? matched.summary : null, feed: matched ? matched.feed : null, statuses: matched ? matched.statuses : [], findings, gaps, licenses: matched ? matched.licenses : null, closure: c.closure };
+}
+
+// ── isolated evaluation (opt in) ─────────────────────────────────────────────────
+/** Runs the isolated evaluation when AGENTIC_SECURITY_NIX_EVAL=1; otherwise null. Never throws; a failure is a recorded state. */
+export async function runSelectedNixEval(root, env = process.env, overrides = {}) {
+  if (env.AGENTIC_SECURITY_NIX_EVAL !== '1') return null;
+  const attribute = env.AGENTIC_SECURITY_NIX_TARGET || '';
+  const nixBin = overrides.nix || (_which ? _which('nix') : null);
+  if (!attribute) return { status: 'blocked', reason: 'no evaluation target: set AGENTIC_SECURITY_NIX_TARGET to a flake output attribute (for example nixosConfigurations.host.config.system.build.toplevel.drvPath)', projectCodeEvaluated: false };
+  if (!nixBin) return { status: 'unsupported', reason: 'the nix binary was not found on PATH; the project\'s Nix code was NOT evaluated', projectCodeEvaluated: false };
+  try { return await runIsolatedEval({ nix: typeof nixBin === 'string' ? { file: nixBin } : nixBin, root, attribute, system: env.AGENTIC_SECURITY_NIX_SYSTEM || null, ...overrides }); }
+  catch (e) { return { status: 'failed', reason: `the evaluation harness failed: ${String((e && e.message) || e).slice(0, 160)}`, projectCodeEvaluated: false }; }
+}
+
+export { mergeEvaluationHealth };