@secureport/core 2.2.0 → 2.3.0

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/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,

package/src/report/markdown.ts

@@ -16,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, ' ');
 }
 
@@ -54,8 +60,14 @@ function changeSummary(model: ReportModel): string[] {
   ];
 }
 
-/** One issue, in full. The Penetration Test presentation. */
-function issueDetail(entry: SnapshotIssue, verbosity: EvidenceVerbosity): 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}`,
@@ -142,8 +154,12 @@ function evidenceLine(finding: Finding): string {
   return `${where} — ${detail.join('; ')}`;
 }
 
-/** One issue, as a table row. The Vulnerability Assessment presentation. */
-function issueRow(entry: SnapshotIssue): string {
+/**
+ * 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})`;

package/src/report/model.ts

@@ -1,4 +1,4 @@
-import type { RunSummary } from '../run.js';
+import type { RunKind, RunSummary } from '../run.js';
 import type { Severity } from '../severity.js';
 import { SEVERITY_ORDER } from '../severity.js';
 import type { Snapshot, SnapshotIssue } from '../snapshot.js';
@@ -534,18 +534,31 @@ function describeRetest(snapshot: Snapshot): RetestOutcome | undefined {
  * an issue left open because the run never covered it looks identical to one
  * left open because the run found it again, and telling a reader those are the
  * same thing is the failure this report exists to avoid.
+ *
+ * Exported: it is per-issue and needs nothing but the one entry, which is
+ * exactly what the streaming machine renderers can offer it a row at a time.
  */
-function verdictFor(entry: SnapshotIssue): RetestVerdict {
+export function verdictFor(entry: SnapshotIssue): RetestVerdict {
   if (entry.change === 'resolved') return 'fixed';
   if (entry.change === 'regressed') return 'returned';
   if (entry.change === 'new') return 'new';
   return entry.findings.length > 0 ? 'still_present' : 'not_retested';
 }
 
-/** Works out what a report cannot establish, from the run rather than a template. */
-function describeLimitations(
-  snapshot: Snapshot,
+/**
+ * Works out what a report cannot establish, from the run rather than a
+ * template.
+ *
+ * Takes primitives rather than a {@link Snapshot} so the streaming machine
+ * renderers can produce the same wording from a fold over a cursor, without
+ * needing the eagerly-materialised issue array this package's PDF/HTML path
+ * builds.
+ */
+export function describeLimitations(
+  coveragePaths: readonly string[],
+  runCreatedAt: Date,
   basis: TestingBasis,
+  suppressedCount: number,
   omitted: OmittedIssues | undefined,
 ): string[] {
   const limitations: string[] = [];
@@ -561,11 +574,11 @@ function describeLimitations(
       'upon as audit evidence.',
   );
   limitations.push(
-    `Testing covered only ${snapshot.run.coverage.paths.join(', ')}. Anything outside that ` +
+    `Testing covered only ${coveragePaths.join(', ')}. Anything outside that ` +
       'was not examined, and its absence from this document is not evidence that it is sound.',
   );
   limitations.push(
-    `This reflects the state of the target as of ${snapshot.run.createdAt
+    `This reflects the state of the target as of ${runCreatedAt
       .toISOString()
       .slice(0, 10)}. It says nothing about the target before or after that date.`,
   );
@@ -573,9 +586,9 @@ function describeLimitations(
     'Automated testing cannot establish the absence of a vulnerability. A clean result means ' +
       'nothing was detected, not that nothing is there.',
   );
-  if (snapshot.suppressed.length > 0) {
+  if (suppressedCount > 0) {
     limitations.push(
-      `${snapshot.suppressed.length} finding${snapshot.suppressed.length === 1 ? ' has' : 's have'} been ` +
+      `${suppressedCount} finding${suppressedCount === 1 ? ' has' : 's have'} been ` +
         'suppressed and excluded from the counts above. They are listed in full in the appendix.',
     );
   }
@@ -597,7 +610,74 @@ function describeLimitations(
  */
 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({
+/**
+ * Why this branding cannot be rendered, or `undefined` if it can.
+ *
+ * **Exported so the rules have one home rather than two.** {@link buildReportModel}
+ * enforces these at render time, which is the last possible moment — by then the
+ * value has been stored, and the caller who set it is long gone. A hosted
+ * service wants to refuse it at the boundary instead, with a `400` naming the
+ * field. That needs the same two rules in two places, and a colour pattern
+ * copied into an API schema is a copy free to drift from the one that actually
+ * protects the stylesheet.
+ *
+ * So both callers ask this. The messages are identical wherever the value is
+ * rejected, because there is only one place that composes them.
+ *
+ * The white-label rule is deliberately **not** here: it depends on the report
+ * kind and on `preparedBy`, so it is a property of the options rather than of
+ * the branding, and only the renderer can decide it.
+ */
+export function brandingProblem(branding: Branding | undefined): string | undefined {
+  const colour = branding?.primaryColour;
+  if (colour !== undefined && !HEX_COLOUR.test(colour)) {
+    return (
+      `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/')) {
+    return (
+      `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'
+    );
+  }
+
+  return undefined;
+}
+
+/**
+ * Who the document says carried out the testing, resolved once so the PDF/HTML
+ * path and the streaming machine path cannot word it two different ways.
+ *
+ * @throws TypeError A white-labelled attestation naming nobody: a formal
+ *   statement that testing was carried out has to say who carried it out.
+ */
+export function resolveAttestor(
+  options: Pick<ReportOptions, 'kind' | 'preparedBy' | 'branding'>,
+): string {
+  const attestor = options.preparedBy ?? options.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 &&
+    options.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 attestor ?? 'Secureport';
+}
+
+/** The title printed when {@link ReportOptions.title} is not given. */
+export const DEFAULT_TITLES: Readonly<Record<ReportKind, string>> = Object.freeze({
   pen: 'Penetration Test Report',
   vap: 'Vulnerability Assessment Report',
   exec: 'Executive Summary',
@@ -605,11 +685,19 @@ const DEFAULT_TITLES: Readonly<Record<ReportKind, string>> = Object.freeze({
   retest: 'Retest Report',
 });
 
-/** Works out how the findings were produced, from the run rather than a claim. */
-function describeBasis(snapshot: Snapshot): TestingBasis {
-  const kind = snapshot.run.kind;
-  const engines = snapshot.run.engines;
-  const includesManual = snapshot.issues.some((i) => i.issue.origin === 'manual');
+/**
+ * Works out how the findings were produced, from the run rather than a claim.
+ *
+ * Takes `kind`/`engines`/`includesManual` as primitives, the same reason
+ * {@link describeLimitations} does: the streaming machine renderers know
+ * `includesManual` only once a fold over the issue cursor finishes, and have
+ * no `Snapshot` to read `run.kind`/`run.engines` from.
+ */
+export function describeBasis(
+  kind: RunKind,
+  engines: readonly string[],
+  includesManual: boolean,
+): TestingBasis {
   const automated = kind === 'scan';
   const uploaded = kind === 'upload';
 
@@ -733,7 +821,11 @@ export function buildReportModel(snapshot: Snapshot, options: ReportOptions): Re
         };
 
   const outstandingTotal = SEVERITY_ORDER.reduce((sum, s) => sum + outstanding[s], 0);
-  const basis = describeBasis(snapshot);
+  const basis = describeBasis(
+    snapshot.run.kind,
+    snapshot.run.engines,
+    snapshot.issues.some((i) => i.issue.origin === 'manual'),
+  );
   const retest = describeRetest(snapshot);
 
   // Rendering a retest of nothing is the over-claim §7 warns about: the
@@ -745,33 +837,10 @@ 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 problem = brandingProblem(branding);
+  if (problem !== undefined) throw new TypeError(problem);
 
-  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',
-    );
-  }
+  const attestor = resolveAttestor(options);
 
   return {
     kind: options.kind,
@@ -780,13 +849,19 @@ 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',
+    attestor,
     coverPage: options.coverPage === true,
     tableOfContents: options.tableOfContents === true,
     ...(branding === undefined ? {} : { branding }),
     basis,
     evidenceVerbosity: options.evidenceVerbosity ?? 'summary',
-    limitations: describeLimitations(snapshot, basis, omitted),
+    limitations: describeLimitations(
+      snapshot.run.coverage.paths,
+      snapshot.run.createdAt,
+      basis,
+      snapshot.suppressed.length,
+      omitted,
+    ),
     sections,
     resolved: options.includeResolved === false ? [] : resolved,
     ...(omitted === undefined ? {} : { omitted }),

package/src/report/sarif.ts

@@ -0,0 +1,166 @@
+import type { Severity } from '../severity.js';
+import type { SnapshotIssue } from '../snapshot.js';
+import type { ReportHeader } from './stream.js';
+
+/**
+ * What a SARIF export can be asked for.
+ *
+ * Deliberately its own type rather than {@link ReportOptions}: SARIF has no
+ * `kind` — it is always "the issues open right now", never a retest or an
+ * attestation — and no branding, cover page or evidence verbosity. Accepting
+ * `ReportOptions` and silently ignoring most of its fields would be a worse
+ * API than a type that only offers what SARIF actually uses.
+ */
+export interface SarifOptions {
+  /**
+   * Keep issues below this severity out of `results`.
+   *
+   * Unlike the other formats, there is no `omitted` count to report: SARIF
+   * has no prose to carry a disclosure sentence in, and a consumer asking
+   * for `critical` only is asking to scope a code-scanning feed, not
+   * reading a document that owes it an explanation of what it left out.
+   */
+  readonly severityFloor?: Severity;
+}
+
+/** SARIF's four severity levels, from the SARIF 2.1.0 spec §3.27.10. */
+type SarifLevel = 'error' | 'warning' | 'note' | 'none';
+
+const SARIF_LEVEL: Readonly<Record<Severity, SarifLevel>> = Object.freeze({
+  critical: 'error',
+  high: 'error',
+  medium: 'warning',
+  low: 'note',
+  advisory: 'note',
+});
+
+/**
+ * The `security-severity` GitHub code scanning reads to rank an alert, as a
+ * string 0.0–10.0 — GitHub's convention, not part of the SARIF spec itself.
+ * Fixed bands rather than a CVSS score, because not every finding has one
+ * and two issues at the same {@link Severity} should rank the same.
+ */
+const SECURITY_SEVERITY: Readonly<Record<Severity, string>> = Object.freeze({
+  critical: '9.0',
+  high: '7.5',
+  medium: '5.0',
+  low: '3.0',
+  advisory: '1.0',
+});
+
+/** `SEVERITY_ORDER`, duplicated as an index rather than imported, to keep this file's only dependency on `severity.ts` the type. */
+const FLOOR_RANK: Readonly<Record<Severity, number>> = Object.freeze({
+  critical: 0,
+  high: 1,
+  medium: 2,
+  low: 3,
+  advisory: 4,
+});
+
+/** `"key":value`, run through `JSON.stringify` so nothing is hand-escaped. */
+function field(key: string, value: unknown): string {
+  return `${JSON.stringify(key)}:${JSON.stringify(value)}`;
+}
+
+/**
+ * Renders a snapshot's open issues as SARIF 2.1.0, from a header and a
+ * cursor — the machine path's format for GitHub code scanning (P8), and the
+ * streaming sibling of {@link renderJsonStream} and
+ * {@link renderMarkdownStream}. See {@link renderJsonStream} for the memory
+ * argument.
+ *
+ * **Resolved issues never appear, unconditionally — there is no
+ * `includeResolved` option.** SARIF is not a document a person reads; it is
+ * the input to GitHub's own diffing, which closes an alert when a new
+ * upload no longer contains it. Including a resolved issue would tell
+ * GitHub the finding is still open, which is the opposite of what resolving
+ * it meant.
+ *
+ * **Suppressed issues never appear either, and take no `suppressed`
+ * parameter at all.** An accepted risk is not a code-scanning alert; SARIF
+ * has no accepted-risk register to carry it in the way the appendix does
+ * for the human and other machine formats.
+ *
+ * **`ruleId` is `Issue.vulnKey`, not `Finding.sourceRuleId` or
+ * `sourceEngine`.** `vulnKey` is engine-independent by construction
+ * (`fingerprint.ts`), and naming a scanner in a customer-facing artefact is
+ * the thing this package's report options have twice had to stop doing
+ * (`ReportOptions.evidenceVerbosity`'s own TSDoc records it). `rules[]` is
+ * built from the same stream, deduplicated on `vulnKey` — bounded by the
+ * number of distinct weakness classes, not by issue count, so buffering it
+ * (unlike `results`) costs nothing worth avoiding.
+ *
+ * @param header - The run and the target. Never scales with issue count.
+ * @param issues - Every open issue, in any order — SARIF results are an
+ *   unordered set, so this format is the one place in the streaming
+ *   contract with no ordering requirement on its input.
+ * @param options - A severity floor, and nothing else.
+ * @returns Chunks of JSON text; concatenated, they are one SARIF document.
+ */
+export async function* renderSarifStream(
+  header: ReportHeader,
+  issues: AsyncIterable<SnapshotIssue>,
+  options: SarifOptions = {},
+): AsyncGenerator<string> {
+  const floor = options.severityFloor;
+  const floorAt = floor === undefined ? 4 : FLOOR_RANK[floor];
+  // Small — bounded by distinct weakness classes, not by issue count — and
+  // known only once the stream is exhausted. So `results` (the one array
+  // that must never be buffered) is written first and `tool.driver.rules`
+  // last, the one key order that lets both be true without a second pass
+  // over `issues`: JSON does not care which key comes first.
+  const rules = new Map<string, { readonly title: string; readonly cwe: string | undefined }>();
+
+  yield '{';
+  // The schema's own `id`, not a GitHub raw link — checked by hand, because
+  // an unreachable $schema is a broken document a validator would still call
+  // valid, and getting it wrong once cost the trip to the OASIS repo to
+  // learn its real path (`tests/fixtures/README.md` records that trip).
+  yield field(
+    '$schema',
+    'https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/schemas/sarif-schema-2.1.0.json',
+  );
+  yield ',' + field('version', '2.1.0');
+  yield ',"runs":[{"results":[';
+
+  let firstResult = true;
+  for await (const entry of issues) {
+    const { issue } = entry;
+    if (issue.status === 'resolved') continue;
+    if (FLOOR_RANK[issue.effectiveSeverity] > floorAt) continue;
+
+    if (!rules.has(issue.vulnKey)) {
+      rules.set(issue.vulnKey, { title: issue.title, cwe: issue.cwe });
+    }
+
+    const message = entry.findings[0]?.description ?? issue.title;
+    const result = {
+      ruleId: issue.vulnKey,
+      level: SARIF_LEVEL[issue.effectiveSeverity],
+      message: { text: message },
+      locations: [
+        {
+          physicalLocation: {
+            artifactLocation: { uri: issue.location },
+          },
+        },
+      ],
+      partialFingerprints: { secureportFingerprint: issue.fingerprint },
+      properties: { 'security-severity': SECURITY_SEVERITY[issue.effectiveSeverity] },
+    };
+    yield (firstResult ? '' : ',') + JSON.stringify(result);
+    firstResult = false;
+  }
+  yield ']';
+
+  const ruleDefs = [...rules.entries()].map(([vulnKey, rule]) => ({
+    id: vulnKey,
+    shortDescription: { text: rule.title },
+    ...(rule.cwe === undefined ? {} : { properties: { tags: [rule.cwe] } }),
+  }));
+  yield ',"tool":{"driver":{';
+  yield field('name', 'Secureport');
+  yield ',' + field('informationUri', 'https://secureport.io/');
+  yield ',"rules":' + JSON.stringify(ruleDefs);
+  yield '}}}]}';
+}