@secureport/core 0.2.1 → 0.4.0

package/src/severity.ts

@@ -0,0 +1,250 @@
+/**
+ * How urgent an issue is.
+ *
+ * Five levels, ordered most to least urgent. `advisory` is the bottom of the
+ * scale rather than a separate "informational" category: it carries a weight of
+ * zero in the exposure score and no SLA, but it is still an issue, still
+ * tracked across runs, and still appears in reports.
+ *
+ * @see {@link SEVERITY_ORDER} for comparing two severities.
+ * @see {@link SEVERITY_WEIGHTS} for the exposure-score weights.
+ */
+export type Severity = 'critical' | 'high' | 'medium' | 'low' | 'advisory';
+
+/**
+ * Every {@link Severity}, most urgent first.
+ *
+ * Iteration order is part of the contract: report sections, severity
+ * breakdowns and count tables all render in this order, so a reader sees the
+ * same shape everywhere.
+ */
+export const SEVERITY_ORDER = ['critical', 'high', 'medium', 'low', 'advisory'] as const;
+
+/**
+ * Rank of a {@link Severity}, where a **higher number is more urgent**.
+ *
+ * Use this to compare severities rather than comparing the strings, which sort
+ * alphabetically and would put `advisory` above `critical`.
+ *
+ * @param severity - The severity to rank.
+ * @returns `4` for `critical` down to `0` for `advisory`.
+ *
+ * @example
+ * ```ts
+ * severityRank(finding.detectedSeverity) > severityRank(issue.severityAtIgnore);
+ * ```
+ */
+export function severityRank(severity: Severity): number {
+  return SEVERITY_ORDER.length - 1 - SEVERITY_ORDER.indexOf(severity);
+}
+
+/**
+ * Exposure-score weight for each {@link Severity}.
+ *
+ * `exposure_score = Σ over open issues of weight × min(daysOpen, 90)`.
+ *
+ * `advisory` weighs nothing, so advisories never inflate the number — they are
+ * tracked and reported, but they do not represent exposure.
+ *
+ * These weights are **placeholders** until ten design partners have looked at
+ * the number, and are stated as such in `00-DOMAIN.md` §8. Treat a change to
+ * them as a change to a published contract.
+ */
+export const SEVERITY_WEIGHTS: Readonly<Record<Severity, number>> = Object.freeze({
+  critical: 10,
+  high: 5,
+  medium: 2,
+  low: 1,
+  advisory: 0,
+});
+
+/**
+ * Why a finding was given the severity it has.
+ *
+ * Recorded on every finding because auditors ask, and because a severity with
+ * no provenance is not evidence. Listed here in precedence order — an earlier
+ * source wins over a later one:
+ *
+ * 1. `explicit` — stated by the scanner or the operator for this exact finding.
+ * 2. `cvss` — derived from a CVSS base score via {@link severityFromCvss}.
+ * 3. `engine_default` — the engine's own rating for the rule that fired.
+ * 4. `advisory` — taken from a published advisory for the associated CVE.
+ *
+ * Note the unfortunate collision: `advisory` is both the lowest
+ * {@link Severity} and the least-preferred severity *source*. They are
+ * unrelated — a finding can be `critical` from an `advisory` source. The names
+ * come from `00-DOMAIN.md` §3 and are kept so code and document agree.
+ */
+export type SeveritySource = 'explicit' | 'cvss' | 'engine_default' | 'advisory';
+
+/**
+ * Every {@link SeveritySource}, most authoritative first.
+ *
+ * The order is the precedence rule: when two sources offer a severity for the
+ * same finding, the one appearing earlier here wins.
+ */
+export const SEVERITY_SOURCE_PRECEDENCE = [
+  'explicit',
+  'cvss',
+  'engine_default',
+  'advisory',
+] as const;
+
+/**
+ * Maps a CVSS base score to a {@link Severity}.
+ *
+ * Uses the CVSS v3.1 qualitative severity rating scale unchanged, so a score
+ * rated "High" by any other tool is rated `high` here. The one adaptation is
+ * at the bottom: CVSS calls `0.0` "None", and this model has no "none", so it
+ * becomes `advisory`.
+ *
+ * | CVSS score  | CVSS rating | {@link Severity} |
+ * | ----------- | ----------- | ---------------- |
+ * | 9.0 – 10.0  | Critical    | `critical`       |
+ * | 7.0 – 8.9   | High        | `high`           |
+ * | 4.0 – 6.9   | Medium      | `medium`         |
+ * | 0.1 – 3.9   | Low         | `low`            |
+ * | 0.0         | None        | `advisory`       |
+ *
+ * @param score - A CVSS base score between 0 and 10.
+ * @returns The corresponding severity.
+ * @throws RangeError If `score` is outside 0–10 or is not a number. A score
+ * that cannot be mapped is a data problem worth surfacing, not something to
+ * silently round into `advisory`.
+ *
+ * @example
+ * ```ts
+ * severityFromCvss(9.8); // 'critical'
+ * severityFromCvss(0);   // 'advisory'
+ * ```
+ */
+export function severityFromCvss(score: number): Severity {
+  if (!Number.isFinite(score) || score < 0 || score > 10) {
+    throw new RangeError(`CVSS score must be between 0 and 10, received ${String(score)}`);
+  }
+  if (score >= 9) return 'critical';
+  if (score >= 7) return 'high';
+  if (score >= 4) return 'medium';
+  if (score > 0) return 'low';
+  return 'advisory';
+}
+
+/**
+ * How long each severity may stay open before it breaches, and how long before
+ * breaching an issue starts warning.
+ *
+ * A policy rather than a constant because remediation windows are a customer
+ * agreement, not a property of the domain: a payments company and a hobby
+ * project do not owe the same turnaround on a `high`.
+ *
+ * @see {@link DEFAULT_SLA_POLICY} for the shipped default.
+ */
+export interface SlaPolicy {
+  /**
+   * Days allowed to remediate an issue of each severity, from `firstSeen`.
+   *
+   * `null` means no deadline applies — the issue is tracked and reported, but
+   * it can never be "due" or "breached". `advisory` is `null` by default.
+   */
+  readonly durationDays: Readonly<Record<Severity, number | null>>;
+
+  /**
+   * How many days before the deadline an issue starts reporting `due_soon`.
+   *
+   * Exists so a report can distinguish "you have time" from "this is about to
+   * breach" without the reader doing arithmetic.
+   */
+  readonly dueSoonDays: number;
+}
+
+/**
+ * The default remediation windows.
+ *
+ * Chosen to be defensible rather than derived: they line up with the windows
+ * most vulnerability-management programmes already run, so a customer can
+ * adopt them without an argument and override them without a migration.
+ *
+ * `advisory` has no deadline at all. Giving a zero-weight severity a due date
+ * would manufacture breaches out of things nobody agreed to fix.
+ *
+ * | Severity   | Window   |
+ * | ---------- | -------- |
+ * | `critical` | 7 days   |
+ * | `high`     | 30 days  |
+ * | `medium`   | 90 days  |
+ * | `low`      | 180 days |
+ * | `advisory` | none     |
+ *
+ * **These are defaults, not the domain.** `00-DOMAIN.md` says only that
+ * `sla_due_at` is "derived from effective severity"; the numbers are this
+ * package's opinion and are meant to be replaced by an org's own policy.
+ */
+export const DEFAULT_SLA_POLICY: SlaPolicy = Object.freeze({
+  durationDays: Object.freeze({
+    critical: 7,
+    high: 30,
+    medium: 90,
+    low: 180,
+    advisory: null,
+  }),
+  dueSoonDays: 7,
+});
+
+/**
+ * Where an issue stands against its remediation deadline.
+ *
+ * - `within` — inside the window, and not close enough to warn about.
+ * - `due_soon` — inside the window but within {@link SlaPolicy.dueSoonDays}.
+ * - `breached` — past the deadline.
+ *
+ * An issue with no deadline (see {@link DEFAULT_SLA_POLICY}) is always
+ * `within`: it cannot breach something it was never given.
+ */
+export type SlaStatus = 'within' | 'due_soon' | 'breached';
+
+/**
+ * When an issue of this severity, first seen at this moment, is due.
+ *
+ * Pure: the deadline is computed from the arguments alone, so the same inputs
+ * always give the same answer and a test needs no control over the clock.
+ *
+ * @param severity - The issue's **effective** severity, not its detected one —
+ * an override is a deliberate statement about how urgent something is, and the
+ * deadline should follow it.
+ * @param firstSeen - When the issue was first seen. Never the current run:
+ * `first_seen` is never reset, so neither is the deadline (invariant 4).
+ * @param policy - The remediation windows to apply.
+ * @returns The deadline, or `null` where the severity has no window.
+ */
+export function slaDueAt(
+  severity: Severity,
+  firstSeen: Date,
+  policy: SlaPolicy = DEFAULT_SLA_POLICY,
+): Date | null {
+  const days = policy.durationDays[severity];
+  if (days === null) return null;
+  return new Date(firstSeen.getTime() + days * 24 * 60 * 60 * 1000);
+}
+
+/**
+ * Where an issue stands against a deadline, as of a given moment.
+ *
+ * Pure, and takes `now` explicitly rather than reading the clock, so a report
+ * rendered for a past run reports the status *as of that run* rather than as of
+ * today.
+ *
+ * @param dueAt - The deadline from {@link slaDueAt}, or `null` for no deadline.
+ * @param now - The moment to evaluate against.
+ * @param policy - Supplies the `due_soon` window.
+ * @returns The status. Always `within` when `dueAt` is `null`.
+ */
+export function slaStatus(
+  dueAt: Date | null,
+  now: Date,
+  policy: SlaPolicy = DEFAULT_SLA_POLICY,
+): SlaStatus {
+  if (dueAt === null) return 'within';
+  if (now.getTime() > dueAt.getTime()) return 'breached';
+  const warnFrom = dueAt.getTime() - policy.dueSoonDays * 24 * 60 * 60 * 1000;
+  return now.getTime() >= warnFrom ? 'due_soon' : 'within';
+}

