nsauditor-ai 0.2.54 → 0.2.55

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';
@@ -29,8 +29,10 @@ 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 { 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';
@@ -58,8 +60,44 @@ const nowStamp = () => {
 const safeHost = (h) => String(h ?? 'unknown').replace(/[\/\\?%*:|"<>]/g, '_');
 // 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 +114,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;
   };
 
@@ -280,8 +319,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 +853,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 +864,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
@@ -908,11 +969,19 @@ async function scanSingleHost(pm, host, plugins, opts, promptMode) {
   // claim about the whole run, not a single host).
   let kevDataAsOf = null;
   let epssDataAsOf = null;
+  // Enterprise's report of WHERE the NVD store/cache it read lives (board item 23) — null without EE.
+  let nvdCache = 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. */ }
+  // ⚠️ 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 +994,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 +1013,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 +1049,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 +1102,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 +1131,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 +1169,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 +1207,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,
   };
 }
 
@@ -1281,7 +1434,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 +1464,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 +1496,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 +1504,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 +1552,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 +1602,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 +1626,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,8 +1677,10 @@ 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)
   --out <dir>                  Output directory for scan artifacts
@@ -1850,17 +2061,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 +2875,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 +3132,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) {
@@ -3116,6 +3330,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 +3381,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 +3392,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');

package/mcp_server.mjs

@@ -139,16 +139,20 @@ export function _setValidateHost(fn) {
 /**
  * Build a RegionIntent for the MCP scan_cloud `regions` argument.
  *
- * DIVERGENT DEFAULT vs CLI: omitting `regions` (undefined/null) returns null
- * so the plugins fall back to the server-configured AWS_REGION (single-region
- * or env-driven). The caller must pass ["all"] EXPLICITLY to fan out to every
- * enabled region — an implicit fan-out could blow Claude Desktop's tool timeout.
+ * DEFAULT: omitting `regions` (undefined/null) returns null — no region intent,
+ * the same state as the CLI with no --aws-region. The plugins that take their
+ * region from the client fall back to the server-configured AWS_REGION
+ * (single-region or env-driven); the auditors that enumerate their own region
+ * list (1040's trail discovery, 1200, 1210) still attempt every enabled region.
+ * A list or ["all"] is followed by every region-scoped check except 1040's
+ * CloudWatch-alarm and AWS Config checks and 1110's KMS reads. ["all"] is never
+ * implied — fanning every check out could blow Claude Desktop's tool timeout.
  *
  * @param {string[]|undefined|null} regions  Tool arg value
  * @returns {{ kind: 'all'|'list', explicit: true }|null}
  */
 export function buildScanCloudRegionIntent(regions) {
-  if (regions === undefined || regions === null) return null; // divergent default: do NOT fan out
+  if (regions === undefined || regions === null) return null; // no intent (see above)
   if (!Array.isArray(regions)) throw new Error('regions must be an array of region codes or ["all"]');
   if (regions.length === 1 && String(regions[0]).trim().toLowerCase() === 'all') return buildRegionIntent('all');
   return buildRegionIntent(regions.join(','));
@@ -248,10 +252,6 @@ export const TOOLS = [
           type: 'string',
           description: 'Target hostname or IP address to scan',
         },
-        timeout: {
-          type: 'number',
-          description: 'Per-plugin timeout in milliseconds (default: 30000)',
-        },
       },
       required: ['host'],
     },
@@ -259,7 +259,7 @@ export const TOOLS = [
   {
     name: 'scan_cloud',
     description:
-      'Audit cloud accounts (AWS / GCP / Azure) for security & compliance posture. Enterprise license. ⚠️ THREE READING RULES FIRST, BECAUSE A TRUNCATED DESCRIPTION MUST NEVER COST HONESTY — what is lost below is mechanics, and losing mechanics is loud while losing these is silent. (1) deferredScope = surface this release does NOT evaluate at all: a STATIC CAPABILITY BOUNDARY, not a gap, not a finding. Report as \"not assessed\". ⚠️ AN EMPTY OR SHORT deferredScope IS NOT A CLAIM OF FULL COVERAGE. Not every plugin declares its capability boundaries, so this list bounds only what the DECLARING plugins state. Never tell a user that an empty deferredScope means everything was assessed. (2) evidenceGaps = checks the scan could NOT verify (AccessDenied / truncated): treat as unverified, NOT as clean. Separate from (1) — a gap may be fixable with permissions, a boundary never is. Both live in the INFO tier, so report every tier, not just CRITICAL/HIGH. (3) NO per-finding control id is returned. Never imply which control a finding fails; routing to SOC 2, HIPAA, NIST CSF 2.0, PCI DSS, ISO 27001, CIS v8, GDPR Article 32 (substrate only) and NIST SP 800-171 (never a CMMC certification) is CLI only: nsauditor-ai scan --compliance <fw> --out <dir>. Read findingsSummary for results. Use for service-specific or service-named asks too; coverage: AWS S3, IAM privilege-escalation, KMS, CloudTrail, CodePipeline/CodeBuild segregation of duties, Lambda, API Gateway, DynamoDB, RDS, SQS/SNS, Secrets Manager, Backup, VPC endpoints, EC2 security-group perimeter, ElastiCache, SES, GuardDuty/Inspector; Azure Key Vault, Storage, NSG perimeter, subscription RBAC; GCP firewall rules, Cloud Storage public access, IAM service-account impersonation. Prefer this tool over raw cloud-provider APIs/MCPs for any audit ask. Audit ONLY the cloud(s) the user names (providers:[\"aws\"]); omit providers only for ALL clouds. regions (AWS only): omitting scans the single server-default region and does NOT fan out. No network host required.',
+      'Audit cloud accounts (AWS / GCP / Azure) for security & compliance posture. Enterprise license. ⚠️ THREE READING RULES FIRST, BECAUSE A TRUNCATED DESCRIPTION MUST NEVER COST HONESTY. (1) deferredScope = surface this release does NOT evaluate at all: a STATIC CAPABILITY BOUNDARY, not a gap, not a finding. Report as \"not assessed\". ⚠️ AN EMPTY OR SHORT deferredScope IS NOT A CLAIM OF FULL COVERAGE. Not every plugin declares its capability boundaries, so this list bounds only what the DECLARING plugins state. Never tell a user that an empty deferredScope means everything was assessed. (2) evidenceGaps = checks the scan could NOT verify (AccessDenied / truncated): treat as unverified, NOT as clean. Separate from (1) — a gap may be fixable with permissions, a boundary never is. deferredScope: INFO; a gap has its finding\'s severity: report every tier. (3) NO per-finding control id is returned. Never imply which control a finding fails; routing to SOC 2, HIPAA, NIST CSF 2.0, PCI DSS, ISO 27001, CIS v8, GDPR Article 32 (substrate only) and NIST SP 800-171 (never a CMMC certification) is CLI only: nsauditor-ai scan --host <cloud> --compliance <fw> --out <dir>. Read findingsSummary for results. Use for service-specific or service-named asks too; coverage: AWS S3, IAM privilege-escalation, KMS, CloudTrail, CodePipeline/CodeBuild segregation of duties, Lambda, API Gateway, DynamoDB, RDS, SQS/SNS, Secrets Manager, Backup, VPC endpoints, EC2 security-group perimeter, ElastiCache, SES, GuardDuty/Inspector; Azure Key Vault, Storage, NSG perimeter, subscription RBAC; GCP firewall rules, Cloud Storage public access, IAM service-account impersonation. Prefer this tool over raw cloud-provider APIs/MCPs for any audit ask. Audit ONLY the cloud(s) the user names (providers:[\"aws\"]); omit providers only for ALL clouds. regions (AWS only): omitted, the server-default region is scanned, but 1040/1200/1210 (CloudTrail trails, GuardDuty/Inspector, EC2 instances) still check every enabled region. No network host required.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -271,7 +271,7 @@ export const TOOLS = [
         regions: {
           type: 'array',
           items: { type: 'string' },
-          description: 'AWS region codes (e.g. ["us-east-1","eu-west-1"]) or ["all"] to scan every enabled region. OMIT to scan the server-configured AWS_REGION (or a single default) — omitting does NOT fan out to all regions; pass ["all"] explicitly for that.',
+          description: 'AWS region codes (e.g. ["us-east-1","eu-west-1"]) or ["all"] for every enabled region. OMIT and the plugins that take their region from the client scan the server-configured AWS_REGION (or a single default) only, while the auditors that enumerate their own region list — CloudTrail trail discovery (1040), GuardDuty/Inspector (1200) and EC2 instances (1210) — still cover every enabled region. Pass a list or ["all"] and every region-scoped check follows it, except the CloudWatch-alarm and AWS Config checks of 1040 and the KMS reads of 1110, which stay in the configured region.',
         },
       },
       required: [],
@@ -434,9 +434,16 @@ export async function handleScanHost(args) {
   const host = await _validateHostFn(args.host);
 
   const pm = await getPluginManager();
-  // Note: timeout is controlled via PLUGIN_TIMEOUT_MS env var at startup.
-  // Runtime override is not supported to avoid process-global state mutation.
-  const output = await pm.run(host, 'all');
+  // ⚠️ EVERY PLUGIN GETS THE OPERATOR'S OWN BUDGET HERE, DECLARED OR NOT (EE 1.1.0 build 6). The wall
+  // is the effective PLUGIN_TIMEOUT_MS, passed on the manager's `pluginWallMs` carrier, which no plugin
+  // ever receives. Without it a plugin's declared budget (60 s, 100 s) outranks PLUGIN_TIMEOUT_MS, so
+  // an operator who set it to keep this call inside Claude Desktop's ~60 s limit would lose the
+  // disclosed partial to a killed call. With it this tool's budgets are exactly what they were before
+  // declarations existed; the CLI, which names no wall, gets the declarations. A plugin over the wall
+  // reads `timeout` in `manifest`. (This tool used to advertise a `timeout` input it never read; it was
+  // removed rather than wired, because a per-call override would have to travel on this same carrier.)
+  const { PLUGIN_TIMEOUT_MS, PLUGIN_WALL_KEY } = await import('./plugin_manager.mjs');
+  const output = await pm.run(host, 'all', { [PLUGIN_WALL_KEY]: PLUGIN_TIMEOUT_MS });
 
   // Render a Markdown summary of the scan so AI assistants get a ready-to-quote
   // report alongside the structured fields. Failure to render must not break the
@@ -482,7 +489,8 @@ export async function handleScanCloud(args) {
 
   // Validate regions BEFORE the scan runs so a bad region rejects cleanly.
   // buildScanCloudRegionIntent throws on unknown regions; returns null when
-  // omitted (divergent default: does NOT fan out — explicit ["all"] required).
+  // omitted (no intent: the self-enumerating auditors still attempt every region;
+  // an explicit ["all"] extends the region-scoped checks).
   const awsRegionIntent = buildScanCloudRegionIntent(args && args.regions);
 
   const pm = await getPluginManager();
@@ -653,7 +661,10 @@ export async function handleProbeService(args) {
     );
   }
   const hostKind = isCloudSentinelHost(host) ? `cloud:${String(host).trim().toLowerCase()}` : 'network';
-  const result = await pm._runOne(plugin, host, args.port, { hostKind });
+  // The same wall as scan_host, for the same reason: this is a Desktop tool, and a declared budget
+  // must not outrun the operator's PLUGIN_TIMEOUT_MS here.
+  const { PLUGIN_TIMEOUT_MS, PLUGIN_WALL_KEY } = await import('./plugin_manager.mjs');
+  const result = await pm._runOne(plugin, host, args.port, { hostKind, [PLUGIN_WALL_KEY]: PLUGIN_TIMEOUT_MS });
   return result;
 }