nsauditor-ai 0.2.50 → 0.2.51

package/cli.mjs

@@ -30,6 +30,11 @@ import { getAllTechniques } from './utils/attack_map.mjs';
 import { TOOL_VERSION } from './utils/tool_version.mjs';
 import { resolveBaseOutDir } from './utils/output_dir.mjs';
 import { toCleanPath } from './utils/path_helpers.mjs';
+import { newRunId, writeRunStart, appendHostWritten, finalizeRunRecord, pruneRunRecordsForCE } from './utils/run_record.mjs';
+import { loadRun } from './utils/report_inputs.mjs';
+import { loadBrand } from './utils/brand.mjs';
+import { renderExecutiveReport } from './utils/executive_report.mjs';
+import { renderJiraCsv } from './utils/jira_export.mjs';
 
 /* ------------------------- helpers & utilities ------------------------- */
 
@@ -95,7 +100,7 @@ function redactSensitiveForAI(input, targetHost) {
 
 /* ------------------------- OpenAI & reporting -------------------------- */
 
-async function maybeSendToOpenAI({ host, results, conclusion, promptMode = 'basic', outDir: presetOutDir = null }) {
+async function maybeSendToOpenAI({ host, results, conclusion, promptMode = 'basic', outDir: presetOutDir = null, runId = null, pluginStatus = [] }) {
   // --- env & opts -----------------------------------------------------------
   const sendEnabled   = parseBool(process.env.AI_ENABLED);
   const redactEnabled = parseBool(process.env.OPENAI_REDACT, true);
@@ -200,7 +205,11 @@ async function maybeSendToOpenAI({ host, results, conclusion, promptMode = 'basi
 
   // --- Admin RAW (unsanitized) JSON + Admin HTML ----------------------------
   try {
-    const adminRaw = { host, summary: summaryWithFullSerial, results, conclusion };
+    // `runId` ties this per-host raw to the run record written at scan start
+    // (utils/run_record.mjs); `pluginStatus` is the manifest classifying every selected
+    // plugin as ran|skipped|timeout|error — both additive, no existing consumer reads
+    // either name (verified with `grep -rn "adminRaw\." cli.mjs`).
+    const adminRaw = { host, summary: summaryWithFullSerial, results, conclusion, runId, pluginStatus };
     await fsp.writeFile(adminRawPath, JSON.stringify(adminRaw, null, 2), 'utf8');
     console.log('[OpenAI] Wrote admin RAW:', adminRawPath);
 
@@ -784,6 +793,29 @@ export async function parseArgs(argv) {
   const awsRegionVal = get('aws-region');
   args.awsRegion = awsRegionVal === undefined ? undefined : awsRegionVal;
 
+  // ── the Pro `report` subcommand (Task 8) ────────────────────────────────────────────────────
+  // ⚠️ CC-4: `--brand`/`--run`/`--out`/`--from` do NOT go through `str()` — `str()` collapses a
+  // value-less flag to the SAME `null` an absent flag produces, and for these four that erases a
+  // real distinction. `--brand` absent is a legitimate default (unbranded); `--brand` typed with
+  // its value swallowed by a shell glob is an operator MISTAKE that must not silently produce the
+  // exact same unbranded report while exiting 0 — "a flag that quietly does nothing is how an
+  // operator concludes a subject was resolved" (runReport's own header). Same reasoning as the
+  // existing `--sla-policy`/`--compliance-history` tri-state below: keep `get()`'s raw tri-state
+  // (undefined absent / `true` value-less / string present) and let `runReport` refuse the `true`
+  // case by name. `--format` is deliberately NOT included here — it has no valid "absent" default
+  // (both absent and value-less already fail its enum check with a clear message), so collapsing
+  // it via `str()` costs nothing.
+  const fromVal = get('from');
+  args.from = fromVal === undefined ? undefined : fromVal;
+  args.format = str('format');
+  const runVal = get('run');
+  args.run = runVal === undefined ? undefined : runVal;
+  const brandVal = get('brand');
+  args.brand = brandVal === undefined ? undefined : brandVal;
+  const reportOutVal = get('out');
+  args.out = reportOutVal === undefined ? undefined : reportOutVal;
+  args.allowPartial = a.includes('--allow-partial');
+
   return args;
 }
 
@@ -822,7 +854,10 @@ async function scanSingleHost(pm, host, plugins, opts, promptMode) {
     }
   }
 
-  const { results, conclusion } = await pm.run(host, plugins || 'all', opts);
+  // `manifest` classifies every selected plugin as ran|skipped|timeout|error with a reason.
+  // Discarding it is what makes "no findings" ambiguous between a clean estate and one whose
+  // plugins never loaded — see utils/run_record.mjs.
+  const { results, conclusion, manifest: pluginStatus = [] } = await pm.run(host, plugins || 'all', opts);
 
   // Enrich conclusion with MITRE ATT&CK technique mapping
   const techniques = getAllTechniques(conclusion);
@@ -864,8 +899,19 @@ async function scanSingleHost(pm, host, plugins, opts, promptMode) {
   // is marked, because an operator who asked for `--compliance` and got no report must not
   // have to diff directories to discover it.
   let ee = null;
+  // The KEV/EPSS store's OWN `dataAsOf`, read from the same enrichment result CE already
+  // receives — set (or left null) inside the try below, and hoisted here so it survives
+  // past that block's scope. `null` means "not loaded for this host" — either EE is absent,
+  // enrichment threw before reaching exploit intel, or the tier/store genuinely has none;
+  // all three collapse to the same honest "not evaluated" reading for THIS host, and the
+  // top-level scan loop aggregates across hosts (utils/run_record.mjs's `kevLoaded` is a
+  // claim about the whole run, not a single host).
+  let kevDataAsOf = null;
+  let epssDataAsOf = null;
   try {
-    ee = await import('@nsasoft/nsauditor-ai-ee');
+    // `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. */ }
   try {
     const eeEnrichment = ee ? await ee.enrichScan(conclusion, {
@@ -881,6 +927,17 @@ async function scanSingleHost(pm, host, plugins, opts, promptMode) {
       results,
       onWarn: (msg) => console.warn(`[EE] ${msg}`),
     }) : 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
+    // `exploitIntel.stores.{kev,epss}.dataAsOf`. EE's own comment there says this object is
+    // "ALWAYS PRESENT on a Pro scan, including when no store is configured" — so `null` here
+    // means the store genuinely was not loaded, not that we asked the wrong field and got
+    // `undefined` by accident. Independent of `enrichedPrompt` below: that governs whether the
+    // AI prompt gets the enrichment envelope, not whether a store was loaded for this host.
+    const stores = eeEnrichment?.exploitIntel?.stores;
+    kevDataAsOf = stores?.kev?.dataAsOf ?? null;
+    epssDataAsOf = stores?.epss?.dataAsOf ?? null;
     if (eeEnrichment?.enrichedPrompt) {
       conclusion.result = conclusion.result || {};
       conclusion.result.eeEnrichment = eeEnrichment;
@@ -896,15 +953,50 @@ async function scanSingleHost(pm, host, plugins, opts, promptMode) {
     conclusion.result.eeEnrichmentError = String(err?.message ?? err);
   }
 
-  const { file_paths: ai_file_paths, ai_conclusion, ai_status, ai_error } = await maybeSendToOpenAI({ host, results, conclusion, promptMode, outDir });
+  const { file_paths: ai_file_paths, ai_conclusion, ai_status, ai_error } = await maybeSendToOpenAI({
+    host, results, conclusion, promptMode, outDir, runId: opts?.runId ?? null, pluginStatus,
+  });
   // BUG1 (fail-VISIBLE): a one-line end-of-scan AI status so a failed/aborted AI
   // conclusion is not silently swallowed under the per-stage logs.
   console.log(aiSummaryLine({ host, ai_status, ai_error }));
 
   // --- Scan history: record & compare ---
   let scanDiff = null;
+  // Whether THIS host actually landed in the run record's `hostsWritten` — distinct from
+  // whether the scan itself succeeded. `appendHostWritten` can fail independently (a
+  // malformed argument, a disk fault) while the rest of the scan completes cleanly, and the
+  // top-level KEV/EPSS aggregation must count only hosts the record actually NAMES — a host
+  // whose directory the record never mentions cannot be claimed to have been "evaluated"
+  // 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';
+
+    // 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
+    // that a caller-side throw (e.g. a `dir`/`host` that fails to coerce) rejects straight to
+    // its caller, unlike an fs fault, which `appendHostWritten` always wraps — so this call
+    // must sit inside an existing try/catch or a malformed argument could fail an otherwise
+    // fine scan. `opts.runId` is unset under CTEM watch mode (no single run record there);
+    // skipping in that case is a scope decision, not an error.
+    //
+    // ⚠️ DELIBERATELY NOT `outRoot` ABOVE. The record NAMES this host's directory
+    // (`dir: path.basename(outDir)`), so it must resolve the SAME root `outDir` was created
+    // under — resolveBaseOutDir(), the resolver `baseOutDir` above (and maybeSendToOpenAI's
+    // own fallback) already use. `outRoot` above is the OLDER inline expression
+    // (`toCleanPath(...).replace(/\.[^/.]+$/, '')`), kept as-is here because it also locates
+    // `scan_history.jsonl` — a different artifact with no directory references, so moving it
+    // would relocate an existing file and is out of scope. The two resolvers agree only when
+    // `--out` has no dot in it; resolveBaseOutDir()'s own header comment documents the
+    // divergence as a fixed silent evidence-misplacement bug (`--out .../ee-0.32.8` read as a
+    // file extension under the inline regex and scattered artifacts into the parent directory,
+    // EE 0.32.8 pre-publish smoke gate). Do NOT "tidy" this back to match `outRoot` above —
+    // 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) });
+    }
+
     const services = conclusion?.result?.services ?? [];
     const serviceFindingsCount = services.reduce((n, svc) => {
       if (svc.anonymousLogin === true) n++;
@@ -959,7 +1051,44 @@ async function scanSingleHost(pm, host, plugins, opts, promptMode) {
     console.warn('[ScanHistory] Failed to record/compare scan:', err?.message || err);
   }
 
-  return { host, results, conclusion, ai_file_paths, ai_conclusion, ai_status, ai_error, scanDiff };
+  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,
+  };
+}
+
+// The run record's `kevLoaded`/`kevSnapshot` (and the same pair for epss) are a claim about
+// the WHOLE run, read by Task 4's consumer as one sentence covering every finding on the
+// page ("Known-exploited status evaluated against the CISA KEV snapshot dated <date>") — so
+// the aggregate across hosts must be ALL-OR-NOTHING, never "first non-null" and never "last
+// host wins":
+//   - loaded:true  only if EVERY WRITTEN host reported a non-null `dataAsOf` for this store.
+//   - any written host lacking one -> loaded:false (a warning names how many DID have it) —
+//     a run where the store was present for host 1 and absent for host 2 must not print
+//     "evaluated" over host 2's findings; that is the same false clean this whole fix exists
+//     to remove, with the sign flipped.
+//   - all loaded but disagreeing on the date -> loaded:true, snapshot:null, plus a warning —
+//     a snapshot date true for some hosts and wrong for others is worse than no date at all.
+// Scoped to hosts with `hostAppended === true` — a host the record does not NAME in
+// `hostsWritten` cannot be the subject of a claim the record makes, whatever its own
+// enrichment found (see `hostAppended`'s own comment in scanSingleHost).
+function aggregateStoreLoad(writtenOutputs, field, label) {
+  if (writtenOutputs.length === 0) return { loaded: false, snapshot: null };
+  const values = writtenOutputs.map((o) => o[field] ?? null);
+  const present = values.filter((v) => v != null);
+  if (present.length < values.length) {
+    console.warn(`[RunRecord] ${label} store was loaded for only ${present.length} of `
+      + `${values.length} written host(s) — recording ${label} as NOT loaded for this run.`);
+    return { loaded: false, snapshot: null };
+  }
+  const unique = [...new Set(present)];
+  if (unique.length > 1) {
+    console.warn(`[RunRecord] ${label} store dataAsOf disagreed across written hosts `
+      + `(${unique.join(', ')}) — recording loaded with no snapshot date.`);
+    return { loaded: true, snapshot: null };
+  }
+  return { loaded: true, snapshot: unique[0] };
 }
 
 /* -------------------- CI/CD severity threshold helpers ------------------- */
@@ -1109,7 +1238,200 @@ export async function preflightGrcIfRequested(env, opts = {}) {
   return { ran: true };
 }
 
-export async function main() {
+// `testHooks` is additive and test-only — every real invocation (the auto-run at the bottom
+// of this file, and the published `bin`) calls `main()` with no argument, so `testHooks`
+// defaults to `{}` and changes nothing about production behaviour. `testHooks.importEE`
+// mirrors `preflightNsauditorPosture`'s `importEE` option elsewhere in this file: it lets a
+// 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.
+// 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
+// test suite via `resolveCapabilities('pro')` with no env override (see runReport's header), and
+// a refusal message built from a DIFFERENT source than the one that gated the request would be
+// able to name a tier inconsistent with the caps that were actually checked. resolveCapabilities()
+// is monotonic (ce ⊆ pro ⊆ enterprise), so checking one sentinel capability per tier, from the
+// top down, exactly recovers the tier it was resolved from.
+function tierLabelFromCaps(caps) {
+  if (hasCapability(caps, 'cloudScanners')) return 'enterprise';
+  if (hasCapability(caps, 'intelligenceEngine')) return 'pro';
+  return 'ce';
+}
+
+/**
+ * `report` subcommand handler.
+ *
+ * Consumes Tasks 4-7: `loadRun` (utils/report_inputs.mjs), `loadBrand` (utils/brand.mjs),
+ * `renderExecutiveReport` (utils/executive_report.mjs), `renderJiraCsv` (utils/jira_export.mjs).
+ *
+ * `caps` is an ARGUMENT, never resolved inside this function — that is what makes the Pro path
+ * testable via `resolveCapabilities('pro')` with no env override; an env override here would be
+ * a licence bypass in product code. The real CLI dispatch (in `main()`, below) is the only
+ * caller that resolves it from the environment, via `resolveCapabilities(getTierFromEnv())`.
+ *
+ * Never calls `console.log`/`console.error` directly: every line is accumulated into `stdout`/
+ * `stderr` strings and returned, so the CLI dispatch can write them to the real streams and a
+ * handler-level test can assert on exactly what would have been printed without spawning a
+ * process.
+ *
+ * Exit codes (constraint 5 — an EXHAUSTIVE switch below, not an if/else, so an eleventh
+ * `loadRun` reason can never fall through unclassified): **2** = the request itself is malformed
+ * 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).
+ *
+ * @returns {Promise<{ code: number, stdout: string, stderr: string }>}
+ */
+export async function runReport(args, caps) {
+  const outLines = [];
+  const errLines = [];
+  const log = (s) => outLines.push(s);
+  const logErr = (s) => errLines.push(s);
+  const finish = (code) => ({
+    code,
+    stdout: outLines.length ? `${outLines.join('\n')}\n` : '',
+    stderr: errLines.length ? `${errLines.join('\n')}\n` : '',
+  });
+
+  // ⚠️ FLAGS VALIDATE BEFORE THE CAPABILITY GATE (constraint 4). Otherwise every flag error on
+  // CE is reported as a tier problem and no flag validation is testable from the CLI at all.
+  //
+  // CC-4: a value-less `--brand`/`--run`/`--out`/`--from` must be FATAL, not silently absorbed
+  // into the same behaviour as the flag never having been typed. `parseArgs` preserves the raw
+  // tri-state for these four (see its own comment) precisely so this check can tell "the operator
+  // never asked" (undefined — fine, defaults apply) apart from "the operator asked and the shell
+  // ate the value" (`true` — a shell glob that matched nothing, a trailing flag with nothing
+  // after it). `--brand` is the sharpest case: an absent brand and a swallowed brand path both
+  // produce the identical unbranded default report at exit 0, so nothing downstream can ever
+  // 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]]) {
+    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.');
+      return finish(2);
+    }
+  }
+  if (!args.from || typeof args.from !== 'string') {
+    logErr('`report` needs `--from <out-dir>`.');
+    return finish(2);
+  }
+  const format = String(args.format ?? '');
+  if (!['executive', 'jira'].includes(format)) {
+    logErr('`report` needs `--format executive` or `--format jira`.');
+    return finish(2);
+  }
+  if (args.brand && format === 'jira') {
+    logErr('`--brand` applies to `--format executive` only; the jira format is a CSV with no '
+      + 'branded surface. Refusing rather than ignoring the flag.');
+    return finish(2);
+  }
+
+  if (!hasCapability(caps, 'clientReporting')) {
+    logErr('`report` is a Pro capability. Your licence resolves to tier '
+      + `"${tierLabelFromCaps(caps)}". No file has been written.`);
+    return finish(2);
+  }
+
+  const loaded = await loadRun(args.from, { runId: args.run ?? null, allowPartial: !!args.allowPartial },
+    { tier: tierLabelFromCaps(caps) });
+  if (!loaded.ok) {
+    logErr(loaded.message);
+    // MAP BY REASON, not by "loadRun said no" — an EXHAUSTIVE switch over the ten 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.
+    switch (loaded.reason) {
+      case 'no-run':
+      case 'record-unreadable':
+        return finish(2);
+      case 'ambiguous-run':
+      case 'binding-mismatch':
+      case 'incomplete-run':
+      case 'older-format':
+      case 'partial-hosts':
+      case 'record-absent-inside-window':
+      case 'record-absent-outside-window':
+      case 'unknown-schema':
+        return finish(1);
+      default:
+        logErr(`report: internal error — loadRun returned an unrecognised refusal reason `
+          + `"${loaded.reason}". Refusing rather than guessing whether this is a command or a `
+          + 'run problem.');
+        return finish(2);
+    }
+  }
+
+  const { model } = loaded;
+  log(`[report] runId ${model.runId} · started ${model.startedAt}`);
+  // The container census ran inside loadRun. A container holding finding-like objects that
+  // no reader opens is announced to the OPERATOR here and disclosed to the READER in the
+  // report itself — two audiences, two surfaces, because a warning nobody reads is not a
+  // guard, and the artifact is what reaches the customer.
+  for (const u of (model.unreadContainers ?? [])) {
+    for (const [container, n] of Object.entries(u.unread)) {
+      logErr(`[report] WARNING: ${n} finding-like object(s) on host ${u.host} live in `
+        + `\`${container}\`, which this report does not read. They are NOT in the output.`);
+    }
+  }
+  // Both caveats are independent facts about the SAME run and either can hold without the
+  // other — a run can be missing hosts AND never have recorded completion at once. Two separate
+  // `if`s, deliberately, not `if`/`else if`: the latter would silently drop whichever caveat it
+  // checked second, which is exactly the "operator concludes the wrong thing from what they see"
+  // failure this feature exists to prevent.
+  if (model.coverage.partial) {
+    // ⚠️ `model.coverage.missing` names only the NAMED-missing hosts — an unparseable `--host`
+    // input is counted but can never be named (report_inputs.mjs's own computeMissing split), so
+    // `missing.length` alone would read a run with only an unparseable deficit as "0 missing"
+    // while `coverage.partial` is true. `requested - written` is the authoritative count
+    // regardless of whether the deficit can be named.
+    const gap = Math.max(0, model.coverage.requested - model.coverage.written);
+    log(`[report] coverage: partial — ${gap} of ${model.coverage.requested} not scanned`);
+  }
+  if (model.coverage.incomplete) {
+    log('[report] coverage: incomplete — the run did not record completion');
+  }
+
+  let body;
+  let ext;
+  if (format === 'executive') {
+    const brandResult = await loadBrand(args.brand ?? null);
+    if (!brandResult.ok) {
+      logErr(brandResult.message);
+      return finish(2);
+    }
+    body = renderExecutiveReport(model, brandResult.brand, { renderedAt: new Date() });
+    ext = 'html';
+  } else {
+    body = renderJiraCsv(model);
+    ext = 'csv';
+  }
+
+  // Beside the run record, named for the run — deterministic across re-renders (a re-render of
+  // the SAME run overwrites the same file rather than accumulating one file per render, which
+  // would leave no way to tell which copy is current).
+  const outPath = (args.out && typeof args.out === 'string')
+    ? args.out
+    : path.join(args.from, `report_${model.runId}.${ext}`);
+
+  try {
+    await fsp.writeFile(outPath, body, 'utf8');
+  } catch (e) {
+    // A WRITE FAILURE (an unwritable --out, a directory in its place, a missing parent, a full
+    // disk) is an ENVIRONMENT problem, not a run problem: name the path and refuse loudly rather
+    // than falling through as a silent 0.
+    logErr(`report: could not write ${outPath}: ${e?.message || e}`);
+    return finish(2);
+  }
+  log(`[report] wrote ${outPath}`);
+  return finish(0);
+}
+
+export async function main(testHooks = {}) {
   const args = await parseArgs(process.argv);
   const { cmd, host, plugins, insecureHttps, hostFile, parallel, failOn, outputFormat, watch, intervalMinutes, webhookUrl, alertSeverity, ports, compliance, complianceScope, complianceHistory, slaPolicy, attestWindow, framework, awsRegion, approvalArgs, feedArgs } = args;
 
@@ -1130,6 +1452,7 @@ export async function main() {
 Usage:
   nsauditor-ai [scan] --host <ip|cidr|hostname> [options]
   nsauditor-ai [scan] --host-file <path> [options]
+  nsauditor-ai report --from <dir> --format executive|jira [options]   (Pro)
   nsauditor-ai license <subcommand>
   nsauditor-ai security <subcommand>
   nsauditor-ai validate
@@ -1321,6 +1644,30 @@ Examples:
   nsauditor-ai license install enterprise_eyJhbGciOiJFUzI1NiIs...
   nsauditor-ai license --status
 
+Report subcommand (Pro):
+  nsauditor-ai report --from <dir> --format executive|jira [--run <id>]
+                       [--brand <brand.json>] [--out <path>] [--allow-partial]
+        Renders a client-facing deliverable from a completed scan run under --from.
+        --from <dir>          The scan --out directory that holds the run's record
+                               and per-host evidence. Required.
+        --format executive    A self-contained, print-ready HTML report with a no-egress
+                               invariant (no live network reference other than an
+                               http(s)/mailto <a href>).
+        --format jira         A Jira-importer CSV (Summary/Description/Priority/Labels/
+                               External ID); the import mapping is done in Jira and has
+                               not been verified against a live Jira instance.
+        --run <id>             Report a specific run id instead of the newest one under
+                               --from.
+        --brand <brand.json>  Cover-page branding (company name, prepared-by, contact,
+                               logo) for --format executive only.
+        --out <path>           Write to this path instead of the default
+                               report_<runId>.<ext> beside the run record.
+        --allow-partial        Render even if some requested hosts were never written, or
+                               the run never recorded completion. The report states this
+                               on its cover; it never hides it.
+        A value-less --from/--brand/--run/--out (nothing after the flag, or a shell glob
+        that swallowed the argument) is a fatal error, not a silent default.
+
 Docs: https://www.nsauditor.com/ai/   |   Pricing: https://www.nsauditor.com/ai/pricing/`);
     process.exit(0);
   }
@@ -2558,6 +2905,17 @@ Docs: https://www.nsauditor.com/ai/   |   Pricing: https://www.nsauditor.com/ai/
     }
   }
 
+  if (cmd === 'report') {
+    // The CLI resolves capabilities from the verified licence and hands them to the handler;
+    // the handler never resolves them itself (see runReport()'s own header for why — an env
+    // override there would be a licence bypass in product code, and it is what makes the Pro
+    // path testable via resolveCapabilities('pro') with no env override at all).
+    const { code, stdout, stderr } = await runReport(args, resolveCapabilities(getTierFromEnv()));
+    if (stdout) process.stdout.write(stdout);
+    if (stderr) process.stderr.write(stderr);
+    process.exit(code);
+  }
+
   if (cmd !== 'scan') {
     console.error(`Unknown command: ${cmd}`);
     process.exit(2);
@@ -2583,6 +2941,7 @@ Docs: https://www.nsauditor.com/ai/   |   Pricing: https://www.nsauditor.com/ai/
   }
 
   const opts = { insecureHttps };
+  if (testHooks.importEE) opts.importEE = testHooks.importEE;
   if (ports) opts.ports = ports;
   if (compliance) opts.compliance = compliance;
   if (complianceScope) opts.complianceScope = complianceScope;
@@ -2694,6 +3053,66 @@ Docs: https://www.nsauditor.com/ai/   |   Pricing: https://www.nsauditor.com/ai/
     return; // keep process alive via setInterval
   }
 
+  // ── Run record: START, before any host runs ────────────────────────────────
+  // Scoped to this (non-watch) path: CTEM watch mode returns above and has its own
+  // indefinite-cycle lifecycle with no single "end" to finalize against — opts.runId
+  // stays unset there, which scanSingleHost's per-host append guard reads.
+  // Written at START so an interrupted scan leaves a record with NO finishedAt — the case
+  // `requested − written` arithmetic cannot see when the crash preceded any host directory.
+  // Wrapped: utils/run_record.mjs documents that a caller-side throw building the record
+  // (never an fs fault, which writeRunStart already wraps) rejects to ITS caller — this
+  // must not be able to fail an otherwise-fine scan.
+  //
+  // ⚠️ resolveBaseOutDir(), NOT the inline `toCleanPath(...).replace(/\.[^/.]+$/, '')`
+  // expression scan-history uses elsewhere in this file. The record NAMES every host
+  // directory it references (`hostsWritten[].dir`), and those directories are created under
+  // resolveBaseOutDir() (scanSingleHost's `baseOutDir`) — the two resolvers diverge for a
+  // dotted `--out` (resolveBaseOutDir()'s own header comment documents this exact shape as a
+  // fixed silent evidence-misplacement bug: `--out .../ee-0.32.8` read as a file extension
+  // under the inline regex). Using the inline expression here would write the record to one
+  // directory while every directory it names lives in another — a coverage lie. Do NOT
+  // "tidy" this back to match the neighbouring inline calls (scan-history intentionally keeps
+  // using the inline expression; it locates `scan_history.jsonl`, a different artifact with
+  // no directory references, so moving IT is out of scope).
+  const outRoot = resolveBaseOutDir();
+  const runId = newRunId();
+  try {
+    // AFTER `all` expansion: the word `all` alone says nothing about what actually ran.
+    // Mirrors PluginManager._resolveSelection()'s own logic using only its public surface
+    // (pm.plugins / pm.findPlugin), rather than reaching into a private method.
+    const pluginSpecForRecord = plugins || 'all';
+    const pluginNamesForRecord = (!pluginSpecForRecord || pluginSpecForRecord === 'all')
+      ? null
+      : (Array.isArray(pluginSpecForRecord) ? pluginSpecForRecord
+          : String(pluginSpecForRecord).split(',').map((s) => s.trim()).filter(Boolean));
+    const pluginsRequested = pluginNamesForRecord
+      ? pluginNamesForRecord.map((n) => pm.findPlugin(n)).filter(Boolean).map((p) => String(p.id ?? ''))
+      : pm.plugins.map((p) => String(p.id ?? ''));
+    let eeVersionForRecord = null;
+    try {
+      const eeManifest = _require('@nsasoft/nsauditor-ai-ee/package.json');
+      eeVersionForRecord = eeManifest?.version ?? null;
+    } catch { /* CE-only install — fine, the record just says so */ }
+    await writeRunStart(outRoot, {
+      runId, startedAt: new Date().toISOString(),
+      hostsRequested: hosts,               // the RESOLVED host list, never the --host-file path
+      pluginsRequested,
+      portsRequested: ports ?? null,
+      tier: getTierFromEnv(),
+      ceVersion: TOOL_VERSION, eeVersion: eeVersionForRecord,
+      // kevLoaded/kevSnapshot/epssLoaded/epssSnapshot are DELIBERATELY omitted here.
+      // writeRunStart's own defaults (false/null) are the correct STARTING state — before any
+      // host has run, nothing has been evaluated yet — and an interrupted scan that never
+      // reaches finalizeRunRecord() below is honestly left at that pessimistic default. The
+      // REAL values, aggregated across every host this run actually wrote, are set at
+      // finalize time (see below): this code path serves EE too (`ee.enrichScan` above), and
+      // EE, when a KEV/EPSS store is configured, reports the store's own `dataAsOf`.
+    });
+  } catch (err) {
+    console.warn('[RunRecord] Failed to write run start:', err?.message || err);
+  }
+  opts.runId = runId;
+
   // Collect all scan outputs for post-processing
   const scanOutputs = [];
 
@@ -2742,6 +3161,23 @@ Docs: https://www.nsauditor.com/ai/   |   Pricing: https://www.nsauditor.com/ai/
     console.log(JSON.stringify(out, null, 2));
   }
 
+  // ── Run record: FINALIZE, after every host has completed (or failed) ───────
+  // Wrapped for the same reason the START block is: a malformed argument here must
+  // never fail a scan that otherwise completed successfully.
+  try {
+    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, {
+      finishedAt: new Date().toISOString(),
+      kevLoaded: kevAgg.loaded, kevSnapshot: kevAgg.snapshot,
+      epssLoaded: epssAgg.loaded, epssSnapshot: epssAgg.snapshot,
+    });
+    if (getTierFromEnv() === 'ce') await pruneRunRecordsForCE(outRoot);
+  } catch (err) {
+    console.warn('[RunRecord] Failed to finalize/prune run record:', err?.message || err);
+  }
+
   // --- SARIF output ---
   const wantSarif = outputFormat && String(outputFormat).toLowerCase().includes('sarif');
   if (wantSarif) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nsauditor-ai",
-  "version": "0.2.50",
+  "version": "0.2.51",
   "description": "Modular AI-assisted network security audit platform \u2014 Community Edition",
   "type": "module",
   "private": false,