@clear-capabilities/agentic-security-scanner 0.158.0 → 0.160.0

package/src/language/nix-advisory-feed.js

@@ -0,0 +1,275 @@
+// Live advisory feed for the upstream software inside a Nix closure (NIX-009 follow-on).
+//
+// OSV has no nixpkgs ecosystem, so the Hackage approach (ask OSV by ecosystem and package name) does not carry over. The source used
+// here is the NVD CVE API 2.0 (https://services.nvd.nist.gov/rest/json/cves/2.0), queried by CPE vendor:product, because a nixpkgs
+// package declares its upstream identity as a CPE in meta.identifiers and NVD is the one public, machine-readable feed keyed by it.
+// What it can and cannot answer is stated in docs/guides/nix-nixos.md: an identity that has no CPE (a purl or a source URL alone) is
+// not something this feed is keyed by, so it is reported unknown, never clean.
+//
+// Contract (the same as haskell-advisory-feed.js, in the order it matters):
+//   * Opt in. Nothing here touches the network unless AGENTIC_SECURITY_NIX_ADVISORIES_LIVE=1, and never when AGENTIC_SECURITY_OFFLINE=1.
+//     An operator-pinned snapshot (AGENTIC_SECURITY_NIX_ADVISORIES) is used as given and is never refreshed over. A hand-written
+//     nix-advisories.json in the operator configuration directory is never overwritten either.
+//   * Coverage is recorded, not assumed. The snapshot lists every vendor:product it fully read and when. One it did not read, or read
+//     only in part, is NOT covered and the matcher reports it unknown.
+//   * Failure degrades. An unreachable or throttling feed leaves the previous snapshot in place; the scan runs on it with its age stated.
+//   * Everything from the wire is untrusted: the identity is validated before it reaches a URL, responses are size-capped, a record
+//     that does not name the requested product is dropped, and a cache whose records fail their own hashes is discarded.
+//   * Rate limits. NVD allows 5 requests per rolling 30 seconds without an API key and 50 with one (a key is free; set
+//     AGENTIC_SECURITY_NVD_API_KEY). Requests are spaced to stay under that, a throttling response stops the run instead of retrying,
+//     and the number of requests per scan is capped, so a large closure fills in over several scans rather than hammering the service.
+
+import { mkdirSync, readFileSync, writeFileSync, renameSync, chmodSync } from 'node:fs';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { operatorConfigDir } from './trusted-inputs.js';
+
+export const FEED_ENV = 'AGENTIC_SECURITY_NIX_ADVISORIES_LIVE';
+export const PINNED_ENV = 'AGENTIC_SECURITY_NIX_ADVISORIES';
+export const KEY_ENV = 'AGENTIC_SECURITY_NVD_API_KEY';
+export const SNAPSHOT_FILE = 'nix-advisories.json';
+export const SNAPSHOT_SCHEMA = 'nix-advisories-live/1';
+export const NVD_BASE = 'https://services.nvd.nist.gov/rest/json/cves/2.0';
+
+const DEFAULTS = Object.freeze({
+  ttlMs: 24 * 3600 * 1000,        // a covered identity is not queried again inside this window
+  timeoutMs: 20000,
+  maxProducts: 60,                // identities considered per scan
+  maxRequestsKeyless: 20,         // about 2 minutes at the keyless spacing
+  maxRequestsKeyed: 120,
+  intervalKeylessMs: 6500,        // 5 per 30 s, with margin
+  intervalKeyedMs: 700,           // 50 per 30 s, with margin
+  pageSize: 2000,                 // the NVD maximum
+  maxPages: 3,
+  maxResponseBytes: 32 << 20,
+  maxSnapshotRecords: 30000,
+});
+
+const PART = /^[a-z0-9][a-z0-9_.+~-]{0,63}$/;       // a CPE vendor or product, in the lowercase form NVD uses; no colon, slash, quote or escape
+const CVE_ID = /^CVE-\d{4}-\d{4,12}$/;
+const VERSION_OK = /^[A-Za-z0-9][A-Za-z0-9._+~-]{0,63}$/;
+const KEY_OK = /^[0-9a-fA-F-]{20,64}$/;
+
+/** 'vendor:product' from a full CPE 2.3 string, a {vendor, product} / {cpe} object, or a key already in that form; null if it cannot be made safely. */
+export function cpeKey(x) {
+  let v = null; let p = null;
+  if (x && typeof x === 'object') {
+    if (typeof x.vendor === 'string' && typeof x.product === 'string') { v = x.vendor; p = x.product; }
+    else if (typeof x.cpe === 'string') return cpeKey(x.cpe);
+    else return null;
+  } else if (typeof x === 'string') {
+    if (x.startsWith('cpe:2.3:')) { const parts = x.split(':'); if (parts.length < 5) return null; v = parts[3]; p = parts[4]; }
+    else { const parts = x.split(':'); if (parts.length !== 2) return null; [v, p] = parts; }
+  } else return null;
+  v = v.toLowerCase(); p = p.toLowerCase();
+  return PART.test(v) && PART.test(p) ? `${v}:${p}` : null;
+}
+export const validCpeKey = (k) => typeof k === 'string' && cpeKey(k) === k;
+
+let last = null;
+/** What the most recent refresh in this process did, so a "no feed" reason can say why. */
+export const getLastRefresh = () => last;
+export const _resetLastRefresh = () => { last = null; };
+
+export function liveFeedEnabled(env = process.env) {
+  return env[FEED_ENV] === '1' && env.AGENTIC_SECURITY_OFFLINE !== '1';
+}
+export function snapshotPath(env = process.env, dir = null) { return join(dir || operatorConfigDir(env), SNAPSHOT_FILE); }
+
+const sha256 = (s) => createHash('sha256').update(s).digest('hex');
+
+/**
+ * Validate a snapshot written by this module. Returns {ok:true, records, covered, generatedAt} or {ok:false, reason}.
+ * `foreign` marks a parseable file that is not ours (a hand-written operator snapshot): not an error, and never overwritten.
+ */
+export function loadLiveSnapshot(raw) {
+  if (!raw || typeof raw !== 'object' || raw.schema !== SNAPSHOT_SCHEMA) return { ok: false, foreign: true, reason: 'not a live-feed snapshot' };
+  if (!Array.isArray(raw.records) || !raw.recordHashes || typeof raw.recordHashes !== 'object') return { ok: false, reason: 'the snapshot has no record list or no record hashes' };
+  for (const rec of raw.records) {
+    if (!rec || typeof rec.id !== 'string' || !CVE_ID.test(rec.id)) return { ok: false, reason: 'a record has no valid identifier' };
+    if (raw.recordHashes[rec.id] !== sha256(JSON.stringify(rec))) return { ok: false, reason: `record ${rec.id} does not match its recorded hash` };
+  }
+  const covered = {};
+  if (!raw.covered || typeof raw.covered !== 'object' || Array.isArray(raw.covered)) return { ok: false, reason: 'the coverage table is missing or malformed' };
+  for (const [k, t] of Object.entries(raw.covered)) { if (!validCpeKey(k) || !Number.isFinite(Date.parse(t))) return { ok: false, reason: 'the coverage table has a malformed entry' }; covered[k] = t; }
+  return { ok: true, records: raw.records, covered, generatedAt: typeof raw.generatedAt === 'string' ? raw.generatedAt : null };
+}
+
+function readCurrent(path) {
+  let raw;
+  try { raw = JSON.parse(readFileSync(path, 'utf8')); } catch (e) { return { records: new Map(), covered: {}, problem: e && e.code === 'ENOENT' ? null : 'the cached snapshot was unreadable and was discarded', foreign: false }; }
+  const r = loadLiveSnapshot(raw);
+  if (r.foreign) return { records: new Map(), covered: {}, problem: null, foreign: true };
+  if (!r.ok) return { records: new Map(), covered: {}, problem: `the cached snapshot was discarded: ${r.reason}`, foreign: false };
+  return { records: new Map(r.records.map((x) => [x.id, x])), covered: r.covered, problem: null, foreign: false };
+}
+
+const splitCpe = (s) => s.split(/(?<!\\):/);
+const isoOrNull = (t) => {
+  if (typeof t !== 'string') return null;
+  const ms = Date.parse(/[zZ]|[+-]\d\d:?\d\d$/.test(t) ? t : `${t}Z`);   // NVD timestamps carry no zone and are UTC
+  return Number.isFinite(ms) ? new Date(ms).toISOString() : null;
+};
+
+/**
+ * One NVD CVE object -> an OSV-style record limited to the requested vendor:product, or null when the record does not name it
+ * (or is rejected, or carries nothing usable). Only `vulnerable` matches of the requested product are read; operating-system or
+ * hardware conditions on a combined configuration are NOT evaluated (see the guide).
+ * A start bound that is exclusive is carried as an `introduced_excluding` event, which the Nix matcher understands.
+ */
+export function nvdToOsv(cve, key) {
+  if (!cve || typeof cve !== 'object' || typeof cve.id !== 'string' || !CVE_ID.test(cve.id)) return null;
+  if (typeof cve.vulnStatus === 'string' && /^rejected$/i.test(cve.vulnStatus)) return null;
+  const ranges = []; const versions = [];
+  for (const cfg of Array.isArray(cve.configurations) ? cve.configurations : []) {
+    for (const node of Array.isArray(cfg && cfg.nodes) ? cfg.nodes : []) {
+      if (node && node.negate === true) continue;
+      for (const m of Array.isArray(node && node.cpeMatch) ? node.cpeMatch : []) {
+        if (!m || m.vulnerable !== true || typeof m.criteria !== 'string' || !m.criteria.startsWith('cpe:2.3:')) continue;
+        const parts = splitCpe(m.criteria);
+        if (parts.length < 6 || !['a', 'o', '*'].includes(parts[2]) || `${parts[3]}:${parts[4]}` !== key) continue;
+        const ver = parts[5]; const upd = parts[6];
+        if (ver === '*') {
+          const s1 = m.versionStartIncluding; const s2 = m.versionStartExcluding; const e1 = m.versionEndIncluding; const e2 = m.versionEndExcluding;
+          if ([s1, s2, e1, e2].some((x) => x !== undefined && (typeof x !== 'string' || !VERSION_OK.test(x)))) continue;
+          const events = [];
+          if (s1) events.push({ introduced: s1 }); else if (s2) events.push({ introduced_excluding: s2 }); else events.push({ introduced: '0' });
+          if (e2) events.push({ fixed: e2 }); else if (e1) events.push({ last_affected: e1 });
+          ranges.push({ type: 'ECOSYSTEM', events });
+        } else if (ver !== '-' && ver !== '?') {
+          const v = upd && upd !== '*' && upd !== '-' ? `${ver}-${upd}` : ver;
+          if (VERSION_OK.test(v)) versions.push(v);
+        }
+      }
+    }
+  }
+  if (!ranges.length && !versions.length) return null;
+  const desc = (Array.isArray(cve.descriptions) ? cve.descriptions : []).find((d) => d && d.lang === 'en' && typeof d.value === 'string');
+  const refs = (Array.isArray(cve.references) ? cve.references : []).map((r) => r && r.url).filter((u) => typeof u === 'string' && /^https?:\/\//.test(u) && u.length <= 300).slice(0, 5);
+  return {
+    id: cve.id, aliases: [], summary: desc ? desc.value.slice(0, 400) : '', published: isoOrNull(cve.published), modified: isoOrNull(cve.lastModified),
+    affected: [{ package: { ecosystem: 'NVD-CPE', name: key.split(':')[1], cpe: key }, ranges, versions }],
+    references: refs.map((url) => ({ type: 'WEB', url })), database_specific: { source: 'nvd-cve-2.0' },
+  };
+}
+
+const sleepReal = (ms) => new Promise((r) => setTimeout(r, ms));
+
+async function getJson(fetchImpl, url, headers, timeoutMs, maxBytes) {
+  const resp = await fetchImpl(url, { headers, signal: AbortSignal.timeout(timeoutMs) });
+  if (!resp) throw Object.assign(new Error('no response'), { http: 0 });
+  if (resp.status !== 200) throw Object.assign(new Error(`HTTP ${resp.status}`), { http: resp.status });
+  const text = await resp.text();
+  if (Buffer.byteLength(text) > maxBytes) throw new Error('response too large');
+  return JSON.parse(text);
+}
+
+/**
+ * Refresh the operator's Nix advisory snapshot for the given CPE identities ('vendor:product' keys or anything cpeKey accepts).
+ * Never throws. Returns a plain result; the snapshot file is rewritten only when something was read.
+ *
+ * @param {Array<string|object>} identities
+ * @param {{env?: object, fetchImpl?: Function, now?: number, dir?: string, sleep?: Function}} [opts]
+ */
+export async function refreshNixAdvisories(identities, opts = {}) {
+  const env = opts.env || process.env;
+  const cfg = { ...DEFAULTS, ...Object.fromEntries(Object.entries(opts).filter(([k]) => k in DEFAULTS)) };
+  const now = opts.now ?? Date.now();
+  const done = (r) => { last = { ...r, at: new Date(now).toISOString() }; return last; };
+
+  if (env[PINNED_ENV]) return done({ status: 'pinned-snapshot-in-use', detail: `${PINNED_ENV} names an operator snapshot; it is used as given and is not refreshed` });
+  if (env[FEED_ENV] !== '1') return done({ status: 'disabled', detail: `set ${FEED_ENV}=1 to fetch advisories for the closure's upstream software from the NVD` });
+  if (env.AGENTIC_SECURITY_OFFLINE === '1') return done({ status: 'offline', detail: 'AGENTIC_SECURITY_OFFLINE=1: no advisory data was fetched' });
+
+  const all = (identities || []).map(cpeKey);
+  const invalid = all.filter((k) => !k).length;
+  const wanted = [...new Set(all.filter(Boolean))].sort().slice(0, cfg.maxProducts);
+  if (!wanted.length) return done({ status: 'nothing-to-do', detail: invalid ? `${invalid} identity value(s) were not valid CPE vendor:product names and were not queried` : 'the closure declares no CPE identity to look up', invalid });
+
+  const path = snapshotPath(env, opts.dir);
+  const cur = readCurrent(path);
+  if (cur.foreign) return done({ status: 'operator-snapshot-in-use', detail: `${path} is an operator-written snapshot; it is used as given and the live feed does not overwrite it` });
+  const need = wanted.filter((k) => { const t = Date.parse(cur.covered[k]); return !Number.isFinite(t) || now - t > cfg.ttlMs || t > now + 3600000; });
+  if (!need.length) return done({ status: 'current', detail: `${wanted.length} identity(ies) covered within the last ${Math.round(cfg.ttlMs / 3600000)}h; no request made`, identities: wanted.length, requested: 0 });
+
+  const fetchImpl = opts.fetchImpl || globalThis.fetch;
+  if (typeof fetchImpl !== 'function') return done({ status: 'failed', detail: 'no fetch implementation is available in this runtime' });
+  const sleep = opts.sleep || sleepReal;
+  const apiKey = typeof env[KEY_ENV] === 'string' && KEY_OK.test(env[KEY_ENV]) ? env[KEY_ENV] : null;
+  const keyNote = env[KEY_ENV] && !apiKey ? ` (${KEY_ENV} is set but is not a valid key; it was ignored)` : '';
+  const headers = { 'User-Agent': 'agentic-security-advisory-feed', Accept: 'application/json', ...(apiKey ? { apiKey } : {}) };
+  const interval = apiKey ? cfg.intervalKeyedMs : cfg.intervalKeylessMs;
+  const maxRequests = apiKey ? cfg.maxRequestsKeyed : cfg.maxRequestsKeyless;
+
+  let requests = 0; let throttled = false; let dropped = 0;
+  const failures = []; const fresh = new Map();      // key -> Map(cveId -> record)
+  const request = async (url) => { if (requests > 0) await sleep(interval); requests++; return getJson(fetchImpl, url, headers, cfg.timeoutMs, cfg.maxResponseBytes); };
+
+  for (const key of need) {
+    if (throttled) { failures.push(`${key}: not queried (the service signalled a rate limit)`); continue; }
+    if (requests >= maxRequests) { failures.push(`${key}: not queried (per-scan request cap of ${maxRequests} reached; a later scan will cover it)`); continue; }
+    const recs = new Map();
+    try {
+      let start = 0; let total = null; let seen = 0;
+      for (let page = 0; page < cfg.maxPages; page++) {
+        if (page > 0 && requests >= maxRequests) throw new Error('per-scan request cap reached part-way through this identity');
+        const url = `${NVD_BASE}?virtualMatchString=${encodeURIComponent(`cpe:2.3:*:${key}`)}&resultsPerPage=${cfg.pageSize}&startIndex=${start}`;
+        const data = await request(url);
+        if (!data || typeof data !== 'object' || !Array.isArray(data.vulnerabilities) || !Number.isInteger(data.totalResults) || data.totalResults < 0 || data.startIndex !== start) throw new Error('the response is not a CVE 2.0 page for this request');
+        if (total === null) { total = data.totalResults; if (total > cfg.pageSize * cfg.maxPages) throw new Error(`${total} CVEs name this product, more than the ${cfg.pageSize * cfg.maxPages} this feed reads; not treated as covered`); }
+        else if (data.totalResults !== total) throw new Error('the result set changed while it was being read');
+        for (const v of data.vulnerabilities) {
+          const rec = nvdToOsv(v && v.cve, key);
+          if (rec) recs.set(rec.id, rec); else dropped++;
+        }
+        seen += data.vulnerabilities.length; start += data.vulnerabilities.length;
+        if (seen >= total || !data.vulnerabilities.length) break;
+      }
+      if (seen < total) throw new Error('the result set was not read to the end');
+      fresh.set(key, recs);
+    } catch (e) {
+      const http = e && e.http;
+      if (http === 403 || http === 429 || http === 503) throttled = true;
+      failures.push(`${key}: ${String((e && e.message) || e).slice(0, 100)}`);
+    }
+  }
+
+  const uncovered = need.filter((k) => !fresh.has(k));
+  if (!fresh.size) return done({ status: 'failed', detail: `the NVD feed could not be read (${failures.slice(0, 2).join('; ') || 'no response'}); ${cur.records.size ? 'the previous snapshot is used and its age is disclosed' : 'no advisory data is available'}${keyNote}`, identities: wanted.length, requested: need.length, requests, uncovered, failures: failures.slice(0, 10), throttled, cacheProblem: cur.problem });
+
+  // merge: for each fully read identity, replace what the cache held for it and keep everything else
+  const records = new Map([...cur.records].map(([id, r]) => [id, { ...r, affected: [...(r.affected || [])] }]));
+  for (const [key, recs] of fresh) {
+    for (const [id, r] of [...records]) { r.affected = r.affected.filter((a) => !(a.package && a.package.cpe === key)); if (!r.affected.length) records.delete(id); }
+    for (const [id, rec] of recs) {
+      const have = records.get(id);
+      if (have) have.affected.push(...rec.affected); else records.set(id, rec);
+    }
+  }
+  if (records.size > cfg.maxSnapshotRecords) return done({ status: 'failed', detail: `the snapshot would exceed ${cfg.maxSnapshotRecords} records; refusing to write it`, identities: wanted.length, requested: need.length, uncovered });
+  const covered = { ...cur.covered };
+  const iso = new Date(now).toISOString();
+  for (const k of fresh.keys()) covered[k] = iso;
+
+  const sorted = [...records.values()].sort((a, b) => (a.id < b.id ? -1 : 1));
+  const snap = {
+    schema: SNAPSHOT_SCHEMA, source: 'nvd-cve-2.0', generatedAt: iso, records: sorted,
+    recordHashes: Object.fromEntries(sorted.map((r) => [r.id, sha256(JSON.stringify(r))])),
+    covered: Object.fromEntries(Object.entries(covered).sort(([a], [b]) => (a < b ? -1 : 1))),
+  };
+  try {
+    const dir = opts.dir || operatorConfigDir(env);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(snap), { mode: 0o600 });
+    try { chmodSync(tmp, 0o600); } catch { /* best effort on filesystems without modes */ }
+    renameSync(tmp, path);
+  } catch (e) {
+    return done({ status: 'failed', detail: `the snapshot could not be written: ${e.code || e.message}`, identities: wanted.length, requested: need.length, uncovered });
+  }
+  return done({
+    status: uncovered.length ? 'partial' : 'refreshed',
+    detail: `${fresh.size} identity(ies) covered in ${requests} request(s)${uncovered.length ? `; ${uncovered.length} NOT covered (${uncovered.slice(0, 3).join(', ')}${uncovered.length > 3 ? ', ...' : ''}) and will be reported as unknown` : ''}${throttled ? '; the service signalled a rate limit and the run stopped' : ''}${apiKey ? '' : `; no ${KEY_ENV} set (keyless limit: 5 requests per 30 s)`}${keyNote}`,
+    identities: wanted.length, requested: need.length, requests, records: records.size, dropped, uncovered, failures: failures.slice(0, 10), throttled, path, cacheProblem: cur.problem,
+  });
+}

