@secureport/core 2.1.0 → 2.3.0

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 '}}}]}';
+}