nsauditor-ai 0.2.53 → 0.2.55

package/utils/cloud_providers.mjs

@@ -0,0 +1,90 @@
+// THE CLOUD-PROVIDER VOCABULARY, IN ONE PLACE, BECAUSE IT HAS TWO READERS IN TWO REPOSITORIES.
+//
+// A cloud scan addresses its provider as the HOST — `nsauditor-ai scan --host aws` writes a run
+// directory named `aws_<timestamp>` and a run record whose `hostsWritten[].host` is the literal
+// string `aws`. That makes the provider name a vocabulary, and a vocabulary with two copies is a
+// vocabulary that drifts.
+//
+// ⚠️ IT LIVED IN `scan_delta.mjs` AS A PRIVATE CONST UNTIL EE NEEDED IT TOO, and the obvious
+// alternative was for Enterprise's CPE mapper to import the delta engine for one literal — a
+// PRODUCER importing a CONSUMER, to learn a fact that belongs to neither. The other alternative
+// was a second list in EE, which is the shape this file exists to prevent.
+//
+// ⚠️ ONE LIST, NOT TWO. The host set is DERIVED from the unit map's keys rather than written
+// beside it, so there is no second place to forget. Adding a provider means adding its coverage
+// unit, and the host set follows.
+
+/**
+ * The coverage unit each provider resolves. A provider scan's scope is recorded in these terms,
+ * and the cross-run delta refuses to call a finding fixed or new when its unit was outside the
+ * other run's recorded scope.
+ */
+export const PROVIDER_SCOPE_UNIT = Object.freeze({
+  aws: 'region',
+  azure: 'subscription',
+  gcp: 'project',
+});
+
+/**
+ * The hosts that ARE a cloud provider rather than a network target. Derived from the unit map.
+ *
+ * Used to answer "is this scan addressing an estate or an address?" — a question with different
+ * right answers for the same code. Enterprise's CPE mapper asks it because a cloud scan produces
+ * no services BY CONSTRUCTION (cloud envelopes carry no port-bearing rows), so on a cloud host an
+ * empty service set is not evidence of anything and an upstream that failed there was never an
+ * upstream of the mapper at all.
+ */
+export const CLOUD_PROVIDER_HOSTS = Object.freeze(Object.keys(PROVIDER_SCOPE_UNIT));
+
+/**
+ * Is this host a cloud provider?
+ *
+ * Case- and whitespace-insensitive because it is applied to a value that reaches the record from
+ * a command line. Anything that is not a declared provider is a network target — the safe
+ * direction: a misspelling reads as a network host, where the mapper's questions all still apply.
+ *
+ * @param {unknown} host
+ * @returns {boolean}
+ */
+export function isCloudProviderHost(host) {
+  return typeof host === 'string'
+    && Object.hasOwn(PROVIDER_SCOPE_UNIT, host.trim().toLowerCase());
+}
+
+/**
+ * THE HOST A RECORD, A LOADER AND A COMPARISON AGREE ON.
+ *
+ * ⚠️ `--host AWS` IS ACCEPTED, AND UNTIL THIS THE RECORD KEPT IT AS TYPED. The CLI lowercased the
+ * sentinel only for its own address check; `parseHostArg` returned `AWS`, the run record carried
+ * `AWS`, and the cross-run delta compares hosts by string — so a baseline scanned as `AWS` beside a
+ * current scanned as `aws` read every finding as host-not-scanned. Folded at PARSE, so every record
+ * from now on carries the provider's own spelling, and at every READ — the loader and the delta —
+ * because records already on disk still say `AWS`.
+ *
+ * ONLY the three provider names are folded, and only on an exact case-insensitive match. A network
+ * host is RECORDED exactly as given — whether two runs saw the same host is `hostKey`'s question, not
+ * this one's; a misspelled provider is a network host (the safe direction, as for `isCloudProviderHost`).
+ *
+ * @param {unknown} host
+ * @returns {unknown} the provider's own spelling for a provider host; the value unchanged otherwise
+ */
+export function canonicalHost(host) {
+  return isCloudProviderHost(host) ? host.trim().toLowerCase() : host;
+}
+
+/**
+ * THE ONE ANSWER TO "IS THIS THE SAME HOST?" — trimmed and lower-cased, for EVERY host.
+ *
+ * ⚠️ TWO CONSUMERS ANSWERED IT DIFFERENTLY. Enterprise's MTTR history folded every host's case; this
+ * repository's delta compared hosts as exact strings, so a host scanned as `MyHost.local` and later as
+ * `myhost.local` read every finding host-not-scanned in one and paired in the other. DNS names are
+ * case-insensitive (RFC 4343), and a provider name is a fixed word, so the key folds both. It is a
+ * COMPARISON key only: a record keeps a network host as typed (only the provider names fold at parse,
+ * `canonicalHost`), and anything shown to a reader uses the recorded spelling.
+ *
+ * @param {unknown} host
+ * @returns {string} '' for a non-string
+ */
+export function hostKey(host) {
+  return typeof host === 'string' ? host.trim().toLowerCase() : '';
+}

