@secureport/core 2.1.0 → 2.3.0

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';
@@ -43,8 +43,185 @@ export interface ReportOptions {
    * with the copy somebody was sent.
    */
   readonly now: Date;
+
+  /**
+   * Keep issues below this severity out of the detail sections.
+   *
+   * **The counts do not move, and that asymmetry is the whole design.**
+   * {@link ReportModel.outstanding}, the exposure score and the breach count
+   * describe the target, not the document, so a floor that changed them would
+   * let somebody produce a report saying "3 outstanding" about a target with
+   * forty. What the floor removes is pages, not facts: the header still sums
+   * everything, and {@link ReportModel.limitations} gains a sentence naming
+   * how many issues were left out.
+   *
+   * That is the same shape the suppressed appendix already uses — excluded
+   * from the sections, stated in the limitations — because it answers the
+   * same question, which is what a reader is not being shown.
+   *
+   * Omitted entirely by default: every issue is listed.
+   */
+  readonly severityFloor?: Severity;
+
+  /**
+   * Whether to list the issues this run resolved. Defaults to `true`.
+   *
+   * Off is a legitimate choice for a document that only needs to state what is
+   * outstanding, and unlike {@link ReportOptions.severityFloor} it needs no disclosure —
+   * omitting evidence of remediation understates the good news rather than the
+   * bad, so a reader cannot be misled about risk by its absence.
+   *
+   * It does not touch {@link ReportModel.retest}: a retest's `fixed` verdict is
+   * the document's entire point, and a caller asking for less detail about
+   * resolved issues is not asking for a retest that cannot do its job.
+   */
+  readonly includeResolved?: boolean;
+
+  /**
+   * How much of each issue's evidence to print. Defaults to `'summary'`.
+   *
+   * - `'none'` — no evidence at all. The issue, its severity, its location and
+   *   what to do about it. External references are still listed: an advisory is
+   *   reading, not evidence.
+   * - `'summary'` — how many findings support the issue, and nothing about any
+   *   one of them. What every report printed before this option existed.
+   * - `'full'` — each supporting finding in its own right: where it was seen,
+   *   when, at what severity, with its CVSS and CVE where the engine supplied
+   *   them, and pointers to any stored capture.
+   *
+   * **No verbosity names an engine, and that is not negotiable.** Which scanner
+   * produced a finding is an implementation detail of the assessment, and
+   * naming the stack in a customer-facing document gives away more than it
+   * explains — `00-DOMAIN.md` §7 and {@link TestingBasis.engines}. The engine
+   * name has leaked into rendered output twice already, so `'full'` prints
+   * what was found and never who found it.
+   */
+  readonly evidenceVerbosity?: EvidenceVerbosity;
+
+  /** Whose document this is. See {@link Branding}. */
+  readonly branding?: Branding;
+
+  /**
+   * Open the report with a cover page. Defaults to `false`.
+   *
+   * **On the options rather than on {@link Branding}, and the split is
+   * deliberate.** Branding is org-level configuration, stored once and the
+   * same for every document; whether a particular render wants a cover is a
+   * per-report layout decision — a PDF for a client does, a Markdown export
+   * piped into a terminal does not.
+   *
+   * Markdown has no pages, so there it is a block at the top rather than a
+   * page of its own. The statement is the same; the format has one form for
+   * it.
+   */
+  readonly coverPage?: boolean;
+
+  /**
+   * Open the body with a contents list, and give every section an anchor.
+   * Defaults to `false`.
+   *
+   * **The anchors are what a PDF needs, not the list.** Chromium derives a
+   * document outline from the heading structure, which is how a reader
+   * navigates a sixty-page report in a viewer's sidebar; the printed contents
+   * list is for whoever has it on paper. Both come from the same scan of the
+   * rendered headings, so a list entry cannot point at an anchor that is not
+   * there.
+   *
+   * Individual issues (`<h4>`) are left out on purpose: a report with sixty
+   * findings would have a contents list longer than its summary.
+   */
+  readonly tableOfContents?: boolean;
+}
+
+/**
+ * Whose document this is — the marks on it, and the name on it.
+ *
+ * Per `00-TIER-MATRIX.md`: free-tier reports are watermarked, branding is
+ * `[branding]`, and white-label is Enterprise only. **None of that is enforced
+ * here.** This package has no idea what anyone is paying, and a pure function
+ * that consulted an entitlement would be the wrong place to find out; the
+ * caller passes what the caller is entitled to.
+ */
+export interface Branding {
+  /**
+   * The name that appears where Secureport's otherwise would — on an
+   * Attestation Letter, as the party who carried out the testing.
+   *
+   * {@link ReportOptions.preparedBy} wins over it when both are given, because
+   * it is the more specific statement: branding is who owns the document,
+   * `preparedBy` is who did the work, and they are not always the same party.
+   */
+  readonly companyName?: string;
+
+  /**
+   * Accent colour for headings and rules, as a hex triplet — `#0a7`,
+   * `#00aa77`, or `#00aa77ff`.
+   *
+   * **Hex only, and the restriction is a security boundary rather than
+   * fussiness.** This value is interpolated into the document's `<style>`
+   * block, which is a context the HTML renderer's escaping does not protect:
+   * it escapes text nodes, and a colour of `red</style><script>…` would close
+   * the element and run. Anything that does not match the pattern is refused by
+   * {@link buildReportModel} rather than sanitised, because silently altering
+   * somebody's brand colour is its own kind of wrong.
+   */
+  readonly primaryColour?: string;
+
+  /**
+   * Remove Secureport's own marks from the document entirely.
+   *
+   * An Attestation Letter with this set and no name to put in Secureport's
+   * place is refused: a formal statement that testing was carried out has to
+   * say who carried it out, and an unattributed one is worth nothing to the
+   * auditor it exists for.
+   */
+  readonly whiteLabel?: boolean;
+
+  /**
+   * Text printed across every page — what the free tier stamps on a report.
+   *
+   * Rendered as an element rather than through CSS `content`, so it goes
+   * through the same escaping as every other value from outside.
+   */
+  readonly watermark?: string;
+
+  /**
+   * The logo, as a `data:` URI — never a URL.
+   *
+   * **The restriction is what keeps a report a single file.** `renderHtml`
+   * emits a self-contained document with its stylesheet inlined and nothing
+   * linked, which is what lets P7 render it through Chromium with no network
+   * and get the same bytes in CI as on a laptop. One `<img src="https://…">`
+   * would trade that for a logo, and trade it silently: the report would look
+   * right on the machine that rendered it and lose its mark for a reader
+   * offline, or three months later when the URL stops resolving.
+   *
+   * Refused by {@link buildReportModel} rather than fetched, because a pure
+   * function that reached the network would stop being one.
+   *
+   * Rendered into an `<img>`, which is also why an SVG data URI is allowed: an
+   * image context does not execute script, where inlining the same markup into
+   * the document would.
+   */
+  readonly logo?: string;
+
+  /**
+   * Address, registration number, contact — whatever belongs under the name on
+   * a cover page, one line each.
+   *
+   * Only shown when {@link ReportOptions.coverPage} is set, because there is
+   * nowhere else in the document these belong.
+   */
+  readonly companyDetails?: readonly string[];
 }
 
