nsauditor-ai 0.2.55 → 0.2.56

package/utils/ee_load.mjs

@@ -0,0 +1,45 @@
+// utils/ee_load.mjs — load the Enterprise package, telling "not installed" from "installed and broken" (1.1.1).
+//
+// ⚠️ PRESENCE IS DECIDED BY RESOLUTION, NEVER BY THE ERROR. The scan path used to import inside a bare `catch {}` read as
+// "EE not installed — the ONLY silent case", and every failure landed there: a named import Community does not export
+// (Enterprise installed above the Community it runs on — the measured case at EE 174212f), a missing dependency of
+// Enterprise's own, a syntax error. The scan then ran with no analysis agents, no CVE mapper and no compliance report,
+// said nothing, and the Pro delta read every agent and engine row RESOLVED. An error CODE cannot separate the cases —
+// a dependency Enterprise lacks is `ERR_MODULE_NOT_FOUND` too — so the package's MANIFEST is resolved first (see
+// `isInstalled`): no manifest is absence, the one silent case; installed-but-the-import-throws is a load failure,
+// returned for the caller to report and record.
+//
+// Seams (tests only): `resolveEE(specifier)` replaces the resolver; `importEE()` replaces the import. An import seam
+// with NO resolver means the package is installed — a test that injects a module is describing one that resolves.
+
+export const EE_PACKAGE = '@nsasoft/nsauditor-ai-ee';
+
+// The DEFAULT resolver, as a replaceable dependency: Enterprise resolves from a development checkout, so a test that must
+// describe a checkout without it replaces this rather than the environment. Nothing in the product assigns it.
+export const resolverDeps = { resolve: (s) => import.meta.resolve(s) };
+
+/**
+ * PRESENCE IS THE PACKAGE'S MANIFEST, NEVER ITS ENTRY (the audit seat's T1-c fold 2). Resolving the entry answers "does
+ * the entry resolve": a package whose main file is missing (a truncated install) or whose exports map does not serve
+ * "." throws at RESOLUTION — measured on node 24 with real packages — and read as absent, which is installed-but-broken
+ * one layer down. The manifest resolves for any installed package; an exports map that declines to serve it
+ * (ERR_PACKAGE_PATH_NOT_EXPORTED) still proves the package directory is there. Only a manifest that cannot be found at
+ * all is absence. (Community's MCP server resolves the same manifest for the compliance matrix.)
+ */
+function isInstalled(resolve) {
+  try { resolve(`${EE_PACKAGE}/package.json`); return true; } catch (err) { return err?.code === 'ERR_PACKAGE_PATH_NOT_EXPORTED'; }
+}
+
+/**
+ * @param {{ importEE?: () => Promise<object>, resolveEE?: (specifier: string) => string }} [opts]
+ * @returns {Promise<{ ee: object|null, loadError: string|null }>}
+ */
+export async function loadEnterprise({ importEE = null, resolveEE = null } = {}) {
+  const resolve = resolveEE ?? (importEE ? null : resolverDeps.resolve);
+  if (resolve && !isInstalled(resolve)) return { ee: null, loadError: null };
+  try {
+    return { ee: await (importEE ?? (() => import(EE_PACKAGE)))(), loadError: null };
+  } catch (err) {
+    return { ee: null, loadError: String(err?.message ?? err) };
+  }
+}

package/utils/executive_report.mjs

@@ -636,6 +636,12 @@ function deltaBasis(delta) {
   return `comparable: ${legs} present in both runs; framework enumeration: ${fw}; ${integrity}`;
 }
 
