@secureport/core 1.0.0-rc.1 → 2.1.0

package/src/fingerprint.ts

@@ -13,7 +13,7 @@ import { createHash } from 'node:crypto';
  * If you are tempted to "just tweak" the normaliser, that is this constant's
  * job to prevent.
  */
-export const FINGERPRINT_VERSION = 'fp_v1';
+export const FINGERPRINT_VERSION = 'fp_v2';
 
 /** A path segment that is entirely digits, e.g. the `123` in `/orders/123`. */
 const NUMERIC_SEGMENT = /^\d+$/u;
@@ -80,10 +80,17 @@ function collapseSegment(segment: string): string {
  *   one issue into two.
  * - **Drops the fragment**, which the server never sees.
  *
- * Anything that is not a parseable absolute URL — a bare host, a file path, a
- * `host:port` pair from a network scan — is normalised as a path alone. That is
- * deliberate: refusing to fingerprint a non-HTTP finding would exclude whole
- * classes of scanner from the model.
+ * - **Reads `host:443` and `host:80` as the URL the port implies**, so a
+ *   network scanner's `app.example.com:443` and a web scanner's
+ *   `https://app.example.com/` are one endpoint (B102, `fp_v2`). Only those two
+ *   ports: any other is left alone rather than guessed at, because
+ *   `host:8443` could be TLS or plaintext and inventing a scheme to force a
+ *   match would assert something nobody measured.
+ *
+ * Anything else that is not a parseable absolute URL — a bare host, a file
+ * path — is normalised as a path alone. That is deliberate: refusing to
+ * fingerprint a non-HTTP finding would exclude whole classes of scanner from
+ * the model.
  *
  * @param location - Where the weakness was found.
  * @returns The normalised location.
@@ -107,7 +114,9 @@ export function normaliseLocation(location: string): string {
   // Not an absolute URL: normalise it as a bare path and stop. `new URL` would
   // otherwise turn `example.com/x` into the `example.com:` protocol.
   if (!url || url.protocol === '' || !url.host) {
-    return normalisePathOnly(trimmed);
+    const implied = impliedSchemeUrl(trimmed);
+    if (implied === undefined) return normalisePathOnly(trimmed);
+    url = implied;
   }
 
   // Not `decodeOnce` here: normalisePathOnly decodes, and decoding on the way
@@ -123,6 +132,32 @@ export function normaliseLocation(location: string): string {
   return `${url.protocol}//${url.host}${path}${query}`;
 }
 
+/**
+ * A bare `host:port` read as the URL its port implies, or `undefined`.
+ *
+ * **Only `:443` and `:80`, and that restraint is the point.** A network scanner
+ * reports `app.example.com:443` for the weakness a web scanner reports at
+ * `https://app.example.com/`, and those are one endpoint: 443 means TLS and an
+ * empty path means the root. Both are convention rather than guarantee, but
+ * they are conventions every scanner in this model already relies on, and
+ * leaving the two unmatched means a network scan and a web scan of one host
+ * can never agree about anything — which is the duplication P6 exists to
+ * remove (B102).
+ *
+ * Any other port is left alone rather than guessed at. `app.example.com:8443`
+ * could be TLS or plaintext, and inventing a scheme to make a match happen
+ * would be asserting something nobody measured.
+ */
+function impliedSchemeUrl(location: string): URL | undefined {
+  const match = /^([a-z0-9.\-_]+|\[[0-9a-f:]+\]):(443|80)$/iu.exec(location);
+  if (!match) return undefined;
+  try {
+    return new URL(`${match[2] === '443' ? 'https' : 'http'}://${location}`);
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Normalises a path with no scheme or host.
  */
@@ -197,6 +232,15 @@ export const VULN_KEY_MAP: Readonly<Record<string, string>> = Object.freeze({
   // the other stops the two agreeing, so these travel together.
   'nuclei:xss-reflected': 'xss-reflected',
   'nuclei:missing-hsts': 'hsts-missing',
+
+  // Burp and Nessus, added in `fp_v2`. Neither had a single entry, so both fell
+  // through to the CWE for every finding — which is worse than no table at all:
+  // ZAP and Nuclei keyed `hsts-missing` while Burp and Nessus keyed `CWE-319`
+  // for the same weakness, so half a table was actively splitting issues that a
+  // plain CWE fallback would have kept together.
+  'burp:5244160': 'xss-reflected',
+  'burp:6234880': 'hsts-missing',
+  'nessus:42822': 'hsts-missing',
 });
 
 /**
@@ -306,10 +350,32 @@ export interface FingerprintInput {
  * ```
  */
 export function fingerprint(input: FingerprintInput): string {
-  const tail = input.parameter ?? (input.port !== undefined ? String(input.port) : '');
-  const material = [input.targetId, input.vulnKey, normaliseLocation(input.location), tail].join(
-    '|',
-  );
+  // The port is no longer part of the tail. `normaliseLocation` now canonicalises
+  // a `host:port` location, so a non-default port is already in the location and
+  // a default one is deliberately absent from it — counting the port again here
+  // made a Nessus finding on 443 unable to match a web scanner's finding on the
+  // same endpoint. `import/nessus.ts` recorded this double-count as something
+  // that had to stay because removing it would force a re-fingerprint migration;
+  // `fp_v2` is that migration.
+  const tail = input.parameter ?? '';
+
+  // A named parameter makes the query string redundant: both describe the same
+  // input, and keeping the query too means a scanner that reports the parameter
+  // separately (Burp: `/search`, parameter `q`) can never match one that leaves
+  // it in the URL (ZAP: `/search?q=test`, parameter `q`). When no parameter is
+  // named the query names stay, because then they are the only thing
+  // distinguishing one page from another — and Nuclei never names a parameter,
+  // so dropping them unconditionally would merge `/view?id` with `/view?page`.
+  const location = normaliseLocation(input.location);
+  const addressed = input.parameter === undefined ? location : stripQuery(location);
+
+  const material = [input.targetId, input.vulnKey, addressed, tail].join('|');
 
   return createHash('sha256').update(material, 'utf8').digest('hex');
 }
+
+/** Everything before the `?` of an already-normalised location. */
+function stripQuery(location: string): string {
+  const at = location.indexOf('?');
+  return at === -1 ? location : location.slice(0, at);
+}

package/src/import/nessus.ts

@@ -24,16 +24,19 @@ const NESSUS_SEVERITY: Readonly<Record<string, Severity>> = Object.freeze({
  *
  * Nessus is host-oriented: every `ReportItem` hangs off a `ReportHost`, and the
  * port and protocol are attributes rather than part of a URL. The location is
- * assembled as `host:port`, which is **the only place the port survives** —
- * `00-DOMAIN.md` §3 defines no `port` on a finding, so anything not in the
- * location is lost. A network finding with no path still fingerprints
- * distinctly per service because the port is inside its location.
+ * assembled as `host:port`, so a network finding with no path still
+ * fingerprints distinctly per service.
  *
- * A consequence worth knowing: the fingerprint's last component is
- * `parameter ?? port ?? ''`, so a Nessus port is counted twice — once inside
- * the location and once as that component. Harmless, but it means a port
- * cannot be recovered from a finding except by parsing its location. Recorded
- * as backlog **B42**.
+ * The port is also recorded on {@link Finding.port} (**B42**), which is a
+ * record and nothing more. **The double-count is gone in `fp_v2`** (6.9c): the
+ * fingerprint's last component was `parameter ?? port ?? ''`, so a Nessus port
+ * was counted twice — once inside the location and once as that component —
+ * and this comment said it had to stay because removing it would force a
+ * re-fingerprint migration. 6.9b built that migration, so it went. The tail is
+ * now `parameter ?? ''`, and the port is carried by the location alone, which
+ * `normaliseLocation` canonicalises: `app.example.com:443` and
+ * `https://app.example.com/` are one endpoint (B102), and a non-default port
+ * stays in the location where it belongs.
  *
  * Severity comes from the CVSS v3 base score where Nessus supplies one, and from
  * its own numeric rating otherwise.
@@ -121,6 +124,7 @@ export function importNessus(xml: string, options: ImportOptions): Finding[] {
         vulnKey: key,
         ...(family === undefined ? {} : { category: family.toLowerCase() }),
         location,
+        ...(port === undefined ? {} : { port }),
         ...(childText(item, 'solution') === undefined
           ? {}
           : { recommendation: childText(item, 'solution')! }),

package/src/index.ts

@@ -16,6 +16,15 @@
 
 export type { Finding } from './finding.js';
 export type { FingerprintInput, VulnKeyInput } from './fingerprint.js';
+export type {
+  FingerprintAlgorithm,
+  IssuePlan,
+  IssueWithEvidence,
+  RefingerprintOutcome,
+  RefingerprintPlan,
+} from './refingerprint.js';
+export { currentAlgorithm, planRefingerprint } from './refingerprint.js';
+export { exposureOf } from './reconcile.js';
 export {
   FINGERPRINT_VERSION,
   PATH_PLACEHOLDER,
@@ -60,7 +69,15 @@ export type { JsonReport } from './report/json.js';
 export { renderJson } from './report/json.js';
 export type { ReconcileInput, ReconcileResult } from './reconcile.js';
 export { reconcile } from './reconcile.js';
-export type { Coverage, Run, RunKind, RunSummary, RunTrigger, SeverityCounts } from './run.js';
+export type {
+  Coverage,
+  Run,
+  RunKind,
+  RunStatus,
+  RunSummary,
+  RunTrigger,
+  SeverityCounts,
+} from './run.js';
 export type { IssueChange, Snapshot, SnapshotIssue, SuppressedIssue, Target } from './snapshot.js';
 export type { Severity, SeveritySource, SlaPolicy, SlaStatus } from './severity.js';
 export {

package/src/issue.ts

@@ -186,9 +186,15 @@ export interface Issue {
    * When remediation is due, derived from {@link Issue.effectiveSeverity}.
    *
    * Recomputed whenever the effective severity changes. `null` where the
-   * severity carries no deadline.
+   * severity carries no deadline — `advisory` under
+   * {@link DEFAULT_SLA_POLICY}.
+   *
+   * **Required, and nullable.** Two states, not three: reconciliation always
+   * computes this when it creates an issue, so "never computed" does not occur
+   * downstream and an optional field would describe a state nothing produces.
+   * One nullable column stores it exactly.
    */
-  readonly slaDueAt?: Date | null;
+  readonly slaDueAt: Date | null;
 }
 
 /**

package/src/reconcile.ts

@@ -146,6 +146,40 @@ function defaultThreshold(kind: RunKind): number {
   return kind === 'upload' ? 1 : 2;
 }
 
+/**
+ * How much a single issue contributes to an exposure score.
+ *
+ * **Severity times age in days, capped at ninety.** The cap is the load-bearing
+ * part: without it a two-year-old advisory eventually outweighs a critical
+ * found this morning, and the number stops being about risk and starts being
+ * about how long you have had the account. Ninety days is where an unfixed
+ * issue stops getting worse and simply *is* bad.
+ *
+ * **Only `open` and `regressed` count.** A resolved issue is not exposure, and
+ * an ignored one is excluded from exposure exactly as it is excluded from
+ * every count but its own (invariant 7) — suppressing an issue is a statement
+ * that it is not currently risk, and a score that disagreed with that would
+ * make the suppression pointless.
+ *
+ * Exported because `reconcile()` is not the only thing that needs it: the
+ * nightly rollup scores a whole organisation across every target, and two
+ * implementations of this would be two definitions of exposure.
+ *
+ * @param issue - The issue to score.
+ * @param now - When the score is being taken. An argument, so the same issue
+ *   and the same clock always give the same number.
+ * @returns The contribution, which is zero for anything not currently open.
+ */
+export function exposureOf(
+  issue: Pick<Issue, 'status' | 'effectiveSeverity' | 'firstSeen'>,
+  now: Date,
+): number {
+  if (issue.status !== 'open' && issue.status !== 'regressed') return 0;
+  return (
+    SEVERITY_WEIGHTS[issue.effectiveSeverity] * Math.min(daysBetween(issue.firstSeen, now), 90)
+  );
+}
+
 /** An all-zero count, so a report never has to decide what a missing key means. */
 function emptyCounts(): Record<string, number> {
   return Object.fromEntries(SEVERITY_ORDER.map((s) => [s, 0]));
@@ -446,9 +480,7 @@ export function reconcile(input: ReconcileInput): ReconcileResult {
     else if (regressedNow.has(key)) counts.regressed[severity]++;
     else if (updated.has(key)) counts.stillOpen[severity]++;
 
-    if (issue.status === 'open' || issue.status === 'regressed') {
-      exposureScore += SEVERITY_WEIGHTS[severity] * Math.min(daysBetween(issue.firstSeen, now), 90);
-    }
+    exposureScore += exposureOf(issue, now);
   }
 
   const summary: RunSummary = {

package/src/refingerprint.ts

@@ -0,0 +1,282 @@
+import type { Finding } from './finding.js';
+import type { FingerprintInput, VulnKeyInput } from './fingerprint.js';
+import { FINGERPRINT_VERSION, fingerprint, vulnKey } from './fingerprint.js';
+import type { Issue } from './issue.js';
+
+/**
+ * How to compute a fingerprint. Injected so the dry run can be pointed at a
+ * version that does not exist yet.
+ *
+ * **`@secureport/core` only ever contains one algorithm** — the current one,
+ * named by `FINGERPRINT_VERSION`. So on the day a version bump is being
+ * considered, the way to find out what it would do is to hand this planner
+ * the candidate implementation. Against the shipped algorithm the plan is a
+ * no-op by construction, which is exactly what makes it safe to run at any
+ * time and what lets the tests drive real merges and splits without a
+ * released `fp_v2`.
+ */
+export interface FingerprintAlgorithm {
+  readonly version: string;
+  fingerprintOf(input: FingerprintInput): string;
+  vulnKeyOf(input: VulnKeyInput): string;
+}
+
+/** The algorithm this build ships. */
+export const currentAlgorithm: FingerprintAlgorithm = {
+  version: FINGERPRINT_VERSION,
+  fingerprintOf: fingerprint,
+  vulnKeyOf: vulnKey,
+};
+
+/** An issue and the evidence a re-fingerprint would recompute it from. */
+export interface IssueWithEvidence {
+  readonly issue: Issue;
+  /**
+   * The evidence that **defines** this issue, which is not always every
+   * finding linked to it: `gatherForOrg` excludes what a merge attached from
+   * another issue, because that evidence describes a different weakness and
+   * re-deriving a key from it would split the survivor apart.
+   */
+  readonly findings: readonly Finding[];
+}
+
+/**
+ * What would happen to one issue.
+ *
+ * - `unchanged` — recomputes to the fingerprint it already has.
+ * - `moved` — one new fingerprint, different, and nothing else lands on it.
+ *   The issue keeps its identity and its history; only the key changes.
+ * - `merged` — its new fingerprint is shared with at least one other issue.
+ *   They become one, which is the outcome B39 and B41 are chasing.
+ * - `split` — its findings no longer agree on a fingerprint, so the issue
+ *   would become several. The most disruptive outcome and the one that most
+ *   needs reading before an execution.
+ * - `undecidable` — at least one of its findings cannot be re-keyed at all,
+ *   so no honest answer exists for it. See {@link planRefingerprint}.
+ */
+export type RefingerprintOutcome = 'unchanged' | 'moved' | 'merged' | 'split' | 'undecidable';
+
+export interface IssuePlan {
+  readonly issueId: string;
+  readonly targetId: string;
+  readonly title: string;
+  readonly from: string;
+  readonly fromVersion: string;
+  /** Distinct fingerprints this issue's evidence produces at the new version. */
+  readonly to: readonly string[];
+  readonly outcome: RefingerprintOutcome;
+  /** Other issues that land on one of `to`. Empty unless `outcome` involves a merge. */
+  readonly mergesWith: readonly string[];
+  /**
+   * Findings linked to the issue — **not necessarily the number the recompute
+   * read**. A manual issue is keyed from its own columns however much evidence
+   * is attached to it, and a scanner issue with zero findings falls back to
+   * the same path. Both are reported here as they stand so the count stays a
+   * fact about the data rather than about this function.
+   */
+  readonly evidence: number;
+}
+
+export interface RefingerprintPlan {
+  readonly fromVersion: string;
+  readonly toVersion: string;
+  readonly issues: readonly IssuePlan[];
+  readonly counts: Readonly<Record<RefingerprintOutcome, number>>;
+}
+
+/**
+ * Works out what re-fingerprinting every issue would do, and writes nothing.
+ *
+ * **Recomputed from inputs, never by comparing stored strings.** A stored
+ * `fp_v1` fingerprint and a stored `fp_v2` one are not comparable — that is
+ * the whole reason `reconcile()` refuses to run across versions (B45) — so
+ * the only honest question is "what does the new algorithm say about the same
+ * evidence?". That means re-deriving `vulnKey` too: B39's change was to the
+ * `vulnKey` fallback, and reading the stored value would miss precisely the
+ * class of change this migration exists for.
+ *
+ * **A manual issue is keyed from its own columns, evidence or not.** Findings
+ * can be attached to a human-raised issue after the fact; 24 of the 404 manual
+ * issues in the development database are. Re-deriving those from the evidence
+ * would replace the human's `vulnKey` with the scanner's and merge the issue
+ * into whichever upload-origin issue already holds that key — losing the
+ * issue a person raised, in a migration nobody expected to lose anything.
+ *
+ * **An issue an earlier merge retired keeps the key it has**, and this is what
+ * makes the plan reach a fixed point. A merge copies the duplicate's evidence
+ * to the survivor without removing it from the duplicate (B98), so re-deriving
+ * a retired issue from its evidence produces the survivor's key and proposes
+ * the merge that already happened — every run, forever. Checked before the
+ * manual rule, because an issue can be both and retirement is the later
+ * statement about its identity.
+ *
+ * **Findings are never touched, and this never needs them to be.** A finding
+ * is evidence (invariant 1) and `findings` rejects `UPDATE` at the database
+ * (B66); its `fingerprint_version` records which algorithm produced it and
+ * that stays true forever. Only `issues` are re-keyed. B69, 8 September.
+ *
+ * **A finding whose key cannot be re-derived makes its issue `undecidable`,
+ * and does not stop the report.** `vulnKey()` throws when a finding carries
+ * no mapped rule, CWE, category or engine rule id — so a row that was never
+ * produced by an importer at this version (or was produced by a different
+ * one) has no answer. Reporting that is the useful behaviour: a migration
+ * plan that dies on one row tells an operator nothing about the other
+ * thousand, and guessing a key from the stored value would defeat the whole
+ * purpose, since re-deriving `vulnKey` is the point.
+ */
+export function planRefingerprint(
+  input: readonly IssueWithEvidence[],
+  algorithm: FingerprintAlgorithm = currentAlgorithm,
+): RefingerprintPlan {
+  const recomputed = input.map(({ issue, findings }) => {
+    // Retirement is checked first, and the order is load-bearing. An issue an
+    // earlier merge retired is not re-keyed at all: its identity moved to the
+    // survivor, and its evidence — which the merge copied to that survivor —
+    // would re-derive the survivor's key and propose merging the two all over
+    // again, so the plan would never reach a fixed point. A *manual* issue
+    // that was later merged away is both things at once, and retirement is
+    // the later statement about its identity, so it wins. Measured: with the
+    // branches the other way round, 95 issues reported `moved` on every run
+    // while the executor left them alone on every run, forever.
+    if (issue.status === 'ignored' && issue.ignoreReason === 'duplicate') {
+      return { issue, evidence: findings.length, undecidable: false, to: [issue.fingerprint] };
+    }
+
+    // A manual issue is keyed from its own columns: its `vulnKey` and location
+    // were declared by a person, and evidence linked afterwards corroborates
+    // that issue rather than redefining it. Re-deriving would replace the
+    // human's key with the scanner's and dissolve the issue into whichever
+    // upload-origin issue already holds it.
+    //
+    // A *merge survivor* is deliberately not handled here, though it is also
+    // an identity a person asserted. Keying one from its own columns carries a
+    // stale `vulnKey` — written before the mapping table knew the engine's
+    // rule — so the migrated issue stops matching what the importer now
+    // produces, auto-resolves and comes back as new. `gatherForOrg` excludes
+    // the absorbed evidence instead, so a survivor re-derives correctly from
+    // what was always its own.
+    if (issue.origin === 'manual') {
+      return {
+        issue,
+        evidence: findings.length,
+        undecidable: false,
+        to: [fromOwnColumns(issue, algorithm)],
+      };
+    }
+
+    const keys = findings.map((f) => fingerprintOfFinding(issue, f, algorithm));
+    return {
+      issue,
+      evidence: findings.length,
+      undecidable: keys.some((k) => k === undefined),
+      to: [...new Set(keys.filter((k): k is string => k !== undefined))].sort(),
+    };
+  });
+
+  // A scanner-origin issue whose evidence has since been detached has nothing
+  // left to re-derive from, so it falls back to its own columns rather than
+  // vanishing from the report.
+  for (const row of recomputed) {
+    if (row.to.length === 0 && !row.undecidable) {
+      row.to = [fromOwnColumns(row.issue, algorithm)];
+    }
+  }
+
+  const owners = new Map<string, string[]>();
+  for (const row of recomputed) {
+    if (row.undecidable) continue;
+    for (const fp of row.to) {
+      const list = owners.get(fp);
+      if (list) list.push(row.issue.id);
+      else owners.set(fp, [row.issue.id]);
+    }
+  }
+
+  const counts: Record<RefingerprintOutcome, number> = {
+    unchanged: 0,
+    moved: 0,
+    merged: 0,
+    split: 0,
+    undecidable: 0,
+  };
+
+  const issues = recomputed.map(({ issue, evidence, to, undecidable }): IssuePlan => {
+    const mergesWith = [
+      ...new Set(to.flatMap((fp) => owners.get(fp) ?? []).filter((id) => id !== issue.id)),
+    ].sort();
+
+    // Split first: an issue that fragments is the most disruptive outcome
+    // and stays visible even when one of its fragments also collides.
+    const outcome: RefingerprintOutcome = undecidable
+      ? 'undecidable'
+      : to.length > 1
+        ? 'split'
+        : mergesWith.length > 0
+          ? 'merged'
+          : to[0] === issue.fingerprint
+            ? 'unchanged'
+            : 'moved';
+
+    counts[outcome] += 1;
+    return {
+      issueId: issue.id,
+      targetId: issue.targetId,
+      title: issue.title,
+      from: issue.fingerprint,
+      fromVersion: issue.fingerprintVersion,
+      to,
+      outcome,
+      mergesWith,
+      evidence,
+    };
+  });
+
+  const fromVersions = [...new Set(input.map(({ issue }) => issue.fingerprintVersion))].sort();
+  return {
+    fromVersion: fromVersions.join(', ') || algorithm.version,
+    toVersion: algorithm.version,
+    issues,
+    counts,
+  };
+}
+
+/** An issue's fingerprint at the new version, from the issue's own columns. */
+function fromOwnColumns(issue: Issue, algorithm: FingerprintAlgorithm): string {
+  return algorithm.fingerprintOf({
+    targetId: issue.targetId,
+    vulnKey: issue.vulnKey,
+    location: issue.location,
+    ...(issue.parameter === undefined ? {} : { parameter: issue.parameter }),
+  });
+}
+
+/**
+ * One finding's fingerprint at the new version, `vulnKey` re-derived and all,
+ * or `undefined` when the key cannot be derived from what the finding holds.
+ */
+function fingerprintOfFinding(
+  issue: Issue,
+  finding: Finding,
+  algorithm: FingerprintAlgorithm,
+): string | undefined {
+  let key;
+  try {
+    key = algorithm.vulnKeyOf({
+      sourceEngine: finding.sourceEngine,
+      ...(finding.sourceRuleId === undefined ? {} : { sourceRuleId: finding.sourceRuleId }),
+      ...(finding.cwe === undefined ? {} : { cwe: finding.cwe }),
+      ...(finding.category === undefined ? {} : { category: finding.category }),
+    });
+  } catch {
+    return undefined;
+  }
+  return algorithm.fingerprintOf({
+    // The target is the issue's: a finding records the run it came from, and
+    // every run of an issue's evidence is against the same target anyway.
+    targetId: issue.targetId,
+    vulnKey: key,
+    location: finding.location,
+    ...(finding.parameter === undefined ? {} : { parameter: finding.parameter }),
+    ...(finding.port === undefined ? {} : { port: finding.port }),
+  });
+}

package/src/report/html.ts

@@ -121,7 +121,7 @@ function issueDetail(entry: SnapshotIssue): string {
   }</td></tr>
 <tr><td>First seen</td><td>${formatDate(issue.firstSeen)} (${entry.daysOpen} days)</td></tr>
 <tr><td>Remediation</td><td${entry.slaStatus === 'breached' ? ' class="breached"' : ''}>${
-    issue.slaDueAt === undefined || issue.slaDueAt === null
+    issue.slaDueAt === null
       ? 'no deadline'
       : `${formatDate(issue.slaDueAt)} — ${entry.slaStatus.replace('_', ' ')}`
   }</td></tr>

package/src/report/markdown.ts

@@ -67,7 +67,7 @@ function issueDetail(entry: SnapshotIssue): string[] {
     `| 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
+      issue.slaDueAt === null
         ? 'no deadline'
         : `${formatDate(issue.slaDueAt)} — ${entry.slaStatus.replace('_', ' ')}`
     } |`,

package/src/run.ts

@@ -50,6 +50,21 @@ export interface Coverage {
   readonly engines: readonly string[];
 }
 
+/**
+ * Where a run is in its lifecycle.
+ *
+ * - `running` — started and not yet ended.
+ * - `finished` — ended, and its findings are what it found.
+ * - `failed` — ended without a usable result; any findings it recorded are
+ *   partial.
+ *
+ * `finishedAt` alone cannot carry this: it says a run ended, not whether it
+ * succeeded, and reconciling a failed run's partial findings as if they were
+ * complete would resolve everything the run never reached. A running run has
+ * no `finishedAt`; an ended one always does.
+ */
+export type RunStatus = 'running' | 'finished' | 'failed';
+
 /**
  * One execution against a target.
  */
@@ -69,6 +84,9 @@ export interface Run {
   /** What set it going. */
   readonly trigger: RunTrigger;
 
+  /** Where it is in its lifecycle. */
+  readonly status: RunStatus;
+
   /** What it exercised. */
   readonly coverage: Coverage;
 

package/src/snapshot-builder.ts

@@ -145,7 +145,7 @@ export function buildSnapshot(input: BuildSnapshotInput): Snapshot {
       // 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),
+      slaStatus: slaStatus(issue.slaDueAt, input.now, slaPolicy),
       findings: byFingerprint.get(issueKey(issue)) ?? [],
     });
   }