package/src/language/nix-fix.js

@@ -24,7 +24,8 @@ import { analyzeNixScripts } from './nix-script-taint.js';
 import { analyzeNixSecrets } from './nix-secrets.js';
 import { analyzeNixBuildTrust } from './nix-build-trust.js';
 import { analyzeNixosHardening } from './nixos-hardening.js';
-import { runFixLifecycle, unifiedDiff, writeWithBackup, undoFix } from './fix-lifecycle.js';
+import { runFixLifecycle, unifiedDiff, writeWithBackup, undoFix, isRootRelativePath } from './fix-lifecycle.js';
+import { resolveNixosConfig } from './nixos-module-resolver.js';
 import { parseFlakeLock } from './nix-inventory.js';
 
 export const NIX_FIX_VERSION = 'nix-fix/1';
@@ -55,30 +56,137 @@ const MANUAL = {
 };
 const HASH_MANUAL = new Set(['nix-fetch-missing-hash', 'nix-fetch-fake-hash', 'nix-fetch-floating-rev']);
 
-function planOptionFix(finding, files, fx, source) {
-  // `optionEvidence` is the option-level evidence a scan carries; `evidence` is that same array on a finding that comes
-  // straight from the hardening analysis (the scan's own `evidence` field is the list of detectors that agreed).
-  const evList = Array.isArray(finding.optionEvidence) ? finding.optionEvidence : (Array.isArray(finding.evidence) ? finding.evidence.filter((e) => e && typeof e === 'object') : []);
-  const evidence = evList[0] || null;
-  const option = (evidence && evidence.option) || finding.subject;
-  const winner = evidence && (evidence.sources || []).find((s) => s.role === 'winner');
-  const file = source ? source.file : (winner ? winner.file : finding.file);
-  const line = source ? source.line : (winner ? winner.line : finding.line);
-  const text = files[file];
-  if (typeof text !== 'string') return { ok: false, status: 'blocked', tier: TIERS.blocked, reason: `the defining file ${file} is not in the supplied tree` };
+// The option each hardening rule judges. Used to pick the right evidence record when a finding carries several.
+const OPTION_OF = {
+  'ssh-root-login': 'services.openssh.settings.PermitRootLogin',
+  'ssh-password-auth': 'services.openssh.settings.PasswordAuthentication',
+  'ssh-empty-passwords': 'services.openssh.settings.PermitEmptyPasswords',
+  'firewall-disabled': 'networking.firewall.enable',
+  'nix-require-sigs-disabled': 'nix.settings.require-sigs',
+  'nix-sandbox-disabled': 'nix.settings.sandbox',
+  'nix-accept-flake-config': 'nix.settings.accept-flake-config',
+};
+// The literal each rule treats as the weakness: the one a conditional branch must hold to be edited.
+const BAD_OF = { 'ssh-root-login': '"yes"', 'ssh-password-auth': 'true', 'ssh-empty-passwords': 'true', 'firewall-disabled': 'false', 'nix-require-sigs-disabled': 'false', 'nix-sandbox-disabled': 'false', 'nix-accept-flake-config': 'true' };
+const literalValue = (to) => (to.startsWith('"') ? to.slice(1, -1) : to === 'true');
+
+/** The module a human should put an override line in: the entry configuration. */
+const entryOf = (files, opts) => (opts && opts.entry) || (files['configuration.nix'] !== undefined ? 'configuration.nix' : null);
+
+/**
+ * The override line to ADD to the entry module when no definition can be edited. A plain assignment conflicts with an
+ * equal-priority definition, so the wrapper is chosen from the strongest competing priority: nothing when every
+ * definition is weaker than plain, mkForce when plain is the strongest, mkOverride just below anything stronger.
+ */
+function overrideSuggestion(option, fx, sources, files, opts) {
+  const prios = sources.map((s) => s.priority).filter((n) => Number.isFinite(n));
+  const strongest = prios.length ? Math.min(...prios) : 100;
+  const base = { file: entryOf(files, opts), option, automatic: false };
+  if (strongest > 100) return { ...base, line: `${option} = ${fx.to};`, priority: 100, note: 'every existing definition is weaker than a plain assignment, so no override wrapper is needed.' };
+  if (strongest > 50) return { ...base, line: `${option} = lib.mkForce ${fx.to};`, priority: 50, note: 'a plain assignment would conflict with the existing definition at the same priority, so mkForce is required. `lib` must be among the module arguments.' };
+  if (strongest > 1) return { ...base, line: `${option} = lib.mkOverride ${strongest - 1} ${fx.to};`, priority: strongest - 1, note: `an existing definition already uses priority ${strongest}, so the override must be stronger than it. \`lib\` must be among the module arguments.` };
+  return { ...base, line: null, priority: null, note: 'an existing definition uses the strongest possible priority; nothing can override it from another module.' };
+}
+
+const refuse = (status, reason, extra = {}) => ({ ok: false, status, tier: status === 'blocked' ? TIERS.blocked : TIERS.guidance, reason, ...extra });
+
+/**
+ * Edit the single literal that defines `option` at `file`:`line` in `text`. When several bindings share the line (the branches
+ * of one `if`), the one holding the weak literal `bad` is preferred. `skip` reports a definition that already holds the safe value.
+ */
+function literalEdit(file, text, line, option, fx, bad) {
   const parse = parseNix(text, { file });
-  if (!parse.ast) return { ok: false, status: 'blocked', tier: TIERS.blocked, reason: `${file} does not parse` };
+  if (!parse.ast) return { ok: false, reason: `${file} does not parse` };
   const ir = buildNixIR(parse, { file, source: text });
-  const cands = ir.bindings.filter((b) => b.pathText === option && b.valueSpan);
-  const hit = cands.find((b) => b.span && Math.abs(b.span.startLine - line) <= 0) || cands.find((b) => b.span && b.span.startLine <= line && b.span.endLine >= line) || (cands.length === 1 ? cands[0] : null);
-  if (!hit) return { ok: false, status: 'manual', tier: TIERS.guidance, reason: `no literal definition of ${option} was found at ${file}:${line}: it may be set by a function, an import or an attribute-set merge`, proposal: { option, set: fx.to } };
+  const re = fx.kind === 'bool' ? /\b(?:true|false)\b/g : /"(?:[^"\\]|\\.)*"/g;
+  const cands = ir.bindings.filter((b) => b.pathText === option && b.valueSpan && b.span);
+  const onLine = cands.filter((b) => b.span.startLine === line);
+  const within = cands.filter((b) => b.span.startLine <= line && b.span.endLine >= line);
+  const pool = onLine.length ? onLine : (within.length ? within : (cands.length === 1 ? cands : []));
+  const litOf = (b) => { const t = text.slice(b.valueSpan.startOffset, b.valueSpan.endOffset).match(re) || []; return t.length === 1 ? t[0] : null; };
+  const hit = (bad && pool.find((b) => litOf(b) === bad)) || pool.find((b) => litOf(b) !== null && litOf(b) !== fx.to) || pool[0] || null;
+  if (!hit) return { ok: false, reason: `no literal definition of ${option} was found at ${file}:${line}: it may be set by a function, an import or an attribute-set merge` };
   const vs = hit.valueSpan;
   const current = text.slice(vs.startOffset, vs.endOffset);
