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

package/src/language/nix-privacy.js

@@ -0,0 +1,114 @@
+// Personal data in Nix configuration (X-004 / HS-011): a `config.<module>.<field>` option whose NAME classifies as personal data
+// (PII, PHI, PCI, financial) and that is interpolated into the value of another option. Whatever the value of such an option is
+// rendered into (an /etc file, a unit's environment or script, a daemon's configuration text) ends up in the Nix store, which every
+// local user can read, so each reference is a field-to-store flow in the data flow graph.
+//
+// Honest limits:
+//   * a reference is judged by its NAME and position only; whether the option holds real personal data is not known;
+//   * a reference wrapped in a one-way or size-only function (`builtins.hashString`, `stringLength`) or only compared (`== ""`) is
+//     PROTECTED: no flow, and the protection is recorded;
+//   * credential-shaped names are the secret analyzer's (NIX-006), not this module's;
+//   * static analysis of the written expression only: nothing is evaluated.
+
+import { parseNix } from './nix-parser.js';
+import { classifyDataElementName } from '../lineage/classification.js';
+import { isLanguageExcludedPath } from './discovery.js';
+
+export const NIX_PRIVACY_VERSION = 'nix-privacy/1';
+
+const PROTECTORS = new Set(['hashString', 'hashFile', 'stringLength', 'length', 'sha256', 'sha512']);
+const COMPARISONS = new Set(['==', '!=', '<', '>', '<=', '>=']);
+const CONFIG_ROOTS = new Set(['config', 'osConfig']);
+const PERSONAL = new Set(['PII', 'PHI', 'PCI', 'FIN', 'GEOLOCATION', 'DEVICE_ID']);
+
+const staticName = (seg) => (seg && seg.kind === 'static' ? seg.name : null);
+const keyOf = (path) => (path || []).map(staticName);
+
+/** The destination a rendered value lands in, from the attribute path it is assigned to. Always the Nix store; the label says what. */
+export function destinationOf(attr) {
+  const p = attr.filter(Boolean);
+  const last = p[p.length - 1];
+  if (p[0] === 'environment' && p[1] === 'etc') return { label: `/etc/${p[2] || 'file'} (a store file)` };
+  if (p[0] === 'systemd') {
+    if (last === 'script' || /^(?:preStart|postStart|preStop|postStop|reload)$/.test(last)) return { label: 'a systemd unit script (a store file)' };
+    if (p.includes('environment') || last === 'Environment') return { label: 'a systemd unit environment (a store file)' };
+    return { label: 'a systemd unit (a store file)' };
+  }
+  if (p[0] === 'environment' && /^(?:variables|sessionVariables|shellAliases)$/.test(p[1] || '')) return { label: 'system environment variables (a store file)' };
+  if (p[0] === 'networking' && p[1] === 'extraHosts') return { label: '/etc/hosts (a store file)' };
+  if (p[0] === 'programs' && /^(?:bash|zsh|fish)$/.test(p[1] || '')) return { label: 'shell initialisation (a store file)' };
+  return { label: `option ${p.join('.')} (rendered into the Nix store)` };
+}
+
+function* children(node) {
+  if (!node || typeof node !== 'object') return;
+  for (const k of Object.keys(node)) {
+    if (k === 'span' || k === 'start' || k === 'end') continue;
+    const v = node[k];
+    if (Array.isArray(v)) { for (const x of v) if (x && typeof x === 'object') yield x; } else if (v && typeof v === 'object') yield v;
+  }
+}
+
+const calleeName = (fn) => {
+  let f = fn;
+  while (f && (f.type === 'app')) f = f.fn;
+  if (!f) return null;
+  if (f.type === 'ident') return f.name;
+  if (f.type === 'select') { const names = keyOf(f.attrpath); return names[names.length - 1] || null; }
+  return null;
+};
+
+/**
+ * @param {{files: Record<string,string>}} opts
+ * @returns {{references: object[], gaps: string[]}} one reference per (file, option, personal field) occurrence
+ */
+export function analyzeNixPersonalData(opts = {}) {
+  const references = []; const gaps = [];
+  for (const [file, text] of Object.entries(opts.files || {})) {
+    if (!/\.nix$/i.test(file) || typeof text !== 'string' || isLanguageExcludedPath(file)) continue;
+    let rec;
+    try { rec = parseNix(text, { file }); } catch (e) { gaps.push(`${file}: Nix parse failed (${String((e && e.message) || e)})`); continue; }
+    if (!rec || !rec.ast) continue;
+    const visitValue = (node, attr, line, prot) => {
+      if (!node || typeof node !== 'object') return;
+      if (node.type === 'select' && node.base && node.base.type === 'ident' && CONFIG_ROOTS.has(node.base.name)) {
+        const names = keyOf(node.attrpath);
+        if (names.length && names.every(Boolean)) {
+          const field = names[names.length - 1];
+          const classes = classifyDataElementName(field).classes.filter((c) => PERSONAL.has(c));
+          if (classes.length) references.push({ file, line, field, option: `config.${names.join('.')}`, attr, classes, protected: prot });
+        }
+        return;
+      }
+      if (node.type === 'app') {
+        const name = calleeName(node);
+        const nowProt = prot || (name && PROTECTORS.has(name));
+        // the callee chain carries no data; its arguments do
+        let f = node; const args = [];
+        while (f && f.type === 'app') { args.unshift(f.arg); f = f.fn; }
+        for (const a of args) visitValue(a, attr, line, nowProt);
+        return;
+      }
+      if (node.type === 'binop' && COMPARISONS.has(node.op)) { visitValue(node.left, attr, line, true); visitValue(node.right, attr, line, true); return; }
+      if (node.type === 'if') { visitValue(node.cond, attr, line, true); visitValue(node.then, attr, line, prot); visitValue(node.else, attr, line, prot); return; }
+      for (const c of children(node)) visitValue(c, attr, line, prot);
+    };
+    const visit = (node, attrPath) => {
+      if (!node || typeof node !== 'object') return;
+      if (node.type === 'attrset') {
+        for (const b of node.bindings || []) {
+          if (b.kind !== 'attr' || !b.value) continue;
+          const full = [...attrPath, ...keyOf(b.path)];
+          const line = (b.span && b.span.startLine) || 1;
+          // a value that is an attribute set is walked as nested configuration; anything else is a value being assigned
+          if (b.value.type === 'attrset') visit(b.value, full);
+          else { visitValue(b.value, full, line, false); for (const c of children(b.value)) visit(c, full); }
+        }
+        return;
+      }
+      for (const c of children(node)) visit(c, attrPath);
+    };
+    visit(rec.ast, []);
+  }
+  return { references, gaps };
+}