package/utils/delta_reporter.mjs

@@ -71,7 +71,13 @@ export function formatDeltaSummary(deltaReport) {
     let anyChange = false;
     if (deltaReport.hostDiffs) {
       for (const diff of deltaReport.hostDiffs.values()) {
-        if (diff.newServices?.length || diff.removedServices?.length || diff.changedServices?.length || diff.newFindings) {
+        // ⚠️ `findingsNotComparable` COUNTS AS A CHANGE (board C10). `newFindings` is `null` when
+        // the two scans counted findings on a different basis, and null is falsy — so without
+        // this the diff drops out of both gates and the operator hears NOTHING, which reads as
+        // "no change since last scan". That is the false clean this item is about, one layer out.
+        // A comparison we cannot make is news: it is what tells an operator to rescan.
+        if (diff.newServices?.length || diff.removedServices?.length || diff.changedServices?.length
+            || diff.newFindings || diff.findingsNotComparable) {
           anyChange = true;
           break;
         }
@@ -103,6 +109,7 @@ export function hasSignificantChanges(deltaReport) {
       if (diff.removedServices?.length > 0) return true;
       if (diff.changedServices?.length > 0) return true;
       if (diff.newFindings && diff.newFindings !== 0) return true;
+      if (diff.findingsNotComparable) return true;   // see the note in formatDeltaSummary
     }
   }
 

package/utils/executive_report.mjs

@@ -27,6 +27,9 @@
 // vocabulary, even where the producer (report_inputs.mjs) is expected to constrain it.
 
 import { escapeHtml } from './brand.mjs';
+// The two evaluability SENTINELS, imported so the per-row basis is keyed on identity rather
+// than on prose. `scan_delta.mjs` imports nothing from here, so there is no cycle.
+import { SCOPE_NOT_EVALUATED, FRAMEWORK_MOVEMENT_NOT_EVALUATED } from './scan_delta.mjs';
 
 /* ------------------------------------------------------------------------------------------
  * egressViolations — deny-by-default. Two levels: every TAG, then EVERY attribute of it
@@ -605,7 +608,102 @@ function describeBrand(v) {
 // left to a reading — `tests/executive_report_brand_absent.test.mjs` pins this module's export
 // surface, so exporting either helper fails the build rather than silently opening an
 // unguarded path.
-export function renderExecutiveReport(model, brand, { renderedAt = new Date() } = {}) {
+
+// ── The cross-run delta, rendered for the CLIENT rather than the operator. ───────────────────
+//
+// ⚠️ A `resolved` ROW HERE IS AN ASSERTION OF REMEDIATION TO THAT CLIENT'S AUDITOR, so the basis
+// travels PER ROW and never as a footnote. A footnote is precisely the shape a compression pass
+// keeps while emptying it of force, and this lane has already watched a bare COUNT survive a
+// mutation battery on the easier stdout surface. The reader of this document does not know what
+// the tool does; the operator did.
+// ⚠️ DERIVED FROM THE LIMITS IN FORCE, NEVER WRITTEN AS A CONSTANT. This returned a fixed
+// sentence — "host, plugin, scope and framework enumeration present in both runs" — beside every
+// resolved / new / changed row, on a page whose own limits block said framework movement was NOT
+// EVALUATED and (before scope was threaded) that scope never was either. The page contradicted
+// itself, and of the two the ROW is the one that has to be true: the limit is what a compression
+// pass deletes, and the row is what a reader sees beside the word `resolved`.
+//
+// ⚠️ KEYED ON THE EXPORTED SENTINELS, NEVER ON PROSE. Matching the limit text would rot the first
+// time somebody copy-edits a sentence, and it would rot SILENTLY in the direction that overstates.
+function deltaBasis(delta) {
+  const limits = delta.limits ?? [];
+  const scopeEvaluated = !limits.includes(SCOPE_NOT_EVALUATED);
+  const fwEvaluated = !limits.includes(FRAMEWORK_MOVEMENT_NOT_EVALUATED);
+  const legs = ['host', 'plugin', scopeEvaluated ? 'scope' : null].filter(Boolean).join(', ');
+  const fw = fwEvaluated ? 'present in both runs' : 'not evaluated';
+  // BOTH sides' integrity: the run being REPORTED is as alterable as the one compared against.
+  const integrity = `baseline ${delta.baselineIntegrity} · current ${delta.currentIntegrity ?? 'not recorded'}`;
+  return `comparable: ${legs} present in both runs; framework enumeration: ${fw}; ${integrity}`;
+}
+
+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
+  // is also why the delta keyed identity on a decorated value. E1 removes the decoration and
+  // makes `region` a field, and the delta's key separates the regions correctly; but a reader
+  // sees this table, and six `backup:account` rows from six regions would render IDENTICALLY.
+  // Six indistinguishable rows in a change table is worse than a collapse — it reads as a
+  // rendering fault and a reader can act on none of them.
+  //
+  // It is appended to the cell rather than given a column of its own because most producers
+  // carry no region at all: a sixth column would be em-dashes on every network finding, which
+  // trains a reader to ignore the cell that matters. Absent region → the cell is exactly what
+  // it was before.
+  const resourceCell = f.region
+    ? `${escapeHtml(f.resource ?? '—')} <span class="delta-region">[${escapeHtml(f.region)}]</span>`
+    : escapeHtml(f.resource ?? '—');
+  return `<tr class="delta-${bucket}"><td>${escapeHtml(bucket)}</td>`
+    + `<td>${escapeHtml(f.title ?? '')}</td>`
+    + `<td>${resourceCell}</td>`
+    + `<td>${escapeHtml(String(f.severity ?? '—'))}</td>`
+    + `<td>${escapeHtml(basis)}</td></tr>`;
+}
+
+function renderDelta(delta) {
+  if (!delta) return '';   // no `--since` was asked for: no section, never an empty or invented one.
+
+  if (!delta.comparable) {
+    // ⚠️ A REFUSED COMPARISON NAMES NO FINDING. Listing them beside a refusal invites the reader
+    // to draw the verdict the refusal exists to withhold.
+    return `<section id="delta">
+<h2>Since Last Scan</h2>
+<p class="delta-refused"><strong>No comparison was made.</strong> ${escapeHtml(delta.refusal.reason)} —
+${escapeHtml(delta.refusal.detail)}</p>
+<p>Nothing in this report is stated as fixed, new or unchanged relative to an earlier scan.</p>
+</section>`;
+  }
+
+  const rows = [
+    ...delta.resolved.map((f) => deltaRow('resolved', f, deltaBasis(delta))),
+    ...delta.newFindings.map((f) => deltaRow('new', f, deltaBasis(delta))),
+    ...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}`)),
+  ].join('\n');
+
+  const counts = `${delta.newFindings.length} new · ${delta.resolved.length} resolved · `
+    + `${delta.changed.length} changed · ${delta.notComparable.length} not comparable · `
+    + `${delta.unchanged.length} unchanged`;
+
+  return `<section id="delta">
+<h2>Since Last Scan</h2>
+<p class="delta-counts">${escapeHtml(counts)}</p>
+${delta.notComparable.length ? `<p class="delta-nc-note">${escapeHtml(String(delta.notComparable.length))} finding(s) could NOT be compared between the two scans. They are listed below with the reason. A finding that could not be compared is <strong>not</strong> a finding that was fixed.</p>` : ''}
+<table class="delta"><thead><tr><th>Change</th><th>Finding</th><th>Resource</th><th>Severity</th><th>Basis</th></tr></thead>
+<tbody>
+${rows}
+</tbody></table>
+<div class="delta-limits">
+${delta.limits.map((l) => `<p class="limit">${escapeHtml(l)}</p>`).join('\n')}
+</div>
+</section>`;
+}
+
+export function renderExecutiveReport(model, brand, { renderedAt = new Date(), delta = null } = {}) {
   if (brand === null || typeof brand !== 'object' || Array.isArray(brand)) {
     throw new TypeError(
       'renderExecutiveReport: `brand` must be an object — pass the `brand` field of '
@@ -626,6 +724,7 @@ export function renderExecutiveReport(model, brand, { renderedAt = new Date() }
 <body>
 ${renderCover(model, brand, renderedAt)}
 ${renderTopRisks(model.findings)}
+${renderDelta(delta)}
 <section id="chart">
 <h2>Severity Distribution</h2>
 ${renderChart(model.findings)}

package/utils/finding_identity.mjs

@@ -0,0 +1,127 @@
+/**
+ * ONE canonical `resource`, shared by every channel that identifies a finding across runs.
+ *
+ * Two such channels ship, and before E1 they derived this noun independently:
+ *   · CE's cross-run delta  (`report --since`)      — `utils/scan_delta.mjs`'s `keyOf`
+ *   · EE's SLA/MTTR tracker (`--compliance-history`) — `utils/mttr_engine.mjs`'s fingerprint
+ * Two channels deriving the same noun two ways is the C10 defect one noun down, and its cost is
+ * concrete: an assessor can be shown one report where a finding is "resolved" and another where
+ * it is "unchanged", for the same finding on the same estate.
+ *
+ * ⚠️ THIS CANONICALISES THE NOUN, NOT THE KEY. Each channel keeps its OWN composition, and that
+ * is deliberate rather than an omission — they ask different questions. The delta asks *what
+ * changed* and needs `contentDigest` in its key; the tracker asks *how long has this been open*
+ * and must NOT reset a remediation clock because some prose it does not key on was reworded.
+ * Sharing the whole key would import each channel's sensitivities into the other.
+ *
+ * WHY A CANONICALISER EXISTS AT ALL — the decoration it removes was manufactured downstream of
+ * every producer. `utils/aws_region_scan.mjs::_stampRegion` (EE) rewrote `resource` on every
+ * finding routed through `forEachRegion`: a finding WITHOUT a resource got the region itself as
+ * its object identity, and a finding WITH one got ` [<region>]` appended. E1 stops both, but the
+ * published CE 0.2.54 already wrote baselines carrying the decorated values — and
+ * `RUN_RECORD_SCHEMA` is 1 on both sides, so those baselines are COMPARABLE by declaration. This
+ * function is what makes that declaration true for every producer that already named its object.
+ */
+
+/**
+ * The shape of a cloud region token. Two to four leading letters, one to three dash-separated
+ * alpha groups, a trailing number: `us-east-1` · `us-gov-west-1` · `ap-southeast-2` ·
+ * `cn-north-1` · `eusc-de-east-1` (European Sovereign Cloud).
+ *
+ * ⚠️ IT IS ONLY EVER USED ANCHORED, and that is the load-bearing part. Applied as a SCAN over a
+ * resource string it matches **562 of the 1786** stored violation resources in the 1.1.0
+ * evidence tree — `s3:bucket:s3-violator-bucket-522412052794` contains `ator-bucket-52` — and
+ * every one of those would attribute a fabricated region to a finding.
+ *
+ * ⚠️ AND ITS FIRST DRAFT WAS DERIVED FROM A SINGLE-REGION CORPUS, so it missed `eusc-de-east-1`
+ * and left that suffix decorating identity forever. A shape derived from a corpus that carries
+ * one value is a shape nobody has tested.
+ */
+// ⚠️ EXPORTED so a consumer can assert against the SHAPE rather than against a region somebody
+// typed. Enterprise's MTTR gap-text canonicaliser has to preserve a region token while cutting
+// the volatile count beside it, and a fixture written from one remembered region is a fixture
+// that tests the memory — this comment's own history says so: the first draft of this shape was
+// derived from a single-region corpus and missed `eusc-de-east-1`.
+export const REGION_TOKEN = '[a-z]{2,4}(?:-[a-z]+){1,3}-\\d{1,2}';
+const TRAILING_REGION_DECORATION = new RegExp(`^(.*?) \\[(${REGION_TOKEN})\\]$`);
+
+/**
+ * The region a finding belongs to — the STAMPED FIELD, and deliberately nothing cleverer.
+ *
+ * ⚠️ TWO RICHER VERSIONS OF THIS FUNCTION WERE SPECIFIED AND BOTH WERE WITHDRAWN BY
+ * MEASUREMENT, which is why this one is three lines. The idea was to recover a region for a
+ * STORED violation — from the ` [<region>]` decoration, or by parsing an ARN's region field —
+ * so that `region` could join the MTTR composite. Measured over the whole evidence tree, all
+ * 69,792 stored violations:
+ *   · carrying a `region` field ............................ 0
+ *   · whose resource EMBEDS a region token ................. 0   → the ARN parse has no occupant
+ *   · carrying a ` [<region>]` suffix ...................... 2,873
+ *   · whose resource IS a bare region ...................... 5,950 (the basis-bumped producers)
+ *   · with no region recoverable by any means ............. 60,959
+ * Sixty thousand priors can yield no region at all — mostly producers with an empty or
+ * name-only resource. So ANY composite carrying region on the current side while the prior
+ * yields null resets those lifecycles at the upgrade boundary: the repair would have introduced
+ * the defect it was written to prevent, on a larger population than the one it fixed.
+ *
+ * Region enters MTTR identity by COMPOSITION NEGOTIATION instead (see `mttr_engine.mjs`): the
+ * composition is chosen by what the PRIOR scan stores, so the two sides are always commensurable
+ * by construction rather than by rescuing one of them. Here, region is simply the field — which
+ * is all the delta ever needed, because both sides of a delta are loader-shaped runs that carry
+ * it.
+ *
+ * @param {object} v — a finding or a stored violation.
+ * @returns {string|null}
+ */
+export function regionOf(v) {
+  return typeof v?.region === 'string' && v.region.length > 0 ? v.region : null;
+}
+
+/**
+ * @param {unknown} resource — the raw `resource` as the producer (or the stamper) left it.
+ * @param {unknown} region   — the finding's OWN region, from its own field. Never a default:
+ *   without it nothing can be decoration, and guessing one would strip a real name.
+ * @returns {string|null} the canonical resource, or null when it is not an object identity.
+ */
+export function canonicaliseResource(resource, region) {
+  if (typeof resource !== 'string') return null;
+
+  // ⚠️ THE REGION-UNKNOWN PATH, and it is not a convenience — without it this function
+  // reintroduces the defect it exists to prevent, on the channel that needed it first.
+  // EE's MTTR tracker fingerprints PRIOR scans from their stored `scan_compliance_*.json`
+  // violations, and that shape has no `region`: measured over the 1.1.0 evidence tree, 3735
+  // violations, all with `resource`, ZERO with `region`. So on the prior side the exact rule
+  // below can never fire, a decorated prior written by the published build never matches a
+  // clean current, every lifecycle restarts and the SLA section reports mass remediation that
+  // did not happen.
+  //
+  // A trailing bracketed token of STRICT REGION SHAPE is therefore treated as decoration when
+  // the region is unknowable. The shape is tight because the alphabet was DERIVED from the real
+  // records rather than imagined: bracketed suffixes there are `[us-east-1]` ×286, and also
+  // `[target-1]` ×32, `[1022]`, `[1021]`, `[1030]`, `[1020]` and `[ERROR]` — none of them
+  // decoration, every one of them eaten by a loose "strip any trailing bracket" rule. Two alpha
+  // groups and a trailing number are required, which is what separates `us-east-1` from
+  // `target-1`.
+  //
+  // Rule 2 is deliberately NOT applied here: with no region to compare against, a resource of
+  // `us-east-1` is indistinguishable from an object legitimately so named, and leaving identity
+  // alone is the safe direction where nulling it is not.
+  if (typeof region !== 'string' || region.length === 0) {
+    const m = TRAILING_REGION_DECORATION.exec(resource);
+    return m ? m[1] : resource;
+  }
+
+  // Rule 2 — the resource IS the region: `_stampRegion`'s missing-resource branch claimed a
+  // region as the thing a finding was about. That is scope, not an object, so it is not an
+  // identity. Checked first: it is the stronger statement of the two.
+  if (resource === region) return null;
+
+  // Rule 1 — a TRAILING bracketed suffix equal to this finding's own region is decoration.
+  // Trailing and bracketed and region-equal, all three: an ARN contains its region, a bucket may
+  // be NAMED for one, and a producer may legitimately qualify a scope literal with one. Matching
+  // any of those would collapse distinct objects onto one key, which is the masking this lane
+  // exists to close — and over-stripping is the worse direction, because it is silent.
+  const suffix = ` [${region}]`;
+  if (resource.endsWith(suffix)) return resource.slice(0, -suffix.length);
+
+  return resource;
+}

package/utils/host_iterator.mjs

@@ -3,6 +3,7 @@
 
 import fsp from 'node:fs/promises';
 import path from 'node:path';
+import { canonicalHost } from './cloud_providers.mjs';
 
 /**
  * Parse a dotted-quad IPv4 string into a 32-bit unsigned integer.
@@ -95,7 +96,8 @@ export async function parseHostFile(filePath) {
         return false;
       }
       return true;
-    });
+    })
+    .map(canonicalHost); // a provider named in a host file is recorded as the provider, whatever its case
 }
 
 /**
@@ -172,15 +174,16 @@ export async function parseHostArg(arg) {
   }
 
   // Path traversal guard: reject absolute paths and paths resolving outside cwd
-  if (path.isAbsolute(arg)) return [arg]; // treat as hostname, not file
+  if (path.isAbsolute(arg)) return [canonicalHost(arg)]; // treat as hostname, not file
   const resolved = path.resolve(arg);
-  if (!resolved.startsWith(process.cwd() + path.sep)) return [arg]; // outside CWD = hostname
+  if (!resolved.startsWith(process.cwd() + path.sep)) return [canonicalHost(arg)]; // outside CWD = hostname
 
   try {
     await fsp.access(arg);
     return parseHostFile(arg);
   } catch {
-    // Not a file — treat as single host
-    return [arg];
+    // Not a file — treat as single host. `--host AWS` is the provider: recorded as `aws`
+    // (see `canonicalHost`), so the record and every later comparison agree on it.
+    return [canonicalHost(arg)];
   }
 }