+// What a not-comparable row's direction means, in the words a client reads.
+const NC_DIRECTION_WORDS = Object.freeze({
+  appeared: 'appeared in this run — not counted as NEW',
+  disappeared: 'absent from this run — not counted as RESOLVED',
+});
+
 function deltaRow(bucket, f, basis) {
   // ⚠️ THE REGION RIDES THE RESOURCE CELL (board E1(b)). Until E1 the region reached this table
   // only as a ` [<region>]` suffix that EE's region stamper had written INTO `resource` — which
@@ -674,15 +680,22 @@ ${escapeHtml(delta.refusal.detail)}</p>
   }
 
   const rows = [
-    ...delta.resolved.map((f) => deltaRow('resolved', f, deltaBasis(delta))),
-    ...delta.newFindings.map((f) => deltaRow('new', f, deltaBasis(delta))),
+    // A UDP row carries WHY its port counts as measured (1.1.1 — `basisNote`, e.g. "53/udp answered in the other run
+    // (dns open · dnsmasq 2.79)"), so a resolved UDP row shows its work on the row, never in a footer.
+    ...delta.resolved.map((f) => deltaRow('resolved', f, `${deltaBasis(delta)}${f.basisNote ? `; ${f.basisNote}` : ''}`)),
+    ...delta.newFindings.map((f) => deltaRow('new', f, `${deltaBasis(delta)}${f.basisNote ? `; ${f.basisNote}` : ''}`)),
     ...delta.changed.map((f) => deltaRow('changed', f, `${deltaBasis(delta)}; severity ${escapeHtml(String(f.from))} → ${escapeHtml(String(f.to))}`)),
     // The reason rides the row, not a legend.
     // ⚠️ THE CODE IS PRINTED VERBATIM, AND THAT IS THE DESIGN. A render-time label map was tried
     // here and reverted: it moved this seam and left the terminal's, so one outcome carried two
     // names. The noun that made a code wrong in front of a human was removed from the CODE
     // instead, which fixes every seam at once. See `NOT_COMPARABLE_REASONS` in scan_delta.mjs.
-    ...delta.notComparable.map((f) => deltaRow('not-comparable', f, `${f.reason}: ${f.detail}`)),
+    // ⚠️ THE DIRECTION RIDES THE ROW (1.1.1, the audit seat's fold). Every detail sentence is direction-neutral by
+    // construction ("open in the run that HOLDS this finding"), so without this a client could not tell a finding that
+    // APPEARED — a new-exposure candidate the run could not confirm — from one that VANISHED. The terminal view has
+    // always printed it; this page had not.
+    ...delta.notComparable.map((f) => deltaRow('not-comparable', f,
+      `${NC_DIRECTION_WORDS[f.direction] ?? 'direction not recorded'}; ${f.reason}: ${f.detail}`)),
   ].join('\n');
 
   const counts = `${delta.newFindings.length} new · ${delta.resolved.length} resolved · `

package/utils/output_dir.mjs

@@ -12,6 +12,7 @@
 //     can't recur in a new format writer (Task N.17).
 //   - `OPENAI_OUT_PATH` is honored as a legacy fallback.
 
+import fsp from 'node:fs/promises';
 import path from 'node:path';
 import { toCleanPath } from './path_helpers.mjs';
 
@@ -57,3 +58,70 @@ export function resolveBaseOutDir() {
 }
 
 // (toCleanPath moved to utils/path_helpers.mjs in v0.1.20 — no _internals export needed.)