package/src/language/nix-sca.js

@@ -0,0 +1,358 @@
+// Patch-aware Nix vulnerability matching and reachability (NIX-009).
+//
+// Input is a resolved closure (nix-closure.js), pinned advisory records, optional nixpkgs metadata
+// (`knownVulnerabilities`, license, identifiers) and optional overlay/patch evidence from the Nix source.
+// The outcome for each component is one of:
+//
+//   affected             the upstream version is inside an affected range and nothing excuses it
+//   fixed                the version/revision is at or past the fix (or the overlay moves it there)
+//   backported-verified  in range, BUT a patch whose content hash is in the advisory's fix-patch list is applied
+//   possibly-affected    in range with an UNVERIFIED patch claim (a CVE-named patch file proves nothing),
+//                        or only a range overlap, or an ambiguous identity with a plausible match
+//   candidate            the upstream identity is ambiguous or name-only: matches are leads, never verdicts
+//   unknown              no usable version/identity/feed: this is NEVER reported as "not affected"
+//   not-affected         mapped, version outside every affected range
+//
+// A nixpkgs commit, a store hash or a derivation hash is never an upstream software version and is never
+// put in a query. Wrapped Haskell packages reuse the Hackage matcher (PVP ordering). Inclusion in the
+// runtime closure and Haskell import/API reachability are separate evidence tiers: a store path or a build
+// input can establish the first and never the second.
+
+import { AdvisoryDb, matchComponent as matchHackage, reachability as hackageReachability, licensePolicy, hackagePurl, normalizeAdvisory } from './haskell-sca.js';
+import { parseVersion as parsePvp } from './haskell-manifests.js';
+import { parseNix } from './nix-parser.js';
+
+export const NIX_SCA_VERSION = 'nix-sca/1';
+const HEX40 = /^[0-9a-f]{40}$/i;
+const STORE_HASH = /^[0-9a-df-np-sv-z]{32}$/;
+const UPSTREAM_NOISE = /^(?:git|unstable|master|main|HEAD|latest|unstable-\d{4}-\d{2}-\d{2})$/i;
+
+/** A nixpkgs revision, a store-path hash or a date stamp is not an upstream version. */
+export function isNotAnUpstreamVersion(v) {
+  if (typeof v !== 'string' || !v) return 'no version';
+  if (HEX40.test(v)) return 'a 40-hex string is a git revision (for example a nixpkgs commit), not a software version';
+  if (STORE_HASH.test(v)) return 'a 32-character base32 string is a store-path hash, not a software version';
+  if (/^[0-9a-f]{7,12}$/i.test(v) && /[a-f]/i.test(v)) return 'a short hexadecimal string is a revision, not a software version';
+  if (UPSTREAM_NOISE.test(v)) return `"${v}" is a moving ref, not a software version`;
+  if (!/\d/.test(v)) return `"${v}" has no numeric component`;
+  return null;
+}
+
+// ── generic version ordering for upstream software ───────────────────────────
+const PRE = /^(?:alpha|beta|rc|pre|dev|snapshot|a|b)$/i;
+function tokens(v) { return String(v).toLowerCase().replace(/^v(?=\d)/, '').split(/[^a-z0-9]+/).filter(Boolean).flatMap((t) => t.match(/\d+|[a-z]+/g) || []); }
+export function compareUpstream(a, b) {
+  const x = tokens(a), y = tokens(b);
+  const n = Math.max(x.length, y.length);
+  for (let i = 0; i < n; i++) {
+    const p = x[i], q = y[i];
+    if (p === undefined) return PRE.test(q) ? 1 : (/^\d+$/.test(q) && Number(q) === 0 ? 0 : -1);
+    if (q === undefined) return PRE.test(p) ? -1 : (/^\d+$/.test(p) && Number(p) === 0 ? 0 : 1);
+    const pn = /^\d+$/.test(p), qn = /^\d+$/.test(q);
+    if (pn && qn) { const d = Number(p) - Number(q); if (d) return d < 0 ? -1 : 1; continue; }
+    if (pn !== qn) { if (!pn && PRE.test(p)) return -1; if (!qn && PRE.test(q)) return 1; return pn ? 1 : -1; }
+    if (p !== q) return p < q ? -1 : 1;
+  }
+  return 0;
+}
+
+// ── advisories ───────────────────────────────────────────────────────────────
+const sha = (s) => String(s || '').toLowerCase().replace(/^sha256[-:]/, '');
+function eventsToRanges(events) {
+  const out = []; let lo = null;
+  for (const e of events || []) {
+    if ('introduced' in e) lo = e.introduced === '0' ? null : e.introduced;
+    else if ('fixed' in e) { out.push({ lo, hi: e.fixed, hiInc: false }); lo = null; }
+    else if ('last_affected' in e) { out.push({ lo, hi: e.last_affected, hiInc: true }); lo = null; }
+  }
+  if (events && events.some((e) => 'introduced' in e) && (lo !== null || !out.length || !events.some((e) => 'fixed' in e || 'last_affected' in e))) out.push({ lo, hi: null, hiInc: false });
+  return out;
+}
+const inRange = (v, r) => (r.lo === null || compareUpstream(v, r.lo) >= 0) && (r.hi === null || (r.hiInc ? compareUpstream(v, r.hi) <= 0 : compareUpstream(v, r.hi) < 0));
+
+/** Normalize a non-Hackage OSV-style record into what Nix matching needs. */
+export function normalizeGenericAdvisory(rec) {
+  if (!rec || typeof rec.id !== 'string') return null;
+  const aliases = [...new Set((rec.aliases || []).filter((x) => typeof x === 'string'))];
+  const affected = [];
+  for (const a of rec.affected || []) {
+    if (!a || !a.package) continue;
+    const ranges = (a.ranges || []).filter((r) => r.type !== 'GIT').flatMap((r) => eventsToRanges(r.events));
+    const git = (a.ranges || []).filter((r) => r.type === 'GIT').map((r) => ({ repo: r.repo || null, events: r.events || [] }));
+    affected.push({
+      ecosystem: a.package.ecosystem || null, name: a.package.name || null, purl: a.package.purl || null, cpe: a.package.cpe || null,
+      ranges, versions: Array.isArray(a.versions) ? a.versions : [], git,
+      fixedIn: [...new Set((a.ranges || []).flatMap((r) => (r.events || []).filter((e) => 'fixed' in e).map((e) => e.fixed)))],
+      fixPatches: ((a.database_specific && a.database_specific.fix_patches) || (rec.database_specific && rec.database_specific.fix_patches) || []).map((p) => ({ name: p.name || null, sha256: p.sha256 ? sha(p.sha256) : null })),
+    });
+  }
+  return { id: rec.id, ids: [rec.id, ...aliases], cves: [rec.id, ...aliases].filter((x) => /^CVE-/.test(x)), summary: rec.summary || '', withdrawn: rec.withdrawn || null, published: rec.published || null, modified: rec.modified || null, references: (rec.references || []).map((r) => r.url).filter(Boolean), affected };
+}
+
+export class NixAdvisoryData {
+  constructor({ records = [], hackage = null, source = 'records', generatedAt = null, now = Date.now(), maxAgeDays = 30 } = {}) {
+    this.source = source; this.generatedAt = generatedAt; this.maxAgeDays = maxAgeDays;
+    this.records = records.map(normalizeGenericAdvisory).filter(Boolean);
+    this.hackage = hackage;                      // an AdvisoryDb (HS-009) for wrapped Haskell packages
+    const gen = generatedAt ? Date.parse(generatedAt) : NaN;
+    this.ageDays = Number.isFinite(gen) ? (now - gen) / 86400000 : null;
+    this.stale = this.ageDays === null ? true : this.ageDays > maxAgeDays;
+    this.feed = { source, generatedAt, status: this.stale ? 'stale-cache' : 'current', records: this.records.length };
+  }
+}
+
+// ── upstream identity ────────────────────────────────────────────────────────
+const HASKELL_ENV_HINTS = ['libraryHaskellDepends', 'setupHaskellDepends', 'executableHaskellDepends', 'isLibrary', 'isExecutable', 'enableSeparateDataOutput', 'compilerName', 'enableLibraryProfiling'];
+function purlFromUrl(u) {
+  const m = /^https?:\/\/(?:www\.)?github\.com\/([^/]+)\/([^/#?]+?)(?:\.git)?(?:\/|$)/.exec(u || '');
+  if (m) return { purl: `pkg:github/${m[1].toLowerCase()}/${m[2].toLowerCase()}`, host: 'github' };
+  const g = /^https?:\/\/gitlab\.com\/([^/]+)\/([^/#?]+?)(?:\.git)?(?:\/|$)/.exec(u || '');
+  if (g) return { purl: `pkg:gitlab/${g[1].toLowerCase()}/${g[2].toLowerCase()}`, host: 'gitlab' };
+  return null;
+}
+
+/**
+ * The identity a component can be matched under. Never invents authority: `explicit` needs the package
+ * metadata to say so, `src-derived` needs a recognised source host, anything else is `name-only`.
+ */
+export function upstreamIdentity(node, drvEnv, meta, overlay) {
+  const cands = [];
+  const version = (overlay && overlay.version) || node.version;
+  const vguard = isNotAnUpstreamVersion(version);
+  const base = { pname: node.pname, version: vguard ? null : version, versionRejected: vguard || null, versionSource: overlay && overlay.version ? 'overlay' : node.versionAuthority };
+  const isHs = drvEnv && HASKELL_ENV_HINTS.some((k) => k in drvEnv);
+  if (isHs && node.pname) cands.push({ ecosystem: 'Hackage', name: node.pname, purl: hackagePurl(node.pname, base.version), authority: 'explicit', basis: 'Haskell build attributes in the derivation' });
+  const ids = meta && meta.identifiers ? meta.identifiers : null;
+  if (ids && typeof ids.purl === 'string') cands.push({ purl: ids.purl, authority: 'explicit', basis: 'meta.identifiers.purl' });
+  const cpes = ids ? [].concat(ids.cpe || [], ids.possibleCPEs || [], ids.v1 && ids.v1.cpeParts ? [ids.v1.cpeParts] : []).filter(Boolean) : [];
+  const cpeStrings = cpes.map((c) => (typeof c === 'string' ? c : (c.vendor && c.product ? `${c.vendor}:${c.product}` : null))).filter(Boolean);
+  const uniqueCpe = [...new Set(cpeStrings)];
+  if (uniqueCpe.length === 1 && ids && ids.cpe && !ids.possibleCPEs) cands.push({ cpe: uniqueCpe[0], authority: 'explicit', basis: 'meta.identifiers.cpe' });
+  else for (const c of uniqueCpe) cands.push({ cpe: c, authority: 'candidate', basis: uniqueCpe.length > 1 ? 'one of several possible CPEs' : 'possible CPE' });
+  for (const u of (node.upstream && node.upstream.urls) || []) { const p = purlFromUrl(u); if (p) cands.push({ purl: p.purl, authority: 'src-derived', basis: `source URL host ${p.host}` }); }
+  if (meta && meta.homepage) { const p = purlFromUrl(meta.homepage); if (p) cands.push({ purl: p.purl, authority: 'src-derived', basis: 'meta.homepage' }); }
+  if (!cands.some((c) => c.authority === 'explicit' || c.authority === 'src-derived') && node.pname) cands.push({ name: node.pname, authority: 'name-only', basis: 'store/derivation name only' });
+  const uniq = []; const seen = new Set();
+  for (const c of cands) { const k = JSON.stringify([c.ecosystem, c.name, c.purl, c.cpe, c.authority]); if (!seen.has(k)) { seen.add(k); uniq.push(c); } }
+  const strong = uniq.filter((c) => c.authority === 'explicit' || c.authority === 'src-derived');
+  const distinctTargets = new Set(strong.map((c) => c.purl || c.cpe || `${c.ecosystem}:${c.name}`));
+  return { ...base, candidates: uniq, ambiguous: distinctTargets.size > 1 || (strong.length === 0 && uniq.length > 1) || uniq.some((c) => c.authority === 'candidate'), authority: strong.length && distinctTargets.size === 1 && !uniq.some((c) => c.authority === 'candidate') ? strong[0].authority : (uniq[0] ? 'name-only' : 'none'), haskell: !!isHs };
+}
+
+// ── overlays and patches ─────────────────────────────────────────────────────
+const segName = (s) => (s && s.kind === 'static' ? s.name : null);
+const unparen = (n) => { let x = n; while (x && x.type === 'paren') x = x.expr; return x; };
+
+/** pname -> {version?, patches:[{name,source,sha256?,url?}], file, line} from overlay `overrideAttrs` calls. */
+export function overlayEvidence(files) {
+  const out = {};
+  for (const [file, text] of Object.entries(files || {})) {
+    if (!/\.nix$/i.test(file) || typeof text !== 'string') continue;
+    const parse = parseNix(text, { file });
+    if (!parse.ast) continue;
+    const stack = [parse.ast];
+    while (stack.length) {
+      const n = stack.pop();
+      if (!n || typeof n !== 'object') continue;
+      if (n.type === 'attrset') {
+        for (const b of n.bindings || []) {
+          if (b.kind !== 'attr' || !b.value) continue;
+          const key = (b.path || []).map(segName);
+          if (key.length !== 1 || !key[0]) continue;
+          const call = unparen(b.value);
+          if (!call || call.type !== 'app') continue;
+          const fn = unparen(call.fn);
+          const last = fn && fn.type === 'select' ? segName(fn.attrpath[fn.attrpath.length - 1]) : null;
+          if (last !== 'overrideAttrs') continue;
+          const rec = out[key[0]] || (out[key[0]] = { patches: [], file, line: b.span ? b.span.startLine : null, mechanism: 'overlay-overrideAttrs' });
+          let body = unparen(call.arg);
+          while (body && body.type === 'lambda') body = unparen(body.body);
+          if (body && body.type === 'attrset') {
+            for (const ob of body.bindings) {
+              if (ob.kind !== 'attr') continue;
+              const k = (ob.path || []).map(segName).join('.');
+              if (k === 'version') { const v = unparen(ob.value); if (v && v.literal !== undefined) rec.version = v.literal; }
+              if (k === 'patches') collectPatches(ob.value, rec.patches);
+            }
+          }
+        }
+      }
+      for (const k of Object.keys(n)) { const c = n[k]; if (c && typeof c === 'object') { if (Array.isArray(c)) stack.push(...c); else stack.push(c); } }
+    }
+  }
+  return out;
+}
+function collectPatches(node, acc) {
+  const n = unparen(node);
+  if (!n) return;
+  if (n.type === 'list') for (const it of n.items) collectPatches(it, acc);
+  else if (n.type === 'binop') { collectPatches(n.left, acc); collectPatches(n.right, acc); }
+  else if (n.type === 'path' && n.literal) acc.push({ name: String(n.literal).replace(/^.*\//, ''), source: 'path', sha256: null });
+  else if (n.type === 'app') {
+    const flat = []; let f = n; while (f && f.type === 'app') { flat.unshift(f.arg); f = unparen(f.fn); }
+    const nm = f && f.type === 'select' ? segName(f.attrpath[f.attrpath.length - 1]) : (f && f.type === 'ident' ? f.name : null);
+    if (nm === 'fetchpatch' || nm === 'fetchpatch2') {
+      const a = unparen(flat[0]); let url = null; let hash = null;
+      if (a && a.type === 'attrset') for (const b of a.bindings) { if (b.kind !== 'attr') continue; const k = (b.path || []).map(segName).join('.'); const v = unparen(b.value); if (k === 'url' && v) url = v.literal ?? null; if ((k === 'sha256' || k === 'hash') && v) hash = v.literal ?? null; }
+      acc.push({ name: url ? url.replace(/[?#].*$/, '').replace(/^.*\//, '') : 'fetchpatch', source: 'fetchpatch', url, sha256: hash ? sha(hash) : null });
+    }
+  }
+}
+
+// ── matching ─────────────────────────────────────────────────────────────────
+const CVE_IN_NAME = /CVE-\d{4}-\d{4,}/i;
+function patchEvidence(patches, advisory, aff) {
+  const claims = []; let verified = null;
+  const fixHashes = new Set((aff.fixPatches || []).map((p) => p.sha256).filter(Boolean));
+  const fixNames = new Set((aff.fixPatches || []).map((p) => p.name).filter(Boolean));
+  for (const p of patches || []) {
+    const cveInName = (CVE_IN_NAME.exec(p.name || '') || [])[0];
+    const namesThis = cveInName && advisory.ids.some((i) => i.toUpperCase() === cveInName.toUpperCase());
+    if (p.sha256 && fixHashes.has(sha(p.sha256))) { verified = verified || { patch: p.name, by: 'content hash matches an advisory fix patch' }; continue; }
+    if (namesThis || (p.name && fixNames.has(p.name))) claims.push({ patch: p.name, claim: namesThis ? `named after ${cveInName}` : 'name matches an advisory fix patch', verified: false, why: p.sha256 ? 'its content hash is not one the advisory lists' : 'no content hash: a file name proves nothing about what the patch does' });
+  }
+  return { verified, claims };
+}
+
+function genericMatch(adv, aff, ident, node, patches) {
+  const v = ident.version;
+  const out = { status: 'unknown', reason: '' };
+  if (aff.git.length && node.upstream && node.upstream.rev) {
+    const rev = node.upstream.rev.toLowerCase();
+    const fixed = aff.git.flatMap((g) => g.events.filter((e) => 'fixed' in e).map((e) => String(e.fixed).toLowerCase()));
+    const listed = new Set([...(aff.versions || []).map((x) => String(x).toLowerCase()), ...aff.git.flatMap((g) => g.events.filter((e) => 'introduced' in e || 'last_affected' in e).map((e) => String(e.introduced ?? e.last_affected).toLowerCase()))]);
+    if (fixed.includes(rev)) return { status: 'fixed', reason: 'the source revision is the advisory fix commit' };
+    if ([...listed].includes(rev)) return { status: 'affected', reason: 'the source revision is an affected commit listed by the advisory' };
+    out.reason = 'the source revision is neither the fix nor a listed affected commit; commit ordering is not available, so no verdict';
+    if (!v) return out;
+  }
+  if (!v) return { status: 'unknown', reason: ident.versionRejected || 'no upstream version' };
+  let inside = aff.ranges.some((r) => inRange(v, r));
+  if (!inside && aff.versions.some((x) => compareUpstream(v, x) === 0)) inside = true;
+  if (!aff.ranges.length && !aff.versions.length) return { status: 'unknown', reason: 'the advisory has no version information for this package' };
+  if (inside) return { status: 'affected', reason: 'the version is inside an affected range' };
+  if ((aff.fixedIn || []).some((f) => compareUpstream(v, f) >= 0)) return { status: 'fixed', reason: `the version is at or past the fix (${aff.fixedIn.join(', ')})` };
+  return { status: 'not-affected', reason: 'the version is outside every affected range' };
+}
+
+/**
+ * @param {{closure: object, data: NixAdvisoryData|null, meta?: Record<string,object>, overlays?: object,
+ *          haskellUsage?: {imports: object[], callees: Set<string>}, services?: Array<{service:string, packages:string[]}>,
+ *          symbols?: Record<string,string[]>, kev?: Set<string>|null, epss?: Record<string,number>|null,
+ *          licensePolicy?: object, drvEnv?: Record<string,object>}} opts
+ *   meta is keyed by derivation name or pname; drvEnv by derivation path (the env block of the drv show export).
+ */
+export function matchNixVulnerabilities(opts = {}) {
+  const { closure, data = null, meta = {}, overlays = {}, haskellUsage = null, services = [], symbols = {}, kev = null, epss = null } = opts;
+  const findings = []; const statuses = [];
+  const feed = data ? data.feed : { source: null, generatedAt: null, status: 'feed-unavailable', records: 0 };
+  const nodes = (closure && closure.nodes) || [];
+  const byId = new Map(nodes.map((n) => [n.id, n]));
+  // one subject per derivation: its outputs are one build
+  const subjects = new Map();
+  const roots = new Set((closure && closure.roots) || []);
+  for (const n of nodes) {
+    if (n.kind !== 'output' || roots.has(n.id)) continue;      // the target itself is not a dependency of itself
+    const key = n.deriver || n.id;
+    if (!subjects.has(key)) subjects.set(key, { drv: n.deriver || null, outputs: [], node: n });
+    const s = subjects.get(key); s.outputs.push(n);
+    if (n.outputName === 'out' || (s.node.outputName !== 'out' && n.scopes.includes('runtime'))) s.node = n;
+  }
+  const summary = { components: 0, matched: 0, mappedNoMatch: 0, unmapped: 0, candidates: 0 };
+  for (const s of subjects.values()) {
+    const node = s.node;
+    const env = (opts.drvEnv && s.drv && opts.drvEnv[s.drv]) || null;
+    const m = meta[node.pname] || meta[node.storeName] || null;
+    const ov = overlays[node.pname] || null;
+    const patches = [...(node.patches || []), ...((ov && ov.patches) || [])];
+    const ident = upstreamIdentity(node, env, m, ov);
+    summary.components++;
+    const nixBuild = { derivation: s.drv, outputs: s.outputs.map((o) => ({ name: o.outputName, path: o.id })), system: node.system, storeHash: node.hash, patches: patches.map((p) => ({ name: p.name, source: p.source || 'derivation', sha256: p.sha256 || null })), overlay: ov ? { file: ov.file, line: ov.line, versionOverride: ov.version || null } : null, scopes: node.scopes };
+    const inclusion = node.scopes.includes('runtime') ? 'runtime-closure' : (node.scopes.length ? 'build-only' : 'unknown');
+    const svc = services.filter((x) => x.packages.some((p) => p === node.pname || p === node.storeName)).map((x) => x.service);
+    const tiers = { inclusion, services: svc, reachability: { import: 'unknown', function: 'unknown', basis: 'a store path or a build input proves inclusion only, never that code is called' } };
+    const base = { name: node.pname, version: ident.version, nixBuild, identity: { authority: ident.authority, candidates: ident.candidates, versionSource: ident.versionSource, versionRejected: ident.versionRejected }, tiers, feed };
+    const push = (st, extra = {}) => statuses.push({ ...base, status: st.status, reason: st.reason, ...extra });
+
+    // knownVulnerabilities marked by nixpkgs themselves
+    const kvs = (m && Array.isArray(m.knownVulnerabilities) ? m.knownVulnerabilities : []).filter((x) => typeof x === 'string');
+    for (const kv of kvs) findings.push(finding(base, { id: `nixpkgs:knownVulnerabilities:${node.pname}`, ids: [kv.match(CVE_IN_NAME) ? kv.match(CVE_IN_NAME)[0] : `nixpkgs-known-vulnerable:${node.pname}`], summary: kv }, 'affected', 'nixpkgs marks this package with knownVulnerabilities', { source: 'nixpkgs-meta', ghc: false }, { kev, epss }));
+    if (!data) { push({ status: 'unknown', reason: 'no advisory feed was supplied: absence of a match is not a clean result' }); summary.unmapped++; continue; }
+    if (ident.versionRejected && !ident.haskell && !(node.upstream && node.upstream.rev)) { push({ status: 'unknown', reason: `the version cannot be queried: ${ident.versionRejected}` }); summary.unmapped++; continue; }
+
+    let matched = false; let mapped = false;
+    // Hackage (wrapped Haskell packages): reuse the PVP matcher
+    if (ident.haskell && data.hackage && ident.version && parsePvp(ident.version)) {
+      mapped = true;
+      for (const { adv, aff } of data.hackage.forPackage(node.pname)) {
+        if (adv.withdrawn) continue;
+        const r = matchHackage(aff, { name: node.pname, version: ident.version });
+        if (r.status === 'not-affected') continue;
+        const pe = patchEvidence(patches, { ids: adv.ids }, { fixPatches: [] });
+        const st = decide(r, pe, ident);
+        matched = true;
+        if (haskellUsage) { const rr = hackageReachability(node.pname, haskellUsage.imports, haskellUsage.callees, symbols[adv.id] || null); tiers.reachability = { import: rr.import, function: rr.function, basis: rr.reason }; }
+        findings.push(finding({ ...base, tiers: { ...tiers } }, { id: adv.canonicalId, ids: adv.ids, summary: adv.summary, cves: adv.cveAliases }, st.status, st.reason, { source: data.hackage.source, ecosystem: 'Hackage', fixedIn: aff.fixedIn, patchEvidence: pe }, { kev, epss }));
+      }
+    }
+    // generic records by PURL / CPE; only authoritative identities are matched, candidates are leads
+    for (const adv of data.records) {
+      for (const aff of adv.affected) {
+        const target = ident.candidates.find((c) => (c.purl && aff.purl && c.purl === aff.purl) || (c.cpe && aff.cpe && c.cpe === aff.cpe) || (c.name && aff.name && !aff.purl && !aff.cpe && c.name === aff.name && c.authority === 'name-only') || (c.ecosystem === 'Hackage' && aff.ecosystem === 'Hackage' && c.name === aff.name));
+        if (!target) continue;
+        if (aff.ecosystem === 'Hackage') continue;                   // handled above
+        mapped = mapped || target.authority === 'explicit' || target.authority === 'src-derived';
+        const gm = genericMatch(adv, aff, ident, node, patches);
+        if (gm.status === 'not-affected' && target.authority !== 'candidate' && target.authority !== 'name-only') continue;
+        const pe = patchEvidence(patches, adv, aff);
+        let st = gm.status === 'affected' ? decide(gm, pe, ident) : gm;
+        // identity gate: only an authoritative, unambiguous identity may produce a firm verdict
+        if (target.authority === 'candidate' || target.authority === 'name-only' || ident.ambiguous) {
+          st = { status: gm.status === 'affected' || gm.status === 'possibly-affected' ? 'candidate' : (gm.status === 'fixed' ? 'candidate' : gm.status === 'not-affected' ? 'unknown' : gm.status), reason: `${gm.reason}; the upstream identity is ${target.authority === 'candidate' ? 'ambiguous (several possible CPEs)' : 'name-only'}, so this is a lead, not a verdict` };
+          summary.candidates++;
+        }
+        matched = true;
+        findings.push(finding({ ...base, tiers: { ...tiers } }, adv, st.status, st.reason, { source: data.source, ecosystem: aff.ecosystem, fixedIn: aff.fixedIn, patchEvidence: pe, identityBasis: target.basis, identityAuthority: target.authority }, { kev, epss }));
+      }
+    }
+    if (matched) summary.matched++;
+    else if (mapped) { summary.mappedNoMatch++; push({ status: 'not-affected', reason: 'mapped to an upstream identity and no advisory in the supplied feed matches this version' }, { identityMapped: true }); }
+    else { summary.unmapped++; push({ status: 'unknown', reason: ident.ambiguous ? 'the upstream identity is ambiguous: no verdict' : 'the upstream identity could not be mapped to anything an advisory is keyed by' }, { identityMapped: false }); }
+  }
+  return { version: NIX_SCA_VERSION, findings, statuses, feed, summary, licenses: licenseReport(nodes.filter((n) => !roots.has(n.id)), meta, opts.licensePolicy) };
+}
+
+function decide(r, pe, ident) {
+  if (r.status === 'possibly-affected') return { status: 'possibly-affected', reason: r.reason };
+  if (pe.verified) return { status: 'backported-verified', reason: `in the affected range, but ${pe.verified.by} (${pe.verified.patch})` };
+  if (pe.claims.length) return { status: 'possibly-affected', reason: `in the affected range with an UNVERIFIED patch claim (${pe.claims[0].patch}: ${pe.claims[0].why})` };
+  return { status: 'affected', reason: r.reason };
+}
+
+function finding(base, adv, status, reason, extra, { kev, epss }) {
+  const cves = adv.cves || (adv.ids || []).filter((x) => /^CVE-/.test(x));
+  const kevHit = cves.length ? (kev ? cves.some((c) => kev.has(c)) : 'unknown') : 'not-applicable';
+  const ep = cves.map((c) => epss && epss[c]).filter((x) => typeof x === 'number');
+  const level = { affected: 'high', 'possibly-affected': 'medium', candidate: 'low', 'backported-verified': 'info', fixed: 'info', unknown: 'low', 'not-affected': 'info' }[status] || 'low';
+  return {
+    type: 'vulnerable_dep', ecosystem: 'nix', language: 'nix', capability: 'sca', analysisKind: 'application', evidenceKind: 'closure',
+    name: base.name, version: base.version, osvId: adv.id, ids: adv.ids || [adv.id], cveAliases: cves, summary: adv.summary || '',
+    status, matchStatus: status, matchReason: reason, severity: level, severityBasis: 'the advisory carries no severity rating',
+    nixBuild: base.nixBuild, identity: base.identity, tiers: base.tiers, feed: base.feed,
+    kev: kevHit, epss: ep.length ? Math.max(...ep) : 'unknown',
+    fixedIn: extra.fixedIn || [], patchEvidence: extra.patchEvidence || { verified: null, claims: [] }, dataSource: { feed: extra.source || base.feed.source, ecosystem: extra.ecosystem || null, identityBasis: extra.identityBasis || null, identityAuthority: extra.identityAuthority || null, feedStatus: base.feed.status },
+    file: null, line: null, vuln: `Vulnerable package in the Nix closure (${status})`, cwe: 'CWE-1104', parser: 'NIX-SCA', family: 'sca',
+    description: `${base.name}${base.version ? ` ${base.version}` : ''} (${adv.id}): ${reason}.`,
+    remediation: (extra.fixedIn && extra.fixedIn.length) ? `Update ${base.name} to ${extra.fixedIn.join(' or ')} (override the input or overlay), then regenerate the closure export.` : 'No fixed version is recorded in the advisory data.',
+    confidence: status === 'affected' ? 0.85 : status === 'possibly-affected' ? 0.5 : 0.3,
+  };
+}
+
+function licenseReport(nodes, meta, policy) {
+  const comps = nodes.filter((n) => n.kind === 'output' && (n.outputName === 'out' || !n.outputName)).map((n) => ({ name: n.pname, version: n.version }));
+  const md = {};
+  for (const c of comps) { const m = meta[c.name]; if (m && m.license) md[c.name] = { license: typeof m.license === 'string' ? m.license : (m.license.spdxId || m.license.shortName || null) }; }
+  return licensePolicy(comps, md, policy);
+}
+
+export { AdvisoryDb, normalizeAdvisory };