@secureport/core 2.1.0 → 2.3.0

package/src/reconcile.ts

@@ -1,6 +1,6 @@
 import type { Finding } from './finding.js';
 import { FINGERPRINT_VERSION } from './fingerprint.js';
-import type { Issue, IssueEvent } from './issue.js';
+import type { IgnoreReason, IgnoreScope, Issue, IssueEvent } from './issue.js';
 import type { Run, RunKind, RunSummary, SeverityCounts } from './run.js';
 import {
   DEFAULT_SLA_POLICY,
@@ -73,6 +73,56 @@ export interface ReconcileInput {
 
   /** How long the run took, for the summary. */
   readonly durationMs?: number;
+
+  /**
+   * Consulted for each issue this run would newly open, to suppress it at
+   * birth — a standing rule rather than a decision about one issue.
+   *
+   * **It has to live here, and B89 records why the obvious alternative fails.**
+   * `reconcile()` computes the run summary, so an issue it opens is counted
+   * `new`. A caller that suppressed that issue after the fact would produce a
+   * report whose opening line said `new` while its own appendix said
+   * `suppressed`, about the same issue, in the same document. Filtering the
+   * findings before reconciling is no better: the issue then vanishes from the
+   * summary entirely rather than being suppressed, and invariant 7 says a
+   * suppressed issue is never absent from the appendix.
+   *
+   * Return `undefined` to open the issue normally. The suppressed issue is
+   * counted `ignored` in the same pass that counts everything else, which the
+   * summary already does correctly because it tests `status` before it tests
+   * whether the run created the issue.
+   *
+   * **Consulted only for new issues**, never for one that already exists: an
+   * issue a person has looked at is theirs, and a rule written afterwards does
+   * not get to reach back and hide it.
+   */
+  readonly suppress?: (issue: Issue) => SuppressionDecision | undefined;
+}
+
+/**
+ * Why a standing rule suppressed an issue at the moment it was opened.
+ *
+ * @see {@link ReconcileInput.suppress}
+ */
+export interface SuppressionDecision {
+  /** Which of the domain's ignore reasons applies. */
+  readonly reason: IgnoreReason;
+
+  /** The justification an auditor reads in the suppressed appendix. */
+  readonly comment?: string;
+
+  /** How widely the suppression applies. */
+  readonly scope?: IgnoreScope;
+
+  /**
+   * Who accepted the risk. Defaults to {@link ReconcileInput.actor}.
+   *
+   * Worth passing. The appendix is an accepted-risk register, and a register
+   * whose every row says `reconciler` answers "who accepted this?" with "the
+   * clock did" — which `00-DOMAIN.md` §3 is explicit is not an identity. The
+   * rule that matched has an author; this is where to name them.
+   */
+  readonly by?: string;
 }
 
 /**
@@ -319,8 +369,42 @@ export function reconcile(input: ReconcileInput): ReconcileResult {
         origin: run.kind,
         slaDueAt: slaDueAt(worst.detectedSeverity, now, slaPolicy),
       };
-      updated.set(key, issue);
+      const decision = input.suppress?.(issue);
+      if (decision === undefined) {
+        updated.set(key, issue);
+        emit(id, 'created', { findingIds, severity: worst.detectedSeverity });
+        continue;
+      }
+
+      // Both events, in order. The issue was opened and then suppressed; a
+      // history that recorded only the suppression would have an issue whose
+      // first event is `ignored`, and invariant 2 wants every state change
+      // accounted for rather than the net result.
+      //
+      // `severityAtIgnore` is set deliberately, which is what makes a rule
+      // liftable: the existing branch above un-ignores an issue whose detected
+      // severity rises past what was accepted, and a standing rule should not
+      // be more permanent than a person's own decision. Accepting the risk of
+      // a medium is not accepting the risk of a critical, however the
+      // acceptance was expressed. **A merge survivor is the deliberate
+      // exception and omits it** (P6, B98) — that is a statement about
+      // identity rather than risk, and it has to survive a severity rise.
+      const suppressed: Issue = {
+        ...issue,
+        status: 'ignored',
+        ignoreReason: decision.reason,
+        ...(decision.comment === undefined ? {} : { ignoreComment: decision.comment }),
+        ...(decision.scope === undefined ? {} : { ignoreScope: decision.scope }),
+        ignoredBy: decision.by ?? actor,
+        severityAtIgnore: worst.detectedSeverity,
+      };
+      updated.set(key, suppressed);
       emit(id, 'created', { findingIds, severity: worst.detectedSeverity });
+      emit(id, 'ignored', {
+        reason: decision.reason,
+        ...(decision.comment === undefined ? {} : { comment: decision.comment }),
+        bornSuppressed: true,
+      });
       continue;
     }
 

package/src/report/anchors.ts

@@ -0,0 +1,96 @@
+/**
+ * Heading anchors and the contents list, produced together.
+ *
+ * **One pass over the rendered body, not two walks over the document.** A
+ * contents list built separately from the ids it links to is a list that can
+ * point at nothing — the failure is silent, it only shows up when somebody
+ * clicks, and it would appear the moment a heading's wording changed in one
+ * place and not the other. Here the ids and the entries come out of the same
+ * scan, so a heading that exists has an anchor and an entry, and one that does
+ * not exist has neither.
+ *
+ * This post-processes the renderer's **own** output, inside the same function
+ * that produced it. That is a different thing from the string surgery P7.1
+ * rules out: the rule there is against forking a published template, and this
+ * never reads one — every heading it matches was emitted a few lines earlier by
+ * the renderer calling it.
+ */
+
+/** One line of the contents list. */
+export interface TocEntry {
+  /** Heading level, 2 or 3. */
+  readonly level: number;
+
+  /** The anchor it links to, without the `#`. */
+  readonly id: string;
+
+  /** The heading as printed. */
+  readonly text: string;
+}
+
+/**
+ * A heading's anchor: lowercase, punctuation dropped, spaces hyphenated.
+ *
+ * The same rule GitHub and most Markdown renderers use, so a Markdown
+ * report's contents links resolve in the places Markdown is usually read —
+ * which is the only way this can work at all, because Markdown headings carry
+ * no explicit id to point at.
+ */
+function slug(text: string): string {
+  return (
+    text
+      .toLowerCase()
+      // Entities first: a heading rendered as `AT&T` should anchor on the
+      // text a reader sees, not on the escape that produced it.
+      .replace(/&[a-z]+;/gu, ' ')
+      .replace(/[^a-z0-9]+/gu, '-')
+      .replace(/^-+|-+$/gu, '') || 'section'
+  );
+}
+
+/** Makes `id` unique within a document, the way a duplicate heading is usually handled. */
+function unique(id: string, taken: Map<string, number>): string {
+  const seen = taken.get(id) ?? 0;
+  taken.set(id, seen + 1);
+  return seen === 0 ? id : `${id}-${String(seen)}`;
+}
+
+/**
+ * Gives every `<h2>` and `<h3>` an id, and reports what it found.
+ *
+ * `<h4>` is deliberately left alone: it is an individual issue, and a report
+ * with sixty findings would have a contents list longer than its summary.
+ */
+export function anchorHtmlHeadings(html: string): { html: string; toc: TocEntry[] } {
+  const toc: TocEntry[] = [];
+  const taken = new Map<string, number>();
+
+  // Safe over this input because it is this package's own markup rather than
+  // anything from outside: h2 and h3 are emitted with plain escaped text and
+  // never with nested elements.
+  const anchored = html.replace(
+    /<h([23])([^>]*)>([\s\S]*?)<\/h\1>/gu,
+    (_match, level: string, attrs: string, text: string) => {
+      const id = unique(slug(text), taken);
+      toc.push({ level: Number(level), id, text });
+      return `<h${level}${attrs} id="${id}">${text}</h${level}>`;
+    },
+  );
+
+  return { html: anchored, toc };
+}
+
+/** The same, for Markdown, where the anchor is implied by the heading text. */
+export function markdownHeadings(lines: readonly string[]): TocEntry[] {
+  const toc: TocEntry[] = [];
+  const taken = new Map<string, number>();
+
+  for (const line of lines) {
+    const match = /^(#{2,3})\s+(.*)$/u.exec(line);
+    if (!match) continue;
+    const text = match[2];
+    toc.push({ level: match[1].length, id: unique(slug(text), taken), text });
+  }
+
+  return toc;
+}

package/src/report/csv.ts

@@ -0,0 +1,180 @@
+import type { Severity } from '../severity.js';
+import type { SnapshotIssue, SuppressedIssue } from '../snapshot.js';
+import { verdictFor } from './model.js';
+import type { ReportHeader } from './stream.js';
+
+/**
+ * What a CSV export can be asked for.
+ *
+ * Its own type rather than {@link ReportOptions}, for the reason
+ * {@link SarifOptions} is: a spreadsheet has no `kind`, no branding and no
+ * cover page, and a type offering fields it ignores is the worse API.
+ */
+export interface CsvOptions {
+  /** Keep issues below this severity out of the rows. */
+  readonly severityFloor?: Severity;
+
+  /** Whether to include issues this run resolved. Defaults to `true`. */
+  readonly includeResolved?: boolean;
+}
+
+const FLOOR_RANK: Readonly<Record<Severity, number>> = Object.freeze({
+  critical: 0,
+  high: 1,
+  medium: 2,
+  low: 3,
+  advisory: 4,
+});
+
+/**
+ * The column order, which is a contract: a spreadsheet someone built a
+ * formula against should not have its columns move underneath them.
+ * Append-only — a new column goes on the end, never in the middle.
+ */
+const COLUMNS = [
+  'issue_id',
+  'title',
+  'status',
+  'change',
+  'effective_severity',
+  'detected_severity',
+  'location',
+  'parameter',
+  'cwe',
+  'first_seen',
+  'last_seen',
+  'days_open',
+  'sla_due',
+  'sla_status',
+  'findings',
+  'retest_verdict',
+  'suppressed',
+  'ignore_reason',
+  'ignored_by',
+  'ignored_at',
+  'ignore_expires',
+  'justification',
+] as const;
+
+/**
+ * One CSV field, escaped per RFC 4180.
+ *
+ * A field containing a comma, a quote or a newline is wrapped in quotes with
+ * its own quotes doubled. **Everything else is passed through unquoted**, so
+ * the common row stays readable in a diff.
+ *
+ * `undefined` becomes empty rather than the string "undefined", which is the
+ * kind of thing that reaches a customer's spreadsheet and stays there.
+ */
+function csvField(value: string | number | boolean | undefined): string {
+  if (value === undefined) return '';
+  const text = String(value);
+  if (!/[",\r\n]/u.test(text)) return text;
+  return `"${text.replace(/"/gu, '""')}"`;
+}
+
+/** A date as `YYYY-MM-DD`, or empty. One format, no locale to disagree about. */
+function csvDate(value: Date | undefined | null): string {
+  return value === undefined || value === null ? '' : value.toISOString().slice(0, 10);
+}
+
+function row(fields: readonly (string | number | boolean | undefined)[]): string {
+  return fields.map(csvField).join(',') + '\r\n';
+}
+
+/**
+ * Renders a snapshot's issues as CSV, streamed from a header and cursors —
+ * the fourth streaming machine format, alongside
+ * {@link renderJsonStream}, {@link renderMarkdownStream} and
+ * {@link renderSarifStream}. See {@link renderJsonStream} for the memory
+ * argument.
+ *
+ * **Suppressed issues are rows too, flagged rather than omitted.** A CSV is
+ * a data export, not a document with an appendix — so invariant 7's rule
+ * ("excluded from the metrics, never from the register") takes the form of a
+ * `suppressed` column plus the reason, author and justification beside it.
+ * Dropping them would hide an accepted risk from the one format most likely
+ * to be filtered and pivoted.
+ *
+ * **Line endings are CRLF, per RFC 4180.** Excel is the consumer that cares,
+ * and it is the consumer a CSV export exists for.
+ *
+ * @param header - The run, its baseline, and the target.
+ * @param issues - Every issue in scope, in the order the rows should appear.
+ * @param suppressed - The accepted-risk register, appended after them.
+ * @param options - A severity floor and whether to include resolved issues.
+ * @returns Chunks of CSV text; concatenated, they are one document.
+ */
+export async function* renderCsvStream(
+  header: ReportHeader,
+  issues: AsyncIterable<SnapshotIssue>,
+  suppressed: AsyncIterable<SuppressedIssue>,
+  options: CsvOptions = {},
+): AsyncGenerator<string> {
+  const floorAt = options.severityFloor === undefined ? 4 : FLOOR_RANK[options.severityFloor];
+  const hasBaseline = header.baseline !== undefined;
+
+  yield COLUMNS.join(',') + '\r\n';
+
+  for await (const entry of issues) {
+    const { issue } = entry;
+    if (issue.status === 'resolved') {
+      if (options.includeResolved === false) continue;
+    } else if (FLOOR_RANK[issue.effectiveSeverity] > floorAt) {
+      continue;
+    }
+
+    yield row([
+      issue.id,
+      issue.title,
+      issue.status,
+      entry.change,
+      issue.effectiveSeverity,
+      issue.detectedSeverity,
+      issue.location,
+      issue.parameter,
+      issue.cwe,
+      csvDate(issue.firstSeen),
+      csvDate(issue.lastSeen),
+      entry.daysOpen,
+      csvDate(issue.slaDueAt),
+      entry.slaStatus,
+      entry.findings.length,
+      hasBaseline ? verdictFor(entry) : undefined,
+      false,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+    ]);
+  }
+
+  for await (const entry of suppressed) {
+    const { issue } = entry;
+    yield row([
+      issue.id,
+      issue.title,
+      issue.status,
+      undefined,
+      issue.effectiveSeverity,
+      issue.detectedSeverity,
+      issue.location,
+      issue.parameter,
+      issue.cwe,
+      csvDate(issue.firstSeen),
+      csvDate(issue.lastSeen),
+      undefined,
+      csvDate(issue.slaDueAt),
+      undefined,
+      undefined,
+      undefined,
+      true,
+      entry.reason,
+      entry.ignoredBy,
+      csvDate(entry.ignoredAt),
+      csvDate(entry.expiresAt),
+      entry.comment,
+    ]);
+  }
+}

package/src/report/html.ts

@@ -1,7 +1,11 @@
+import type { Finding } from '../finding.js';
+import { anchorHtmlHeadings } from './anchors.js';
 import { SEVERITY_ORDER } from '../severity.js';
 import type { Snapshot, SnapshotIssue } from '../snapshot.js';
 import {
   buildReportModel,
+  type EvidenceVerbosity,
+  VERDICT_LABELS,
   type ReportModel,
   type ReportOptions,
   type RetestVerdict,
@@ -61,6 +65,30 @@ td code, code { font: .88em ui-monospace, SFMono-Regular, Menlo, monospace; word
 .breached { color: var(--critical); font-weight: 600; }
 .issue { break-inside: avoid; page-break-inside: avoid; margin-bottom: 1.5rem; }
 .none { color: var(--muted); font-style: italic; }
+.evidence { color: var(--muted); font-size: .92em; margin: 0 0 1rem; }
+/* Fixed rather than absolute: Chromium repeats a fixed element on every page
+   of a PDF, which is the only way one element can mark a whole document. */
+.toc { margin: 2rem 0; }
+.toc h2 { margin-top: 0; }
+.toc ul { list-style: none; padding: 0; margin: 0; }
+.toc li { margin: .2rem 0; }
+.toc-3 { padding-left: 1.25rem; font-size: .94em; }
+.toc a { color: inherit; text-decoration: none; border-bottom: 1px solid var(--rule); }
+.cover {
+  min-height: 88vh; display: flex; flex-direction: column; justify-content: center;
+  break-after: page; page-break-after: always;
+}
+.cover img { max-height: 5rem; max-width: 18rem; margin-bottom: 2.5rem; }
+.cover h1 { font-size: 2.6rem; margin: 0 0 .5rem; }
+.cover .for { font-size: 1.15rem; margin: 0 0 3rem; }
+.cover .details { color: var(--muted); font-size: .92em; }
+.cover .details div { margin: .15rem 0; }
+.watermark {
+  position: fixed; inset: 0; z-index: -1; pointer-events: none;
+  display: flex; align-items: center; justify-content: center;
+  font: 700 5.5rem/1 ui-serif, Georgia, serif; letter-spacing: .08em;
+  color: rgba(20, 24, 31, .07); transform: rotate(-28deg); text-transform: uppercase;
+}
 footer { margin-top: 3rem; padding-top: .75rem; border-top: 1px solid var(--rule); color: var(--muted); font-size: .85em; }
 
 @media print {
@@ -101,8 +129,51 @@ function changeSummary(model: ReportModel): string {
   }</p>`;
 }
 
+/**
+ * One supporting finding, in a sentence.
+ *
+ * Every field here is something that was *found*. Nothing identifies what
+ * found it — the engine name has leaked into rendered output twice.
+ */
+function evidenceLine(finding: Finding): string {
+  const where =
+    finding.parameter === undefined
+      ? `<code>${esc(finding.location)}</code>`
+      : `<code>${esc(finding.location)}</code> (<code>${esc(finding.parameter)}</code>)`;
+
+  const detail: string[] = [`${finding.detectedSeverity}, seen ${formatDate(finding.createdAt)}`];
+  if (finding.cve !== undefined) detail.push(esc(finding.cve));
+  if (finding.cvssScore !== undefined) {
+    detail.push(
+      finding.cvssVector === undefined
+        ? `CVSS ${String(finding.cvssScore)}`
+        : `CVSS ${String(finding.cvssScore)} <code>${esc(finding.cvssVector)}</code>`,
+    );
+  }
+  if (finding.confidence !== undefined) {
+    detail.push(`confidence ${String(Math.round(finding.confidence * 100))}%`);
+  }
+  const captures = finding.evidenceUri ?? [];
+  if (captures.length > 0) {
+    detail.push(`${String(captures.length)} capture${captures.length === 1 ? '' : 's'} stored`);
+  }
+
+  return `${where} — ${detail.join('; ')}`;
+}
+
+/** The count, the detail, or nothing — never the engine. */
+function evidenceBlock(entry: SnapshotIssue, verbosity: EvidenceVerbosity): string {
+  if (entry.findings.length === 0 || verbosity === 'none') return '';
+  if (verbosity === 'summary') {
+    return `<p class="lede">Evidence: ${entry.findings.length} finding${entry.findings.length === 1 ? '' : 's'} recorded.</p>`;
+  }
+  return `<p class="lede">Evidence</p><ul class="evidence">${entry.findings
+    .map((f) => `<li>${evidenceLine(f)}</li>`)
+    .join('')}</ul>`;
+}
+
 /** One issue in full. */
-function issueDetail(entry: SnapshotIssue): string {
+function issueDetail(entry: SnapshotIssue, verbosity: EvidenceVerbosity): string {
   const { issue } = entry;
   const first = entry.findings[0];
   const references = [...new Set(entry.findings.flatMap((f) => f.references ?? []))];
@@ -129,11 +200,7 @@ ${issue.cwe === undefined ? '' : `<tr><td>Weakness</td><td>${esc(issue.cwe)}</td
 </tbody></table>
 ${first?.description === undefined ? '' : `<p>${esc(first.description)}</p>`}
 ${first?.recommendation === undefined ? '' : `<p><strong>Recommendation.</strong> ${esc(first.recommendation)}</p>`}
-${
-  entry.findings.length === 0
-    ? ''
-    : `<p class="lede">Evidence: ${entry.findings.length} finding${entry.findings.length === 1 ? '' : 's'} recorded.</p>`
-}
+${evidenceBlock(entry, verbosity)}
 ${
   references.length === 0
     ? ''
@@ -142,15 +209,6 @@ ${
 </div>`;
 }
 
-/** How a verdict is printed. The dashes are an implementation detail. */
-const VERDICT_LABELS: Readonly<Record<RetestVerdict, string>> = Object.freeze({
-  fixed: 'fixed',
-  still_present: 'still present',
-  returned: 'returned',
-  not_retested: 'not retested',
-  new: 'new since',
-});
-
 /** The Retest body: the difference between two runs, and nothing else. */
 function retestBody(model: ReportModel): string {
   // `buildReportModel` refuses to build a retest without one.
@@ -291,7 +349,7 @@ function attestationBody(model: ReportModel): string {
   ).join('');
 
   return `<h2>Statement</h2>
-<p>${esc(model.preparedBy ?? 'Secureport')} carried out security testing of <strong>${esc(
+<p>${esc(model.attestor)} carried out security testing of <strong>${esc(
     snapshot.target.name,
   )}</strong> (${esc(snapshot.target.url)}) on ${formatDate(snapshot.run.createdAt)}.</p>
 <p>${esc(model.basis.statement)}</p>
@@ -360,7 +418,13 @@ ${changeSummary(model)}`;
   } else if (model.kind === 'attest') {
     findings = attestationBody(model);
   } else if (model.sections.length === 0) {
-    findings = '<h2>Findings</h2><p class="none">No issues were found.</p>';
+    // "No issues were found" is false when a floor is what emptied the
+    // section, and it is the most dangerous sentence in the document to get
+    // wrong — a reader would take it as a clean result.
+    findings =
+      model.omitted === undefined
+        ? '<h2>Findings</h2><p class="none">No issues were found.</p>'
+        : '<h2>Findings</h2><p class="none">No issues at or above the reporting threshold were found.</p>';
   } else if (model.kind === 'pen') {
     findings =
       '<h2>Findings</h2>' +
@@ -368,7 +432,7 @@ ${changeSummary(model)}`;
         .map(
           (section) =>
             `<h3 class="${sevClass(section.severity)}">${section.severity} (${section.issues.length})</h3>` +
-            section.issues.map(issueDetail).join(''),
+            section.issues.map((e) => issueDetail(e, model.evidenceVerbosity)).join(''),
         )
         .join('');
   } else {
@@ -388,6 +452,15 @@ ${changeSummary(model)}`;
     findings = `<h2>Findings</h2><table><thead><tr><th>Issue</th><th>Severity</th><th>Location</th><th>Change</th><th>Days open</th><th>Remediation</th></tr></thead><tbody>${rows}</tbody></table>`;
   }
 
+  // Beside the section it is about, rather than left to the limitations list,
+  // which only the Attestation Letter renders (B109). The Executive Summary
+  // and the Attestation have no findings section to attach it to, and both
+  // already print counts rather than issues, so neither is misled by its
+  // absence.
+  if (model.omitted !== undefined && model.kind !== 'exec' && model.kind !== 'attest') {
+    findings += `<p class="lede">${esc(model.omitted.statement)}</p>`;
+  }
+
   const resolved =
     model.kind === 'exec' ||
     model.kind === 'attest' ||
@@ -425,25 +498,72 @@ ${changeSummary(model)}`;
           )
           .join('')}</tbody></table>`;
 
+  // Appended rather than interpolated into STYLES, so the base stylesheet is
+  // one constant that every report shares and the brand is visibly an
+  // override. `primaryColour` is refused unless it is a hex triplet
+  // (`buildReportModel`), which is what makes this safe to put in a <style>
+  // element at all — `esc` protects text nodes, not CSS.
+  const accent = model.branding?.primaryColour;
+  const brandStyles =
+    accent === undefined
+      ? ''
+      : `\n:root { --accent: ${accent}; }\nh1 { color: var(--accent); }\nh2 { border-bottom-color: var(--accent); }`;
+
+  const brand = model.branding;
+  const cover = !model.coverPage
+    ? ''
+    : `<section class="cover">
+${brand?.logo === undefined ? '' : `<img src="${esc(brand.logo)}" alt="${esc(model.attestor)}">`}
+<h1>${esc(model.title)}</h1>
+<p class="for"><strong>${esc(target.name)}</strong> — ${esc(target.url)}</p>
+<div class="details">
+<div>${esc(model.attestor)}</div>
+${(brand?.companyDetails ?? []).map((line) => `<div>${esc(line)}</div>`).join('\n')}
+<div>${formatDate(model.generatedAt)}</div>
+${model.preparedFor === undefined ? '' : `<div>Prepared for ${esc(model.preparedFor)}</div>`}
+</div>
+</section>`;
+
+  const watermark =
+    model.branding?.watermark === undefined
+      ? ''
+      : `<div class="watermark" aria-hidden="true">${esc(model.branding.watermark)}</div>`;
+
+  // One scan produces both, so an entry cannot point at an anchor that does
+  // not exist. Always run, even when no list is printed: the anchors are what
+  // Chromium turns into a PDF outline.
+  const body = anchorHtmlHeadings([preamble, findings, resolved, suppressed].join('\n'));
+
+  const contents = !model.tableOfContents
+    ? ''
+    : `<nav class="toc"><h2>Contents</h2><ul>${body.toc
+        .map(
+          (entry) =>
+            `<li class="toc-${String(entry.level)}"><a href="#${entry.id}">${entry.text}</a></li>`,
+        )
+        .join('')}</ul></nav>`;
+
   return `<!doctype html>
 <html lang="en">
 <head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>${esc(model.title)} — ${esc(target.name)}</title>
-<style>${STYLES}</style>
+<style>${STYLES}${brandStyles}</style>
 </head>
 <body>
+${watermark}
+${cover}
 <h1>${esc(model.title)}</h1>
 <p class="lede"><strong>${esc(target.name)}</strong> — ${esc(target.url)}</p>
 <table class="meta"><tbody>${meta}</tbody></table>
-${preamble}
-${findings}
-${resolved}
-${suppressed}
-<footer>Generated by Secureport from run ${esc(snapshot.run.runId)}. Issue state as of ${formatDate(
-    snapshot.run.createdAt,
-  )}.</footer>
+${contents}
+${body.html}
+<footer>${
+    model.branding?.whiteLabel === true
+      ? `Run ${esc(snapshot.run.runId)}`
+      : `Generated by Secureport from run ${esc(snapshot.run.runId)}`
+  }. Issue state as of ${formatDate(snapshot.run.createdAt)}.</footer>
 </body>
 </html>`;
 }

package/src/report/json.ts

@@ -34,6 +34,22 @@ export interface JsonReport {
   /** Who it is for, if stated. */
   readonly preparedFor?: string;
 
+  /**
+   * The party that carried out the testing.
+   *
+   * **Content rather than presentation, which is why this is the one branding-
+   * derived value the JSON carries** (7.4b). A logo and an accent colour
+   * describe how a document looks and mean nothing to a consumer building a
+   * dashboard; who attested is the substance of an Attestation Letter, and a
+   * machine-readable report that omitted it would be missing the claim the
+   * document exists to make.
+   *
+   * Resolved the same way the prose resolves it: `preparedBy`, else the
+   * branding's `companyName`, else `Secureport`. Always present, because every
+   * report is produced by somebody.
+   */
+  readonly attestor: string;
+
   /**
    * How the findings were produced.
    *
@@ -104,6 +120,7 @@ export function renderJson(snapshot: Snapshot, options: ReportOptions): string {
     generatedAt: model.generatedAt.toISOString(),
     ...(model.preparedBy === undefined ? {} : { preparedBy: model.preparedBy }),
     ...(model.preparedFor === undefined ? {} : { preparedFor: model.preparedFor }),
+    attestor: model.attestor,
     basis: {
       automated: model.basis.automated,
       uploaded: model.basis.uploaded,