@secureport/core 2.2.0 → 2.3.1

package/src/report/markdown.ts

@@ -5,6 +5,7 @@ import type { Snapshot, SnapshotIssue } from '../snapshot.js';
 import {
   buildReportModel,
   type EvidenceVerbosity,
+  timelineFor,
   VERDICT_LABELS,
   type ReportModel,
   type ReportOptions,
@@ -16,8 +17,14 @@ export function formatDate(date: Date): string {
   return date.toISOString().slice(0, 10);
 }
 
-/** Escapes the characters that would break out of a Markdown table cell. */
-function cell(value: string): string {
+/**
+ * Escapes the characters that would break out of a Markdown table cell.
+ *
+ * Exported: the streaming renderer formats a row the moment it sees it, and
+ * needs the exact same escaping — a second copy is a copy free to miss the
+ * next character somebody discovers breaks a table.
+ */
+export function cell(value: string): string {
   return value.replace(/\|/gu, '\\|').replace(/\n/gu, ' ');
 }
 
@@ -54,8 +61,14 @@ function changeSummary(model: ReportModel): string[] {
   ];
 }
 
-/** One issue, in full. The Penetration Test presentation. */
-function issueDetail(entry: SnapshotIssue, verbosity: EvidenceVerbosity): string[] {
+/**
+ * One issue, in full. The Penetration Test presentation.
+ *
+ * Exported: it is already a pure per-issue function needing nothing but the
+ * one entry, which is exactly what the streaming renderer can offer it a row
+ * at a time — the same reason `verdictFor` is exported from `model.ts`.
+ */
+export function issueDetail(entry: SnapshotIssue, verbosity: EvidenceVerbosity): string[] {
   const { issue } = entry;
   const lines: string[] = [
     `#### ${issue.title}`,
@@ -142,14 +155,32 @@ function evidenceLine(finding: Finding): string {
   return `${where} — ${detail.join('; ')}`;
 }
 
-/** One issue, as a table row. The Vulnerability Assessment presentation. */
-function issueRow(entry: SnapshotIssue): string {
+/**
+ * One issue, as a table row. The Vulnerability Assessment presentation.
+ *
+ * Exported for the same reason {@link issueDetail} is.
+ */
+export function issueRow(entry: SnapshotIssue): string {
   const { issue } = entry;
   const location =
     issue.parameter === undefined ? issue.location : `${issue.location} (${issue.parameter})`;
   return `| ${cell(issue.title)} | ${issue.effectiveSeverity} | \`${cell(location)}\` | ${entry.change.replace('_', ' ')} | ${entry.daysOpen} | ${entry.slaStatus.replace('_', ' ')} |`;
 }
 
+/**
+ * An issue's remediation chronology, as a single table cell.
+ *
+ * Exported for the same reason {@link issueRow} is: the streaming renderer
+ * formats a row the moment it sees it, and needs the identical rendering of
+ * {@link timelineFor}'s events — a second join-and-escape is a second one
+ * free to drift.
+ */
+export function timelineCell(entry: SnapshotIssue): string {
+  return timelineFor(entry)
+    .map((event) => cell(event.statement))
+    .join(' · ');
+}
+
 /** The Retest body: the difference between two runs, and nothing else. */
 function retestBody(model: ReportModel): string[] {
   // `buildReportModel` refuses to build a retest without one.
@@ -212,13 +243,13 @@ function retestBody(model: ReportModel): string[] {
   lines.push(
     '## Issue by issue',
     '',
-    '| Issue | Severity | Verdict | Location | Open for |',
+    '| Issue | Severity | Verdict | Location | Timeline |',
     '| --- | --- | --- | --- | --- |',
     ...retest.entries.map((entry) => {
       const { issue } = entry.issue;
       const location =
         issue.parameter === undefined ? issue.location : `${issue.location} (${issue.parameter})`;
-      return `| ${cell(issue.title)} | ${issue.effectiveSeverity} | ${VERDICT_LABELS[entry.verdict]} | \`${cell(location)}\` | ${entry.issue.daysOpen} days |`;
+      return `| ${cell(issue.title)} | ${issue.effectiveSeverity} | ${VERDICT_LABELS[entry.verdict]} | \`${cell(location)}\` | ${timelineCell(entry.issue)} |`;
     }),
     '',
   );
@@ -327,6 +358,27 @@ function executiveBody(model: ReportModel): string[] {
   return lines;
 }
 
+/**
+ * "What this report does not establish" — every kind but the Attestation
+ * Letter, which states its limits inline as part of the formal statement
+ * itself (`attestationBody`) rather than as a separate section (B109).
+ *
+ * Placed immediately before the suppressed appendix in every caller, which is
+ * also where the streaming Markdown renderer (`stream.ts`) is forced to put
+ * it: `describeLimitations` needs the suppressed count and the omitted-below-
+ * floor count, both fold-dependent and only known once the issue cursor is
+ * drained. The array renderer has no such constraint but uses the same
+ * position, so the two cannot drift apart on placement.
+ */
+function limitationsSection(model: ReportModel): string[] {
+  return [
+    '## What this report does not establish',
+    '',
+    ...model.limitations.map((l) => `- ${l}`),
+    '',
+  ];
+}
+
 /** The Attestation Letter body: a formal statement, with its limits stated. */
 function attestationBody(model: ReportModel): string[] {
   const { snapshot } = model;
@@ -466,12 +518,22 @@ export function renderMarkdown(snapshot: Snapshot, options: ReportOptions): stri
   lines.push(...changeSummary(model), '');
 
   if (model.kind === 'exec') {
-    lines.push(...executiveBody(model), ...suppressedAppendix(snapshot), '');
+    lines.push(
+      ...executiveBody(model),
+      ...limitationsSection(model),
+      ...suppressedAppendix(snapshot),
+      '',
+    );
     return withContents(lines, model);
   }
 
   if (model.kind === 'retest') {
-    lines.push(...retestBody(model), ...suppressedAppendix(snapshot), '');
+    lines.push(
+      ...retestBody(model),
+      ...limitationsSection(model),
+      ...suppressedAppendix(snapshot),
+      '',
+    );
     return withContents(lines, model);
   }
 
@@ -508,10 +570,12 @@ export function renderMarkdown(snapshot: Snapshot, options: ReportOptions): stri
     lines.push('');
   }
 
-  // Printed here, beside the section it is about, rather than left to the
-  // limitations list — which only the Attestation Letter renders (B109). A
-  // floor that removed issues from this section and said so nowhere the reader
-  // will look is the quiet form of the over-claim §7 exists to stop.
+  // Printed here too, beside the section it is about, even though it also
+  // appears in `limitationsSection` below (B109). A reader looking at a short
+  // Findings section learns why it is short at the point of confusion rather
+  // than having to find the register at the end; the register entry is what
+  // keeps the disclosure surviving there once the reader has moved past this
+  // section. Two honest statements, not a duplicate to trim.
   if (model.omitted !== undefined) lines.push(`_${model.omitted.statement}_`, '');
 
   if (model.resolved.length > 0) {
@@ -530,6 +594,6 @@ export function renderMarkdown(snapshot: Snapshot, options: ReportOptions): stri
     );
   }
 
-  lines.push(...suppressedAppendix(snapshot), '');
+  lines.push(...limitationsSection(model), ...suppressedAppendix(snapshot), '');
   return withContents(lines, model);
 }

package/src/report/model.ts

@@ -1,4 +1,4 @@
-import type { RunSummary } from '../run.js';
+import type { RunKind, RunSummary } from '../run.js';
 import type { Severity } from '../severity.js';
 import { SEVERITY_ORDER } from '../severity.js';
 import type { Snapshot, SnapshotIssue } from '../snapshot.js';
@@ -277,6 +277,10 @@ export interface TestingBasis {
  * The issues are still open, still counted and still the target's problem;
  * only the pages describing them are gone. That distinction is the reason this
  * is reported at all rather than silently applied.
+ *
+ * **Never set for a `retest` report.** Its own per-issue table lists every
+ * carried issue regardless of the floor (7.9a) — a floor changes nothing a
+ * reader sees, so there is nothing to disclose.
  */
 export interface OmittedIssues {
   /** How many outstanding issues were left out. Never `0` — the field is absent instead. */
@@ -534,18 +538,145 @@ function describeRetest(snapshot: Snapshot): RetestOutcome | undefined {
  * an issue left open because the run never covered it looks identical to one
  * left open because the run found it again, and telling a reader those are the
  * same thing is the failure this report exists to avoid.
+ *
+ * Exported: it is per-issue and needs nothing but the one entry, which is
+ * exactly what the streaming machine renderers can offer it a row at a time.
  */
-function verdictFor(entry: SnapshotIssue): RetestVerdict {
+export function verdictFor(entry: SnapshotIssue): RetestVerdict {
   if (entry.change === 'resolved') return 'fixed';
   if (entry.change === 'regressed') return 'returned';
   if (entry.change === 'new') return 'new';
   return entry.findings.length > 0 ? 'still_present' : 'not_retested';
 }
 
-/** Works out what a report cannot establish, from the run rather than a template. */
-function describeLimitations(
-  snapshot: Snapshot,
+// What kind of moment a `TimelineEvent` records. Four of the five are things
+// that already happened, in the order they happened. `deadline` is not: it is
+// a standing obligation that can be in the future, and `timelineFor` never
+// sorts it in among the other four — see that function's own doc comment for
+// why. Not exported: nothing outside this module names the union, only the
+// `kind` field it types.
+type TimelineEventKind = 'opened' | 'resolved' | 'returned' | 'last_seen' | 'deadline';
+
+/** One moment in an issue's remediation history, worded ready to print. */
+export interface TimelineEvent {
+  /** What kind of moment this is. */
+  readonly kind: TimelineEventKind;
+
+  /** When it happened, or — for `deadline` alone — when it is due. */
+  readonly at: Date;
+
+  /**
+   * One sentence, ready to print, so no two renderers word it differently.
+   *
+   * `deadline`'s wording follows {@link SnapshotIssue.slaStatus}, never a
+   * second comparison of `at` against `now` — `slaStatus` is already the
+   * derived answer to "is this overdue", and a fresh comparison here would be
+   * a second one free to disagree.
+   */
+  readonly statement: string;
+}
+
+/**
+ * An issue's remediation chronology, derived only from dates already on
+ * {@link Issue} — no `issue_events` read, no migration.
+ *
+ * Exported for the same reason {@link verdictFor} is: it is per-issue and
+ * needs nothing but the one entry, which is exactly what the streaming
+ * Markdown renderer can offer it a row at a time.
+ *
+ * **`deadline` is appended last, unconditionally — never sorted in among the
+ * other four.** Those four are things that already happened; a remediation
+ * deadline is a standing obligation, not an event, and it can be in the past
+ * (breached) or the future (within the window). Sorting it by `at` would let
+ * a breached deadline land in the middle of the chronology, worded as though
+ * it were a fact that occurred between two sightings — this function's
+ * version of the mistake `not_retested` exists to stop: reporting something
+ * that has not happened as though it had.
+ *
+ * **No `deadline` event for a resolved issue**, even one whose `slaDueAt` has
+ * passed. A deadline is a claim about outstanding remediation; printing
+ * "overdue since …" beside a `fixed` verdict would report finished work as
+ * work still owed — the same dishonesty from the other direction. None
+ * either when {@link Issue.slaDueAt} is `null` (an `advisory` under
+ * {@link DEFAULT_SLA_POLICY}), since there is no deadline to state.
+ */
+export function timelineFor(entry: SnapshotIssue): readonly TimelineEvent[] {
+  const { issue } = entry;
+  const events: TimelineEvent[] = [
+    {
+      kind: 'opened',
+      at: issue.firstSeen,
+      statement: `opened ${formatIsoDate(issue.firstSeen)} (${entry.daysOpen} days)`,
+    },
+  ];
+
+  if (issue.resolvedAt !== undefined) {
+    events.push({
+      kind: 'resolved',
+      at: issue.resolvedAt,
+      statement: `resolved ${formatIsoDate(issue.resolvedAt)}`,
+    });
+  }
+  if (issue.reopenedAt !== undefined) {
+    events.push({
+      kind: 'returned',
+      at: issue.reopenedAt,
+      statement: `returned ${formatIsoDate(issue.reopenedAt)}`,
+    });
+  }
+
+  // Deduplicated by exact timestamp: `reconcile()` sets `firstSeen` and
+  // `lastSeen` to the same instant when it creates an issue, and an issue
+  // that regressed this run has `reopenedAt === lastSeen` — without this
+  // check the same moment would print twice under two different names.
+  if (!events.some((e) => e.at.getTime() === issue.lastSeen.getTime())) {
+    events.push({
+      kind: 'last_seen',
+      at: issue.lastSeen,
+      statement: `last seen ${formatIsoDate(issue.lastSeen)}`,
+    });
+  }
+
+  // Sorted, not pushed in field-declaration order: `lastSeen` is the last
+  // time the issue was *detected*, which for a resolved issue predates
+  // `resolvedAt` — the date reconciliation stopped seeing it and started
+  // counting misses, not the date it stopped existing. Pushing in the order
+  // above would print "resolved … last seen …" backwards.
+  events.sort((a, b) => a.at.getTime() - b.at.getTime());
+
+  if (issue.slaDueAt !== null && issue.status !== 'resolved') {
+    const due = formatIsoDate(issue.slaDueAt);
+    const statement =
+      entry.slaStatus === 'breached'
+        ? `overdue since ${due}`
+        : entry.slaStatus === 'due_soon'
+          ? `due ${due} (due soon)`
+          : `due ${due}`;
+    events.push({ kind: 'deadline', at: issue.slaDueAt, statement });
+  }
+
+  return events;
+}
+
+/** A date, printed the same way everywhere in this module. */
+function formatIsoDate(date: Date): string {
+  return date.toISOString().slice(0, 10);
+}
+
+/**
+ * Works out what a report cannot establish, from the run rather than a
+ * template.
+ *
+ * Takes primitives rather than a {@link Snapshot} so the streaming machine
+ * renderers can produce the same wording from a fold over a cursor, without
+ * needing the eagerly-materialised issue array this package's PDF/HTML path
+ * builds.
+ */
+export function describeLimitations(
+  coveragePaths: readonly string[],
+  runCreatedAt: Date,
   basis: TestingBasis,
+  suppressedCount: number,
   omitted: OmittedIssues | undefined,
 ): string[] {
   const limitations: string[] = [];
@@ -561,11 +692,11 @@ function describeLimitations(
       'upon as audit evidence.',
   );
   limitations.push(
-    `Testing covered only ${snapshot.run.coverage.paths.join(', ')}. Anything outside that ` +
+    `Testing covered only ${coveragePaths.join(', ')}. Anything outside that ` +
       'was not examined, and its absence from this document is not evidence that it is sound.',
   );
   limitations.push(
-    `This reflects the state of the target as of ${snapshot.run.createdAt
+    `This reflects the state of the target as of ${runCreatedAt
       .toISOString()
       .slice(0, 10)}. It says nothing about the target before or after that date.`,
   );
@@ -573,9 +704,9 @@ function describeLimitations(
     'Automated testing cannot establish the absence of a vulnerability. A clean result means ' +
       'nothing was detected, not that nothing is there.',
   );
-  if (snapshot.suppressed.length > 0) {
+  if (suppressedCount > 0) {
     limitations.push(
-      `${snapshot.suppressed.length} finding${snapshot.suppressed.length === 1 ? ' has' : 's have'} been ` +
+      `${suppressedCount} finding${suppressedCount === 1 ? ' has' : 's have'} been ` +
         'suppressed and excluded from the counts above. They are listed in full in the appendix.',
     );
   }
@@ -597,7 +728,74 @@ function describeLimitations(
  */
 const HEX_COLOUR = /^#(?:[0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/iu;
 
-const DEFAULT_TITLES: Readonly<Record<ReportKind, string>> = Object.freeze({
+/**
+ * Why this branding cannot be rendered, or `undefined` if it can.
+ *
+ * **Exported so the rules have one home rather than two.** {@link buildReportModel}
+ * enforces these at render time, which is the last possible moment — by then the
+ * value has been stored, and the caller who set it is long gone. A hosted
+ * service wants to refuse it at the boundary instead, with a `400` naming the
+ * field. That needs the same two rules in two places, and a colour pattern
+ * copied into an API schema is a copy free to drift from the one that actually
+ * protects the stylesheet.
+ *
+ * So both callers ask this. The messages are identical wherever the value is
+ * rejected, because there is only one place that composes them.
+ *
+ * The white-label rule is deliberately **not** here: it depends on the report
+ * kind and on `preparedBy`, so it is a property of the options rather than of
+ * the branding, and only the renderer can decide it.
+ */
+export function brandingProblem(branding: Branding | undefined): string | undefined {
+  const colour = branding?.primaryColour;
+  if (colour !== undefined && !HEX_COLOUR.test(colour)) {
+    return (
+      `primaryColour must be a hex triplet such as #0a7 or #00aa77, not ${JSON.stringify(colour)}: ` +
+      'it is interpolated into the document stylesheet, where anything else could end the element'
+    );
+  }
+
+  const logo = branding?.logo;
+  if (logo !== undefined && !logo.startsWith('data:image/')) {
+    return (
+      `logo must be a data: URI, not ${JSON.stringify(logo.slice(0, 40))}: ` +
+      'a linked image would make the report depend on a network at render time, ' +
+      'which is the guarantee that lets it be rendered to PDF reproducibly'
+    );
+  }
+
+  return undefined;
+}
+
+/**
+ * Who the document says carried out the testing, resolved once so the PDF/HTML
+ * path and the streaming machine path cannot word it two different ways.
+ *
+ * @throws TypeError A white-labelled attestation naming nobody: a formal
+ *   statement that testing was carried out has to say who carried it out.
+ */
+export function resolveAttestor(
+  options: Pick<ReportOptions, 'kind' | 'preparedBy' | 'branding'>,
+): string {
+  const attestor = options.preparedBy ?? options.branding?.companyName;
+  // An attestation is a statement that a named party carried out testing. With
+  // Secureport's name removed and nothing put in its place there is no such
+  // party, and the document would assert something on nobody's behalf.
+  if (
+    attestor === undefined &&
+    options.branding?.whiteLabel === true &&
+    options.kind === 'attest'
+  ) {
+    throw new TypeError(
+      'a white-labelled attestation must name who carried out the testing: ' +
+        'set branding.companyName or preparedBy',
+    );
+  }
+  return attestor ?? 'Secureport';
+}
+
+/** The title printed when {@link ReportOptions.title} is not given. */
+export const DEFAULT_TITLES: Readonly<Record<ReportKind, string>> = Object.freeze({
   pen: 'Penetration Test Report',
   vap: 'Vulnerability Assessment Report',
   exec: 'Executive Summary',
@@ -605,11 +803,19 @@ const DEFAULT_TITLES: Readonly<Record<ReportKind, string>> = Object.freeze({
   retest: 'Retest Report',
 });
 
-/** Works out how the findings were produced, from the run rather than a claim. */
-function describeBasis(snapshot: Snapshot): TestingBasis {
-  const kind = snapshot.run.kind;
-  const engines = snapshot.run.engines;
-  const includesManual = snapshot.issues.some((i) => i.issue.origin === 'manual');
+/**
+ * Works out how the findings were produced, from the run rather than a claim.
+ *
+ * Takes `kind`/`engines`/`includesManual` as primitives, the same reason
+ * {@link describeLimitations} does: the streaming machine renderers know
+ * `includesManual` only once a fold over the issue cursor finishes, and have
+ * no `Snapshot` to read `run.kind`/`run.engines` from.
+ */
+export function describeBasis(
+  kind: RunKind,
+  engines: readonly string[],
+  includesManual: boolean,
+): TestingBasis {
   const automated = kind === 'scan';
   const uploaded = kind === 'upload';
 
@@ -696,7 +902,11 @@ export function buildReportModel(snapshot: Snapshot, options: ReportOptions): Re
     }
 
     if (SEVERITY_ORDER.indexOf(severity) > floorAt) {
-      omittedBelowFloor++;
+      // B208: `retest`'s own table lists every carried issue regardless of
+      // the floor (7.9a) — nothing is actually left out of the document for
+      // this kind, so counting it here would make `limitations` state an
+      // omission the very next section contradicts.
+      if (options.kind !== 'retest') omittedBelowFloor++;
       continue;
     }
 
@@ -733,7 +943,11 @@ export function buildReportModel(snapshot: Snapshot, options: ReportOptions): Re
         };
 
   const outstandingTotal = SEVERITY_ORDER.reduce((sum, s) => sum + outstanding[s], 0);
-  const basis = describeBasis(snapshot);
+  const basis = describeBasis(
+    snapshot.run.kind,
+    snapshot.run.engines,
+    snapshot.issues.some((i) => i.issue.origin === 'manual'),
+  );
   const retest = describeRetest(snapshot);
 
   // Rendering a retest of nothing is the over-claim §7 warns about: the
@@ -745,33 +959,10 @@ export function buildReportModel(snapshot: Snapshot, options: ReportOptions): Re
   }
 
   const branding = options.branding;
-  const colour = branding?.primaryColour;
-  if (colour !== undefined && !HEX_COLOUR.test(colour)) {
-    throw new TypeError(
-      `primaryColour must be a hex triplet such as #0a7 or #00aa77, not ${JSON.stringify(colour)}: ` +
-        'it is interpolated into the document stylesheet, where anything else could end the element',
-    );
-  }
-
-  const logo = branding?.logo;
-  if (logo !== undefined && !logo.startsWith('data:image/')) {
-    throw new TypeError(
-      `logo must be a data: URI, not ${JSON.stringify(logo.slice(0, 40))}: ` +
-        'a linked image would make the report depend on a network at render time, ' +
-        'which is the guarantee that lets it be rendered to PDF reproducibly',
-    );
-  }
+  const problem = brandingProblem(branding);
+  if (problem !== undefined) throw new TypeError(problem);
 
-  const attestor = options.preparedBy ?? branding?.companyName;
-  // An attestation is a statement that a named party carried out testing. With
-  // Secureport's name removed and nothing put in its place there is no such
-  // party, and the document would assert something on nobody's behalf.
-  if (attestor === undefined && branding?.whiteLabel === true && options.kind === 'attest') {
-    throw new TypeError(
-      'a white-labelled attestation must name who carried out the testing: ' +
-        'set branding.companyName or preparedBy',
-    );
-  }
+  const attestor = resolveAttestor(options);
 
   return {
     kind: options.kind,
@@ -780,13 +971,19 @@ export function buildReportModel(snapshot: Snapshot, options: ReportOptions): Re
     generatedAt: options.now,
     ...(options.preparedBy === undefined ? {} : { preparedBy: options.preparedBy }),
     ...(options.preparedFor === undefined ? {} : { preparedFor: options.preparedFor }),
-    attestor: attestor ?? 'Secureport',
+    attestor,
     coverPage: options.coverPage === true,
     tableOfContents: options.tableOfContents === true,
     ...(branding === undefined ? {} : { branding }),
     basis,
     evidenceVerbosity: options.evidenceVerbosity ?? 'summary',
-    limitations: describeLimitations(snapshot, basis, omitted),
+    limitations: describeLimitations(
+      snapshot.run.coverage.paths,
+      snapshot.run.createdAt,
+      basis,
+      snapshot.suppressed.length,
+      omitted,
+    ),
     sections,
     resolved: options.includeResolved === false ? [] : resolved,
     ...(omitted === undefined ? {} : { omitted }),