nsauditor-ai 0.2.53 → 0.2.55

package/utils/scan_delta_view.mjs

@@ -0,0 +1,218 @@
+// `report --since` — baseline SELECTION and the operator-facing delta view.
+//
+// ⚠️ THE BASELINE SELECTION IS ITSELF A CLAIM, which is why this module names it rather than
+// silently diffing against it. If the selected run was narrow — a `--plugins` subset, one host,
+// an interrupted run — the delta is technically correct and practically a wall of NOT-COMPARABLE,
+// and an operator who meets that twice stops reading the feature. So the baseline's id, timestamp
+// and scope are printed BEFORE any verdict.
+//
+// ⚠️ AND REFUSING IS NOT STONEWALLING. When the selected baseline cannot support a verdict, this
+// says which earlier records exist and which of them are chain-verified — but it NEVER
+// auto-falls-back to one. Falling back silently changes the SUBJECT of the comparison, which is
+// the single thing the delta engine exists not to do.
+import { listRunRecords, readRunRecord } from './run_record.mjs';
+import { verifyRunChain, predecessorOf, buildRunRecordDigestIndex } from './run_chain.mjs';
+import { buildScanDelta, SCAN_DELTA_SCHEMA, CURRENT_UNCHAINED, CURRENT_CHAIN_LINK_BROKEN } from './scan_delta.mjs';
+import { loadRun } from './report_inputs.mjs';
+
+// ⚠️ WRITTEN, NOT REQUESTED — AND BOTH WHEN THEY DIFFER (board C5). This counted
+// `hostsRequested`, while the bucketing in `scan_delta.mjs` counts `hostsWritten`: G4's rule is
+// that scope is what a run WROTE, and it reached the verdicts without reaching the sentence that
+// EXPLAINS them. An interrupted baseline therefore printed `scope 2 host(s)` directly above
+// `host-not-scanned: host 10.0.0.9 was not scanned in the other run` — the line whose whole job
+// is to make that row make sense was the line that made it look like a bug. Same shape as G8,
+// where a per-row basis contradicted the limits block on the same page.
+//
+// Naming the gap rather than just correcting the number, because `1 of 2` is the fact an
+// operator needs: the baseline did not finish, which is why rows below are not comparable.
+const scopeOf = (rec) => {
+  const written = (rec?.hostsWritten ?? []).length;
+  const requested = (rec?.hostsRequested ?? []).length;
+  const plugins = (rec?.pluginsRequested ?? []).join(', ') || 'none recorded';
+  const hosts = (requested && requested !== written)
+    ? `${written} of ${requested} host(s) written`
+    : `${written} host(s)`;
+  return `${hosts} · plugins ${plugins}`;
+};
+
+/** `prior` = the record immediately before the current one; otherwise an explicit runId. */
+export async function resolveBaseline(outRoot, currentRunId, since, records = null) {
+  // `records` lets a caller that already has the list share it; omitting it reads them, so no
+  // caller is obliged to know. Same shape as `verifyRunChain`'s `linkIndex`.
+  const all = records ?? await listRunRecords(outRoot);   // newest startedAt first
+  if (since === 'prior') {
+    // ⚠️ THE SAME ORDERING THE CHAIN USES, and previously it was not. `all[i + 1]` is a POSITION
+    // in a list whose sort key is `startedAt` — and `localeCompare` returns 0 for two records
+    // that share one, so ties fell through to `Array.prototype.sort`'s stability, i.e. to readdir
+    // order, i.e. to the filename. The chain picked by filename too, but by a DIFFERENT filename
+    // rule, so the two could name different records for the same run. One ordering now, keyed on
+    // the record's contents, with ties broken deterministically.
+    // ⚠️ AND IT DOES NOT REQUIRE THE PREDECESSOR TO BE SEALED, unlike the chain. Skipping an
+    // unsealed record would compare against an OLDER run without saying so — the subject
+    // substitution this command refuses — while comparing against an unsealed baseline merely
+    // earns the disclosed `baseline-unchained` limit. Disclose, never substitute.
+    const cur = all.find((r) => r?.runId === currentRunId);
+    return predecessorOf(all, cur?.startedAt ?? all[0]?.startedAt) ?? null;
+  }
+  return all.find((r) => r?.runId === since) ?? null;
+}
+
+// ⚠️ TWO KINDS OF EXIT 2, AND THE ARTIFACT IS WHAT DISTINGUISHES THEM (board C9).
+//   WITH a delta    — the requested COMPARISON was refused. The report still renders, and the
+//                     client artifact carries the refusal and NO verdict rows.
+//   WITHOUT a delta — the REQUEST or the RUN ITSELF was refused. There is nothing honest to
+//                     render at all, so nothing is written and any pre-existing `--out` file is
+//                     NAMED as stale by the caller rather than left to pass as this run's output.
+// Could-not-measure stays loud either way: the exit is 2, never 0.
+const refusedComparison = (out, err, reason, detail) => ({
+  code: 2, out, err,
+  delta: { schema: SCAN_DELTA_SCHEMA, comparable: false, refusal: { reason, detail },
+    newFindings: [], resolved: [], unchanged: [], changed: [], notComparable: [],
+    baselineIntegrity: null, currentIntegrity: null, limits: [detail] },
+});
+
+export async function buildSinceView({ outRoot, model, since, allowPartial, tier }) {
+  const out = [];
+  const err = [];
+  // Hashed ONCE for this whole invocation and shared with every `verifyRunChain` below. Without
+  // it each call rescans and rehashes every record in the out root, and the two alternatives
+  // loops call it once per record — N passes over N files, on the refusal path.
+  const linkIndex = await buildRunRecordDigestIndex(outRoot);
+  // Read ONCE too. Three call sites each read every record in the out root — `resolveBaseline`
+  // and both alternatives loops — so the record list was walked three times per invocation on
+  // top of the per-call hashing.
+  const records = await listRunRecords(outRoot);
+  const baseRec = await resolveBaseline(outRoot, model.runId, since, records);
+  if (!baseRec) {
+    err.push(`[report] --since ${since}: no such run record in ${outRoot}. `
+      + 'Refusing rather than comparing against an arbitrary run.');
+    return { code: 2, out, err };
+  }
+
+  // Name it FIRST — before verifying it, before any verdict. A refusal about a named baseline is
+  // actionable; a refusal about an unnamed one is not.
+  out.push(`[report] baseline: runId ${baseRec.runId} · started ${baseRec.startedAt} · scope ${scopeOf(baseRec)}`);
+
+  const chain = await verifyRunChain(outRoot, baseRec.runId, { linkIndex });
+  if (chain.status === 'chain-broken' || chain.status === 'chain-unreadable') {
+    // ⚠️ THE DECLARED CODE TRAVELS WITH THE PROSE. This refusal used to name only
+    // `chain.status`, so the vocabulary an operator could grep for (`baseline-chain-broken`,
+    // `baseline-integrity-unmeasurable`) appeared NOWHERE on any surface, while `buildScanDelta`
+    // carried both codes in branches this refusal made unreachable. Two names for one event, and
+    // the declared one was the unreachable one — found by the outcome census.
+    err.push(`[report] REFUSED: ${chain.status === 'chain-broken' ? 'baseline-chain-broken' : 'baseline-integrity-unmeasurable'}`
+      + ` — the baseline is ${chain.status}: ${chain.reason}. `
+      + 'No finding can be called resolved against a baseline that may have been altered.');
+    const others = records
+      .filter((r) => r?.runId && r.runId !== baseRec.runId && r.runId !== model.runId);
+    if (others.length) {
+      err.push('[report] earlier records you can name explicitly with `--since <runId>`:');
+      for (const r of others) {
+        const v = await verifyRunChain(outRoot, r.runId, { linkIndex });
+        err.push(`[report]   ${r.runId} · ${r.startedAt} · ${v.status}`);
+      }
+      err.push('[report] NOT falling back automatically: choosing a different baseline changes the '
+        + 'subject of the comparison, and that is the operator\'s decision to make, not this command\'s.');
+    }
+    // The BASELINE is untrustworthy; this run is fine. That is a refused COMPARISON, so the
+    // client still gets an artifact — one that names the refusal and no finding.
+    return refusedComparison(out, err,
+      chain.status === 'chain-broken' ? 'baseline-chain-broken' : 'baseline-integrity-unmeasurable',
+      `the baseline is ${chain.status}: ${chain.reason}. No finding can be called resolved against `
+      + 'a baseline that may have been altered.');
+  }
+
+  // ⚠️ THE CURRENT RECORD'S LINK, WHICH WAS COMPUTED AND NEVER READ. `verifyRunChain` works out
+  // whether this run's `prevDigest` still names bytes that exist; this view read `status` alone.
+  // Delete the middle of three chained records and `prior` quietly resolved to the survivor — the
+  // silent substitution this module's own header says it never makes, and the verdict that
+  // vanished with the deleted record is the one the operator was relying on.
+  //
+  // ⚠️ SCOPED TO `prior`, DELIBERATELY, AND NARROWER THAN THE PRESCRIPTION. Under `prior` a broken
+  // link CHANGED THE SUBJECT: the command picked a baseline other than the one it names. Under an
+  // explicit `--since <runId>` the operator chose the subject, so nothing was substituted, and
+  // refusing there would turn ordinary housekeeping — deleting old records — into a blanket
+  // refusal. That is the accuse-honest-evidence direction. Refuse the substitution; DISCLOSE the
+  // integrity fact.
+  const curChain = await verifyRunChain(outRoot, model.runId, { linkIndex });
+  // ⚠️ THE CURRENT RUN IS JUST AS ALTERABLE AS THE BASELINE, and only the baseline was verified.
+  // `report --run <older> --since <even-older>` is a legitimate invocation — both records are
+  // historical — and an edited CURRENT findings file produced `new` and `resolved` rows with no
+  // mention of it. The refusal NAMES the side, because "the run is chain-broken" sends an operator
+  // to whichever file they assume, and the point of naming a subject is that they check the right
+  // one. Same two fatal statuses as the baseline: an altered current run cannot support a `new`
+  // row any more than an altered baseline supports a `resolved` one.
+  if (curChain.status === 'chain-broken' || curChain.status === 'chain-unreadable') {
+    err.push(`[report] REFUSED: the CURRENT run ${model.runId} is ${curChain.status} — ${curChain.reason}. `
+      + 'No finding can be called new or resolved when the run being REPORTED may have been altered.');
+    return { code: 2, out, err };
+  }
+  // ⚠️ COLLECTED, NOT PRINTED. These are facts about the RUNS that the engine cannot derive — it
+  // is deliberately filesystem-free — so the view supplies them. Pushing them to `out` alone would
+  // put them on STDOUT ONLY: read by the operator, who knows what the tool does, and absent from
+  // the HTML read by the person being billed. That is the stdout-only shape this lane already
+  // retired once, for the not-comparable count. They go into `delta.limits`, which renders into
+  // the client artifact AND is echoed to stdout by the limits loop below.
+  const viewLimits = [];
+  if (curChain.status === 'chain-absent') {
+    viewLimits.push(CURRENT_UNCHAINED);
+  }
+  if (curChain.linkBroken) {
+    if (since === 'prior') {
+      err.push('[report] REFUSED: this run\'s record names a predecessor whose bytes no longer exist, '
+        + `so \`--since prior\` would compare against ${baseRec.runId}, which is NOT that predecessor. `
+        + 'Silently changing the subject of the comparison is the one thing this command does not do.');
+      const others = records
+        .filter((r) => r?.runId && r.runId !== model.runId);
+      if (others.length) {
+        err.push('[report] records you can name explicitly with `--since <runId>`:');
+        for (const r of others) {
+          const v = await verifyRunChain(outRoot, r.runId, { linkIndex });
+          err.push(`[report]   ${r.runId} · ${r.startedAt} · ${v.status}`);
+        }
+      }
+      return { code: 2, out, err };
+    }
+    viewLimits.push(CURRENT_CHAIN_LINK_BROKEN);
+  }
+
+  const loadedBase = await loadRun(outRoot, { runId: baseRec.runId, allowPartial: !!allowPartial }, { tier });
+  if (!loadedBase.ok) {
+    err.push(`[report] REFUSED: baseline-unloadable — the baseline run could not be loaded: ${loadedBase.message}`);
+    return refusedComparison(out, err, 'baseline-unloadable',
+      `the baseline run ${baseRec.runId} could not be loaded: ${loadedBase.message}`);
+  }
+
+  const currentRec = await readRunRecord(outRoot, model.runId);
+  // ⚠️ `pluginStatus` TRAVELS WITH EACH SIDE, and its ABSENCE is a different fact from an empty
+  // one. The loader has always carried it (`model.plugins.byHost`); this view passed only
+  // `findings`, so the engine could not tell a plugin that RAN from one that ERRORED on the host
+  // and could not tell "no gaps" from "no oracle". Both read as clean, which is the fail-open
+  // direction: a finding whose plugin crashed read as REMEDIATED in the client's report.
+  const delta = buildScanDelta({
+    baseline: { record: baseRec, findings: loadedBase.model.findings, integrity: chain.status,
+      pluginStatus: loadedBase.model.plugins.byHost },
+    current: { record: currentRec, findings: model.findings, pluginStatus: model.plugins.byHost,
+      integrity: curChain.status },
+  });
+
+  if (!delta.comparable) {
+    err.push(`[report] REFUSED: ${delta.refusal.reason} — ${delta.refusal.detail}`);
+    // ⚠️ THE DELTA TRAVELS WITH THE REFUSAL. It was dropped here, which is what made
+    // `executive_report.mjs`'s `delta-refused` block unreachable through every shipped path.
+    return { code: 2, out, err, delta };
+  }
+  delta.limits.push(...viewLimits);
+
+  out.push(`[report] delta vs ${baseRec.runId}: ${delta.newFindings.length} new · `
+    + `${delta.resolved.length} resolved · ${delta.changed.length} changed · `
+    + `${delta.notComparable.length} not-comparable · ${delta.unchanged.length} unchanged`);
+  for (const f of delta.changed) out.push(`[report]   CHANGED  ${f.title}${f.resource ? ` (${f.resource})` : ''} — ${f.from} → ${f.to}`);
+  // ⚠️ NOT-COMPARABLE IS PRINTED WITH ITS REASON, EVERY TIME. A count alone re-creates the defect
+  // this engine exists to prevent: the reader assumes the rest were comparable.
+  for (const f of delta.notComparable) {
+    out.push(`[report]   NOT COMPARABLE (${f.direction})  ${f.title}${f.resource ? ` (${f.resource})` : ''} — ${f.reason}: ${f.detail}`);
+  }
+  for (const l of delta.limits) out.push(`[report]   LIMIT: ${l}`);
+  return { code: 0, out, err, delta };
+}

