@secureport/core 1.0.0 → 2.2.0

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/markdown.ts

@@ -1,7 +1,11 @@
+import type { Finding } from '../finding.js';
+import { markdownHeadings } 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,
@@ -51,7 +55,7 @@ function changeSummary(model: ReportModel): string[] {
 }
 
 /** One issue, in full. The Penetration Test presentation. */
-function issueDetail(entry: SnapshotIssue): string[] {
+function issueDetail(entry: SnapshotIssue, verbosity: EvidenceVerbosity): string[] {
   const { issue } = entry;
   const lines: string[] = [
     `#### ${issue.title}`,
@@ -81,22 +85,63 @@ function issueDetail(entry: SnapshotIssue): string[] {
     lines.push('**Recommendation.** ' + first.recommendation, '');
   }
 
-  if (entry.findings.length > 0) {
-    // The count, not the engine. 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.
+  // The count or the detail, never the engine. 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 —
+  // it has leaked into rendered output twice, so no branch below reads
+  // `sourceEngine` or `sourceRuleId`.
+  if (entry.findings.length > 0 && verbosity === 'summary') {
     lines.push(
       `_Evidence: ${entry.findings.length} finding${entry.findings.length === 1 ? '' : 's'} recorded._`,
       '',
     );
-    const references = [...new Set(entry.findings.flatMap((f) => f.references ?? []))];
-    if (references.length > 0) {
-      lines.push(...references.map((r) => `- ${r}`), '');
-    }
+  } else if (entry.findings.length > 0 && verbosity === 'full') {
+    lines.push('**Evidence**', '');
+    for (const finding of entry.findings) lines.push(`- ${evidenceLine(finding)}`);
+    lines.push('');
+  }
+
+  // Outside the verbosity branch: an advisory is external reading, not
+  // evidence, so `none` still lists it.
+  const references = [...new Set(entry.findings.flatMap((f) => f.references ?? []))];
+  if (references.length > 0) {
+    lines.push(...references.map((r) => `- ${r}`), '');
   }
   return lines;
 }
 
+/**
+ * One supporting finding, in a sentence.
+ *
+ * Every field here is something that was *found*. Nothing identifies what
+ * found it.
+ */
+function evidenceLine(finding: Finding): string {
+  const where =
+    finding.parameter === undefined
+      ? `\`${cell(finding.location)}\``
+      : `\`${cell(finding.location)}\` (\`${cell(finding.parameter)}\`)`;
+
+  const detail: string[] = [`${finding.detectedSeverity}, seen ${formatDate(finding.createdAt)}`];
+  if (finding.cve !== undefined) detail.push(cell(finding.cve));
+  if (finding.cvssScore !== undefined) {
+    detail.push(
+      finding.cvssVector === undefined
+        ? `CVSS ${finding.cvssScore}`
+        : `CVSS ${finding.cvssScore} \`${cell(finding.cvssVector)}\``,
+    );
+  }
+  if (finding.confidence !== undefined) {
+    detail.push(`confidence ${Math.round(finding.confidence * 100)}%`);
+  }
+  const captures = finding.evidenceUri ?? [];
+  if (captures.length > 0) {
+    detail.push(`${captures.length} capture${captures.length === 1 ? '' : 's'} stored`);
+  }
+
+  return `${where} — ${detail.join('; ')}`;
+}
+
 /** One issue, as a table row. The Vulnerability Assessment presentation. */
 function issueRow(entry: SnapshotIssue): string {
   const { issue } = entry;
@@ -105,15 +150,6 @@ function issueRow(entry: SnapshotIssue): string {
   return `| ${cell(issue.title)} | ${issue.effectiveSeverity} | \`${cell(location)}\` | ${entry.change.replace('_', ' ')} | ${entry.daysOpen} | ${entry.slaStatus.replace('_', ' ')} |`;
 }
 
-/** 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.
@@ -299,7 +335,7 @@ function attestationBody(model: ReportModel): string[] {
   return [
     '## Statement',
     '',
-    `${model.preparedBy ?? 'Secureport'} carried out security testing of **${snapshot.target.name}**`,
+    `${model.attestor} carried out security testing of **${snapshot.target.name}**`,
     `(${snapshot.target.url}) on ${formatDate(snapshot.run.createdAt)}.`,
     '',
     model.basis.statement,
@@ -324,6 +360,37 @@ function attestationBody(model: ReportModel): string[] {
   ];
 }
 
+/**
+ * The contents list, inserted above the first section.
+ *
+ * Computed from the finished document rather than from a list kept alongside
+ * it, for the reason `anchors.ts` explains: a contents list assembled
+ * separately from the headings it points at is one that can point at nothing,
+ * and the failure is silent.
+ *
+ * Markdown headings carry no explicit id, so the links rely on the anchor
+ * every common Markdown renderer derives from the heading text. `slug` matches
+ * that convention, which is the only way this can work at all.
+ */
+function withContents(lines: readonly string[], model: ReportModel): string {
+  if (!model.tableOfContents) return lines.join('\n');
+
+  // Before inserting, so the contents list does not list itself.
+  const toc = markdownHeadings(lines);
+  if (toc.length === 0) return lines.join('\n');
+
+  const block = [
+    '## Contents',
+    '',
+    ...toc.map((entry) => `${entry.level === 3 ? '  ' : ''}- [${entry.text}](#${entry.id})`),
+    '',
+  ];
+
+  const firstSection = lines.findIndex((line) => /^##\s/u.test(line));
+  const at = firstSection < 0 ? lines.length : firstSection;
+  return [...lines.slice(0, at), ...block, ...lines.slice(at)].join('\n');
+}
+
 /**
  * Renders a snapshot as Markdown.
  *
@@ -347,9 +414,24 @@ export function renderMarkdown(snapshot: Snapshot, options: ReportOptions): stri
   const { target } = snapshot;
 
   const lines: string[] = [
+    // Markdown has no pages and no rotation, so the stamp the HTML puts across
+    // every page becomes a line at the top. Same statement, in the only form
+    // this format has for it.
+    ...(model.branding?.watermark === undefined ? [] : [`**${model.branding.watermark}**`, '']),
     `# ${model.title}`,
     '',
     `**${target.name}** — ${target.url}`,
+    // Markdown has no pages, so the cover is a block under the title rather
+    // than a page of its own. The same facts, in the only form this format
+    // has for them.
+    ...(model.coverPage
+      ? [
+          '',
+          model.attestor,
+          ...(model.branding?.companyDetails ?? []),
+          ...(model.preparedFor === undefined ? [] : [`Prepared for ${model.preparedFor}`]),
+        ].map((line, i) => (i === 0 ? line : `_${line}_`))
+      : []),
     '',
     `| | |`,
     `| --- | --- |`,
@@ -366,7 +448,7 @@ export function renderMarkdown(snapshot: Snapshot, options: ReportOptions): stri
   // reader stops trusting.
   if (model.kind === 'attest') {
     lines.push(...attestationBody(model), ...suppressedAppendix(snapshot), '');
-    return lines.join('\n');
+    return withContents(lines, model);
   }
 
   lines.push('## Basis of testing', '', model.basis.statement, '');
@@ -385,21 +467,33 @@ export function renderMarkdown(snapshot: Snapshot, options: ReportOptions): stri
 
   if (model.kind === 'exec') {
     lines.push(...executiveBody(model), ...suppressedAppendix(snapshot), '');
-    return lines.join('\n');
+    return withContents(lines, model);
   }
 
   if (model.kind === 'retest') {
     lines.push(...retestBody(model), ...suppressedAppendix(snapshot), '');
-    return lines.join('\n');
+    return withContents(lines, model);
   }
 
   if (model.sections.length === 0) {
-    lines.push('## Findings', '', '_No issues were found._', '');
+    // "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.
+    lines.push(
+      '## Findings',
+      '',
+      model.omitted === undefined
+        ? '_No issues were found._'
+        : '_No issues at or above the reporting threshold were found._',
+      '',
+    );
   } else if (model.kind === 'pen') {
     lines.push('## Findings', '');
     for (const section of model.sections) {
       lines.push(`### ${section.severity} (${section.issues.length})`, '');
-      for (const entry of section.issues) lines.push(...issueDetail(entry));
+      for (const entry of section.issues) {
+        lines.push(...issueDetail(entry, model.evidenceVerbosity));
+      }
     }
   } else {
     lines.push(
@@ -414,6 +508,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.
+  if (model.omitted !== undefined) lines.push(`_${model.omitted.statement}_`, '');
+
   if (model.resolved.length > 0) {
     lines.push(
       '## Resolved since the last run',
@@ -431,5 +531,5 @@ export function renderMarkdown(snapshot: Snapshot, options: ReportOptions): stri
   }
 
   lines.push(...suppressedAppendix(snapshot), '');
-  return lines.join('\n');
+  return withContents(lines, model);
 }