@secureport/core 0.3.0 → 1.0.0-rc.0

package/src/report/markdown.ts

@@ -0,0 +1,435 @@
+import { SEVERITY_ORDER } from '../severity.js';
+import type { Snapshot, SnapshotIssue } from '../snapshot.js';
+import {
+  buildReportModel,
+  type ReportModel,
+  type ReportOptions,
+  type RetestVerdict,
+} from './model.js';
+
+/** A date, printed the same way everywhere, without a locale to disagree about. */
+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 {
+  return value.replace(/\|/gu, '\\|').replace(/\n/gu, ' ');
+}
+
+/** The change summary every report opens with, per `00-DOMAIN.md` §7. */
+function changeSummary(model: ReportModel): string[] {
+  const { run, baseline } = model.snapshot;
+  const rows = SEVERITY_ORDER.map((severity) => {
+    const cells = [
+      severity,
+      run.new[severity],
+      run.stillOpen[severity],
+      run.regressed[severity],
+      run.resolved[severity],
+      run.ignored[severity],
+    ];
+    return `| ${cells.join(' | ')} |`;
+  });
+
+  return [
+    '## What changed',
+    '',
+    baseline === undefined
+      ? '_First run against this target, so every issue is new._'
+      : `_Compared with the run of ${formatDate(baseline.createdAt)}._`,
+    '',
+    '| Severity | New | Still open | Regressed | Resolved | Suppressed |',
+    '| --- | --- | --- | --- | --- | --- |',
+    ...rows,
+    '',
+    `**${model.outstandingTotal} outstanding.** Exposure score ${model.exposureScore}.` +
+      (model.breached > 0
+        ? ` **${model.breached} past ${model.breached === 1 ? 'its' : 'their'} remediation deadline.**`
+        : ''),
+  ];
+}
+
+/** One issue, in full. The Penetration Test presentation. */
+function issueDetail(entry: SnapshotIssue): string[] {
+  const { issue } = entry;
+  const lines: string[] = [
+    `#### ${issue.title}`,
+    '',
+    `| | |`,
+    `| --- | --- |`,
+    `| Severity | ${issue.effectiveSeverity}${
+      issue.effectiveSeverity === issue.detectedSeverity
+        ? ''
+        : ` (detected ${issue.detectedSeverity})`
+    } |`,
+    `| Status | ${issue.status} · ${entry.change.replace('_', ' ')} |`,
+    `| Location | \`${cell(issue.location)}\`${issue.parameter === undefined ? '' : ` (\`${cell(issue.parameter)}\`)`} |`,
+    `| First seen | ${formatDate(issue.firstSeen)} (${entry.daysOpen} days) |`,
+    `| Remediation | ${
+      issue.slaDueAt === undefined || issue.slaDueAt === null
+        ? 'no deadline'
+        : `${formatDate(issue.slaDueAt)} — ${entry.slaStatus.replace('_', ' ')}`
+    } |`,
+  ];
+  if (issue.cwe !== undefined) lines.push(`| Weakness | ${issue.cwe} |`);
+  lines.push('');
+
+  const first = entry.findings[0];
+  if (first?.description !== undefined) lines.push(first.description, '');
+  if (first?.recommendation !== undefined) {
+    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.
+    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}`), '');
+    }
+  }
+  return lines;
+}
+
+/** One issue, as a table row. The Vulnerability Assessment presentation. */
+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.
+  const retest = model.retest as NonNullable<ReportModel['retest']>;
+  const { counts } = retest;
+  const carried = counts.fixed + counts.still_present + counts.returned + counts.not_retested;
+
+  const lines = [
+    '## Retest verdict',
+    '',
+    `Retested against the run of ${formatDate(retest.baseline.createdAt)}.`,
+    '',
+    carried === 0
+      ? 'No issues were carried into this retest.'
+      : `Of the ${carried} issue${carried === 1 ? '' : 's'} carried into this retest, ` +
+        `**${counts.fixed} ${counts.fixed === 1 ? 'is' : 'are'} confirmed fixed**, ` +
+        `${counts.still_present} ${counts.still_present === 1 ? 'is' : 'are'} still present, ` +
+        `${counts.returned} returned, and ${counts.not_retested} could not be retested.` +
+        (counts.new === 0
+          ? ''
+          : ` A further ${counts.new} ${counts.new === 1 ? 'issue was' : 'issues were'} found for the first time by this run.`),
+    '',
+  ];
+
+  if (retest.fixRate !== null) {
+    lines.push(
+      `${Math.round(retest.fixRate * 100)}% of the issues this run could check are fixed.`,
+      '',
+    );
+  }
+
+  lines.push(
+    '| Verdict | Issues |',
+    '| --- | --- |',
+    ...(Object.keys(VERDICT_LABELS) as RetestVerdict[]).map(
+      (v) => `| ${VERDICT_LABELS[v]} | ${counts[v]} |`,
+    ),
+    '',
+  );
+
+  // The section that stops this document reporting a coverage gap as
+  // remediation. Stated before the issue table, not in a footnote after it.
+  if (counts.not_retested > 0) {
+    lines.push(
+      '## Not retested',
+      '',
+      `${counts.not_retested} issue${counts.not_retested === 1 ? '' : 's'} could not be retested by this run:`,
+      'the run did not cover where they were found, or has not missed them often enough to',
+      'call them resolved. **They are not fixed.** An issue nobody looked at is neither fixed',
+      'nor unfixed, and it is excluded from the percentage above rather than counted either way.',
+      '',
+    );
+  }
+
+  if (retest.entries.length === 0) {
+    lines.push('## Issue by issue', '', '_No issues._', '');
+    return lines;
+  }
+
+  lines.push(
+    '## Issue by issue',
+    '',
+    '| Issue | Severity | Verdict | Location | Open for |',
+    '| --- | --- | --- | --- | --- |',
+    ...retest.entries.map((entry) => {
+      const { issue } = entry.issue;
+      const location =
+        issue.parameter === undefined ? issue.location : `${issue.location} (${issue.parameter})`;
+      return `| ${cell(issue.title)} | ${issue.effectiveSeverity} | ${VERDICT_LABELS[entry.verdict]} | \`${cell(location)}\` | ${entry.issue.daysOpen} days |`;
+    }),
+    '',
+  );
+  return lines;
+}
+
+/** The suppressed-findings appendix. On by default, never optional. */
+function suppressedAppendix(snapshot: Snapshot): string[] {
+  if (snapshot.suppressed.length === 0) {
+    return ['## Suppressed findings', '', '_None._'];
+  }
+  return [
+    '## Suppressed findings',
+    '',
+    'Accepted, out of scope or dismissed. Listed because an accepted risk that',
+    'nobody can see is not an accepted risk.',
+    '',
+    '| Issue | Severity when suppressed | Reason | By | Expires | Justification |',
+    '| --- | --- | --- | --- | --- | --- |',
+    ...snapshot.suppressed.map(
+      (s) =>
+        `| ${cell(s.issue.title)} | ${s.severityAtIgnore} | ${s.reason.replace('_', ' ')} | ${cell(s.ignoredBy)} | ${
+          s.expiresAt === undefined ? 'never' : formatDate(s.expiresAt)
+        } | ${cell(s.comment)} |`,
+    ),
+  ];
+}
+
+/** The Executive Summary body: what changed, what it means, no technical detail. */
+function executiveBody(model: ReportModel): string[] {
+  const resolvedCount = model.resolved.length;
+  const regressed = model.sections
+    .flatMap((s) => s.issues)
+    .filter((i) => i.change === 'regressed').length;
+
+  const headline =
+    model.outstandingTotal === 0
+      ? 'Nothing is currently outstanding on this target.'
+      : `${model.outstandingTotal} issue${model.outstandingTotal === 1 ? '' : 's'} ${
+          model.outstandingTotal === 1 ? 'is' : 'are'
+        } currently outstanding, of which ${model.outstanding.critical + model.outstanding.high} ` +
+        `${model.outstanding.critical + model.outstanding.high === 1 ? 'is' : 'are'} critical or high.`;
+
+  const lines = ['## Where things stand', '', headline, ''];
+
+  if (resolvedCount > 0) {
+    lines.push(
+      `${resolvedCount} issue${resolvedCount === 1 ? ' was' : 's were'} resolved since the last run.`,
+      '',
+    );
+  }
+  if (regressed > 0) {
+    lines.push(
+      `**${regressed} previously resolved issue${regressed === 1 ? ' has' : 's have'} returned.** ` +
+        'A returning issue usually means a fix was reverted or incompletely applied.',
+      '',
+    );
+  }
+  if (model.breached > 0) {
+    lines.push(
+      `**${model.breached} ${model.breached === 1 ? 'is' : 'are'} past the remediation deadline** ` +
+        'set by the severity policy.',
+      '',
+    );
+  }
+
+  lines.push(
+    '## Outstanding by severity',
+    '',
+    '| Severity | Outstanding |',
+    '| --- | --- |',
+    ...SEVERITY_ORDER.filter((sev) => model.outstanding[sev] > 0).map(
+      (sev) => `| ${sev} | ${model.outstanding[sev]} |`,
+    ),
+    '',
+  );
+  if (model.outstandingTotal === 0) lines.push('_Nothing outstanding._', '');
+
+  // Named, but not explained. An executive summary that reproduces the
+  // technical report is not a summary, and the reader who wants detail has the
+  // other three.
+  const notable = model.sections
+    .flatMap((s) => s.issues)
+    .filter((i) => ['critical', 'high'].includes(i.issue.effectiveSeverity))
+    .slice(0, 10);
+  if (notable.length > 0) {
+    lines.push(
+      '## What needs attention first',
+      '',
+      ...notable.map(
+        (entry) =>
+          `- **${entry.issue.effectiveSeverity}** — ${entry.issue.title} (open ${entry.daysOpen} days)`,
+      ),
+      '',
+      '_Full detail, including evidence, is in the accompanying technical report._',
+      '',
+    );
+  }
+
+  lines.push(
+    `Exposure score ${model.exposureScore}. This is a single number combining how many issues`,
+    'are open, how severe they are and how long they have been open. It falls as issues are',
+    'fixed and rises while they are not.',
+    '',
+  );
+  return lines;
+}
+
+/** The Attestation Letter body: a formal statement, with its limits stated. */
+function attestationBody(model: ReportModel): string[] {
+  const { snapshot } = model;
+  const found = snapshot.issues.length + snapshot.suppressed.length;
+
+  return [
+    '## Statement',
+    '',
+    `${model.preparedBy ?? 'Secureport'} carried out security testing of **${snapshot.target.name}**`,
+    `(${snapshot.target.url}) on ${formatDate(snapshot.run.createdAt)}.`,
+    '',
+    model.basis.statement,
+    '',
+    `The testing identified ${found} issue${found === 1 ? '' : 's'} in total, of which`,
+    `${model.outstandingTotal} ${model.outstandingTotal === 1 ? 'remains' : 'remain'} outstanding at the date of this letter:`,
+    '',
+    '| Severity | Outstanding |',
+    '| --- | --- |',
+    ...SEVERITY_ORDER.map((sev) => `| ${sev} | ${model.outstanding[sev]} |`),
+    '',
+    // The most important section in the document, and deliberately not last:
+    // a reader who stops early must still have read it.
+    '## What this letter does not establish',
+    '',
+    ...model.limitations.map((l) => `- ${l}`),
+    '',
+    '## Scope tested',
+    '',
+    ...snapshot.run.coverage.paths.map((p) => `- \`${cell(p)}\``),
+    '',
+  ];
+}
+
+/**
+ * Renders a snapshot as Markdown.
+ *
+ * The Penetration Test report gives every issue in full with its evidence; the
+ * Vulnerability Assessment tabulates the same issues; the Executive Summary
+ * says what changed and what it means without technical detail; the Attestation
+ * Letter states formally that testing was carried out, and states what it does
+ * not establish as prominently as what it found. **They are presentations of one
+ * snapshot** — any difference in substance would be a bug.
+ *
+ * Deterministic: the same snapshot and the same `now` produce byte-identical
+ * output, which is what lets a report be compared with the copy somebody was
+ * sent, and what makes golden-file testing meaningful.
+ *
+ * @param snapshot - Issue state as of a run.
+ * @param options - Which report, attribution, and the render time.
+ * @returns The report as Markdown.
+ */
+export function renderMarkdown(snapshot: Snapshot, options: ReportOptions): string {
+  const model = buildReportModel(snapshot, options);
+  const { target } = snapshot;
+
+  const lines: string[] = [
+    `# ${model.title}`,
+    '',
+    `**${target.name}** — ${target.url}`,
+    '',
+    `| | |`,
+    `| --- | --- |`,
+    `| Generated | ${formatDate(model.generatedAt)} |`,
+    `| Run | ${snapshot.run.runId} (${snapshot.run.trigger}) |`,
+  ];
+  if (model.preparedFor !== undefined) lines.push(`| Prepared for | ${cell(model.preparedFor)} |`);
+  if (model.preparedBy !== undefined) lines.push(`| Prepared by | ${cell(model.preparedBy)} |`);
+  lines.push('');
+
+  // The Attestation Letter carries the basis, the scope and the counts itself,
+  // in the order a letter reads. Adding the report furniture on top would state
+  // each of them twice, and a formal document that repeats itself is one a
+  // reader stops trusting.
+  if (model.kind === 'attest') {
+    lines.push(...attestationBody(model), ...suppressedAppendix(snapshot), '');
+    return lines.join('\n');
+  }
+
+  lines.push('## Basis of testing', '', model.basis.statement, '');
+
+  lines.push(
+    '## Scope',
+    '',
+    `This report covers only what the run exercised: ${snapshot.run.coverage.paths
+      .map((p) => `\`${cell(p)}\``)
+      .join(', ')}.`,
+    'Anything outside that was not tested and is not described here.',
+    '',
+  );
+
+  lines.push(...changeSummary(model), '');
+
+  if (model.kind === 'exec') {
+    lines.push(...executiveBody(model), ...suppressedAppendix(snapshot), '');
+    return lines.join('\n');
+  }
+
+  if (model.kind === 'retest') {
+    lines.push(...retestBody(model), ...suppressedAppendix(snapshot), '');
+    return lines.join('\n');
+  }
+
+  if (model.sections.length === 0) {
+    lines.push('## Findings', '', '_No issues 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));
+    }
+  } else {
+    lines.push(
+      '## Findings',
+      '',
+      '| Issue | Severity | Location | Change | Days open | Remediation |',
+      '| --- | --- | --- | --- | --- | --- |',
+    );
+    for (const section of model.sections) {
+      for (const entry of section.issues) lines.push(issueRow(entry));
+    }
+    lines.push('');
+  }
+
+  if (model.resolved.length > 0) {
+    lines.push(
+      '## Resolved since the last run',
+      '',
+      `${model.resolved.length} issue${model.resolved.length === 1 ? '' : 's'} no longer detected by a run that covered ${model.resolved.length === 1 ? 'it' : 'them'}.`,
+      '',
+      '| Issue | Severity | Location | Open for |',
+      '| --- | --- | --- | --- |',
+      ...model.resolved.map(
+        (entry) =>
+          `| ${cell(entry.issue.title)} | ${entry.issue.effectiveSeverity} | \`${cell(entry.issue.location)}\` | ${entry.daysOpen} days |`,
+      ),
+      '',
+    );
+  }
+
+  lines.push(...suppressedAppendix(snapshot), '');
+  return lines.join('\n');
+}