nsauditor-ai 0.2.54 → 0.2.56

package/cli.mjs

@@ -20,7 +20,7 @@ import { buildMarkdownReport } from './utils/report_md.mjs';
 import { recordScan, getLastScan, computeDiff, formatDiffReport, pruneForCE, HISTORY_FILE } from './utils/scan_history.mjs';
 import { aiBailMessage, computeAiTimeoutMs, aiFailureStubText, aiSummaryLine } from './utils/ai_stage.mjs';
 import { getTierFromEnv, loadLicense } from './utils/license.mjs';
-import { resolveCapabilities, hasCapability, inferRequiredTier } from './utils/capabilities.mjs';
+import { resolveCapabilities, hasCapability, inferRequiredTier, CAPABILITIES } from './utils/capabilities.mjs';
 import { createScheduler } from './utils/scheduler.mjs';
 import { buildDeltaReport, formatDeltaSummary, hasSignificantChanges } from './utils/delta_reporter.mjs';
 import { sendWebhook, buildAlertPayload, isSafeWebhookUrl } from './utils/webhook.mjs';
@@ -28,9 +28,12 @@ import { scrubByKey } from './utils/redact.mjs';
 import { isBlockedIp, resolveAndValidate } from './utils/net_validation.mjs';
 import { getAllTechniques } from './utils/attack_map.mjs';
 import { TOOL_VERSION } from './utils/tool_version.mjs';
-import { resolveBaseOutDir } from './utils/output_dir.mjs';
+import { resolveBaseOutDir, createHostOutDir, safeHost } from './utils/output_dir.mjs';
+import { loadEnterprise } from './utils/ee_load.mjs';
+import { deriveFindingsCount } from './utils/report_inputs.mjs';
 import { toCleanPath } from './utils/path_helpers.mjs';
-import { newRunId, writeRunStart, appendHostWritten, finalizeRunRecord, pruneRunRecordsForCE } from './utils/run_record.mjs';
+import { newRunId, writeRunStart, appendHostWritten, finalizeRunRecord, pruneRunRecordsForCE, aggregateNvdCache, abortReasonOf } from './utils/run_record.mjs';
+import { buildSinceView } from './utils/scan_delta_view.mjs';
 import { loadRun } from './utils/report_inputs.mjs';
 import { loadBrand } from './utils/brand.mjs';
 import { renderExecutiveReport } from './utils/executive_report.mjs';
@@ -43,23 +46,47 @@ const parseBool = (val, def = false) => {
   if (!s && def != null) return !!def;
   return ['true', '1', 'yes', 'on', 'y'].includes(s);
 };