package/utils/scan_history.mjs

@@ -31,6 +31,20 @@ export async function recordScan(outputDir, summary) {
     openPorts: Array.isArray(summary.openPorts) ? summary.openPorts : [],
     os: summary.os ?? null,
     findingsCount: summary.findingsCount ?? 0,
+    // ⚠️ WHAT THAT NUMBER MEANS, carried on the line itself (board C10). `findingsCount` kept its
+    // name and changed its value: it used to be service attributes plus plugin `result.findings`,
+    // and is now what the report loader shapes — which includes the finding QUEUE, where a
+    // network host's findings actually live. Lines written before the change have no basis, and
+    // `computeDiff` refuses to subtract across that boundary rather than reporting a fabricated
+    // "+N new" on the first scan after an upgrade.
+    findingsCountBasis: summary.findingsCountBasis ?? null,
+    // ⚠️ WHICH TIER COUNTED IT (board E9). The tiers do not count the same things: Enterprise
+    // writes a finding QUEUE that Community never produces, and `findingsCount` is shaped by the
+    // report loader, which reads it. So a Community → Pro upgrade would otherwise report "+N new
+    // findings" on the free webhook the day the queue first appears — no estate changed, the
+    // COUNTER changed. `computeDiff` refuses across a tier boundary for the same reason it
+    // refuses across a basis boundary, and this field is what makes that refusal possible.
+    tier: summary.tier ?? null,
     // review re-fold R-1: persist the cloud/service split so a cloud (--host aws)
     // scan's findings are machine-visible in history (findingsCount already
     // includes them; this surfaces how many came from cloud auditors).
@@ -89,6 +103,14 @@ export async function getLastScan(outputDir, host) {
  * @param {object|null} previous - previous scan summary (null for first scan)
  * @returns {object} diff object
  */
+/**
+ * Why `computeDiff` refused to subtract two lines. DECLARED, because a reason string invented at
+ * a call site is one no consumer can switch on; held in two-way equality with what the function
+ * actually emits by `tests/scan_history_tier_comparability.test.mjs`, so a new reason must join
+ * the set and a retired one must leave it.
+ */
+export const NOT_COMPARABLE_REASONS = ['basis-changed', 'tier-changed', 'tier-unknown'];
+
 export function computeDiff(current, previous) {
   if (!previous) {
     return {
@@ -96,6 +118,8 @@ export function computeDiff(current, previous) {
       removedServices: [],
       changedServices: [],
       newFindings: current?.findingsCount ?? 0,
+      findingsNotComparable: false,
+      findingsNotComparableReason: null,
       summary: 'No previous scan for comparison.',
     };
   }
@@ -139,7 +163,53 @@ export function computeDiff(current, previous) {
     }
   }
 
-  const findingsDelta = (current?.findingsCount ?? 0) - (previous?.findingsCount ?? 0);
+  // ⚠️ `findingsCount` KEPT ITS NAME AND CHANGED ITS VALUE (board C10), so two lines are only
+  // subtractable when they were counted the same way. A line written before the fix summed
+  // service attributes plus plugin `result.findings`; one written after counts what the loader
+  // shapes, which includes the finding QUEUE. Subtracting across that boundary reports a
+  // fabricated "+N new" on the first scan after an upgrade — an alarm produced by our own
+  // correction, on an estate where nothing changed.
+  //
+  // contract-v1 §5.3 records the same shape for `findingCount` in the archived packs, and the
+  // answer there was to REFUSE the comparison rather than compute it. Two OLD lines still
+  // compare with each other: they are commensurable, and refusing would break a working
+  // comparison for a customer who has not rescanned yet.
+  const basisOf = (rec) => rec?.findingsCountBasis ?? null;
+  const basisChanged = basisOf(current) !== basisOf(previous);
+
+  // ⚠️ THE TIER BOUNDARY (board E9), and its carve-out mirrors the basis one deliberately: two
+  // lines that BOTH lack a tier still compare. Neither of them can have carried a queue, so they
+  // are commensurable, and refusing would break a working comparison for a customer who has not
+  // rescanned since the field landed — the same judgement made for pre-1.1.0 lines above.
+  // ABSENT-vs-PRESENT is refused, because that is exactly the shape an upgrade takes.
+  const tierOf = (rec) => rec?.tier ?? null;
+  const tierChanged = tierOf(current) !== tierOf(previous);
+  // ⚠️ NO `tierChanged &&` HERE, and its deletion is a MEASUREMENT rather than a tidy-up. With
+  // the verdict gate below, this value is only ever read when the comparison was already refused,
+  // so in the branch that reads it `tierChanged` is necessarily true — the conjunct was dead. It
+  // and the gate each made the other unfalsifiable: BOTH mutants survived, each masked by its
+  // twin, which is the pair-masking shape this repo has recorded before. One mechanism is kept
+  // (the gate, because it holds the invariant by construction for every future branch) and the
+  // redundant one is removed, so the kept one is mutant-provable.
+  const tierUnknown = tierOf(current) === null || tierOf(previous) === null;
+
+  const findingsComparable = !basisChanged && !tierChanged;
+  // Precedence is deterministic and the WIDER boundary wins: a basis change is the older and
+  // more fundamental incommensurability, so it names the refusal when both apply. The tier fact
+  // is still stated in the summary rather than dropped — a reader needs both.
+  // ⚠️ THE REASON IS GATED ON THE VERDICT, so "non-null reason ⟺ refused" holds BY CONSTRUCTION
+  // rather than by three branches agreeing. Found by a surviving mutant: with the reason computed
+  // independently, dropping the both-absent carve-out left `findingsNotComparable: false` sitting
+  // beside `reason: 'tier-unknown'` — a diff that says it compared AND says why it could not, and
+  // a consumer switching on the reason would refuse a comparison the verdict allowed.
+  const findingsNotComparableReason = findingsComparable ? null
+    : basisChanged ? 'basis-changed'
+      : tierUnknown ? 'tier-unknown'
+        : tierChanged ? 'tier-changed'
+          : null;
+  const findingsDelta = findingsComparable
+    ? (current?.findingsCount ?? 0) - (previous?.findingsCount ?? 0)
+    : null;
 
   // Build human-readable summary
   const parts = [];
@@ -152,7 +222,22 @@ export function computeDiff(current, previous) {
   if (changedServices.length) {
     parts.push(`${changedServices.length} service(s) changed`);
   }
-  if (findingsDelta !== 0) {
+  if (!findingsComparable) {
+    // Said out loud, not omitted. A missing findings clause reads as "no findings changed".
+    // BOTH facts when both apply: the reason names one boundary, the sentence states every one
+    // that was crossed, because a reader who is told only about the basis will rescan and be
+    // surprised again by the tier.
+    const why = [];
+    if (basisChanged) {
+      why.push('counted findings on a different basis '
+        + `(${basisOf(previous) ?? 'pre-1.1.0'} → ${basisOf(current) ?? 'pre-1.1.0'})`);
+    }
+    if (tierChanged) {
+      why.push(`ran at a different licence tier (${tierOf(previous) ?? 'unrecorded'} → `
+        + `${tierOf(current) ?? 'unrecorded'}), which counts a different set of findings`);
+    }
+    parts.push(`findings not comparable: the two scans ${why.join(', and ')}; rescan to compare`);
+  } else if (findingsDelta !== 0) {
     const sign = findingsDelta > 0 ? '+' : '';
     parts.push(`findings delta: ${sign}${findingsDelta}`);
   }
@@ -165,7 +250,12 @@ export function computeDiff(current, previous) {
     newServices,
     removedServices,
     changedServices,
+    // `null`, never 0, when the bases differ: 0 is a CLAIM that nothing changed, and this
+    // function does not know that. `delta_reporter` gates its webhook on this value, so a number
+    // here would send the fabricated alarm and a 0 would suppress a real one.
     newFindings: findingsDelta,
+    findingsNotComparable: !findingsComparable,
+    findingsNotComparableReason,
     summary,
   };
 }