+
+// A per-host directory's timestamp: YYYYMMDD_HHMMSS in LOCAL time, second granularity. Moved here from cli.mjs
+// unchanged, beside the helper that uses it, so the directory name has ONE definition.
+export function nowStamp(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())
+  );
+}
+
+// The host as a directory-name component. Moved here from cli.mjs unchanged — the per-host report filenames
+// (`scan_<host>.sarif.json` / `.csv` / `.md`) use it too, so both import it from here.
+export const safeHost = (h) => String(h ?? 'unknown').replace(/[\/\\?%*:|"<>]/g, '_');
+
+/**
+ * Create a FRESH per-host output directory and return its path.
+ *
+ * ⚠️ AN EXCLUSIVE CREATE, NEVER `recursive: true` ON THE LEAF (1.1.1 board — Gate 3-B on build 12). The name is
+ * `${safeHost(host)}_${nowStamp()}`, second-granular, so two scans of one host reaching this line in the same
+ * second computed the SAME name, and a recursive mkdir said yes to both: measured, three localhost scans wrote TWO
+ * directories and run 2's `scan_conclusion_raw.json` was overwritten by run 3's, exit 0, no warning. It is worse when
+ * the later run's finding queue is EMPTY — Enterprise writes `scan_finding_queue.json` only when there is something
+ * to write, so the earlier run's queue stayed in the shared directory and the later run's seal covered it as its own.
+ * The same second is reachable three ways: back-to-back runs, one run naming a host twice (`--host X,X`), and the
+ * repeated hour when daylight saving ends (the stamp is local time).
+ *
+ * So the leaf is created with `recursive: false`, which fails with EEXIST instead of reusing a directory, and a
+ * collision takes the next free suffix (`_2`, `_3`, …) — a COUNTER, not the run id: the run id is shared by every
+ * host of one run (so it cannot separate `--host X,X`) and is unset in watch mode. A WARNING naming both directories
+ * goes to STDOUT, where a scan's own progress lines go.
+ *
+ * ⚠️ When the seconds differ nothing changes: the name is byte-identical to the one this code has always written,
+ * because every reader, every run record's `hostsWritten[].dir` and every manifest keys on it.
+ *
+ * @param {string} baseOutDir   created if absent (recursively — the BASE may already exist; the leaf may not)
+ * @param {string} host
+ * @param {{ stamp?: () => string, log?: (line: string) => void, max?: number }} [opts]
+ *        `stamp` and `log` are seams; every real invocation takes the defaults.
+ * @returns {Promise<string>} the directory created
+ */
+export async function createHostOutDir(baseOutDir, host, { stamp = nowStamp, log = console.log, max = 100 } = {}) {
+  await fsp.mkdir(baseOutDir, { recursive: true });
+  // The stamp is taken ONCE: a suffix always belongs to the second it collided with.
+  const first = `${safeHost(host)}_${stamp()}`;
+  for (let n = 1; n <= max; n += 1) {
+    const dir = path.join(baseOutDir, n === 1 ? first : `${first}_${n}`);
+    try {
+      await fsp.mkdir(dir, { recursive: false });
+    } catch (e) {
+      if (e?.code === 'EEXIST') continue;
+      throw e;
+    }
+    if (n > 1) {
+      log(`[scan] WARNING: ${path.join(baseOutDir, first)} already exists — another scan of ${host} started in the same `
+        + `second — so this scan writes to ${dir} instead. Neither run's evidence overwrites the other's.`);
+    }
+    return dir;
+  }
+  // ⚠️ NEVER fall back to reusing an existing directory: that is the overwrite this function exists to prevent.
+  throw new Error(`could not create a fresh output directory for ${host} under ${baseOutDir}: `
+    + `${first} and ${max - 1} suffixed names already exist`);
+}

package/utils/report_inputs.mjs

@@ -25,6 +25,7 @@ import {
 } from './run_record.mjs';
 import { CE_RETENTION_MS } from './scan_history.mjs';
 import { canonicalHost } from './cloud_providers.mjs';
+import { isUdpTransport, TRANSPORT_OF_LABEL } from './scan_delta.mjs';
 
 const refuse = (reason, message) => ({ ok: false, reason, message });
 
@@ -213,6 +214,12 @@ export function shapeFinding(host, f, plugin = null, pluginName = null) {
     // FIELD and never a suffix: a suffix is a value change that fabricates churn across an
     // upgrade, a field is recomputed identically on both sides of any comparison.
     region,
+    // ⚠️ NO TRANSPORT ON THE PLUGIN PATH (1.1.1), and deliberately null rather than read from `details.protocol`:
+    // there it is a cloud RULE's protocol (an SG / NSG ingress rule, 1170 · 1221), not the transport of a service
+    // finding, and no shipped plugin emits a service finding over UDP (the UDP probes write `data[]` and the
+    // concluder's services, never `result.findings`). So the delta's UDP rule does not reach a plugin row — the
+    // declared limit, pinned in tests/scan_delta_udp_port_not_measured.test.mjs.
+    protocol: null,
     // ⚠️ AN EVIDENCE GAP IS SCOPE, NOT A FINDING, and the delta cannot tell them apart without
     // this. A gap record says "the scanner could not read this surface" — so a finding that
     // vanished behind one was not fixed, nobody looked. It is carried on the finding rather than
@@ -294,6 +301,10 @@ function shapeQueueEntry(host, q) {
   return {
     host,
     port: q?.port ?? q?.target?.port ?? null,
+    // THE PRODUCER'S PROTOCOL LABEL (1.1.1), verbatim — `udp`, `upnp`, `llmnr`, `mdns`, `https`, … It is an
+    // application label, not a transport; the delta's `isUdpTransport` decides which labels are UDP. Before this the
+    // loader dropped it, so a vanished 161/udp row was judged by the TCP port rule and read RESOLVED.
+    protocol: typeof q?.target?.protocol === 'string' ? q.target.protocol : null,
     severity: q?.severity != null ? String(q.severity).toUpperCase() : 'INFO',
     title: q?.title ?? null,
     detail: q?.description ?? q?.detail ?? null,
@@ -503,6 +514,55 @@ export function portScanOf(raw) {
   return { tcpOpen: ports(res.tcpOpen), tcpClosed: ports(res.tcpClosed) };
 }
 
+// What the run recorded about each UDP port (1.1.1) — the delta's UDP oracle. Read from the concluder's service set,
+// the SAME set the queue producers (the analysis agents and the intelligence engine) are pure over, so whether a UDP
+// row's absence is a measurement depends on what this set says about its port: see `udpPortMeasurement` in
+// scan_delta.mjs, which both the delta and Enterprise's MTTR call. Only UDP-transport labels (a `53/tcp` record never
+// stands in for `53/udp`), port > 0. Measured over 27 real router raws the UDP statuses are `open` / `no response` /
+// `unknown` — never `closed`, which the concluder writes only from ECONNREFUSED (an ICMP port-unreachable, a real
+// negative). Null when the raw carries no service set: no oracle, never "nothing answered".
+export function udpServicesOf(raw) {
+  const services = raw?.conclusion?.result?.services;
+  if (!Array.isArray(services)) return null;
+  const out = [];
+  for (const s of services) {
+    const port = Number(s?.port);
+    if (!Number.isInteger(port) || port <= 0 || !isUdpTransport(s?.protocol)) continue;
+    out.push({ port, protocol: String(s.protocol).toLowerCase(), service: s?.service ?? null, status: s?.status ?? null,
+      program: s?.program ?? null, version: s?.version ?? null });
+  }
+  return out.sort((a, b) => a.port - b.port);
+}
+
+// Every transport's service identity (1.2.0 build 2) — the oracle for `serviceIdentityAt` in scan_delta.mjs, which the
+// delta and Enterprise's MTTR both call to decide whether a CVE row vanished while the SAME program and version still
+// answered. Read from the concluder's service set, the set the CVE mapper attributes from; port > 0 and a TCP or UDP
+// transport only. Null when the raw carries no service set: no oracle, never "nothing answered".
+export function servicesOf(raw) {
+  const services = raw?.conclusion?.result?.services;
+  if (!Array.isArray(services)) return null;
+  const out = [];
+  for (const s of services) {
+    const port = Number(s?.port);
+    const t = typeof s?.protocol === 'string' ? TRANSPORT_OF_LABEL[s.protocol.toLowerCase()] : null;
+    if (!Number.isInteger(port) || port <= 0 || (t !== 'tcp' && t !== 'udp')) continue;
+    out.push({ port, protocol: String(s.protocol).toLowerCase(), service: s?.service ?? null, status: s?.status ?? null,
+      program: s?.program ?? null, version: s?.version ?? null });
+  }
+  return out.sort((a, b) => a.port - b.port || a.protocol.localeCompare(b.protocol));
+}
+
+// WHETHER ENTERPRISE'S STAGE RAN ON THIS HOST (1.1.1 — the audit seat's T1-c ruling). The scan writes
+// `conclusion.result.eeLoadError` when the installed Enterprise package failed to LOAD (utils/ee_load.mjs) and
+// `conclusion.result.eeEnrichmentError` when its enrichment THREW; either way its analysis agents and CVE mapper produced
+// nothing on the host. Null when neither was recorded — which is also what a Community-only scan reads.
+export function eeStageOf(raw) {
+  const r = raw?.conclusion?.result ?? {};
+  const loadError = typeof r.eeLoadError === 'string' ? r.eeLoadError : null;
+  const enrichmentError = typeof r.eeEnrichmentError === 'string' ? r.eeEnrichmentError : null;
+  return loadError || enrichmentError ? { loadError, enrichmentError } : null;
+}
+
 function shapeHost(host, dir, raw) {
   const envelopes = Array.isArray(raw.results) ? raw.results : [];
   const up = envelopes.some((e) => e?.result?.up === true);
@@ -520,6 +580,9 @@ function shapeHost(host, dir, raw) {
     // destroyed here, before the consumer ever saw it.
     pluginStatusRecorded: Array.isArray(raw.pluginStatus),
     portScan: portScanOf(raw),
+    udpServices: udpServicesOf(raw),
+    services: servicesOf(raw),
+    eeStage: eeStageOf(raw),
   };
 }
 
@@ -537,7 +600,7 @@ function buildModel(rec, hosts, counts) {
     // which utils/host_iterator.mjs de-duplicates). A name-keyed Map is last-write-wins and
     // silently drops every same-named host's own plugin table but the final one's.
     plugins.byHost.push({ host: h.host, dir: h.dir, status: h.pluginStatus,
-      pluginStatusRecorded: h.pluginStatusRecorded, portScan: h.portScan });
+      pluginStatusRecorded: h.pluginStatusRecorded, portScan: h.portScan, udpServices: h.udpServices, services: h.services, eeStage: h.eeStage });
     for (const ps of h.pluginStatus) {
       if (ps?.status === 'ran') plugins.ran += 1;
       else if (ps?.status === 'skipped') plugins.skipped += 1;

package/utils/report_md.mjs

@@ -237,6 +237,19 @@ export function buildMarkdownReport(scanData) {
   } else {
     lines.push(`- **Security findings:** 0`);
   }
+  // 1.2.0 build 3: this renderer's findings are the service-check FLAGS only — nothing on the scan path fills a service's
+  // CVEs, and Enterprise's analysis agents and exploit intelligence write elsewhere. Without this line "Security findings:
+  // 0" read as a clean verdict over a host whose CLI run carried 16 CVEs (the Gate 3-A preparation's P8).
+  // The counted list names only flags a conclusion can carry: dangerousMethods is read by extractFindings but no adapter puts
+  // it on a service record (tests/concluder_drops_honesty.test.mjs pins that), so it is named among what is NOT counted.
+  lines.push('- **Scope:** counts only these service-check flags: weak SSH algorithms, SNMP default community, weak TLS '
+    + 'protocols / ciphers, and anonymous FTP login and DNS zone transfer when the scan\'s environment enables those two '
+    + 'checks (FTP_CHECK_ANON; DNS_CHECK_AXFR with DNS_AXFR_DOMAIN — both off by default). It does not count a self-signed '
+    + 'certificate or the MCP server checks (both on the service records), nor dangerous HTTP methods, SMB null sessions or '
+    + 'the TLS-certificate, DNS-security and debug-endpoint auditors\' results (the scan\'s conclusion does not carry them); '
+    + 'it does not look up CVEs, and does not include Enterprise analysis-agent findings or exploit intelligence (a CLI scan '
+    + 'with the Enterprise package and a Pro or Enterprise licence records CVE and agent findings in scan_finding_queue.json, '
+    + 'when there are any).');
   lines.push('');
 
   // ---- Services table ----
@@ -267,7 +280,9 @@ export function buildMarkdownReport(scanData) {
   lines.push(`## Findings`);
   lines.push('');
   if (findings.length === 0) {
-    lines.push('_No security findings._');
+    lines.push('_None of the counted service-check flags fired. This is not a statement that the host has no known '
+      + 'vulnerabilities — CVE lookups, analysis-agent findings, the MCP server checks and several checks\' results are not '
+      + 'part of this count (see Scope above), and anonymous FTP login and zone transfer are tested only when enabled._');
     lines.push('');
   } else {
     findings.sort((a, b) => severityRank(a.severity) - severityRank(b.severity));