+/**
+ * How much of an issue's supporting evidence a report prints.
+ *
+ * See {@link ReportOptions.evidenceVerbosity} for what each level shows.
+ */
+export type EvidenceVerbosity = 'none' | 'summary' | 'full';
+
 /**
  * How the findings in a report were actually produced.
  *
@@ -94,6 +271,24 @@ export interface TestingBasis {
   readonly statement: string;
 }
 
+/**
+ * What a severity floor kept out of a report's detail sections.
+ *
+ * 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.
+ */
+export interface OmittedIssues {
+  /** How many outstanding issues were left out. Never `0` — the field is absent instead. */
+  readonly count: number;
+
+  /** The floor that excluded them. */
+  readonly floor: Severity;
+
+  /** One sentence, ready to print, so no two renderers word it differently. */
+  readonly statement: string;
+}
+
 /** A group of issues sharing a severity, most urgent first. */
 export interface ReportSection {
   /** The severity this section covers. */
@@ -123,9 +318,38 @@ export interface ReportModel {
   /** Who it is for, if stated. */
   readonly preparedFor?: string;
 
+  /**
+   * Who the document says carried out the testing.
+   *
+   * Resolved once here from {@link ReportOptions.preparedBy},
+   * {@link Branding.companyName} and the default, because both renderers used
+   * to write `preparedBy ?? 'Secureport'` themselves — two copies of a default
+   * that white-labelling has to change in both places or not at all.
+   */
+  readonly attestor: string;
+
+  /** Whose document this is, as given. Absent when nothing was branded. */
+  readonly branding?: Branding;
+
+  /** Whether to open with a cover, resolved from {@link ReportOptions.coverPage}. */
+  readonly coverPage: boolean;
+
+  /** Whether to print a contents list, resolved from {@link ReportOptions.tableOfContents}. */
+  readonly tableOfContents: boolean;
+
   /** How the findings were produced. */
   readonly basis: TestingBasis;
 
+  /**
+   * How much of each issue's evidence to print, resolved from
+   * {@link ReportOptions.evidenceVerbosity}.
+   *
+   * On the model rather than read from the options by each renderer, so the
+   * Markdown and the HTML cannot disagree about how much of an issue they are
+   * showing — the same reason every number here is derived once.
+   */
+  readonly evidenceVerbosity: EvidenceVerbosity;
+
   /**
    * Outstanding issues grouped by severity, most urgent first, empties dropped.
    *
@@ -140,10 +364,23 @@ export interface ReportModel {
    *
    * Kept and shown rather than dropped: "what you fixed" is the story the
    * product exists to tell, and a report that silently omits it throws away its
-   * best evidence.
+   * best evidence. Empty when {@link ReportOptions.includeResolved} is `false`,
+   * which is the caller saying so deliberately.
    */
   readonly resolved: readonly SnapshotIssue[];
 
+  /**
+   * What {@link ReportOptions.severityFloor} kept out of {@link ReportModel.sections}.
+   * Absent when no floor was set, or when one was set and removed nothing.
+   *
+   * Carried as data and not only as prose, because `00-DOMAIN.md` §7 says what
+   * a report does not establish travels as data too — so a consumer rendering
+   * its own view cannot drop the disclosure simply by not printing a sentence.
+   * `statement` is that sentence, derived once here so the renderers and
+   * {@link ReportModel.limitations} cannot word it three different ways.
+   */
+  readonly omitted?: OmittedIssues;
+
   /** Open and regressed issues, by severity. What the reader owes work on. */
   readonly outstanding: Readonly<Record<Severity, number>>;
 
@@ -195,6 +432,24 @@ export interface ReportModel {
  */
 export type RetestVerdict = 'fixed' | 'still_present' | 'returned' | 'not_retested' | 'new';
 
+/**
+ * How each verdict is printed.
+ *
+ * Exported because it is printed, and a printed vocabulary is a contract —
+ * `00-DOMAIN.md` §7 says so of the verdicts themselves. It was defined
+ * identically in both renderers, which PDF and DOCX would have made four
+ * copies of, each one a chance for `not_retested` to be worded differently in
+ * the format somebody actually reads. The underscores are an implementation
+ * detail of the union and should never reach a page.
+ */
+export const VERDICT_LABELS: Readonly<Record<RetestVerdict, string>> = Object.freeze({
+  fixed: 'fixed',
+  still_present: 'still present',
+  returned: 'returned',
+  not_retested: 'not retested',
+  new: 'new since',
+});
+
 /** One issue, with what the retest established about it. */
 export interface RetestEntry {
   /** The issue as the snapshot sees it. */
@@ -279,16 +534,33 @@ 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, basis: TestingBasis): string[] {
+/**
+ * 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[] = [];
 
   if (!basis.includesManual) {
@@ -302,11 +574,11 @@ function describeLimitations(snapshot: Snapshot, basis: TestingBasis): string[]
       '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.`,
   );
@@ -314,12 +586,17 @@ function describeLimitations(snapshot: Snapshot, basis: TestingBasis): string[]
     '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.',
     );
   }
+  // Immediately after the suppression sentence and before the compliance one,
+  // because it answers the same question a reader is entitled to ask: what am
+  // I not being shown? A floor that removed pages silently would be the
+  // over-claim §7 exists to stop, in a quieter form than the appendix one.
+  if (omitted !== undefined) limitations.push(omitted.statement);
   limitations.push(
     'This document does not certify compliance with any standard, framework or regulation.',
   );
@@ -327,7 +604,80 @@ function describeLimitations(snapshot: Snapshot, basis: TestingBasis): string[]
   return limitations;
 }
 
-const DEFAULT_TITLES: Readonly<Record<ReportKind, string>> = Object.freeze({
+/**
+ * Hex triplets only. See {@link Branding.primaryColour} for why this is a
+ * refusal rather than a sanitisation.
+ */
+const HEX_COLOUR = /^#(?:[0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/iu;
+
+/**
+ * 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',
@@ -335,11 +685,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';
 
@@ -399,6 +757,16 @@ export function buildReportModel(snapshot: Snapshot, options: ReportOptions): Re
   const bySeverity = new Map<Severity, SnapshotIssue[]>();
   const resolved: SnapshotIssue[] = [];
   let breached = 0;
+  let omittedBelowFloor = 0;
+
+  // `SEVERITY_ORDER` is most-severe-first, so "at or above the floor" is a
+  // *lower* index. Same trap `describeRetest` records above, from the other
+  // direction: `severityRank` counts the opposite way and using it here would
+  // floor out everything except the advisories.
+  const floorAt =
+    options.severityFloor === undefined
+      ? SEVERITY_ORDER.length
+      : SEVERITY_ORDER.indexOf(options.severityFloor);
 
   for (const entry of snapshot.issues) {
     if (entry.issue.status === 'resolved') {
@@ -407,14 +775,22 @@ export function buildReportModel(snapshot: Snapshot, options: ReportOptions): Re
     }
 
     const severity = entry.issue.effectiveSeverity;
-    const group = bySeverity.get(severity);
-    if (group) group.push(entry);
-    else bySeverity.set(severity, [entry]);
 
+    // Counted before the floor is consulted, deliberately: the floor decides
+    // what is *listed*, never what is *counted*.
     if (entry.issue.status === 'open' || entry.issue.status === 'regressed') {
       outstanding[severity]++;
       if (entry.slaStatus === 'breached') breached++;
     }
+
+    if (SEVERITY_ORDER.indexOf(severity) > floorAt) {
+      omittedBelowFloor++;
+      continue;
+    }
+
+    const group = bySeverity.get(severity);
+    if (group) group.push(entry);
+    else bySeverity.set(severity, [entry]);
   }
   resolved.sort((a, b) => b.issue.lastSeen.getTime() - a.issue.lastSeen.getTime());
 
@@ -430,8 +806,26 @@ export function buildReportModel(snapshot: Snapshot, options: ReportOptions): Re
     });
   }
 
+  const floor = options.severityFloor;
+  const omitted: OmittedIssues | undefined =
+    omittedBelowFloor === 0 || floor === undefined
+      ? undefined
+      : {
+          count: omittedBelowFloor,
+          floor,
+          statement:
+            `${omittedBelowFloor} issue${omittedBelowFloor === 1 ? '' : 's'} below ${floor} severity ` +
+            `${omittedBelowFloor === 1 ? 'is' : 'are'} not listed individually in this document. ` +
+            `${omittedBelowFloor === 1 ? 'It remains' : 'They remain'} open and ` +
+            `${omittedBelowFloor === 1 ? 'is' : 'are'} included in every count above.`,
+        };
+
   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
@@ -442,6 +836,12 @@ export function buildReportModel(snapshot: Snapshot, options: ReportOptions): Re
     );
   }
 
+  const branding = options.branding;
+  const problem = brandingProblem(branding);
+  if (problem !== undefined) throw new TypeError(problem);
+
+  const attestor = resolveAttestor(options);
+
   return {
     kind: options.kind,
     title: options.title ?? DEFAULT_TITLES[options.kind],
@@ -449,10 +849,22 @@ export function buildReportModel(snapshot: Snapshot, options: ReportOptions): Re
     generatedAt: options.now,
     ...(options.preparedBy === undefined ? {} : { preparedBy: options.preparedBy }),
     ...(options.preparedFor === undefined ? {} : { preparedFor: options.preparedFor }),
+    attestor,
+    coverPage: options.coverPage === true,
+    tableOfContents: options.tableOfContents === true,
+    ...(branding === undefined ? {} : { branding }),
     basis,
-    limitations: describeLimitations(snapshot, basis),
+    evidenceVerbosity: options.evidenceVerbosity ?? 'summary',
+    limitations: describeLimitations(
+      snapshot.run.coverage.paths,
+      snapshot.run.createdAt,
+      basis,
+      snapshot.suppressed.length,
+      omitted,
+    ),
     sections,
-    resolved,
+    resolved: options.includeResolved === false ? [] : resolved,
+    ...(omitted === undefined ? {} : { omitted }),
     outstanding,
     outstandingTotal,
     exposureScore: snapshot.run.exposureScore,