@secureport/core 2.1.0 → 2.3.0

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,
@@ -12,8 +16,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, ' ');
 }
 
@@ -50,8 +60,14 @@ function changeSummary(model: ReportModel): string[] {
   ];
 }
 
-/** One issue, in full. The Penetration Test presentation. */
-function issueDetail(entry: SnapshotIssue): 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}`,
@@ -81,39 +97,75 @@ 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 issue, as a table row. The Vulnerability Assessment presentation. */
-function issueRow(entry: SnapshotIssue): string {
+/**
+ * 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.
+ *
+ * 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('_', ' ')} |`;
 }
 
-/** 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 +351,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 +376,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 +430,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 +464,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 +483,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 +524,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 +547,5 @@ export function renderMarkdown(snapshot: Snapshot, options: ReportOptions): stri
   }
 
   lines.push(...suppressedAppendix(snapshot), '');
-  return lines.join('\n');
+  return withContents(lines, model);
 }