-const nowStamp = () => {
-  const d = new Date();
-  const pad = (n) => String(n).padStart(2, '0');
-  return (
-    d.getFullYear().toString() +
-    pad(d.getMonth() + 1) +
-    pad(d.getDate()) + '_' +
-    pad(d.getHours()) +
-    pad(d.getMinutes()) +
-    pad(d.getSeconds())
-  );
-};
-const safeHost = (h) => String(h ?? 'unknown').replace(/[\/\\?%*:|"<>]/g, '_');
+// `nowStamp` and `safeHost` live in utils/output_dir.mjs beside `createHostOutDir`, so the directory name has one definition.
 // toCleanPath imported from ./utils/path_helpers.mjs (consolidated in v0.1.20)
 
-/** Minimal redactor used if nothing external is provided. */
-function redactSensitiveForAI(input, targetHost) {
+/**
+ * ONE address rule for the whole AI payload, with our own identifiers carved out.
+ *
+ * ⚠️ SHARED BECAUSE IT WAS DUPLICATED AND ONE COPY WAS WRONG. `-` is a non-word character, so a
+ * bare `\b(?:(?:\d{1,3}\.){3}\d{1,3})\b` matches the tail of `EE-0.3.2.4` and rewrites a
+ * four-component identifier as an address. That shipped: two AI payloads carry
+ * `plugin 1020 (EE-[IP] fold)`. The identical rule was applied a second time to
+ * `payloadForAI.summary` — the same defect one field over, not live only because a network-scan
+ * summary happens to carry no identifier. Two copies of a rule, one of which was just found
+ * wrong, is how the next instance arrives; the POLICY differs between call sites (one keeps
+ * private addresses, the other scrubs every address) so the policy is the parameter and the rule
+ * is not.
+ *
+ * ⚠️ ONE ALTERNATION, NEVER TWO PASSES. Scrubbing addresses first destroys the identifier, and
+ * restoring identifiers afterwards cannot tell a real address from one that was always an id.
+ * With a single pass each construct consumes its own extent, so an address standing NEXT TO an
+ * identifier is still scrubbed.
+ *
+ * ⚠️ DECLARED RESIDUAL: an address wearing our own prefix — `EE-203.0.113.5` — is preserved
+ * verbatim, where the old rule scrubbed it. No value test can separate it from a real
+ * `EE-RT.11.1.2.5`, because the two are the same shape. Pinned in
+ * `tests/redact_product_ids.test.mjs` so the limit is stated rather than silent.
+ */
+const PRODUCT_ID_OR_IPV4 = /(\bEE-(?:RT\.)?\d+(?:\.\d+)*\b)|(\b(?:\d{1,3}\.){3}\d{1,3}\b)/g;
+export function scrubIPv4KeepingProductIds(str, replaceAddress) {
+  return String(str).replace(PRODUCT_ID_OR_IPV4,
+    (m, productId, ip) => (productId !== undefined ? productId : replaceAddress(ip)));
+}
+
+/**
+ * Minimal redactor used if nothing external is provided.
+ *
+ * ⚠️ EXPORTED SO IT CAN BE DRIVEN. A redactor's FALSE POSITIVE is invisible from the redacted
+ * artifact alone — `EE-[IP]` reads like a redaction that worked — so the only way to see one is
+ * to compare a raw against its payload, which needs the real function rather than a re-spelling
+ * of its rules. `tests/redact_product_ids.test.mjs` is that census.
+ */
+export function redactSensitiveForAI(input, targetHost) {
   const DROP_KEYS = new Set([
     'ip6', 'deviceWebPage', 'deviceWebPageInstruction',
     'hardwareVersion', 'firmwareVersion'
@@ -76,7 +103,8 @@ function redactSensitiveForAI(input, targetHost) {
     s = s.replace(/\b(?:[0-9a-f]{2}:){5}[0-9a-f]{2}\b/gi, '[MAC]'); // MAC
     s = s.replace(/\bfe80::[0-9a-f:]+\b/gi, '[FE80::/64]');         // IPv6 link-local
     s = s.replace(/\b(?:[0-9a-f]{1,4}:){2,7}[0-9a-f]{1,4}\b/gi, '[IPv6]');
-    s = s.replace(/\b(?:(?:\d{1,3}\.){3}\d{1,3})\b/g, (ip) => (isPrivateV4(ip) ? ip : '[IP]'));
+    // The shared rule; this call site's POLICY keeps private addresses and masks public ones.
+    s = scrubIPv4KeepingProductIds(s, (ip) => (isPrivateV4(ip) ? ip : '[IP]'));
     return s;
   };
 
@@ -118,17 +146,12 @@ async function maybeSendToOpenAI({ host, results, conclusion, promptMode = 'basi
     : await resolveSecret(process.env.OPENAI_API_KEY);
   const key           = keyRaw ? String(keyRaw).trim() : null;
 
-  // Per-scan folder. Caller (scanSingleHost) may pass a pre-computed outDir so
-  // that EE enrichment + compliance artifacts share the same folder as the AI
-  // outputs — otherwise compute one here for legacy callers.
-  let outDir = presetOutDir;
-  if (!outDir) {
-    const baseOutDir = resolveBaseOutDir();
-    await fsp.mkdir(baseOutDir, { recursive: true });
-    const ts     = nowStamp();
-    const runDir = `${safeHost(host)}_${ts}`;
-    outDir       = path.join(baseOutDir, runDir);
-  }
+  // Per-scan folder — REQUIRED. Its only caller, scanSingleHost, creates it exclusively (createHostOutDir) so that EE
+  // enrichment, compliance artifacts and the AI outputs share one folder. ⚠️ The fallback that used to compose a
+  // directory here (`${safeHost(host)}_${nowStamp()}`, recursive mkdir) had no caller and was the same-second
+  // collision's shape kept warm (1.1.1, audit seat's fold); it is gone, and a missing outDir is an error.
+  if (!presetOutDir) throw new Error('maybeSendToOpenAI: outDir is required — scanSingleHost creates it with createHostOutDir');
+  const outDir = presetOutDir;
   await fsp.mkdir(outDir, { recursive: true });
 
   // Paths (fixed names inside per-scan folder)
@@ -280,8 +303,12 @@ async function maybeSendToOpenAI({ host, results, conclusion, promptMode = 'basi
 
     // Redact any remaining IP addresses in the summary field
     if (typeof payloadForAI.summary === 'string') {
-      payloadForAI.summary = payloadForAI.summary
-        .replace(/\b(?:(?:\d{1,3}\.){3}\d{1,3})\b/g, '[REDACTED_HOST]');
+      // ⚠️ THE SAME RULE, A DIFFERENT POLICY: every address goes, private ones included. It
+      // carried its own copy of the address regex — the copy that was NOT fixed when the
+      // identifier defect was found in the redactor, which is exactly how the second instance
+      // of a class arrives. Measured at the time: neither live payload's summary carries an
+      // `EE-` token, so this was a latent duplicate rather than a live defect.
+      payloadForAI.summary = scrubIPv4KeepingProductIds(payloadForAI.summary, () => '[REDACTED_HOST]');
     }
 
     // Also redact private IPs in nested service/evidence strings
@@ -810,6 +837,8 @@ export async function parseArgs(argv) {
   args.format = str('format');
   const runVal = get('run');
   args.run = runVal === undefined ? undefined : runVal;
+  const sinceVal = get('since');
+  args.since = sinceVal === undefined ? undefined : sinceVal;
   const brandVal = get('brand');
   args.brand = brandVal === undefined ? undefined : brandVal;
   const reportOutVal = get('out');
@@ -819,6 +848,22 @@ export async function parseArgs(argv) {
   return args;
 }
 
+/**
+ * The LAST refusal main() makes before it resolves hosts, as a value: an unknown command, then a `scan` with
+ * neither --host nor --host-file. The earlier flag, env, posture, GRC and region refusals are not modelled here. `null` means the command gets past both. main() prints `message` and exits
+ * with `code`; the documented-command census (EE) drives the same function over every `nsauditor-ai scan` the
+ * product teaches, so a documented command is judged by the code that would refuse it rather than by a copy
+ * of its condition. A positional target is not a target (parseArgs reads the host only from a flag).
+ * ⚠️ A value-less `--host` parses to `true` and passes here; main() then fails in parseHostArg (boarded).
+ * @param {{ cmd?: string, host?: string|true, hostFile?: string }} args  parseArgs' result
+ * @returns {{ message: string, code: number }|null}
+ */
+export function scanTargetRefusal({ cmd, host, hostFile } = {}) {
+  if (cmd !== 'scan') return { message: `Unknown command: ${cmd}`, code: 2 };
+  if (!hostFile && !host) return { message: 'Fatal: --host or --host-file is required', code: 2 };
+  return null;
+}
+
 // EE-0.3.2.5 (CE side): cloud-provider sentinel hosts ('aws' / 'gcp' /
 // 'azure', case-insensitive) are NOT real DNS names — they're scoping
 // tokens that EE cloud-scanner plugins (020/021/022/023/030) interpret
@@ -869,11 +914,11 @@ async function scanSingleHost(pm, host, plugins, opts, promptMode) {
   // Pre-compute the per-scan output folder so EE enrichment, compliance
   // artifacts, and AI outputs all land in the same directory. maybeSendToOpenAI
   // will reuse this presetOutDir below.
-  const baseOutDir = resolveBaseOutDir();
-  await fsp.mkdir(baseOutDir, { recursive: true });
-  const ts        = nowStamp();
-  const outDir    = path.join(baseOutDir, `${safeHost(host)}_${ts}`);
-  await fsp.mkdir(outDir, { recursive: true });
+  //
+  // ⚠️ AN EXCLUSIVE CREATE (1.1.1 board): two scans of one host reaching this line in the same second used to share
+  // one directory and the later one overwrote the earlier one's evidence — see createHostOutDir. `opts.nowStamp` is
+  // a test seam (testHooks.nowStamp), absent in every real invocation.
+  const outDir = await createHostOutDir(resolveBaseOutDir(), host, opts?.nowStamp ? { stamp: opts.nowStamp } : {});
 
   // EE enrichment hook — no-op if @nsasoft/nsauditor-ai-ee is not installed
   // or the license tier doesn't grant intelligenceEngine. Compliance + outDir
@@ -908,11 +953,28 @@ async function scanSingleHost(pm, host, plugins, opts, promptMode) {
   // claim about the whole run, not a single host).
   let kevDataAsOf = null;
   let epssDataAsOf = null;
-  try {
-    // `opts.importEE`: test-only injection seam, mirroring `preflightNsauditorPosture`'s
-    // `importEE` option elsewhere in this file — absent in every real invocation.
-    ee = opts?.importEE ? await opts.importEE() : await import('@nsasoft/nsauditor-ai-ee');
-  } catch { /* EE not installed — CE proceeds unchanged. The ONLY silent case. */ }
+  // Enterprise's report of WHERE the NVD store/cache it read lives (board item 23) — null without EE.
+  let nvdCache = null;
+  // ⚠️ "NOT INSTALLED" AND "INSTALLED BUT BROKEN" ARE TWO EVENTS (1.1.1, the audit seat's T1-c ruling). This used to be
+  // a bare `catch {}` read as "EE not installed — the ONLY silent case", and every import failure landed in it — measured
+  // at EE 174212f: Enterprise imported names this Community did not export, so below the floor the whole EE stage
+  // vanished without a word and the Pro delta read its rows RESOLVED. The package is RESOLVED first (utils/ee_load.mjs):
+  // absence stays silent; a failed load is named on stderr and recorded on the conclusion, beside `eeEnrichmentError`.
+  // `opts.importEE` / `opts.resolveEE`: test-only seams — absent in every real invocation.
+  const eeLoad = await loadEnterprise({ importEE: opts?.importEE ?? null, resolveEE: opts?.resolveEE ?? null });
+  ee = eeLoad.ee;
+  if (eeLoad.loadError) {
+    console.error(`[EE] Enterprise is installed but FAILED TO LOAD — this scan has no compliance report, no `
+      + `intelligence enrichment and no analysis-agent findings: ${eeLoad.loadError}`);
+    conclusion.result = conclusion.result || {};
+    conclusion.result.eeLoadError = eeLoad.loadError;
+  }
+  // ⚠️ HOISTED DELIBERATELY, and only this value. `eeEnrichment` is `const` INSIDE the try below,
+  // so reading it at the `appendHostWritten` call ~100 lines on is a ReferenceError — which the
+  // suite caught as 16 failures rather than one, because every history comparison swallowed it as
+  // "Failed to record/compare scan". Widening `eeEnrichment` itself would put the whole EE
+  // envelope in a scope that does not need it; one holder is the smaller contract.
+  let hostScopeScanned = null;
   try {
     const eeEnrichment = ee ? await ee.enrichScan(conclusion, {
       host,
@@ -925,8 +987,14 @@ async function scanSingleHost(pm, host, plugins, opts, promptMode) {
       complianceHistoryRoot: opts.complianceHistoryRoot,
       slaPolicy:             opts.slaPolicy,
       results,
+      // ⚠️ WHAT EACH UPSTREAM DID, forwarded so EE can tell "nothing to map" from "my inputs
+      // never ran". Without it the CPE mapper returns a silently empty result when discovery
+      // times out, and the DISAPPEARANCE of its own coverage-gap records reads to the cross-run
+      // delta as findings RESOLVED — measured on a live run, three such rows.
+      pluginStatus,
       onWarn: (msg) => console.warn(`[EE] ${msg}`),
     }) : null;
+    hostScopeScanned = eeEnrichment?.scopeScanned ?? null;
     // ⚠️ Read from `exploitIntel.stores`, NOT a top-level `exploit` key — measured against
     // EE's actual `enrichScan` return shape (`index.mjs`'s final `return { ... exploitIntel:
     // ctx.exploitIntel, ... }`), which nests the per-store `dataAsOf` at
@@ -938,6 +1006,10 @@ async function scanSingleHost(pm, host, plugins, opts, promptMode) {
     const stores = eeEnrichment?.exploitIntel?.stores;
     kevDataAsOf = stores?.kev?.dataAsOf ?? null;
     epssDataAsOf = stores?.epss?.dataAsOf ?? null;
+    const nvd = eeEnrichment?.nvdStore;
+    nvdCache = (nvd && typeof nvd.path === 'string')
+      ? { path: nvd.path, source: nvd.source ?? null, state: nvd.state ?? null, responseCache: nvd.responseCache ?? null }
+      : null;
     if (eeEnrichment?.enrichedPrompt) {
       conclusion.result = conclusion.result || {};
       conclusion.result.eeEnrichment = eeEnrichment;
@@ -970,7 +1042,36 @@ async function scanSingleHost(pm, host, plugins, opts, promptMode) {
   // through it, whatever its own enrichment found.
   let hostAppended = false;
   try {
-    const outRoot = toCleanPath(process.env.SCAN_OUT_PATH || process.env.OPENAI_OUT_PATH || 'out').replace(/\.[^/.]+$/, '') || 'out';
+    // ⚠️ `resolveBaseOutDir()`, NOT THE INLINE STRIP THAT USED TO BE HERE (board C3). The old
+    // expression was `toCleanPath(...).replace(/\.[^/.]+$/, '')` — remove everything after the
+    // last dot — so `--out …/ee-1.1.0` wrote the scan into `ee-1.1.0/` and its HISTORY into a
+    // SIBLING `ee-1.1/`, created silently beside it. Both `ee-1.1/` and `ee-1.0/` are live
+    // strays in this project's own evidence tree, which is how it was found: by looking at the
+    // directory, not at the code.
+    //
+    // It is the EE 0.32.8 evidence-misplacement bug — "has a dot" read as "is a file" — surviving
+    // in the one call site that never adopted the fixed resolver. A repair applied to a helper
+    // does not reach a caller that does not use it, and the version-named directory convention
+    // this project uses for its own evidence is exactly the shape that breaks.
+    const outRoot = resolveBaseOutDir();
+
+    // ⚠️ AND THE MOVE IS ANNOUNCED RATHER THAN SILENT. A user whose previous scans wrote history
+    // to the stray sibling would otherwise find this scan reporting no prior run — a correct
+    // statement about the new location that reads as "nothing changed since last time". Name the
+    // file instead; it is not read any more and it is not deleted either. Same discipline as the
+    // report command's stale-artifact notice: never let an old file pass for a current one.
+    const legacyHistoryRoot = toCleanPath(
+      process.env.SCAN_OUT_PATH || process.env.OPENAI_OUT_PATH || 'out'
+    ).replace(/\.[^/.]+$/, '') || 'out';
+    if (legacyHistoryRoot !== outRoot) {
+      const here = await fsp.access(path.join(outRoot, HISTORY_FILE)).then(() => true, () => false);
+      const there = await fsp.access(path.join(legacyHistoryRoot, HISTORY_FILE)).then(() => true, () => false);
+      if (!here && there) {
+        console.warn(`[scan] scan history now lives in ${outRoot}. An earlier build wrote it to `
+          + `${legacyHistoryRoot}, which is NOT read any more — this scan starts a new history there. `
+          + 'The old file is left on disk; nothing was deleted.');
+      }
+    }
 
     // Append this host to the run record now that its directory has landed — inside the
     // SAME try/catch as the rest of scan-history recording. utils/run_record.mjs documents
@@ -994,7 +1095,15 @@ async function scanSingleHost(pm, host, plugins, opts, promptMode) {
     // that reintroduces the same bug for the run record.
     const runRecordRoot = resolveBaseOutDir();
     if (opts?.runId) {
-      hostAppended = await appendHostWritten(runRecordRoot, opts.runId, { host, dir: path.basename(outDir) });
+      // ⚠️ THE EFFECTIVE SCOPE THIS HOST'S SCAN COVERED, never the flag — EE's resolver reports
+      // what it actually resolved and CE records it per host, which is per PROVIDER on a cloud
+      // scan. `null` on a network host or a CE-only install, and `null` means UNKNOWN rather than
+      // "covered nothing": the delta stays silent when BOTH records lack it and fails closed when
+      // only one carries it.
+      hostAppended = await appendHostWritten(runRecordRoot, opts.runId, {
+        host, dir: path.basename(outDir),
+        scopeScanned: hostScopeScanned,
+      });
     }
 
     const services = conclusion?.result?.services ?? [];
@@ -1015,7 +1124,36 @@ async function scanSingleHost(pm, host, plugins, opts, promptMode) {
       const f = r?.result?.findings;
       return n + (Array.isArray(f) ? f.length : 0);
     }, 0);
-    const findingsCount = serviceFindingsCount + cloudFindingsCount;
+    // ⚠️ DERIVED FROM THE REPORT LOADER, NOT SUMMED HERE (board C10). The two sums above are
+    // KEPT because `cloudFindingsCount` still ships as its own field, but they no longer decide
+    // `findingsCount`: they could not see the finding QUEUE, so a network host whose findings are
+    // all CVE matches recorded ZERO — measured on the real 192.168.1.1 run, 0 against 37 queue
+    // entries of which 21 carried CVEs. `scan_history` is a COMPARISON channel, so that zero
+    // became "no change" on every subsequent scan, forever.
+    //
+    // The previous repair of this same channel added `cloudFindingsCount` when cloud plugins
+    // recorded 0 over a 201-finding scan. That was per-producer, and a per-producer repair closes
+    // only the producers it enumerates — which is how this channel came to be wrong twice. Using
+    // the shaping `report --since` already uses means a producer the loader learns to read is
+    // counted by BOTH channels on the same day, with nobody remembering to update this line.
+    //
+    // Read from DISK, not from memory: these are the exact bytes `report --since` will read, so
+    // the two channels count the same artifacts and not two views of them. Both are written by
+    // now — the envelope at the output stage, the queue by the enrichment hook.
+    // ⚠️ ONE CALL FOR BOTH THE NUMBER AND ITS BASIS. They were two statements here, and a mutant
+    // that reverted the count to the legacy sum kept the basis stamp — a line claiming to have
+    // been counted the new way while holding an old-way number, which the end-to-end leg could
+    // not see. Only the thing that produces the number may assert how it was produced.
+    const derived = await deriveFindingsCount(outDir, host);
+    const findingsCount = derived ? derived.count : (serviceFindingsCount + cloudFindingsCount);
+    const findingsCountBasis = derived ? derived.basis : null;
+    if (!derived) {
+      // Falls back to the legacy sum WITHOUT claiming the new basis, so `computeDiff` treats the
+      // line as pre-1.1.0 and refuses to subtract it against a properly-counted one rather than
+      // silently comparing two different definitions of a finding.
+      console.warn('[scan] could not derive findingsCount from the written artifacts; recording the '
+        + 'legacy sum and marking the line as un-based, so no comparison is made across it.');
+    }
 
     const scanSummary = {
       timestamp: new Date().toISOString(),
@@ -1024,6 +1162,14 @@ async function scanSingleHost(pm, host, plugins, opts, promptMode) {
       openPorts: services.filter((s) => s.status === 'open').map((s) => s.port),
       os: conclusion?.result?.host?.os ?? null,
       findingsCount,
+      findingsCountBasis,
+      // ⚠️ THE TIER THAT PRODUCED THE COUNT (board E9), read from the SAME resolver this file
+      // already branches on twelve lines below, never re-derived. The tiers do not count the
+      // same things — Enterprise writes a finding queue that Community never produces — so
+      // `computeDiff` refuses to subtract across a tier boundary, and it can only do that if the
+      // line says which tier counted. Without this field every leg of that refusal is
+      // unreachable in production while its unit tests stay green.
+      tier: getTierFromEnv(),
       cloudFindingsCount,
       services: services.map((s) => ({
         port: s.port, protocol: s.protocol ?? 'tcp',
@@ -1054,7 +1200,7 @@ async function scanSingleHost(pm, host, plugins, opts, promptMode) {
   return {
     host, results, conclusion, ai_file_paths, ai_conclusion, ai_status, ai_error, scanDiff,
     // Additive, consumed only by main()'s top-level KEV/EPSS aggregation for the run record.
-    hostAppended, kevDataAsOf, epssDataAsOf,
+    hostAppended, kevDataAsOf, epssDataAsOf, nvdCache,
   };
 }
 
@@ -1123,7 +1269,7 @@ async function readSecretFromStdin(keyName) {
   });
 }
 
-function maxSeverityInConclusion(conclusion) {
+export function maxSeverityInConclusion(conclusion) {
   const services = conclusion?.result?.services || [];
   let max = 0;
 
@@ -1245,7 +1391,9 @@ export async function preflightGrcIfRequested(env, opts = {}) {
 // test drive the real scan pipeline (including this function's own run-record wiring) against
 // a controlled, injected EE module — e.g. one whose `enrichScan` reports a specific KEV/EPSS
 // `dataAsOf` — without depending on the real `@nsasoft/nsauditor-ai-ee` package, a real store
-// file, or the machine's own license/tier state being any particular thing.
+// file, or the machine's own license/tier state being any particular thing. An injected `importEE` counts as an
+// INSTALLED package (utils/ee_load.mjs): to describe one that is NOT installed, pass `testHooks.resolveEE` throwing —
+// a throwing `importEE` alone is now a package that is installed and FAILED to load, which the scan reports.
 // Reconstructs a single tier word ('ce' | 'pro' | 'enterprise') from the resolved capability
 // map — never from getTierFromEnv()'s own global cache. `runReport` below deliberately never
 // reads that cache: `caps` is passed in as an argument specifically so Pro is reachable from the
@@ -1281,7 +1429,9 @@ function tierLabelFromCaps(caps) {
  * or refused (bad/missing flags, a flag mismatch, a tier refusal, `no-run`, `record-unreadable`,
  * a write failure) — fix the request or the environment. **1** = `loadRun` refused for any other
  * reason — fix the run by re-scanning. **0** = rendered (a caveated or zero-finding render is
- * still 0 — the exit code must never encode whether findings exist).
+ * still 0 — the exit code must never encode whether findings exist, and with `--since` it must
+ * never encode WHETHER ANYTHING CHANGED either: a no-change delta and a twelve-new-exposure
+ * delta both exit 0, and only could-not-measure is non-zero).
  *
  * @returns {Promise<{ code: number, stdout: string, stderr: string }>}
  */
@@ -1309,7 +1459,7 @@ export async function runReport(args, caps) {
   // catch this after the fact — it must be caught here or never. Same precedent already applied
   // to `--sla-policy`/`--compliance-history` in the scan path, below.
   for (const [flag, val] of [['--from', args.from], ['--brand', args.brand],
-    ['--run', args.run], ['--out', args.out]]) {
+    ['--run', args.run], ['--out', args.out], ['--since', args.since]]) {
     if (val === true) {
       logErr(`\`report\` needs a value for ${flag}. A flag that quietly does nothing is how an `
         + 'operator concludes a subject was resolved.');
@@ -1341,7 +1491,7 @@ export async function runReport(args, caps) {
     { tier: tierLabelFromCaps(caps) });
   if (!loaded.ok) {
     logErr(loaded.message);
-    // MAP BY REASON, not by "loadRun said no" — an EXHAUSTIVE switch over the ten documented
+    // MAP BY REASON, not by "loadRun said no" — an EXHAUSTIVE switch over the eleven documented
     // reasons, with a loud default. `no-run` and `record-unreadable` are COMMAND/environment
     // problems (fix the invocation or the filesystem); every other reason is a RUN problem the
     // operator fixes by re-scanning.
@@ -1349,6 +1499,7 @@ export async function runReport(args, caps) {
       case 'no-run':
       case 'record-unreadable':
         return finish(2);
+      case 'aborted-run':
       case 'ambiguous-run':
       case 'binding-mismatch':
       case 'incomplete-run':
@@ -1396,6 +1547,48 @@ export async function runReport(args, caps) {
     log('[report] coverage: incomplete — the run did not record completion');
   }
 
+  // ── `--since`: the cross-run delta. Placed AFTER the coverage caveats so a partial or
+  // incomplete CURRENT run is already disclosed before any delta verdict is read.
+  let sinceDelta = null;
+  // A refused COMPARISON still renders and still exits 2: the artifact says the comparison was
+  // refused, and could-not-measure stays loud.
+  let sinceRefusalCode = 0;
+  if (typeof args.since === 'string' && args.since !== '') {
+    const view = await buildSinceView({ outRoot: args.from, model, since: args.since,
+      allowPartial: !!args.allowPartial, tier: tierLabelFromCaps(caps) });
+    view.out.forEach(log);
+    view.err.forEach(logErr);
+    // ⚠️ TWO KINDS OF EXIT 2, AND THE ARTIFACT IS WHAT DISTINGUISHES THEM (board C9). This line
+    // used to `return finish(view.code)` for BOTH, so a refused comparison wrote no file at all
+    // — and `executive_report.mjs`'s `delta-refused` block, which renders exactly the honest
+    // artifact, was unreachable through every shipped path. The consultant's deliverable is
+    // `--out client.html`; a refusal that leaves a STALE client.html there is worse than the
+    // refusal, because the file they hand a client is from an earlier run and says nothing of it.
+    // ⚠️ AND THE ARTIFACT MUST BE ABLE TO CARRY THE REFUSAL, OR IT MUST NOT BE WRITTEN. Only the
+    // executive report renders the delta; `renderJiraCsv` never receives it. Writing a CSV that
+    // says nothing while exiting 2 would make "exit 2 WITH an artifact" mean one thing for HTML
+    // and the opposite for CSV — a contract that depends on the format is not a contract. Any
+    // format that cannot state the refusal falls back to the request/run behaviour: write
+    // nothing, name any stale file, exit 2.
+    if (view.code !== 0 && (!view.delta || format !== 'executive')) {
+      // The REQUEST or the RUN ITSELF was refused: nothing honest to render. Say so about any
+      // file already on disk, so it cannot pass as this run's output.
+      // ⚠️ `fsp`, NOT `fs` — this module imports only `node:fs/promises`. The first draft wrote
+      // `fs.existsSync` and threw ReferenceError on the refusal path. It surfaced immediately
+      // here; the same slip in `report_inputs.mjs` earlier this cycle sat under a bare `catch`
+      // and read CLEAN. Same bug, opposite visibility, and the difference was the catch.
+      const stale = args.out ? await fsp.access(args.out).then(() => true, () => false) : false;
+      if (stale) {
+        logErr(`[report] ${args.out} was NOT rewritten; it is from an earlier run.`);
+      }
+      return finish(view.code);
+    }
+    // ⚠️ CARRIED INTO THE ARTIFACT, not only printed. stdout reaches the OPERATOR, who knows what
+    // the tool does; the HTML reaches the CLIENT being billed.
+    sinceDelta = view.delta ?? null;
+    sinceRefusalCode = view.code !== 0 ? view.code : 0;
+  }
+
   let body;
   let ext;
   if (format === 'executive') {
@@ -1404,7 +1597,7 @@ export async function runReport(args, caps) {
       logErr(brandResult.message);
       return finish(2);
     }
-    body = renderExecutiveReport(model, brandResult.brand, { renderedAt: new Date() });
+    body = renderExecutiveReport(model, brandResult.brand, { renderedAt: new Date(), delta: sinceDelta });
     ext = 'html';
   } else {
     body = renderJiraCsv(model);
@@ -1428,6 +1621,17 @@ export async function runReport(args, caps) {
     return finish(2);
   }
   log(`[report] wrote ${outPath}`);
+  // ⚠️ THE ARTIFACT IS WRITTEN AND THE EXIT IS STILL 2 when the COMPARISON was refused. The
+  // report rendered — that is what the 0 would be claiming — but the thing the operator ASKED
+  // for could not be measured, and could-not-measure stays loud everywhere in this repo. The
+  // artifact itself says which happened, so the pair is unambiguous: exit 2 WITH a file means
+  // the comparison was refused and the file says so; exit 2 WITHOUT one means the request or the
+  // run itself was refused.
+  if (sinceRefusalCode !== 0) {
+    logErr(`[report] the report was written, but the requested comparison was REFUSED — `
+      + `${outPath} states that and contains no resolved, new or changed rows.`);
+    return finish(sinceRefusalCode);
+  }
   return finish(0);
 }
 
@@ -1468,25 +1672,35 @@ Scan options:
   --aws-profile <name>         Use a named profile from the OS-default ~/.aws/credentials.
                                Implies CLOUD_PROVIDER=aws; overrides explicit AWS_* keys.
   --aws-region <r>             AWS region scope: one (us-east-1), CSV (us-east-1,eu-west-1),
-                               or 'all' (every account-enabled region). Default: AWS_REGION
-                               if set, else a single region with an incomplete-coverage notice.
+                               or 'all' (every account-enabled region). Default: no intent —
+                               region-scoped checks use AWS_REGION, else one region (with an
+                               incomplete-coverage notice); CloudTrail trail discovery,
+                               GuardDuty/Inspector and EC2 instances attempt every region.
   --plugins <list|all>         Plugins to run (e.g. 001,003,020 or "all"; default: all)
-  --ports <range>              Override port list (e.g. 22,80,443 or 1-1000)
+  --ports <list>               Ports ADDED to the default set (e.g. 22,80,443 or 161/udp;
+                               a range such as 1-1000 is not parsed and adds nothing)
   --out <dir>                  Output directory for scan artifacts
   --parallel <n>               Parallel host concurrency (default 1)
-  --fail-on <severity>         Exit non-zero if any finding ≥ severity
+  --fail-on <severity>         Exit 1 if a gated flag ≥ severity: anonymous FTP / zone
+                               transfer (critical; tested only with FTP_CHECK_ANON /
+                               DNS_CHECK_AXFR set), weak SSH algorithms (medium); any
+                               concluded scan is info. Dangerous HTTP methods are read
+                               but never reach the conclusion today. Not SNMP community,
+                               weak TLS, MCP checks, CVEs or agent findings — exit 0 is
+                               not a clean host. Exit 2: unknown severity or no conclusion.
   --output-format <fmt>        Additional report format: sarif | csv | md
   --insecure-https             Skip TLS validation on probed HTTPS targets
   --watch                      CTEM continuous ALERTING mode: re-scan on --interval,
-                               diff against the previous cycle, fire --webhook-url when a
-                               change crosses --alert-severity. NOT an evidence cadence —
+                               compare each host with its previous scan ([ScanHistory]
+                               lines); --webhook-url does NOT fire on a service, version or
+                               finding change in this release. NOT an evidence cadence —
                                it adds no retention or cross-run aggregation, skips SARIF/
                                CSV/Markdown output and --fail-on, and dies with this process.
                                Each tick is an ordinary scan, so with --compliance it writes
                                that tick's artifacts; nothing relates them across ticks. For
                                SOC 2 Type II history use a scheduler (cron/systemd/CI).
   --interval <minutes>         Watch interval (default 60)
-  --webhook-url <url>          Send delta alerts (must be public; private/loopback blocked)
+  --webhook-url <url>          Send --watch alerts (must be public; private/loopback blocked)
   --alert-severity <sev>       Min severity to alert on (default: high)
   --compliance <framework>     Map findings to controls. 'all' = all 8 frameworks, or a CSV of
                                soc2,hipaa,nist-csf,pci-dss,iso-27001,cis-v8,gdpr,nist-800-171
@@ -1850,17 +2064,19 @@ Docs: https://www.nsauditor.com/ai/   |   Pricing: https://www.nsauditor.com/ai/
         for (const plugin of sorted) {
           const required = Array.isArray(plugin.requiredCapabilities) ? plugin.requiredCapabilities : [];
           const allMet = required.length === 0 || required.every((c) => Boolean(caps[c]));
-          // Reviewer M2 fold: derive the required tier from the unmet
-          // capability set so the "requires: …" label is accurate even
-          // when the plugin doesn't declare a `tier` field. EE plugins
-          // 021/022/023 (no `tier` declaration) require `cloudScanners`
-          // which is enterprise-gated — pre-fold they showed
-          // "requires: pro" misleadingly. Now they show "requires:
-          // enterprise" via inferRequiredTier(). plugin.tier is the
-          // operator-declared override; fall back to inference.
-          const inferredTier = inferRequiredTier(required);
-          const requiresLabel = plugin.tier ?? inferredTier ?? 'pro';
-          const status = allMet ? '✓ active' : `✗ requires: ${requiresLabel}`;
+          // The label is the tier the GATE enforces, derived from `requiredCapabilities` alone — the
+          // list the plugin manager checks before it runs a plugin. A manifest's `tier` word is NOT
+          // read: until 0.2.55 it outranked the derivation, and EE 1020 / 1030 declared `tier: "pro"`
+          // over `cloudScanners`, so at Community tier this list said Pro unlocks two plugins Pro does
+          // not. (Before that, EE 1021 / 1022 / 1023 declared no capabilities at all and this line
+          // showed them `✓ active` at every tier.) A capability the registry does not define is
+          // granted by no licence — the plugin never loads — so it is NAMED rather than labelled
+          // with a tier; `inferRequiredTier` skips unknown names and would print "requires: ce".
+          // Reachable only when allMet is false, i.e. `required` is non-empty.
+          const unknown = required.filter((c) => !Object.hasOwn(CAPABILITIES, c));
+          const status = allMet ? '✓ active'
+            : unknown.length > 0 ? `✗ requires a capability no licence grants: ${unknown.join(', ')}`
+            : `✗ requires: ${inferRequiredTier(required)}`;
           // Layout matches the EE README example:
           //   "  003 SSH Scanner            ✓ active"
           const idStr = String(plugin.id ?? '?').padEnd(3);
@@ -2662,6 +2878,9 @@ Docs: https://www.nsauditor.com/ai/   |   Pricing: https://www.nsauditor.com/ai/
             extrasDir: F.extrasDir || undefined,
           });
           console.log(`imported ${out.imported} CVE(s), skipped ${out.skipped}, errors ${out.errors}`);
+          // WHERE it went — the same location every scan reads, from any directory (Enterprise 1.1.0).
+          // Printed because an import into a place the operator did not expect is an import nobody uses.
+          if (out.store?.path) console.log(`  store: ${out.store.path} (${out.store.source})`);
           // ⚠️ THE SKIP SPLIT PRINTS HERE BECAUSE THE DATA-LOSS TICKET ORIGINATES HERE.
           // On a real NVD year file ~24% of records are skipped (measured on the 2024 feed:
           // 39,219 in, 29,866 imported, 9,353 skipped). An operator reading a bare "skipped 9353"
@@ -2916,23 +3135,21 @@ Docs: https://www.nsauditor.com/ai/   |   Pricing: https://www.nsauditor.com/ai/
     process.exit(code);
   }
 
-  if (cmd !== 'scan') {
-    console.error(`Unknown command: ${cmd}`);
-    process.exit(2);
+  const targetRefusal = scanTargetRefusal({ cmd, host, hostFile });
+  if (targetRefusal) {
+    console.error(targetRefusal.message);
+    process.exit(targetRefusal.code);
   }
 
-  // Resolve host list
+  // Resolve host list — scanTargetRefusal has established that hostFile or host is set.
   let hosts;
   if (hostFile) {
     // Reuse the up-front resolution done for the CLOUD_PROVIDER reconcile (avoids a
     // second parse + duplicate suspicious-line warnings); re-parse only if that was
     // skipped/failed so a genuine host-file error still surfaces here as before.
     hosts = resolvedHosts ?? await parseHostFile(hostFile);
-  } else if (host) {
-    hosts = await parseHostArg(host);
   } else {
-    console.error('Fatal: --host or --host-file is required');
-    process.exit(2);
+    hosts = await parseHostArg(host);
   }
 
   if (!hosts || hosts.length === 0) {
@@ -2942,6 +3159,10 @@ Docs: https://www.nsauditor.com/ai/   |   Pricing: https://www.nsauditor.com/ai/
 
   const opts = { insecureHttps };
   if (testHooks.importEE) opts.importEE = testHooks.importEE;
+  if (testHooks.resolveEE) opts.resolveEE = testHooks.resolveEE;
+  // `testHooks.nowStamp`: a test seam, absent in every real invocation — it pins the per-host directory's second so a
+  // leg can drive the same-second collision through the shipped scan path.
+  if (testHooks.nowStamp) opts.nowStamp = testHooks.nowStamp;
   if (ports) opts.ports = ports;
   if (compliance) opts.compliance = compliance;
   if (complianceScope) opts.complianceScope = complianceScope;
@@ -3116,6 +3337,13 @@ Docs: https://www.nsauditor.com/ai/   |   Pricing: https://www.nsauditor.com/ai/
   // Collect all scan outputs for post-processing
   const scanOutputs = [];
 
+  // ⚠️ AN ABORT MUST STILL FINALISE THE RUN RECORD (board item 2). A host that throws — the SSRF guard
+  // refusing a private address is the measured case — used to escape straight past the finalize block
+  // below, leaving an open, unsealed record that every later report called `chain-unreadable`. The
+  // error is held, the record is finalised and sealed as `aborted` with its reason, and the error is
+  // then re-thrown so the scan's exit is exactly what it was.
+  let scanAbort = null;
+  try {
   // Single host — preserve original behaviour (flat output)
   if (hosts.length === 1) {
     const out = await scanSingleHost(pm, hosts[0], plugins, opts, promptMode);
@@ -3160,6 +3388,9 @@ Docs: https://www.nsauditor.com/ai/   |   Pricing: https://www.nsauditor.com/ai/
     };
     console.log(JSON.stringify(out, null, 2));
   }
+  } catch (err) {
+    scanAbort = err;
+  }
 
   // ── Run record: FINALIZE, after every host has completed (or failed) ───────
   // Wrapped for the same reason the START block is: a malformed argument here must
@@ -3168,15 +3399,25 @@ Docs: https://www.nsauditor.com/ai/   |   Pricing: https://www.nsauditor.com/ai/
     const writtenOutputs = scanOutputs.filter((o) => o && o.hostAppended === true);
     const kevAgg = aggregateStoreLoad(writtenOutputs, 'kevDataAsOf', 'KEV');
     const epssAgg = aggregateStoreLoad(writtenOutputs, 'epssDataAsOf', 'EPSS');
-    await finalizeRunRecord(outRoot, runId, {
+    const nvdAgg = aggregateNvdCache(writtenOutputs.map((o) => o.nvdCache ?? null));
+    if (nvdAgg.warning) console.warn(`[RunRecord] ${nvdAgg.warning}`);
+    // `testHooks._finalizeRunRecord`: a test seam, absent in every real invocation — it lets a leg prove
+    // that a finalize which itself fails never replaces the scan's own error.
+    await (testHooks?._finalizeRunRecord ?? finalizeRunRecord)(outRoot, runId, {
       finishedAt: new Date().toISOString(),
       kevLoaded: kevAgg.loaded, kevSnapshot: kevAgg.snapshot,
       epssLoaded: epssAgg.loaded, epssSnapshot: epssAgg.snapshot,
+      nvdCache: nvdAgg.value,
+      status: scanAbort ? 'aborted' : 'finished',
+      // A CODE plus the error's MESSAGE (first line), never a stack: a stack carries local paths.
+      abortReason: scanAbort ? abortReasonOf(scanAbort) : null,
     });
     if (getTierFromEnv() === 'ce') await pruneRunRecordsForCE(outRoot);
   } catch (err) {
     console.warn('[RunRecord] Failed to finalize/prune run record:', err?.message || err);
   }
+  // The record is sealed; now the abort takes its original course.
+  if (scanAbort) throw scanAbort;
 
   // --- SARIF output ---
   const wantSarif = outputFormat && String(outputFormat).toLowerCase().includes('sarif');