-  const re = fx.kind === 'bool' ? /\b(?:true|false)\b/g : /"(?:[^"\\]|\\.)*"/g;
   const lits = current.match(re) || [];
-  if (lits.length !== 1) return { ok: false, status: 'manual', tier: TIERS.guidance, reason: `the definition of ${option} is not a single literal (${current.slice(0, 60)}): the edit would have to choose a branch`, proposal: { option, set: fx.to } };
+  if (lits.length !== 1) return { ok: false, reason: `the definition of ${option} at ${file}:${hit.span.startLine} is not a single literal (${current.trim().slice(0, 60)}): the edit would have to choose a branch` };
+  if (lits[0] === fx.to) return { ok: true, skip: true, line: hit.span.startLine };
   const next = current.replace(re, fx.to);
-  return { ok: true, file, before: text, after: splice(text, vs.startOffset, vs.endOffset, next), ruleId: `nix-set-${option}`, label: 'FULL', explanation: `${option} = ${current.trim()} -> ${next.trim()} at ${file}:${hit.span.startLine}, the definition that wins by priority.`, consequences: fx.consequences, tier: TIERS.edit, behavior: { kind: 'option', option, from: current.trim(), to: next.trim() } };
+  return { ok: true, after: splice(text, vs.startOffset, vs.endOffset, next), from: current.trim(), to: next.trim(), line: hit.span.startLine, literal: lits[0] };
+}
+
+function planOptionFix(finding, files, fx, source, opts = {}) {
+  // `optionEvidence` is the option-level evidence a scan carries; `evidence` is that same array on a finding that comes
+  // straight from the hardening analysis (the scan's own `evidence` field is the list of detectors that agreed).
+  const evList = Array.isArray(finding.optionEvidence) ? finding.optionEvidence : (Array.isArray(finding.evidence) ? finding.evidence.filter((e) => e && typeof e === 'object') : []);
+  const evidence = evList.find((e) => e && e.option === OPTION_OF[finding.rule]) || evList[0] || null;
+  const option = (evidence && evidence.option) || finding.subject;
+  const sources = (evidence && Array.isArray(evidence.sources)) ? evidence.sources : [];
+  const bad = BAD_OF[finding.rule] || null;
+  const proposal = (extra = {}) => ({ option, set: fx.to, ...extra });
+
+  // Findings that carry no per-definition evidence keep the single-file behaviour: edit the reported line.
+  if (!sources.length) {
+    const file = source ? source.file : finding.file;
+    const line = source ? source.line : finding.line;
+    if (typeof files[file] !== 'string') return refuse('blocked', `the defining file ${file} is not in the supplied tree`);
+    const r = literalEdit(file, files[file], line, option, fx, bad);
+    if (!r.ok) return refuse(/does not parse/.test(r.reason) ? 'blocked' : 'manual', r.reason, { proposal: proposal() });
+    if (r.skip) return refuse('manual', `the definition of ${option} at ${file}:${r.line} already holds ${fx.to}`, { proposal: proposal() });
+    return optionPlanResult(option, fx, [{ file, before: files[file], after: r.after, from: r.from, to: r.to, line: r.line }], [], bad);
+  }
+
+  // Everything that contributes to the effective value: the definitions that win, and those that apply only under a
+  // condition. Definitions another one overrides do not contribute and are left alone.
+  const live = sources.filter((s) => s.role === 'winner' || s.role === 'conditional');
+  const shadowed = sources.filter((s) => s.role === 'shadowed');
+  const override = () => overrideSuggestion(option, fx, sources, files, opts);
+  if (!live.length) return refuse('manual', `no contributing definition of ${option} could be identified`, { proposal: proposal({ override: override() }) });
+
+  // The caller chose a definition that another one overrides: changing it cannot change the effective value.
+  if (source) {
+    const chosen = sources.find((s) => s.file === source.file && s.line === source.line);
+    if (chosen && chosen.role === 'shadowed') {
+      const by = live.map((w) => `${w.file}:${w.line} (${w.priorityLabel || w.priority})`).join(', ');
+      return refuse('blocked', `${source.file}:${source.line} is overridden by ${by}: editing it would leave the effective value of ${option} unchanged`, { proposal: proposal({ editInstead: live.map((w) => ({ file: w.file, line: w.line })), override: override() }) });
+    }
+  }
+
+  // Every contributing definition must be editable: inside the project, present, a single literal. Several definitions at the
+  // winning priority agree today and the module system rejects a mix, so they are all changed or none is. A conditional
+  // branch is edited only where it holds the weak literal; the verification then proves every branch is safe.
+  const working = { ...files };
+  const edits = [];
+  for (const w of live) {
+    if (!isRootRelativePath(w.file)) return refuse('manual', `the winning definition of ${option} is in ${w.file}, outside the project root, so it is not edited`, { proposal: proposal({ outsideRoot: w.file, override: override() }) });
+    if (typeof working[w.file] !== 'string') return refuse('manual', `the winning definition of ${option} is in ${w.file}, which is not in the supplied tree`, { proposal: proposal({ override: override() }) });
+    const r = literalEdit(w.file, working[w.file], w.line, option, fx, bad);
+    if (!r.ok) return refuse(/does not parse/.test(r.reason) ? 'blocked' : 'manual', r.reason, { proposal: proposal({ override: override() }) });
+    if (r.skip || (w.role === 'conditional' && bad && r.literal !== bad)) continue;
+    const prior = edits.find((e) => e.file === w.file);
+    if (prior) prior.after = r.after; else edits.push({ file: w.file, before: working[w.file], after: r.after, from: r.from, to: r.to, line: r.line });
+    working[w.file] = r.after;
+  }
+  if (!edits.length) return refuse('manual', `no contributing definition of ${option} holds the weak value, so there is nothing to edit`, { proposal: proposal({ override: override() }) });
+  return optionPlanResult(option, fx, edits, shadowed, bad);
+}
+
+function optionPlanResult(option, fx, edits, shadowed, bad = null) {
+  const first = edits[0];
+  const where = edits.map((e) => `${e.file}:${e.line}`).join(', ');
+  const multi = edits.length > 1;
+  const notes = [...fx.consequences];
+  if (shadowed.length) notes.push(`Weaker definitions of ${option} remain at ${shadowed.map((s) => `${s.file}:${s.line}`).join(', ')}; they are overridden and unchanged.`);
+  if (multi) notes.push(`${edits.length} files are edited together (${edits.map((e) => e.file).join(', ')}) because each holds a definition at the winning priority; undo restores all of them.`);
+  return {
+    ok: true, file: first.file, before: first.before, after: first.after,
+    edits: edits.map((e) => ({ file: e.file, before: e.before, after: e.after })),
+    ruleId: `nix-set-${option}`, label: 'FULL',
+    explanation: `${option} = ${first.from} -> ${first.to} at ${where}, the definition${multi ? 's' : ''} that win${multi ? '' : 's'} by priority.`,
+    consequences: notes, tier: TIERS.edit,
+    behavior: { kind: 'option', option, from: first.from, to: first.to, files: edits.map((e) => e.file) },
+    expectEffective: { option, value: literalValue(fx.to), ...(bad ? { bad: literalValue(bad) } : {}) },
+  };
 }
 
 function planTransportFix(finding, files) {
@@ -170,7 +278,7 @@ export function planNixFix(finding, files, opts = {}) {
   const r = finding.rule;
   if (r === 'nix-shell-injection' || r === 'nix-escape-wrong-context') return planShellFix(finding, files);
   if (r === 'nix-service-env-shell') return planEnvQuoteFix(finding, files);
-  if (OPTION_FIXES[r]) return planOptionFix(finding, files, OPTION_FIXES[r], opts.source || null);
+  if (OPTION_FIXES[r]) return planOptionFix(finding, files, OPTION_FIXES[r], opts.source || null, opts);
   if (TRANSPORT_RULES.has(r)) return planTransportFix(finding, files);
   if (MANUAL[r]) return { ok: false, status: 'manual', tier: TIERS.guidance, reason: 'moving a secret out of the store changes where the credential lives and who can read it: it needs a human migration, never an automatic rewrite', proposal: { steps: MANUAL[r], rotate: r !== 'nix-secret-log', manager: 'sops-nix or agenix' } };
   if (HASH_MANUAL.has(r)) return { ok: false, status: 'manual', tier: TIERS.blocked, reason: 'the correct hash or revision can only be obtained by fetching the source, which a scan never does; a placeholder hash would be a fabricated value', proposal: { steps: ['Run `nix-prefetch-url` / `nix store prefetch-file` (or build once with lib.fakeHash and read the reported hash) from a trusted machine.', 'Pin a full revision, not a branch.', 'Paste the real hash.'], neverDo: 'insert a made-up or all-zero hash' } };
@@ -193,16 +301,46 @@ export async function rescanNix(files) {
 }
 const matchKey = (f) => `${f.rule || f.cwe}|${f.subject || f.attrPath || ''}|${f.file}`;
 const syntaxGate = (plan) => {
-  const a = parseNix(plan.before, { file: plan.file }); const b = parseNix(plan.after, { file: plan.file });
-  const na = (a.errors || []).length, nb = (b.errors || []).length;
-  return { ok: !!b.ast && nb <= na, errorsBefore: na, errorsAfter: nb, detail: nb <= na ? 'no new syntax errors' : `${nb - na} new syntax error(s)` };
+  const edits = Array.isArray(plan.edits) && plan.edits.length ? plan.edits : [{ file: plan.file, before: plan.before, after: plan.after }];
+  let na = 0; let nb = 0; let ok = true;
+  for (const e of edits) {
+    const a = parseNix(e.before, { file: e.file }); const b = parseNix(e.after, { file: e.file });
+    na += (a.errors || []).length; nb += (b.errors || []).length;
+    if (!b.ast || (b.errors || []).length > (a.errors || []).length) ok = false;
+  }
+  return { ok, errorsBefore: na, errorsAfter: nb, detail: ok ? 'no new syntax errors' : `${nb - na} new syntax error(s)` };
 };
 
+/**
+ * The effective-configuration gate of an option fix. The rescan only proves a finding stopped being REPORTED, and an edit that
+ * leaves two equal-priority definitions disagreeing does that too (the module system then rejects the configuration). So the
+ * option is resolved again over the patched tree and must be a decided `set` value equal to the intended one.
+ */
+function makeEffectiveCheck(entry) {
+  return (plan, patched) => {
+    const want = plan.expectEffective;
+    if (!want) return { ok: true, ran: false, detail: 'not an option fix' };
+    const multi = Array.isArray(plan.edits) && plan.edits.length > 1;
+    if (!entry) return multi ? { ok: false, ran: false, detail: `no entry configuration was found to resolve ${want.option} over the patched tree, and ${plan.edits.length} files were edited` } : { ok: true, ran: false, detail: 'no entry configuration to resolve; the single definition was edited in place' };
+    const nixOnly = Object.fromEntries(Object.entries(patched).filter(([p, t]) => /\.nix$/.test(p) && typeof t === 'string'));
+    let res;
+    try { res = resolveNixosConfig({ entry, files: nixOnly }).lookup(want.option); } catch (e) { return { ok: false, ran: true, detail: `the patched configuration could not be resolved (${e.message})` }; }
+    // A value that depends on a condition has no single answer; the fix holds when NO branch can still produce the weak value.
+    if (res && res.status === 'conditional' && Array.isArray(res.possibleValues) && res.possibleValues.length && want.bad !== undefined) {
+      if (res.possibleValues.includes(want.bad)) return { ok: false, ran: true, option: want.option, detail: `${want.option} can still be ${JSON.stringify(want.bad)} under some condition after the patch` };
+      return { ok: true, ran: true, option: want.option, possibleValues: res.possibleValues, detail: `${want.option} is conditional and no branch can produce ${JSON.stringify(want.bad)} (possible: ${res.possibleValues.map((v) => JSON.stringify(v)).join(', ')})` };
+    }
+    if (!res || res.status !== 'set') return { ok: false, ran: true, option: want.option, status: res && res.status, detail: `${want.option} is "${res && res.status}" after the patch${res && res.reason ? ` (${res.reason})` : ''}, not a decided value` };
+    if (res.value !== want.value) return { ok: false, ran: true, option: want.option, detail: `${want.option} is ${JSON.stringify(res.value)} after the patch, not ${JSON.stringify(want.value)}` };
+    return { ok: true, ran: true, option: want.option, value: res.value, detail: `${want.option} resolves to ${JSON.stringify(res.value)} over the patched tree` };
+  };
+}
+
 /** Validate (and optionally apply) a fix through the shared lifecycle. */
 export async function validateNixFix(finding, o) {
   const plan = planNixFix(finding, o.files, o);
   if (!plan.ok) return { status: plan.status || 'unsupported', applied: false, tier: plan.tier, reason: plan.reason, proposal: plan.proposal || null, ...plan };
-  const res = await runFixLifecycle({ plan, files: o.files, finding, matchKey, rescan: o.rescan || rescanNix, syntax: syntaxGate, behaviorCheck: o.behaviorCheck, witness: o.witness, requireWitness: o.requireWitness, apply: o.apply, root: o.root });
+  const res = await runFixLifecycle({ plan, files: o.files, finding, matchKey, rescan: o.rescan || rescanNix, syntax: syntaxGate, behaviorCheck: o.behaviorCheck, effectiveCheck: makeEffectiveCheck(entryOf(o.files, o)), writeFile: o.writeFile, witness: o.witness, requireWitness: o.requireWitness, apply: o.apply, root: o.root });
   return { ...res, consequences: plan.consequences || [], tier: res.status === 'blocked' ? TIERS.blocked : plan.tier, explanation: plan.explanation };
 }
 

package/src/language/nix-ir.js

@@ -165,21 +165,23 @@ class IrBuilder {
     if (depth > this.b.maxIrDepth) { this.budget('maxIrDepth'); return []; }
     switch (n.type) {
       case 'attrset': return this.flattenAttrs(n, ctx, depth);
+      // `evalWrap` remembers the OUTERMOST let/with that wraps a leaf value (through nothing but let, with, assert and parentheses), so
+      // the module resolver can evaluate the whole wrapper with correct scoping instead of the bare body. Any other combinator clears it.
       case 'let': {
         const out = this.recordScoped(n, 'let', ctx);
-        return out.concat(this.flatten(n.body, ctx, depth + 1));
+        return out.concat(this.flatten(n.body, { ...ctx, evalWrap: ctx.evalWrap || { span: n.span, withs: ctx.withs } }, depth + 1));
       }
-      case 'with': return this.flatten(n.body, { ...ctx, withs: [...ctx.withs, this.snippet(n.env)] }, depth + 1);
-      case 'assert': return this.flatten(n.body, ctx, depth + 1);
+      case 'with': return this.flatten(n.body, { ...ctx, withs: [...ctx.withs, this.snippet(n.env)], evalWrap: ctx.evalWrap || { span: n.span, withs: ctx.withs } }, depth + 1);
+      case 'assert': return this.flatten(n.body, { ...ctx, evalWrap: ctx.evalWrap || { span: n.span, withs: ctx.withs } }, depth + 1);
       case 'if': {
         const c = { kind: 'if', span: n.cond.span, text: this.snippet(n.cond) };
-        return this.flatten(n.then, { ...ctx, conditions: [...ctx.conditions, { ...c, branch: 'then' }] }, depth + 1)
-          .concat(this.flatten(n.else, { ...ctx, conditions: [...ctx.conditions, { ...c, branch: 'else' }] }, depth + 1));
+        return this.flatten(n.then, { ...ctx, evalWrap: null, conditions: [...ctx.conditions, { ...c, branch: 'then' }] }, depth + 1)
+          .concat(this.flatten(n.else, { ...ctx, evalWrap: null, conditions: [...ctx.conditions, { ...c, branch: 'else' }] }, depth + 1));
       }
       case 'binop':
         if (n.op === '//') {
-          const left = this.flatten(n.left, ctx, depth + 1);
-          const right = this.flatten(n.right, ctx, depth + 1);
+          const left = this.flatten(n.left, { ...ctx, evalWrap: null }, depth + 1);
+          const right = this.flatten(n.right, { ...ctx, evalWrap: null }, depth + 1);
           const over = new Set();
           for (const r of right) if (r.path.length > ctx.prefix.length && r.path[ctx.prefix.length] !== null) over.add(r.path[ctx.prefix.length]);
           const kept = [];
@@ -196,17 +198,17 @@ class IrBuilder {
         const name = calleeName(fn);
         if (name === 'mkMerge' && args.length === 1 && unparen(args[0]).type === 'list') {
           let out = [];
-          for (const it of unparen(args[0]).items) out = out.concat(this.flatten(it, { ...ctx, merge: 'mkMerge' }, depth + 1));
+          for (const it of unparen(args[0]).items) out = out.concat(this.flatten(it, { ...ctx, evalWrap: null, merge: 'mkMerge' }, depth + 1));
           return out;
         }
         if (COND_WRAPPERS.has(name) && args.length === 2) {
           const cond = { kind: name, span: args[0].span, text: this.snippet(args[0]), branch: 'then' };
-          return this.flatten(args[1], { ...ctx, conditions: [...ctx.conditions, cond] }, depth + 1);
+          return this.flatten(args[1], { ...ctx, evalWrap: null, conditions: [...ctx.conditions, cond] }, depth + 1);
         }
         if (PRIORITY_WRAPPERS.has(name) && args.length >= 1) {
           // mkOverride carries its numeric priority as the first argument; keep it so the module resolver can rank it
           const priorityArg = name === 'mkOverride' && args.length >= 2 ? this.summarize(args[0]) : null;
-          return this.flatten(args[args.length - 1], { ...ctx, priority: name, priorityArg }, depth + 1);
+          return this.flatten(args[args.length - 1], { ...ctx, evalWrap: null, priority: name, priorityArg }, depth + 1);
         }
         // a file that is just `mkDerivation { ... }` / `callPackage ./x.nix { ... }`: the last attrset argument is the configuration
         if (!ctx.prefix.length && args.length) {
@@ -229,6 +231,8 @@ class IrBuilder {
       withs: ctx.withs, overridden: false, update: false, callee: ctx.callee || null,
     });
     if (rec && ctx.priorityArg) rec.priorityArg = ctx.priorityArg;
+    if (rec && ctx.evalWrap) { rec.evalSpan = ctx.evalWrap.span; rec.evalWiths = ctx.evalWrap.withs; }
+    if (rec && ctx.inRec) rec.inRec = true;
     if (rec && n.type === 'lambda') this.noteBoundaryLambda(n, ctx);
     return rec ? [rec] : [];
   }
@@ -262,7 +266,7 @@ class IrBuilder {
       if (dynamic) {
         for (const s of b.path) if (s.kind !== 'static') this.gap('dynamic-attribute', `attribute name computed at evaluation time (${this.snippet({ start: s.span.startOffset, end: s.span.endOffset }) || 'interpolated'})`, s.span);
       }
-      const sub = { ...ctx, prefix: [...ctx.prefix, ...segs], span: b.span, origin: 'attr' };
+      const sub = { ...ctx, prefix: [...ctx.prefix, ...segs], span: b.span, origin: 'attr', evalWrap: null, inRec: ctx.inRec || !!n.rec };
       out = out.concat(this.flatten(b.value, sub, depth + 1));
     }
     return out;
@@ -280,7 +284,7 @@ class IrBuilder {
         continue;
       }
       const { path: segs, dynamic } = staticPath(b.path);
-      const r = this.addBinding({ path: segs, pathText: segs.map((p) => (p === null ? '${...}' : p)).join('.'), value: this.summarize(b.value), span: b.span, valueSpan: b.value.span, origin: 'let', scope, dynamic, conditions: ctx.conditions, priority: null, merge: null, withs: ctx.withs, overridden: false, update: false });
+      const r = this.addBinding({ letSpan: n.span, path: segs, pathText: segs.map((p) => (p === null ? '${...}' : p)).join('.'), value: this.summarize(b.value), span: b.span, valueSpan: b.value.span, origin: 'let', scope, dynamic, conditions: ctx.conditions, priority: null, merge: null, withs: ctx.withs, overridden: false, update: false });
       if (r) out.push(r);
       if (dynamic) this.gap('dynamic-attribute', 'dynamic attribute name in let binding', b.span);
     }