@secureport/core 2.2.0 → 2.3.1

package/dist/report/sarif.js

@@ -0,0 +1,125 @@
+const SARIF_LEVEL = 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 = 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 = 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, value) {
+    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, issues, options = {}) {
+    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();
+    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 '}}}]}';
+}
+//# sourceMappingURL=sarif.js.map

package/dist/report/sarif.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sarif.js","sourceRoot":"","sources":["../../src/report/sarif.ts"],"names":[],"mappings":"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"}

package/dist/report/stream.d.ts

@@ -0,0 +1,119 @@
+import type { RunSummary } from '../run.js';
+import type { SnapshotIssue, SuppressedIssue, Target } from '../snapshot.js';
+import { type ReportOptions } from './model.js';
+/**
+ * Everything a streaming machine-readable report needs that is not per-issue.
+ *
+ * **Deliberately not a {@link Snapshot}.** A `Snapshot`'s `issues` and
+ * `suppressed` are eagerly-materialised arrays — the right shape for PDF and
+ * HTML, which are queued, capped at 500 issues, and fully in memory before
+ * Chromium ever runs. The machine formats have no such cap, so their
+ * assembler must never hold every issue at once; a `ReportHeader` carries
+ * only the handful of fields that do not scale with issue count, and the
+ * issues themselves arrive as an `AsyncIterable`.
+ */
+export interface ReportHeader {
+    /** The run this report describes. */
+    readonly run: RunSummary;
+    /** What to compare against, for a retest. Absent for a first run. */
+    readonly baseline?: RunSummary;
+    /** The system under test. */
+    readonly target: Target;
+}
+/**
+ * Renders a report as JSON, from a header and a cursor over its issues,
+ * rather than from a fully-assembled {@link Snapshot}.
+ *
+ * **This is the machine path's whole reason to exist (B124).** `renderJson`
+ * holds every issue in one array before `JSON.stringify` walks it — measured
+ * at 239 MiB for 25,000 issues — so memory scales with the result and three
+ * concurrent exports exhaust a 512 MiB instance. This function instead
+ * yields the document a fragment at a time: everything that does not depend
+ * on having seen every issue is emitted immediately, the `issues` and
+ * `suppressed` arrays are written one element per row as the cursors
+ * produce them, and the handful of fields that need a full pass —
+ * `basis.includesManual`, `breached`, `omitted`, the retest counts — are
+ * accumulated in a fold whose state is a few counters, never the issues
+ * themselves, and written once both cursors are exhausted. Concatenating
+ * every yielded chunk produces one JSON document; nothing here buffers it
+ * as a string first.
+ *
+ * **`sections` grouped by severity and the sorted `resolved` list do not
+ * exist here.** Both require holding the whole array to sort; this function
+ * instead trusts that `issues` and `suppressed` already arrive in the order
+ * the document should show them; a cursor-based caller supplies that with a
+ * SQL `ORDER BY`, not with an in-memory sort. `includeResolved` and
+ * `severityFloor` still apply, filtering rows out of the stream rather than
+ * out of an array.
+ *
+ * @param header - The run, its baseline, and the target. Never scales with
+ *   issue count.
+ * @param issues - Every issue in scope, most urgent first, in the order the
+ *   document should list them.
+ * @param suppressed - The accepted-risk register, in the order the appendix
+ *   should list it.
+ * @param options - Which report, attribution, and the render time.
+ * @returns Chunks of JSON text; concatenated, they are one document.
+ */
+export declare function renderJsonStream(header: ReportHeader, issues: AsyncIterable<SnapshotIssue>, suppressed: AsyncIterable<SuppressedIssue>, options: ReportOptions): AsyncGenerator<string>;
+/**
+ * Renders a report as Markdown, from a header and a cursor over its issues,
+ * rather than from a fully-assembled {@link Snapshot}. The streaming sibling
+ * of {@link renderJsonStream} — see it for the memory argument, which applies
+ * here identically: `renderMarkdown` holds every issue in one array before
+ * formatting any of it.
+ *
+ * **The document is reordered relative to `renderMarkdown`, and that is
+ * forced rather than stylistic.** The array-based renderer opens with "Basis
+ * of testing" and a "What changed" line naming how many issues are past
+ * their remediation deadline — both need to know something about *every*
+ * issue (`basis.includesManual`, `breached`) before the first line can be
+ * printed, which a forward-only stream cannot offer without buffering
+ * everything first. So this function prints what it already knows up front
+ * (title, scope, the New/Still open/Regressed/Resolved/Suppressed table,
+ * which all read straight off `RunSummary`) and moves everything that needs
+ * a full pass — the basis statement, the remediation-deadline count, what a
+ * severity floor omitted, the retest verdict counts, and what the report
+ * does not establish (B109) — into a closing `## Summary` section, written
+ * once both cursors are exhausted.
+ *
+ * **`sections` grouped by severity do not exist here**, for the reason given
+ * in {@link renderJsonStream}: `issues` and `suppressed` are trusted to
+ * already arrive in the order the document should show them. For a `pen`
+ * report that means a severity sub-heading appears whenever the incoming
+ * severity changes, without the issue count that heading carries in
+ * `renderMarkdown` — the count is not known until the section ends. A
+ * `retest` report's per-issue table has no severity floor applied to it,
+ * matching `renderMarkdown`: the whole point of that table is showing what
+ * happened to every issue carried into the retest, not a curated subset.
+ *
+ * **`attest` buffers its suppressed list; nothing else buffers issues.** An
+ * Attestation Letter states counts and names nobody's individual issue, so
+ * it folds the whole `issues` cursor for those counts without printing a
+ * row — but it also prints the suppressed appendix *after* that letter body,
+ * by which point the `suppressed` cursor would already be exhausted. Holding
+ * that one list (the accepted-risk register, ordinarily a minority of the
+ * total) is the one deliberate exception to "never hold more than a row".
+ *
+ * **"What this report does not establish" (B109) lands in the closing
+ * `## Summary` section, after the Suppressed findings table rather than
+ * before it as in `renderMarkdown`.** `describeLimitations` needs
+ * `state.suppressedCount`, complete only once the `suppressed` cursor is
+ * drained — and that drain, and the table it produces, happen earlier in
+ * this stream than the summary does. The array renderer has no such
+ * ordering constraint and keeps limitations immediately before the
+ * appendix; forcing the same document order here would mean buffering the
+ * suppressed rows a second time for no reason `renderJsonStream` needs to.
+ *
+ * @param header - The run, its baseline, and the target. Never scales with
+ *   issue count.
+ * @param issues - Every issue in scope, most urgent first: open/regressed
+ *   before resolved, each group by severity then most-recently-seen first —
+ *   the order the document lists them in.
+ * @param suppressed - The accepted-risk register, in the order the appendix
+ *   should list it.
+ * @param options - Which report, attribution, and the render time.
+ * @returns Chunks of Markdown text; concatenated, they are one document.
+ */
+export declare function renderMarkdownStream(header: ReportHeader, issues: AsyncIterable<SnapshotIssue>, suppressed: AsyncIterable<SuppressedIssue>, options: ReportOptions): AsyncGenerator<string>;
+//# sourceMappingURL=stream.d.ts.map

package/dist/report/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../src/report/stream.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAG5C,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAE7E,OAAO,EASL,KAAK,aAAa,EAEnB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;GAUG;AACH,MAAM,WAAW,YAAY;IAC3B,qCAAqC;IACrC,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IAEzB,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,CAAC,EAAE,UAAU,CAAC;IAE/B,6BAA6B;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAoED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAuB,gBAAgB,CACrC,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,aAAa,CAAC,aAAa,CAAC,EACpC,UAAU,EAAE,aAAa,CAAC,eAAe,CAAC,EAC1C,OAAO,EAAE,aAAa,GACrB,cAAc,CAAC,MAAM,CAAC,CAoGxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,wBAAuB,oBAAoB,CACzC,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,aAAa,CAAC,aAAa,CAAC,EACpC,UAAU,EAAE,aAAa,CAAC,eAAe,CAAC,EAC1C,OAAO,EAAE,aAAa,GACrB,cAAc,CAAC,MAAM,CAAC,CA2UxB"}