package/src/snapshot-builder.ts

@@ -0,0 +1,225 @@
+import type { Finding } from './finding.js';
+import type { Issue } from './issue.js';
+import type { Run } from './run.js';
+import type { IssueChange, Snapshot, SnapshotIssue, SuppressedIssue, Target } from './snapshot.js';
+import { DEFAULT_SLA_POLICY, slaStatus, type SlaPolicy } from './severity.js';
+import { reconcile } from './reconcile.js';
+
+/**
+ * Everything needed to turn a run's findings into a report-ready snapshot.
+ */
+export interface BuildSnapshotInput {
+  /** The system under test. */
+  readonly target: Target;
+
+  /** The run being reported on. */
+  readonly run: Run;
+
+  /** The findings it produced. */
+  readonly findings: readonly Finding[];
+
+  /**
+   * The previous snapshot, if there is one.
+   *
+   * **This is what makes a retest work with no account and no database.** The
+   * prior snapshot carries the issues, so a second run can tell what is new,
+   * what is still open, what got fixed and what came back — from a JSON file on
+   * disk. Parse it with {@link parseSnapshot}.
+   */
+  readonly previous?: Snapshot;
+
+  /** The moment being reported at. */
+  readonly now: Date;
+
+  /** Supplies ids for issues and events. */
+  readonly newId: () => string;
+
+  /** Remediation windows. */
+  readonly slaPolicy?: SlaPolicy;
+
+  /** Consecutive covering misses before an issue resolves. */
+  readonly autoResolveThreshold?: number;
+
+  /** How long the run took. */
+  readonly durationMs?: number;
+}
+
+/**
+ * The key a finding and an issue share when they are the same issue.
+ *
+ * Mirrors the one reconciliation uses, including the version: a fingerprint
+ * means nothing without the algorithm that produced it. The separator is an
+ * escape rather than a literal control character — writing it as a raw byte has
+ * now put an invisible NUL into two source files, and `scripts/check-text.sh`
+ * exists because nothing else noticed.
+ */
+function issueKey(of: {
+  readonly fingerprintVersion: string;
+  readonly fingerprint: string;
+}): string {
+  return `${of.fingerprintVersion}\u0000${of.fingerprint}`;
+}
+
+/** Whole days between two moments, floored. */
+function daysBetween(from: Date, to: Date): number {
+  return Math.max(0, Math.floor((to.getTime() - from.getTime()) / 86_400_000));
+}
+
+/**
+ * Builds the {@link Snapshot} a report renders from.
+ *
+ * Runs {@link reconcile} over the previous snapshot's issues and this run's
+ * findings, then works out what changed for each issue and precomputes the
+ * things a template would otherwise each derive slightly differently —
+ * `daysOpen`, `slaStatus`, and which findings are the evidence.
+ *
+ * **Two runs on disk are enough.** No account, no database: the previous
+ * snapshot is the state, and this function is the only thing that has to
+ * understand it. That is the whole bring-your-own-findings path.
+ *
+ * Suppressed issues are separated out into {@link Snapshot.suppressed} and do
+ * not appear in {@link Snapshot.issues}, so a template cannot count an accepted
+ * risk as an open one (invariant 7).
+ *
+ * @param input - The run, its findings, and optionally the previous snapshot.
+ * @returns A snapshot, ready to render.
+ */
+export function buildSnapshot(input: BuildSnapshotInput): Snapshot {
+  const slaPolicy = input.slaPolicy ?? DEFAULT_SLA_POLICY;
+
+  const priorIssues: Issue[] = [
+    ...(input.previous?.issues.map((i) => i.issue) ?? []),
+    ...(input.previous?.suppressed.map((s) => s.issue) ?? []),
+  ];
+  const priorById = new Map(priorIssues.map((i) => [i.id, i]));
+
+  const { issues, summary } = reconcile({
+    issues: priorIssues,
+    findings: input.findings,
+    run: input.run,
+    now: input.now,
+    newId: input.newId,
+    slaPolicy,
+    ...(input.autoResolveThreshold === undefined
+      ? {}
+      : { autoResolveThreshold: input.autoResolveThreshold }),
+    ...(input.durationMs === undefined ? {} : { durationMs: input.durationMs }),
+  });
+
+  // Evidence, grouped by the issue it belongs to.
+  const byFingerprint = new Map<string, Finding[]>();
+  for (const finding of input.findings) {
+    const key = issueKey(finding);
+    const existing = byFingerprint.get(key);
+    if (existing) existing.push(finding);
+    else byFingerprint.set(key, [finding]);
+  }
+
+  const reported: SnapshotIssue[] = [];
+  const suppressed: SuppressedIssue[] = [];
+
+  for (const issue of issues) {
+    if (issue.status === 'ignored') {
+      suppressed.push({
+        issue,
+        reason: issue.ignoreReason ?? 'accepted_risk',
+        comment: issue.ignoreComment ?? '',
+        ignoredBy: issue.ignoredBy ?? 'unknown',
+        ignoredAt: issue.lastSeen,
+        ...(issue.ignoreExpiresAt === undefined ? {} : { expiresAt: issue.ignoreExpiresAt }),
+        severityAtIgnore: issue.severityAtIgnore ?? issue.effectiveSeverity,
+      });
+      continue;
+    }
+
+    const prior = priorById.get(issue.id);
+    let change: IssueChange;
+    if (prior === undefined) change = 'new';
+    else if (issue.status === 'resolved') change = 'resolved';
+    else if (issue.status === 'regressed' && prior.status !== 'regressed') change = 'regressed';
+    else change = 'still_open';
+
+    reported.push({
+      issue,
+      change,
+      // From firstSeen, which is never reset, so a regression does not make a
+      // year-old problem look new.
+      daysOpen: daysBetween(issue.firstSeen, input.now),
+      slaStatus: slaStatus(issue.slaDueAt ?? null, input.now, slaPolicy),
+      findings: byFingerprint.get(issueKey(issue)) ?? [],
+    });
+  }
+
+  return {
+    run: summary,
+    ...(input.previous === undefined ? {} : { baseline: input.previous.run }),
+    target: input.target,
+    issues: reported,
+    suppressed,
+  };
+}
+
+/** Every field in the snapshot tree that JSON turns into a string. */
+const DATE_FIELDS = new Set([
+  'createdAt',
+  'firstSeen',
+  'lastSeen',
+  'resolvedAt',
+  'reopenedAt',
+  'slaDueAt',
+  'severityOverriddenAt',
+  'ignoreExpiresAt',
+  'ignoredAt',
+  'startedAt',
+  'finishedAt',
+]);
+
+/**
+ * Parses a snapshot written to disk, restoring the `Date` objects JSON lost.
+ *
+ * `JSON.stringify` turns every date into a string and `JSON.parse` leaves it as
+ * one, so a snapshot round-tripped through a file is **not** a `Snapshot` — its
+ * dates are strings wearing the type. Everything that then compares or
+ * subtracts them silently produces nonsense rather than failing.
+ *
+ * Use this rather than `JSON.parse` for any snapshot read back from disk.
+ *
+ * **It checks the shape, because this is where untrusted JSON enters.** A
+ * snapshot arrives from a file somebody chose, and the signature promises a
+ * `Snapshot` — so returning whatever parsed and letting the caller discover
+ * the difference is the function lying about its own return type. The check is
+ * deliberately shallow: the top-level shape, which is enough to tell a
+ * snapshot from any other JSON document and to make the failure say so.
+ *
+ * @param json - The contents of a snapshot file.
+ * @returns The snapshot, with dates revived.
+ * @throws SyntaxError If the text is not valid JSON.
+ * @throws TypeError If the JSON parsed but is not a snapshot.
+ */
+export function parseSnapshot(json: string): Snapshot {
+  const parsed: unknown = JSON.parse(json, (key, value: unknown) => {
+    if (DATE_FIELDS.has(key) && typeof value === 'string') {
+      const parsed = new Date(value);
+      if (!Number.isNaN(parsed.getTime())) return parsed;
+    }
+    return value;
+  });
+
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new TypeError('not a snapshot: expected a JSON object');
+  }
+  const record = parsed as Record<string, unknown>;
+  for (const field of ['run', 'target'] as const) {
+    const value = record[field];
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+      throw new TypeError(`not a snapshot: \`${field}\` is missing`);
+    }
+  }
+  for (const field of ['issues', 'suppressed'] as const) {
+    if (!Array.isArray(record[field])) {
+      throw new TypeError(`not a snapshot: \`${field}\` is missing`);
+    }
+  }
+
+  return parsed as Snapshot;
+}

