@secureport/core 2.1.0 → 2.2.0

package/src/report/model.ts

@@ -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. */
@@ -288,7 +543,11 @@ function verdictFor(entry: SnapshotIssue): RetestVerdict {
 }
 
 /** Works out what a report cannot establish, from the run rather than a template. */
-function describeLimitations(snapshot: Snapshot, basis: TestingBasis): string[] {
+function describeLimitations(
+  snapshot: Snapshot,
+  basis: TestingBasis,
+  omitted: OmittedIssues | undefined,
+): string[] {
   const limitations: string[] = [];
 
   if (!basis.includesManual) {
@@ -320,6 +579,11 @@ function describeLimitations(snapshot: Snapshot, basis: TestingBasis): string[]
         '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,6 +591,12 @@ function describeLimitations(snapshot: Snapshot, basis: TestingBasis): string[]
   return limitations;
 }
 
+/**
+ * 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;
+
 const DEFAULT_TITLES: Readonly<Record<ReportKind, string>> = Object.freeze({
   pen: 'Penetration Test Report',
   vap: 'Vulnerability Assessment Report',
@@ -399,6 +669,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 +687,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,6 +718,20 @@ 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 retest = describeRetest(snapshot);
@@ -442,6 +744,35 @@ 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 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',
+    );
+  }
+
   return {
     kind: options.kind,
     title: options.title ?? DEFAULT_TITLES[options.kind],
@@ -449,10 +780,16 @@ 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',
+    coverPage: options.coverPage === true,
+    tableOfContents: options.tableOfContents === true,
+    ...(branding === undefined ? {} : { branding }),
     basis,
-    limitations: describeLimitations(snapshot, basis),
+    evidenceVerbosity: options.evidenceVerbosity ?? 'summary',
+    limitations: describeLimitations(snapshot, basis, omitted),
     sections,
-    resolved,
+    resolved: options.includeResolved === false ? [] : resolved,
+    ...(omitted === undefined ? {} : { omitted }),
     outstanding,
     outstandingTotal,
     exposureScore: snapshot.run.exposureScore,