@clear-capabilities/agentic-security-scanner 0.128.1 → 0.132.0

package/src/posture/relevance.js

@@ -0,0 +1,379 @@
+// R6 (threat-model-first scoping) + R9 (attack-surface-forward analysis).
+//
+// Every other precision mechanism in this engine kills a false positive by
+// PATTERN — a sanitizer on the path, a proof that didn't reproduce, a
+// confidence model fit to labelled families. This module kills one by
+// RELEVANCE: a finding sitting on a path an attacker can actually reach,
+// inside something the threat model says is worth attacking, matters more
+// than one that is neither. It is a different axis, and it composes with
+// (never replaces) the sink-driven taint engine.
+//
+//   R9 — start at the attack surface and reason FORWARD. `entrypoint-
+//        inventory.js` already enumerates every attacker-reachable entry
+//        point (HTTP/queue/cron/CLI/env/upload/webhook). Here that inventory
+//        stops being a report and starts being an input: we walk the module
+//        import graph out from every entry-point file and record which files
+//        are reachable from the attack surface at all.
+//   R6 — `threat-model.js` already derives assets, trust boundaries and a
+//        STRIDE classification. Here that model re-ranks: a finding on a
+//        modelled asset, or one classified into a modelled STRIDE bucket,
+//        outranks an identical finding that is in neither.
+//
+// ── Recall-preserving contract (non-negotiable) ────────────────────────────
+// Same precedent as `falsification.js` and `dataflow/proof-gate.js`:
+//   • Never removes a finding. The array in is the array out, same length,
+//     same order, same objects.
+//   • Never touches `severity`. Ever. Severity is the customer's triage
+//     contract; relevance is an ordinal re-rank underneath it.
+//   • Never asserts `unreachable` without POSITIVE evidence. "I could not
+//     determine it" is `entrypointReachable: null` / `relevanceTier:
+//     'unknown'` — a distinct state from "I determined it is not reachable".
+//     A negative verdict additionally requires the intra-repo import graph to
+//     be provably COMPLETE: one unresolved relative import anywhere means the
+//     graph has a hole an attacker's path could be hiding in, and every
+//     would-be `unreachable` degrades to `unknown`.
+//   • Demotion has a floor. An unreachable finding's exploitability is scaled,
+//     never zeroed — a wrong reachability call must cost rank, not visibility.
+//
+// Fields set on each finding:
+//   entrypointReachable : true | false | null   (null ≠ false)
+//   relevance           : number 0..1
+//   relevanceTier       : 'direct' | 'indirect' | 'unreachable' | 'unknown'
+//   relevanceFactors    : string[]  (human-readable, like exploitabilityFactors)
+
+// ── Tunables ───────────────────────────────────────────────────────────────
+const BASE_SCORE = {
+  direct: 0.75,
+  indirect: 0.50,
+  unreachable: 0.15,
+  unknown: 0.40,
+};
+// Cap so that no accumulation of R6 bonuses can push an evidenced-unreachable
+// finding into the same band as a reachable one.
+const UNREACHABLE_CAP = 0.30;
+
+// Exploitability re-rank multipliers (R6's "re-rank exploitability").
+const EXPLOIT_MULT = { direct: 1.15, indirect: 1.0, unreachable: 0.6, unknown: 1.0 };
+const EXPLOIT_FLOOR = 0.05;   // demotion never zeroes a finding out
+
+const IMPORT_EXTS = ['', '.js', '.mjs', '.cjs', '.jsx', '.ts', '.tsx', '/index.js', '/index.ts', '/index.mjs'];
+const MAX_FILES = 5000;       // graph-size guard: bail to 'unknown' beyond this
+
+// ── Source-level import extraction ─────────────────────────────────────────
+// Static, literal specifiers only. Anything non-literal is recorded as a hole.
+const RE_IMPORT_FROM = /\bimport\s[^;'"`]*?from\s*['"]([^'"]+)['"]/g;
+const RE_IMPORT_BARE = /\bimport\s*['"]([^'"]+)['"]/g;
+const RE_EXPORT_FROM = /\bexport\s[^;'"`]*?from\s*['"]([^'"]+)['"]/g;
+const RE_REQUIRE = /\brequire\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+const RE_DYN_IMPORT = /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+const RE_PY_FROM = /^\s*from\s+([.\w]+)\s+import\s/gm;
+const RE_PY_IMPORT = /^\s*import\s+([.\w]+)/gm;
+const RE_JAVA_IMPORT = /^\s*import\s+(?:static\s+)?([\w.]+);/gm;
+// Non-literal module loads: the graph cannot see through these.
+const RE_DYNAMIC_HOLE = /\brequire\s*\(\s*[^'")\s]|\bimport\s*\(\s*[^'")\s]/;
+
+function _entries(fileContents) {
+  if (!fileContents) return [];
+  if (fileContents instanceof Map) {
+    return [...fileContents.entries()].filter(([k, v]) => typeof k === 'string' && typeof v === 'string');
+  }
+  if (typeof fileContents === 'object') {
+    return Object.entries(fileContents).filter(([k, v]) => typeof k === 'string' && typeof v === 'string');
+  }
+  return [];
+}
+
+function _norm(p) {
+  const parts = String(p).replace(/\\/g, '/').split('/');
+  const out = [];
+  for (const seg of parts) {
+    if (seg === '' || seg === '.') continue;
+    if (seg === '..') { out.pop(); continue; }
+    out.push(seg);
+  }
+  return out.join('/');
+}
+
+function _dirOf(file) {
+  const i = String(file).replace(/\\/g, '/').lastIndexOf('/');
+  return i < 0 ? '' : String(file).slice(0, i);
+}
+
+// Resolve one specifier to a key in `known`. Returns the key, or null.
+function _resolve(spec, fromFile, known, suffixIndex) {
+  if (!spec) return null;
+  const relative = spec.startsWith('.');
+  const base = relative ? _norm(`${_dirOf(fromFile)}/${spec}`) : null;
+
+  if (relative) {
+    for (const ext of IMPORT_EXTS) {
+      const cand = base + ext;
+      if (known.has(cand)) return cand;
+    }
+    // Also try the raw (already-extensioned) form as written.
+    if (known.has(base)) return base;
+    return null;
+  }
+
+  // Non-relative: python dotted module, java FQCN, or a bare package name.
+  const dotted = spec.replace(/\./g, '/');
+  for (const ext of ['.py', '.java', '.js', '.ts', '/__init__.py']) {
+    const hit = suffixIndex.get(dotted + ext);
+    if (hit) return hit;
+  }
+  return null;
+}
+
+/**
+ * Build the attack-surface reachability view.
+ *
+ * @returns {{
+ *   entryFiles: Set<string>, unauthEntryFiles: Set<string>,
+ *   reachableFiles: Set<string>, knownFiles: Set<string>,
+ *   graphComplete: boolean, holes: number,
+ * }}
+ */
+function buildReachabilityGraph(fileContents, opts = {}) {
+  const knownFiles = new Set();
+  const entryFiles = new Set();
+  const unauthEntryFiles = new Set();
+  const reachableFiles = new Set();
+  let graphComplete = false;
+  let holes = 0;
+
+  try {
+    const files = _entries(fileContents);
+    if (files.length === 0 || files.length > MAX_FILES) {
+      return { entryFiles, unauthEntryFiles, reachableFiles, knownFiles, graphComplete: false, holes: 1 };
+    }
+    for (const [k] of files) knownFiles.add(k);
+
+    // Index by path suffix so a python/java module name can find its file.
+    const suffixIndex = new Map();
+    for (const k of knownFiles) {
+      const norm = k.replace(/\\/g, '/');
+      const segs = norm.split('/');
+      for (let i = 0; i < segs.length; i++) {
+        const suf = segs.slice(i).join('/');
+        if (!suffixIndex.has(suf)) suffixIndex.set(suf, k);
+      }
+    }
+
+    // 1) Entry-point files, from the inventory and/or the raw route list.
+    const inv = opts.entrypointInventory;
+    const invEntries = inv && Array.isArray(inv.entrypoints) ? inv.entrypoints
+      : Array.isArray(opts.entrypoints) ? opts.entrypoints : [];
+    for (const e of invEntries) {
+      if (!e || typeof e.file !== 'string' || !e.file) continue;
+      entryFiles.add(e.file);
+      if (e.trust !== 'authenticated') unauthEntryFiles.add(e.file);
+    }
+    for (const r of (Array.isArray(opts.routes) ? opts.routes : [])) {
+      if (!r || typeof r.file !== 'string' || !r.file) continue;
+      entryFiles.add(r.file);
+      if (r.hasAuth !== true) unauthEntryFiles.add(r.file);
+    }
+
+    // 2) Import edges. A hole is an edge the graph cannot see: an unresolved
+    //    intra-repo (relative) specifier, or a non-literal module load. Holes
+    //    are recorded PER FILE because only holes in files that turn out to be
+    //    REACHABLE can hide a path into somewhere we'd otherwise call
+    //    unreachable — a hidden edge always originates in the importing file,
+    //    so a hole inside an already-unreachable file cannot make anything
+    //    reachable. Anything else would make a negative verdict impossible in
+    //    any real repository (one `require(varName)` anywhere would veto all).
+    const edges = new Map();
+    const holeFiles = new Set();
+    for (const [file, src] of files) {
+      const out = new Set();
+      if (RE_DYNAMIC_HOLE.test(src)) { holes++; holeFiles.add(file); }
+      for (const re of [RE_IMPORT_FROM, RE_EXPORT_FROM, RE_IMPORT_BARE, RE_REQUIRE, RE_DYN_IMPORT,
+        RE_PY_FROM, RE_PY_IMPORT, RE_JAVA_IMPORT]) {
+        re.lastIndex = 0;
+        let m;
+        while ((m = re.exec(src))) {
+          const spec = m[1];
+          if (!spec) continue;
+          const target = _resolve(spec, file, knownFiles, suffixIndex);
+          if (target && target !== file) out.add(target);
+          // Only an unresolved INTRA-repo (relative) specifier is a hole:
+          // a bare package name points at a third-party module that was
+          // never part of `fileContents` in the first place.
+          else if (!target && spec.startsWith('.')) { holes++; holeFiles.add(file); }
+        }
+      }
+      edges.set(file, out);
+    }
+
+    // 3) Forward BFS from the attack surface.
+    const queue = [...entryFiles].filter(f => knownFiles.has(f));
+    for (const f of queue) reachableFiles.add(f);
+    while (queue.length) {
+      const cur = queue.shift();
+      for (const next of (edges.get(cur) || [])) {
+        if (reachableFiles.has(next)) continue;
+        reachableFiles.add(next);
+        queue.push(next);
+      }
+    }
+
+    // A negative verdict is admissible only when we actually found an attack
+    // surface AND no file reachable from it has an invisible edge.
+    let reachableHole = false;
+    for (const f of reachableFiles) if (holeFiles.has(f)) { reachableHole = true; break; }
+    graphComplete = !reachableHole && entryFiles.size > 0;
+  } catch (_) {
+    return { entryFiles, unauthEntryFiles, reachableFiles, knownFiles, graphComplete: false, holes: holes || 1 };
+  }
+  return { entryFiles, unauthEntryFiles, reachableFiles, knownFiles, graphComplete, holes };
+}
+
+// ── R6: threat-model bonuses ───────────────────────────────────────────────
+function _threatBonus(f, threatModel, factors) {
+  let bonus = 0;
+  if (!threatModel || typeof threatModel !== 'object') return bonus;
+
+  const assets = Array.isArray(threatModel.assets) ? threatModel.assets : [];
+  for (const a of assets) {
+    if (!a || a.file !== f.file) continue;
+    const exposed = a.exposure === 'public-api' || a.exposure === 'external-api';
+    bonus += exposed ? 0.10 : 0.07;
+    factors.push(`modelled asset in file: ${a.category || a.name || 'asset'}${exposed ? ` (${a.exposure})` : ''}`);
+    break;
+  }
+
+  const boundaries = Array.isArray(threatModel.trustBoundaries) ? threatModel.trustBoundaries : [];
+  if (boundaries.some(b => b && b.file === f.file)) {
+    bonus += 0.05;
+    factors.push('trust boundary crossed in this file');
+  }
+
+  const stride = threatModel.stride && typeof threatModel.stride === 'object' ? threatModel.stride : null;
+  if (stride) {
+    for (const [cat, items] of Object.entries(stride)) {
+      if (!Array.isArray(items)) continue;
+      if (items.some(it => it && it.file === f.file && (it.line === f.line || it.vuln === f.vuln))) {
+        bonus += 0.08;
+        factors.push(`modelled STRIDE threat: ${cat}`);
+        break;
+      }
+    }
+  }
+  return bonus;
+}
+
+/**
+ * Pure scorer. Does NOT mutate the finding.
+ *
+ * @param graph  the object returned by buildReachabilityGraph (or a subset
+ *               with entryFiles / reachableFiles / knownFiles / graphComplete).
+ * @returns {{ tier, score, reachable, factors }}
+ */
+function scoreRelevance(f, graph, threatModel) {
+  const factors = [];
+  const g = graph || {};
+  const entryFiles = g.entryFiles instanceof Set ? g.entryFiles : new Set();
+  const reachableFiles = g.reachableFiles instanceof Set ? g.reachableFiles : new Set();
+  const knownFiles = g.knownFiles instanceof Set ? g.knownFiles : new Set();
+  const unauthEntryFiles = g.unauthEntryFiles instanceof Set ? g.unauthEntryFiles : new Set();
+  const file = f && typeof f.file === 'string' ? f.file : null;
+
+  let tier;
+  let reachable;
+  if (!file || entryFiles.size === 0) {
+    tier = 'unknown';
+    reachable = null;
+    factors.push(entryFiles.size === 0
+      ? 'no attack surface enumerated — reachability not determinable'
+      : 'finding has no file — reachability not determinable');
+  } else if (entryFiles.has(file)) {
+    tier = 'direct';
+    reachable = true;
+    factors.push('finding sits in an entry-point file (direct attack surface)');
+    if (unauthEntryFiles.has(file)) factors.push('entry point is unauthenticated');
+  } else if (reachableFiles.has(file)) {
+    tier = 'indirect';
+    reachable = true;
+    factors.push('reachable from an entry point via the module import graph');
+  } else if (g.graphComplete === true && knownFiles.has(file)) {
+    tier = 'unreachable';
+    reachable = false;
+    factors.push('no import path from any enumerated entry point (import graph complete)');
+  } else {
+    tier = 'unknown';
+    reachable = null;
+    factors.push(knownFiles.has(file)
+      ? 'import graph incomplete — no reachability verdict admissible'
+      : 'file not present in the scanned set — reachability not determinable');
+  }
+
+  let score = BASE_SCORE[tier];
+  score += _threatBonus(f || {}, threatModel, factors);
+  if (tier === 'direct' && unauthEntryFiles.has(file)) score += 0.10;
+  if (tier === 'unreachable') score = Math.min(score, UNREACHABLE_CAP);
+  score = Math.max(0, Math.min(1, score));
+
+  return { tier, score: Math.round(score * 1000) / 1000, reachable, factors };
+}
+
+/**
+ * Default-on annotator. Recall-preserving: never removes a finding, never
+ * touches severity, never asserts 'unreachable' without positive evidence.
+ *
+ * @param ctx.fileContents          Map|object of scanned sources
+ * @param ctx.entrypointInventory   output of buildEntrypointInventory()
+ * @param ctx.routes                route list (fallback attack surface)
+ * @param ctx.threatModel           output of buildThreatModel()
+ */
+export function annotateRelevance(findings, ctx = {}) {
+  if (!Array.isArray(findings)) return findings;
+  let graph;
+  try {
+    const c = ctx && typeof ctx === 'object' ? ctx : {};
+    graph = buildReachabilityGraph(c.fileContents, {
+      entrypointInventory: c.entrypointInventory,
+      entrypoints: c.entrypoints,
+      routes: c.routes,
+    });
+  } catch (_) {
+    graph = { entryFiles: new Set(), unauthEntryFiles: new Set(), reachableFiles: new Set(), knownFiles: new Set(), graphComplete: false, holes: 1 };
+  }
+  const threatModel = ctx && typeof ctx === 'object' ? ctx.threatModel : null;
+
+  for (const f of findings) {
+    if (!f || typeof f !== 'object') continue;
+    try {
+      const r = scoreRelevance(f, graph, threatModel);
+      f.entrypointReachable = r.reachable;
+      f.relevance = r.score;
+      f.relevanceTier = r.tier;
+      f.relevanceFactors = r.factors;
+
+      // R6 re-rank: exploitability is an ordinal priority, so scaling it by
+      // relevance is exactly the intended re-ranking. Severity is untouched,
+      // and demotion has a floor — a wrong call costs rank, not visibility.
+      const mult = EXPLOIT_MULT[r.tier];
+      if (typeof f.exploitability === 'number' && Number.isFinite(f.exploitability) && mult !== 1) {
+        const adjusted = Math.max(EXPLOIT_FLOOR, Math.min(1, f.exploitability * mult));
+        f.exploitability = Math.round(adjusted * 100) / 100;
+        if (typeof f.priorityScore === 'number') f.priorityScore = f.exploitability;
+        if (Array.isArray(f.exploitabilityFactors)) f.exploitabilityFactors.push(`relevance:${r.tier}`);
+        // Keep the tier label consistent with the re-ranked score. Same
+        // thresholds as annotateExploitability; severity is NOT derived here.
+        if (f.exploitability >= 0.80) f.exploitabilityTier = 'critical';
+        else if (f.exploitability >= 0.60) f.exploitabilityTier = 'high';
+        else if (f.exploitability >= 0.35) f.exploitabilityTier = 'medium';
+        else f.exploitabilityTier = 'low';
+      }
+    } catch (_) {
+      f.entrypointReachable = null;
+      f.relevance = BASE_SCORE.unknown;
+      f.relevanceTier = 'unknown';
+      f.relevanceFactors = ['relevance scoring failed — no verdict'];
+    }
+  }
+  return findings;
+}
+
+// Test-only surface (underscore-prefixed: not part of the public API).
+export const _internals = { buildReachabilityGraph, scoreRelevance, BASE_SCORE, EXPLOIT_MULT };

package/src/posture/rule-overrides.js

@@ -9,7 +9,7 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import * as yaml from 'js-yaml';
+import * as yaml from '../util/yaml.js';
 import { verifyLastScan } from './integrity.js';
 import { statePath } from './state-dir.js';
 

package/src/posture/sca-policy.js

@@ -38,7 +38,7 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import * as yaml from 'js-yaml';
+import * as yaml from '../util/yaml.js';
 
 const DEFAULT_POLICY = {
   acceptRisk: [],

package/src/posture/scan-checkpoint.js

@@ -0,0 +1,277 @@
+// Scan checkpointing / resume (roadmap R8).
+//
+// Long scans currently restart from zero if interrupted, which is what caps the
+// repository size this engine can usefully handle. This module lets the per-file
+// loop in `engine.js#runFullScan` durably record what it has already analysed so
+// a second invocation replays that work instead of redoing it.
+//
+// THE PROPERTY THAT MATTERS: a resumed scan must produce the same finding set as
+// an uninterrupted one. A checkpoint that silently drops findings converts a slow
+// scan into a quietly incomplete one, which is strictly worse than no checkpoint
+// at all. Three design decisions follow from that and should not be relaxed:
+//
+//   1. We persist the *complete* per-file contribution, not just findings —
+//      routes, taint sources/sinks/sanitizers, logic vulns, secrets, ciphers,
+//      the per-file result the cross-file taint pass reads, and the suppression
+//      log delta. Anything the per-file loop appends to must round-trip, or the
+//      post-loop cross-file passes would see a different world on resume.
+//   2. Only the per-file loop is checkpointed. Every cross-file pass and the
+//      whole annotation pipeline re-runs from scratch on resume, so nothing that
+//      depends on the global picture can be stale by construction.
+//   3. Invalidation is conservative to the point of being blunt. The run key
+//      covers the engine version, the ruleset version, the bundle SHA, a content
+//      hash of every file in the scan (which subsumes mtime), and the scanner's
+//      own environment switches. If any of it moved, the checkpoint is discarded
+//      and the scan starts clean. Redoing work is merely slow; resuming stale
+//      work is a correctness bug.
+//
+// CRASH SAFETY: append-and-fsync. The file is a JSONL log — one header line
+// pinning the run key, then one self-describing record per completed file,
+// each carrying a SHA-256 of its own payload. Every record is written with a
+// single `writeSync` and immediately `fsyncSync`'d before the next file is
+// analysed, so a process killed at any instant leaves either a complete record
+// or a torn tail. On recovery we read forward while records verify and truncate
+// the file at the last byte offset that did, so a torn tail is discarded rather
+// than resumed into. Nothing is ever rewritten in place, so there is no window
+// in which the file is neither the old state nor the new one.
+//
+// Everything here follows the posture convention of never throwing: a failure to
+// open, read or append degrades to "no checkpoint", which just means a full scan.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+const STATE_DIR = '.agentic-security';
+const FILE_NAME = 'scan-checkpoint.jsonl';
+const FORMAT = 'agentic-security-scan-checkpoint/1';
+
+// Env switches that change what the engine emits are part of the run identity.
+// These three are deliberately excluded: they change how the run is driven, not
+// what it would find.
+const RUN_KEY_ENV_EXCLUDE = new Set([
+  'AGENTIC_SECURITY_RESUME',
+  'AGENTIC_SECURITY_CHECKPOINT_ABORT_AFTER',
+  'AGENTIC_SECURITY_HMAC_KEY',
+]);
+
+export function checkpointPath(scanRoot) {
+  return path.join(scanRoot || '.', STATE_DIR, FILE_NAME);
+}
+
+function _sha(s) {
+  return crypto.createHash('sha256').update(s, 'utf8').digest('hex');
+}
+
+// SHA-256 of the running bundle, taken from the sidecar next to it. Returns
+// 'unavailable' when running from source — same convention as the attestation
+// path, and deliberately not a guess at some other bundle's hash.
+export function bundleShaForRunKey() {
+  try {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    // src/posture/ -> src/ -> scanner/
+    const sidecar = path.resolve(here, '..', '..', 'dist', 'agentic-security.mjs.sha256');
+    const raw = fs.readFileSync(sidecar, 'utf8').trim();
+    const m = /^([0-9a-f]{64})\b/.exec(raw);
+    if (m) return m[1];
+  } catch { /* not running from a built tree */ }
+  return 'unavailable';
+}
+
+/**
+ * Everything that would invalidate previously-completed per-file work, reduced
+ * to one hex digest. Content hashes rather than mtimes: strictly stronger, and
+ * immune to filesystems with coarse or non-monotonic timestamps.
+ */
+export function computeRunKey({
+  engineVersion, rulesetVersion, bundleSha,
+  fileContents = {}, depFileContents = {}, env = process.env,
+} = {}) {
+  const h = crypto.createHash('sha256');
+  h.update(FORMAT); h.update('\n');
+  h.update(String(engineVersion ?? '')); h.update('\n');
+  h.update(String(rulesetVersion ?? '')); h.update('\n');
+  h.update(String(bundleSha ?? 'unavailable')); h.update('\n');
+  for (const [label, map] of [['f', fileContents], ['d', depFileContents]]) {
+    const names = Object.keys(map || {}).sort();
+    h.update(label); h.update(String(names.length)); h.update('\n');
+    for (const n of names) {
+      h.update(n); h.update('\0');
+      h.update(_sha(String(map[n] ?? '')));
+      h.update('\n');
+    }
+  }
+  const envKeys = Object.keys(env || {})
+    .filter(k => k.startsWith('AGENTIC_SECURITY_') && !RUN_KEY_ENV_EXCLUDE.has(k))
+    .sort();
+  h.update('e'); h.update(String(envKeys.length)); h.update('\n');
+  for (const k of envKeys) { h.update(k); h.update('='); h.update(String(env[k])); h.update('\n'); }
+  return h.digest('hex');
+}
+
+// A value is safe to checkpoint only if JSON can carry it back unchanged. Dates,
+// regexes, Maps, Sets, functions and BigInts all survive `JSON.stringify` in a
+// lossy or throwing way; recording one would mean the resumed run sees different
+// data than the uninterrupted run did. We refuse the record instead, and the
+// file just gets rescanned.
+function _jsonSafe(v, depth = 0, seen = new Set()) {
+  if (depth > 24) return false;
+  if (v === null || v === undefined) return true;
+  const t = typeof v;
+  if (t === 'string' || t === 'boolean') return true;
+  if (t === 'number') return Number.isFinite(v);
+  if (t === 'function' || t === 'symbol' || t === 'bigint') return false;
+  if (t !== 'object') return false;
+  if (seen.has(v)) return false;
+  seen.add(v);
+  try {
+    if (Array.isArray(v)) {
+      for (const x of v) if (!_jsonSafe(x, depth + 1, seen)) return false;
+      return true;
+    }
+    const proto = Object.getPrototypeOf(v);
+    if (proto !== Object.prototype && proto !== null) return false;
+    for (const k of Object.keys(v)) if (!_jsonSafe(v[k], depth + 1, seen)) return false;
+    return true;
+  } finally {
+    seen.delete(v);
+  }
+}
+
+function _emptyHandle(reason) {
+  return {
+    enabled: false, file: null, fd: null, runKey: null,
+    recovered: new Map(), order: [], written: new Set(),
+    discarded: false, reason,
+  };
+}
+
+function _headerLine(runKey) {
+  return JSON.stringify({ v: FORMAT, runKey }) + '\n';
+}
+
+// Read forward from a byte offset, keeping records while they verify. Returns
+// the offset of the first byte that did NOT verify, so the caller can truncate.
+function _recover(handle, file, runKey) {
+  let buf;
+  try { buf = fs.readFileSync(file); }
+  catch { return -1; } // no file yet
+  const text = buf.toString('utf8');
+  const nl = text.indexOf('\n');
+  if (nl < 0) return 0;
+  let header = null;
+  try { header = JSON.parse(text.slice(0, nl)); } catch { return 0; }
+  if (!header || header.v !== FORMAT || header.runKey !== runKey) return 0;
+
+  let offset = Buffer.byteLength(text.slice(0, nl + 1), 'utf8');
+  let cursor = nl + 1;
+  for (;;) {
+    const end = text.indexOf('\n', cursor);
+    if (end < 0) break;                       // torn tail: no terminating newline
+    const line = text.slice(cursor, end);
+    cursor = end + 1;
+    if (!line) { offset = Buffer.byteLength(text.slice(0, cursor), 'utf8'); continue; }
+    let rec;
+    try { rec = JSON.parse(line); } catch { break; }
+    if (!rec || typeof rec.f !== 'string' || typeof rec.d !== 'string') break;
+    if (rec.c !== _sha(rec.d)) break;         // tampered or torn-then-patched
+    let payload;
+    try { payload = JSON.parse(rec.d); } catch { break; }
+    if (!handle.recovered.has(rec.f)) handle.order.push(rec.f);
+    handle.recovered.set(rec.f, payload);
+    offset = Buffer.byteLength(text.slice(0, cursor), 'utf8');
+  }
+  return offset;
+}
+
+/**
+ * Open (or start) the checkpoint for `scanRoot` under `runKey`. Never throws.
+ * A handle whose `enabled` is false silently no-ops through the rest of the API.
+ */
+export function openCheckpoint(scanRoot, { runKey } = {}) {
+  if (!scanRoot || !runKey) return _emptyHandle('no-run-key');
+  const handle = _emptyHandle(null);
+  try {
+    const dir = path.join(scanRoot, STATE_DIR);
+    fs.mkdirSync(dir, { recursive: true });
+    const file = checkpointPath(scanRoot);
+    handle.file = file;
+    handle.runKey = runKey;
+
+    const keepBytes = _recover(handle, file, runKey);
+    if (keepBytes <= 0) {
+      // Absent, foreign, or unreadable — start clean. Conservative by design.
+      handle.recovered.clear();
+      handle.order.length = 0;
+      handle.discarded = keepBytes === 0;
+      fs.writeFileSync(file, _headerLine(runKey));
+    } else {
+      // Drop any torn tail so appends land after the last verified record.
+      try {
+        const size = fs.statSync(file).size;
+        if (size !== keepBytes) fs.truncateSync(file, keepBytes);
+      } catch { /* best-effort */ }
+    }
+
+    handle.fd = fs.openSync(file, 'a');
+    handle.enabled = true;
+  } catch (e) {
+    try { if (handle.fd !== null) fs.closeSync(handle.fd); } catch { /* ignore */ }
+    return _emptyHandle(String((e && e.message) || e));
+  }
+  return handle;
+}
+
+/**
+ * Durably record that `relPath` is fully analysed, along with everything that
+ * analysis produced. `findings` is the per-file payload object (see the engine
+ * call site); it must be plain JSON data. Returns true only if the record is on
+ * disk and fsync'd.
+ */
+export function recordFileDone(handle, relPath, findings) {
+  if (!handle || !handle.enabled || handle.fd === null || typeof relPath !== 'string') return false;
+  try {
+    if (!_jsonSafe(findings)) return false;
+    const d = JSON.stringify(findings === undefined ? null : findings);
+    if (typeof d !== 'string') return false;
+    const line = JSON.stringify({ f: relPath, c: _sha(d), d }) + '\n';
+    fs.writeSync(handle.fd, line);
+    fs.fsyncSync(handle.fd);
+    handle.written.add(relPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Files already analysed — recovered from a prior run plus written by this one. */
+export function completedFiles(handle) {
+  const out = new Set();
+  if (!handle) return out;
+  for (const f of handle.recovered ? handle.recovered.keys() : []) out.add(f);
+  for (const f of handle.written || []) out.add(f);
+  return out;
+}
+
+/** Recovered per-file payloads, in the order they were originally recorded. */
+export function resumeFindings(handle) {
+  if (!handle || !handle.recovered) return [];
+  return (handle.order || []).map(file => ({ file, findings: handle.recovered.get(file) }));
+}
+
+/**
+ * Close the handle. `complete: true` means the scan finished — the checkpoint is
+ * removed so the next run cannot resume state that has already been consumed.
+ */
+export function closeCheckpoint(handle, { complete = false } = {}) {
+  if (!handle || !handle.enabled) return false;
+  let ok = true;
+  try { if (handle.fd !== null) fs.closeSync(handle.fd); } catch { ok = false; }
+  handle.fd = null;
+  handle.enabled = false;
+  if (complete && handle.file) {
+    try { fs.rmSync(handle.file, { force: true }); } catch { ok = false; }
+  }
+  return ok;
+}