nsauditor-ai 0.2.49 → 0.2.51

package/utils/jira_export.mjs

@@ -0,0 +1,174 @@
+// utils/jira_export.mjs — the Jira-importer CSV export.
+//
+// CSV using the column names of Jira's CSV importer (Summary, Description, Priority, Labels,
+// External ID); the import mapping is done in Jira and has not been verified against a live
+// Jira instance.
+//
+// ⚠️ NOTHING HERE MAY CLAIM A WORKING OR VERIFIED JIRA INTEGRATION. `External ID` is stable per
+// finding so that an importer WHICH KEYS ON IT can update rather than duplicate — that is a
+// statement of intent, unverified against Jira. Earn-back is a Gate-3-shaped operator check:
+// import the sample CSV into a free Jira Cloud project once and record PASS with evidence.
+//
+// ⚠️ The formula-injection apostrophe below is visible in the RAW file, not only in a
+// spreadsheet: a title/detail/remediation beginning with `=`, `+`, `-` or `@` carries a
+// prefixed `'` so the cell is inert when opened as a spreadsheet, and that same literal leading
+// apostrophe is exactly what a consultant sees reading the CSV directly, e.g. in a text editor.
+//
+// Consumes Task 4's normalised model (utils/report_inputs.mjs's `loadRun()` — the same object
+// the executive HTML report renders), specifically `model.startedAt` (never a render-time
+// timestamp — the row is a record of what the SCAN found, not of when this file was produced)
+// and `model.findings` (the flat array; each entry's shape is `shapeFinding()`'s: host, port,
+// severity, title, detail, remediation, cves, kev, epss — every one of which can originate in a
+// scanned target's banner text or a hostile `--host-file` and must be treated as untrusted).
+//
+// A CSV is opened in a spreadsheet or an importer, not a browser, so the risk shape here is
+// RFC4180 structural integrity (a stray `,`/`"`/CR/LF must never let one finding's cell bleed
+// into the next row or column) and spreadsheet FORMULA INJECTION (a cell beginning with
+// `=`/`+`/`-`/`@` is executed as a formula by Excel/Sheets/LibreOffice the moment the file is
+// opened) — never HTML/script injection, which does not apply to this output format.
+
+import crypto from 'node:crypto';
+
+export const JIRA_COLUMNS = ['Summary', 'Description', 'Priority', 'Labels', 'External ID'];
+
+// Jira priorities are site-configurable — this mapping is a CLAIM, and an unstated one is a
+// claim nobody can check. Pinned by test; do not change without updating the pinned test.
+export const PRIORITY_BY_SEVERITY = {
+  CRITICAL: 'Highest', HIGH: 'High', MEDIUM: 'Medium', LOW: 'Low', INFO: 'Lowest',
+};
+
+// A severity this repo's own `shapeFinding()` never emits (it always uppercases and defaults to
+// 'INFO') should not be reachable from a well-formed model — but this module does not control
+// its caller, so a null/undefined/unrecognised severity falls back to a stated safe default
+// rather than writing the literal string "undefined" into a Jira Priority cell.
+const DEFAULT_PRIORITY = 'Medium';
+
+// ── RFC4180 quoting + formula-injection neutralisation ──────────────────────────────────────
+//
+// A field is wrapped in `"` (doubling any embedded `"`) when it contains a comma, a double
+// quote, or either newline convention (`\n` alone, `\r` alone, or `\r\n`) — a LONE `\r` must be
+// quoted too, precisely because it is not the row's own separator (rows are joined with `\n`
+// only, below) and an unquoted one would otherwise sit mid-row indistinguishable from ordinary
+// content only by luck.
+//
+// Before that: a cell whose first character is `=`, `+`, `-` or `@` is treated as a formula by
+// Excel, Google Sheets and LibreOffice when the file is opened directly — a well-known CSV
+// hazard, and a real one here, because a finding's title/detail/remediation is scan output from
+// someone else's infrastructure, not text this product authored. A leading `'` forces text
+// interpretation in all three without altering the visible value once opened.
+function csvField(value) {
+  let str = value == null ? '' : String(value);
+  if (/^[=+\-@]/.test(str)) str = `'${str}`;
+  if (/[",\n\r]/.test(str)) str = `"${str.replace(/"/g, '""')}"`;
+  return str;
+}
+
+function csvRow(fields) {
+  return fields.map(csvField).join(',');
+}
+
+// ── External ID ──────────────────────────────────────────────────────────────────────────────
+//
+// Stable (never a counter, never Date.now(), never Math.random()) and unique within one CSV.
+// `host + port + title` alone COLLIDES for two findings reported under one title on one port —
+// e.g. two distinct weak-cipher findings on the same host:port — and an importer keyed on
+// External ID would then treat the second as an UPDATE of the first, silently dropping one
+// finding from the client's board. `detail` is folded into the key for exactly that reason.
+//
+// Two findings can still be identical in all four fields (a genuine duplicate, or a scan that
+// legitimately reports the same condition twice). Those are disambiguated by their ORDINAL
+// among equal keys, not by anything that varies between renders of the SAME model — the
+// ordinal is a pure function of the (model-determined) order of `model.findings`, so re-running
+// this over the same model reproduces the same ids in the same order every time.
+function externalIds(findings) {
+  const seen = new Map();
+  return findings.map((f) => {
+    const key = JSON.stringify([keyPart(f.host), keyPart(f.port), keyPart(f.title), keyPart(f.detail)]);
+    const ordinal = seen.get(key) ?? 0;
+    seen.set(key, ordinal + 1);
+    const material = ordinal === 0 ? key : `${key} ${ordinal}`;
+    return crypto.createHash('sha256').update(material).digest('hex').slice(0, 16);
+  });
+}
+
+function keyPart(v) {
+  return v == null ? '' : String(v);
+}
+
+// ── Labels ───────────────────────────────────────────────────────────────────────────────────
+//
+// Jira's CSV importer takes multiple label VALUES in one cell space-separated (there is only
+// one `Labels` column in JIRA_COLUMNS, never one column per label) — so each token here is
+// sanitised to contain no whitespace of its own, or hostile data (e.g. a CVE-shaped string that
+// happens to contain a space) would silently fragment into more Jira labels than the scan
+// actually reported.
+function labelToken(raw) {
+  return String(raw).trim().toLowerCase().replace(/\s+/g, '-');
+}
+
+function buildLabels(f) {
+  const labels = ['nsauditor'];
+  const severity = keyPart(f.severity);
+  if (severity) labels.push(labelToken(`severity-${severity}`));
+  if (f.kev) labels.push('kev');
+  for (const cve of Array.isArray(f.cves) ? f.cves : []) {
+    const token = labelToken(cve);
+    if (token) labels.push(token);
+  }
+  return labels.join(' ');
+}
+
+// ── Description ──────────────────────────────────────────────────────────────────────────────
+//
+// Carries the SCAN's own timestamp (`model.startedAt`) and the finding's host — never a render
+// date, so re-running this exporter next week over an old run does not make the ticket look
+// like it was just found.
+//
+// Sections are joined with ` | `, never `\n` — a raw newline is what `csvField` quotes FOR, not
+// something this module should manufacture on its own out of otherwise single-line content. The
+// only way this field carries an embedded newline is a genuine one already present in the
+// finding's own `detail`/`remediation` (untrusted scan output), preserved as-is and quoted per
+// RFC4180 — never introduced by this module's own formatting.
+function buildDescription(model, f) {
+  const where = f.port != null ? `${keyPart(f.host)}:${f.port}` : keyPart(f.host);
+  const parts = [`Host: ${where}`, `Scan started: ${keyPart(model?.startedAt)}`];
+  if (f.detail) parts.push(String(f.detail));
+  if (f.remediation) parts.push(`Remediation: ${f.remediation}`);
+  const cves = Array.isArray(f.cves) ? f.cves.filter(Boolean) : [];
+  if (cves.length) parts.push(`CVEs: ${cves.join(', ')}`);
+  if (f.kev) parts.push('Listed in the CISA Known Exploited Vulnerabilities (KEV) catalog.');
+  if (typeof f.epss === 'number' && Number.isFinite(f.epss)) parts.push(`EPSS: ${f.epss}`);
+  return parts.join(' | ');
+}
+
+function priorityFor(severity) {
+  const key = keyPart(severity).toUpperCase();
+  return PRIORITY_BY_SEVERITY[key] ?? DEFAULT_PRIORITY;
+}
+
+/**
+ * Render Task 4's normalised run model as a Jira-CSV-importer-shaped CSV.
+ * @param {object} model - the object `utils/report_inputs.mjs`'s `loadRun()` resolves to.
+ * @returns {string}
+ */
+export function renderJiraCsv(model) {
+  // A Jira issue is a WORK ITEM, and a passing check is not work. Before this filter a
+  // real AWS run emitted all 18 PASS records as issues — 17 of them carrying substrate
+  // prose a consultant would have had to close by hand, and one contentless clean-user
+  // record that imported as an issue with no Summary at all.
+  //
+  // ⚠️ THE FILTER IS DELIBERATELY NARROW — `pass` ONLY. Every other tier, INFO included,
+  // stays: INFO carries the evidence gaps and the scope boundaries, which are exactly the
+  // material a reader needs to tell an incomplete scan from a clean one.
+  const all = Array.isArray(model?.findings) ? model.findings : [];
+  const findings = all.filter((f) => String(f?.severity ?? '').toUpperCase() !== 'PASS');
+  const ids = externalIds(findings);
+  const rows = findings.map((f, i) => csvRow([
+    f.title ?? '',
+    buildDescription(model, f),
+    priorityFor(f.severity),
+    buildLabels(f),
+    ids[i],
+  ]));
+  return [JIRA_COLUMNS.join(','), ...rows].join('\n') + '\n';
+}

package/utils/report_finding_census.mjs

@@ -0,0 +1,123 @@
+// utils/report_finding_census.mjs
+//
+// WHICH CONTAINERS IN A SCAN RECORD CAN HOLD A FINDING, AND DOES THE REPORT READ THEM?
+//
+// Built after Gate 3-B drove the `report` subcommand over a real 192.168.1.1 run and the
+// client deliverable said, over sixteen known CVEs:
+//
+//     "No findings were recorded in this run."
+//     CRITICAL 0 · HIGH 0 · MEDIUM 0 · LOW 0 · INFO 0 · PASS 0 · OTHER 0
+//
+// `shapeHost` read exactly one container — `result.findings[]` as an ARRAY — and on a
+// network host that container is EMPTY. Measured on that run: 47 severity-bearing rows
+// live in four other places, and none of them was opened.
+//
+// ⚠️ WHY THIS IS A CENSUS AND NOT FIVE MORE READERS. The defect was never "we forgot the
+// queue". It was that nothing in the product could answer "is there a finding we are not
+// rendering?" — so each door had to be found by a human reading raw JSON. A census keyed
+// on CONTAINERS answers that question by construction: every container carrying a
+// severity-bearing object is either READ or explicitly ALLOWLISTED with a written reason,
+// and one that is NEITHER fails loudly. Incompleteness costs NOISE, never SILENCE — the
+// inverse of the shape that produced the false clean.
+//
+// ⚠️ AND THE FIXTURE LESSON THAT MADE IT NECESSARY: the fleet fixture written one round
+// earlier proves `shapeFinding` over every finding SHAPE, and it could not see this,
+// because the network path's failure is a SOURCE the consumer never opens. A fixture
+// drawn from a producer's field names cannot catch a producer whose output lives in a
+// different artifact.
+
+/** Containers the report READS. Adding a reader means adding its key here. */
+export const READ_CONTAINERS = Object.freeze([
+  'result.findings[]',                  // array-shaped plugin findings (the cloud shape)
+  'result.findings.<category>[]',       // dict-of-categories (060 DNS Security Auditor)
+  'result.zeroTrust.<dim>.findings[]',  // 1023 Zero Trust Assessment
+  'result.portResults[].issues[]',      // 040 TLS Certificate & Cipher Auditor
+  'findingQueue[]',                     // the EE finding queue (intelligence_engine, crypto_agent)
+]);
+
+/**
+ * Containers that carry a `severity` but are NOT findings. Each needs a written reason —
+ * an allowlist entry with no reason is how a real door gets closed by accident.
+ */
+export const ALLOWLISTED_CONTAINERS = Object.freeze({
+  'result.portResults[]':
+    'A per-port ROLL-UP, not a finding: its severity summarises the port\'s own '
+    + '`issues[]`, which ARE read. Rendering both would double-count every TLS issue.',
+  'result.summary.cisAlarmCoverage.uncovered[]':
+    'A 1:1 SUMMARY MIRROR of 1040\'s own alarm-coverage findings, not a second source. '
+    + 'Adjudicated on the 0.44.0 cloud run: 13 uncovered classes, 13 "alarm missing" '
+    + 'findings, and the set difference of their cis-N.N ids is EMPTY. If that ever stops '
+    + 'holding the mirror has broken and this entry is wrong — re-derive, do not re-assert.',
+  'result.findings[].policyAnalyses[].issues[]':
+    'Per-statement EVIDENCE nested inside a finding that IS rendered — e.g. "Full admin '
+    + 'grant: Action \'*\' in policy X" backing a parent whose own issues[] already say '
+    + '"SHADOW ADMIN: User has full wildcard (*) permissions". Not a missed finding. '
+    + 'RESIDUAL, stated rather than hidden: the per-statement detail is not surfaced in the '
+    + 'report at all, which is a DEPTH choice nobody has ruled on, not a coverage gap.',
+  'result.data[]':
+    'NOT a findings container, and the report must never read it. On a CLOUD host it '
+    + 'MIRRORS result.findings (verified 0.44.0: 1150 16/16, 1170 9/9). On a NETWORK host '
+    + 'it is PROBE TELEMETRY — measured on the 192.168.1.1 run, findings[]=0 while '
+    + 'data[]=85, 84 of them {probe_protocol, probe_port, probe_info} ("Connect refused '
+    + '(ECONNREFUSED)", "No UDP response"). ⚠️ A `findings ?? data` fallback was written '
+    + 'here and REVERTED: it put scan telemetry into a client deliverable, hidden because '
+    + 'the telemetry rows collided on one content hash and collapsed to two. '
+    + 'cloud_finding_summary\'s findingsOf may use that precedence — it only ever sees '
+    + 'cloud producers; this consumer sees both paths.',
+});
+
+const QUEUE_CONTAINER = 'findingQueue[]';
+
+/**
+ * Classify where a severity-bearing object lives. Path is the dotted walk from `result`.
+ * @returns {string} a container key
+ */
+function containerOf(path) {
+  if (/^\.findings\[\d+\]$/.test(path)) return 'result.findings[]';
+  if (/^\.findings\.[A-Za-z0-9_]+\[\d+\]$/.test(path)) return 'result.findings.<category>[]';
+  if (/zeroTrust\..*\.findings\[\d+\]$/.test(path)) return 'result.zeroTrust.<dim>.findings[]';
+  if (/^\.portResults\[\d+\]\.issues\[\d+\]$/.test(path)) return 'result.portResults[].issues[]';
+  if (/^\.portResults\[\d+\]$/.test(path)) return 'result.portResults[]';
+  if (/^\.summary\.cisAlarmCoverage\.uncovered\[\d+\]$/.test(path)) return 'result.summary.cisAlarmCoverage.uncovered[]';
+  if (/^\.findings\[\d+\]\.policyAnalyses\[\d+\]\.issues\[\d+\]$/.test(path)) return 'result.findings[].policyAnalyses[].issues[]';
+  if (/^\.data\[\d+\]$/.test(path)) return 'result.data[]';
+  // An UNRECOGNISED container is reported under its own generalised path rather than
+  // bucketed into "other" — a census that collapses the unknown into one bucket tells you
+  // that something is missing without telling you what.
+  return `UNCLASSIFIED:${path.replace(/\[\d+\]/g, '[]')}`;
+}
+
+function* severityObjects(node, path = '') {
+  if (Array.isArray(node)) {
+    for (let i = 0; i < node.length; i += 1) yield* severityObjects(node[i], `${path}[${i}]`);
+  } else if (node && typeof node === 'object') {
+    if (typeof node.severity === 'string') yield { path, obj: node };
+    for (const [k, v] of Object.entries(node)) yield* severityObjects(v, `${path}.${k}`);
+  }
+}
+
+/**
+ * Census one scan record.
+ * @param {object} raw   the parsed scan_conclusion_raw.json
+ * @param {Array}  queue the host's finding queue (scan_finding_queue.json, or the
+ *                       eeEnrichment fallback) — passed in because it is a SIBLING
+ *                       artifact, not part of `raw`, which is the whole reason it was missed.
+ * @returns {{byContainer: Object<string, number>, unread: Object<string, number>, total: number}}
+ */
+export function censusFindingContainers(raw, queue = []) {
+  const byContainer = {};
+  const bump = (k) => { byContainer[k] = (byContainer[k] || 0) + 1; };
+
+  for (const e of (Array.isArray(raw?.results) ? raw.results : [])) {
+    for (const { path } of severityObjects(e?.result ?? {}, '')) bump(containerOf(path));
+  }
+  if (Array.isArray(queue) && queue.length) byContainer[QUEUE_CONTAINER] = queue.length;
+
+  const unread = {};
+  for (const [k, n] of Object.entries(byContainer)) {
+    if (READ_CONTAINERS.includes(k)) continue;
+    if (Object.prototype.hasOwnProperty.call(ALLOWLISTED_CONTAINERS, k)) continue;
+    unread[k] = n;
+  }
+  return { byContainer, unread, total: Object.values(byContainer).reduce((a, b) => a + b, 0) };
+}