package/src/snapshot.ts

@@ -0,0 +1,146 @@
+import type { Finding } from './finding.js';
+import type { IgnoreReason, Issue } from './issue.js';
+import type { RunSummary } from './run.js';
+import type { Severity, SlaStatus } from './severity.js';
+
+/**
+ * A system under test.
+ *
+ * Targets are the unit of authorisation as well as of organisation: staging,
+ * production and dev are separate targets with separate tokens and separate
+ * verification states.
+ */
+export interface Target {
+  /** Unique id. */
+  readonly id: string;
+
+  /** Organisation it belongs to. */
+  readonly orgId: string;
+
+  /** Human-readable name, as it appears on a report cover. */
+  readonly name: string;
+
+  /** What is being tested — a URL, host or repository. */
+  readonly url: string;
+}
+
+/**
+ * What happened to an issue between the baseline and this run.
+ *
+ * This is the axis every report opens on, because it is the question a reader
+ * actually has: not "what is wrong" but "what changed since last time".
+ */
+export type IssueChange = 'new' | 'still_open' | 'regressed' | 'resolved' | 'ignored';
+
+/**
+ * An issue as a report sees it: its own state, plus everything a template
+ * would otherwise have to compute.
+ *
+ * The derived fields are computed once, when the snapshot is built, so that
+ * five report templates in three formats cannot each work out `daysOpen`
+ * slightly differently.
+ */
+export interface SnapshotIssue {
+  /** The issue itself. */
+  readonly issue: Issue;
+
+  /** What happened to it relative to the baseline. */
+  readonly change: IssueChange;
+
+  /**
+   * Whole days between `firstSeen` and the run this snapshot is for.
+   *
+   * Measured from `firstSeen`, which is never reset, so a regression does not
+   * make a year-old problem look new.
+   */
+  readonly daysOpen: number;
+
+  /** Where it stands against its remediation deadline, as of this run. */
+  readonly slaStatus: SlaStatus;
+
+  /**
+   * The evidence behind it.
+   *
+   * Findings from this run, and from earlier ones where the report shows
+   * history. This is what makes a report checkable rather than merely
+   * assertive.
+   */
+  readonly findings: readonly Finding[];
+}
+
+/**
+ * A suppressed issue, as the appendix shows it.
+ *
+ * Deliberately its own shape rather than a flag on {@link SnapshotIssue}: the
+ * suppressed appendix answers a different question — not "what is wrong" but
+ * "what did you decide not to fix, and who decided it".
+ *
+ * **Every report carries this appendix, on by default.** It is an
+ * accepted-risk register, which is exactly what an auditor asks for, and
+ * hiding it would be both less useful and less honest.
+ */
+export interface SuppressedIssue {
+  /** The issue itself. */
+  readonly issue: Issue;
+
+  /** Why it was suppressed. */
+  readonly reason: IgnoreReason;
+
+  /** The justification given at the time. */
+  readonly comment: string;
+
+  /** Who suppressed it. */
+  readonly ignoredBy: string;
+
+  /** When. */
+  readonly ignoredAt: Date;
+
+  /** When the suppression lapses, if it does. */
+  readonly expiresAt?: Date;
+
+  /** Detected severity at the moment it was suppressed. */
+  readonly severityAtIgnore: Severity;
+}
+
+/**
+ * Issue state as of a run, plus a baseline to compare against.
+ *
+ * **The report engine's only input.** Every template consumes a `Snapshot` and
+ * nothing else — no database handle, no network, no clock. That is what makes
+ * a report reproducible, testable against golden files, and renderable by a
+ * third party who has findings on disk and no account.
+ *
+ * **The snapshot is the artefact; a PDF is a view of it.** Reports are rendered
+ * on demand and never stored (invariant 12). Snapshots are small, deterministic
+ * JSON, so caching one is cheap where storing a rendered document would buy
+ * retention policy, signed-URL expiry, encryption review and a deletion
+ * obligation in exchange for saving a render.
+ */
+export interface Snapshot {
+  /** The run this snapshot describes. */
+  readonly run: RunSummary;
+
+  /**
+   * What to compare against.
+   *
+   * The previous run for an ordinary report, or a specific named run for a
+   * retest. Absent for a first run, where there is nothing to compare to and
+   * every issue is `new`.
+   */
+  readonly baseline?: RunSummary;
+
+  /** The system under test. */
+  readonly target: Target;
+
+  /**
+   * Every issue in scope, with what changed and the evidence for it.
+   *
+   * Excludes suppressed issues, which appear in {@link Snapshot.suppressed}
+   * instead — the two lists are disjoint by construction so a template cannot
+   * accidentally count an accepted risk as an open one.
+   */
+  readonly issues: readonly SnapshotIssue[];
+
+  /** The accepted-risk register. */
+  readonly suppressed: readonly SuppressedIssue[];
+}