@secureport/core 0.2.1 → 0.3.0

package/src/import/nuclei.ts

@@ -0,0 +1,173 @@
+import type { Finding } from '../finding.js';
+import type { Severity, SeveritySource } from '../severity.js';
+import { severityFromCvss } from '../severity.js';
+import { fingerprint, vulnKey, FINGERPRINT_VERSION } from '../fingerprint.js';
+
+/**
+ * What an importer needs that a scanner's output cannot tell it.
+ *
+ * A scanner knows what it found; it does not know which organisation, run or
+ * target the result belongs to, and it must not invent ids. All of it is
+ * supplied, so importing stays pure and repeatable.
+ */
+export interface ImportOptions {
+  /** Organisation the findings belong to. */
+  readonly orgId: string;
+
+  /** The run that produced them. */
+  readonly runId: string;
+
+  /** The target they are against. Part of every fingerprint. */
+  readonly targetId: string;
+
+  /** When the import happened. No importer reads the clock. */
+  readonly now: Date;
+
+  /** Supplies finding ids. Injected so importing is deterministic. */
+  readonly newId: () => string;
+}
+
+/**
+ * Nuclei's severity vocabulary, mapped onto {@link Severity}.
+ *
+ * `info` and `unknown` both become `advisory`: this model has no
+ * "informational" category separate from the bottom of the scale, and an
+ * unrated finding is not evidence of low risk — it is evidence of nothing, which
+ * is what `advisory` means here.
+ */
+const NUCLEI_SEVERITY: Readonly<Record<string, Severity>> = Object.freeze({
+  critical: 'critical',
+  high: 'high',
+  medium: 'medium',
+  low: 'low',
+  info: 'advisory',
+  unknown: 'advisory',
+});
+
+/** The subset of a Nuclei JSONL record this importer reads. */
+interface NucleiRecord {
+  'template-id'?: unknown;
+  'matched-at'?: unknown;
+  host?: unknown;
+  type?: unknown;
+  info?: {
+    name?: unknown;
+    description?: unknown;
+    severity?: unknown;
+    tags?: unknown;
+    reference?: unknown;
+    remediation?: unknown;
+    classification?: {
+      'cve-id'?: unknown;
+      'cwe-id'?: unknown;
+      'cvss-score'?: unknown;
+      'cvss-metrics'?: unknown;
+    };
+  };
+}
+
+const str = (v: unknown): string | undefined =>
+  typeof v === 'string' && v.trim() !== '' ? v.trim() : undefined;
+
+const firstOf = (v: unknown): string | undefined => (Array.isArray(v) ? str(v[0]) : str(v));
+
+const allOf = (v: unknown): string[] | undefined => {
+  if (!Array.isArray(v)) return str(v) === undefined ? undefined : [str(v)!];
+  const items = v.map(str).filter((x): x is string => x !== undefined);
+  return items.length > 0 ? items : undefined;
+};
+
+/**
+ * Turns Nuclei's JSONL output into {@link Finding}s.
+ *
+ * Nuclei writes **one JSON object per line** (`-jsonl`), so the file is not
+ * itself valid JSON. Blank lines are skipped, and a line that will not parse is
+ * skipped rather than thrown on: a single malformed record should not cost a
+ * user every other result in the file. Records with no `template-id` or no
+ * location are skipped for the same reason — there is nothing to fingerprint.
+ *
+ * Severity comes from the CVSS score where Nuclei supplies one, and from its own
+ * rating otherwise; `severitySource` records which, because a severity with no
+ * provenance is not evidence.
+ *
+ * @param jsonl - The contents of a Nuclei JSONL file.
+ * @param options - Ownership, and the injected clock and id source.
+ * @returns One finding per usable record, in file order.
+ */
+export function importNuclei(jsonl: string, options: ImportOptions): Finding[] {
+  const findings: Finding[] = [];
+
+  for (const line of jsonl.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed === '') continue;
+
+    let record: NucleiRecord;
+    try {
+      record = JSON.parse(trimmed) as NucleiRecord;
+    } catch {
+      // One unparseable line must not cost the user the rest of the file.
+      continue;
+    }
+
+    const templateId = str(record['template-id']);
+    const location = str(record['matched-at']) ?? str(record.host);
+    if (templateId === undefined || location === undefined) continue;
+
+    const info = record.info ?? {};
+    const classification = info.classification ?? {};
+
+    const cvss =
+      typeof classification['cvss-score'] === 'number' ? classification['cvss-score'] : undefined;
+    const rated = NUCLEI_SEVERITY[str(info.severity)?.toLowerCase() ?? ''];
+
+    let detectedSeverity: Severity;
+    let severitySource: SeveritySource;
+    if (cvss !== undefined && cvss >= 0 && cvss <= 10) {
+      detectedSeverity = severityFromCvss(cvss);
+      severitySource = 'cvss';
+    } else {
+      detectedSeverity = rated ?? 'advisory';
+      severitySource = 'engine_default';
+    }
+
+    // Nuclei writes CWE as `cwe-502`; the rest of the model uses `CWE-502`.
+    const cwe = firstOf(classification['cwe-id'])?.toUpperCase();
+    const category = firstOf(info.tags);
+    const key = vulnKey({
+      sourceEngine: 'nuclei',
+      sourceRuleId: templateId,
+      ...(cwe === undefined ? {} : { cwe }),
+      ...(category === undefined ? {} : { category }),
+    });
+
+    findings.push({
+      id: options.newId(),
+      orgId: options.orgId,
+      runId: options.runId,
+      fingerprint: fingerprint({ targetId: options.targetId, vulnKey: key, location }),
+      fingerprintVersion: FINGERPRINT_VERSION,
+      title: str(info.name) ?? templateId,
+      ...(str(info.description) === undefined ? {} : { description: str(info.description)! }),
+      detectedSeverity,
+      severitySource,
+      ...(cvss === undefined ? {} : { cvssScore: cvss }),
+      ...(str(classification['cvss-metrics']) === undefined
+        ? {}
+        : { cvssVector: str(classification['cvss-metrics'])! }),
+      ...(cwe === undefined ? {} : { cwe }),
+      ...(firstOf(classification['cve-id']) === undefined
+        ? {}
+        : { cve: firstOf(classification['cve-id'])!.toUpperCase() }),
+      vulnKey: key,
+      ...(category === undefined ? {} : { category }),
+      location,
+      ...(str(info.remediation) === undefined ? {} : { recommendation: str(info.remediation)! }),
+      ...(allOf(info.reference) === undefined ? {} : { references: allOf(info.reference)! }),
+      sourceEngine: 'nuclei',
+      sourceRuleId: templateId,
+      createdAt: options.now,
+    });
+  }
+
+  return findings;
+}

package/src/import/zap.ts

@@ -0,0 +1,161 @@
+import type { Finding } from '../finding.js';
+import type { Severity } from '../severity.js';
+import { fingerprint, vulnKey, FINGERPRINT_VERSION } from '../fingerprint.js';
+import type { ImportOptions } from './nuclei.js';
+
+/**
+ * ZAP's `riskcode` mapped onto {@link Severity}.
+ *
+ * **ZAP has no "critical".** Its scale tops out at High (`3`), so nothing this
+ * importer produces is ever `critical` — a `critical` issue in a report that
+ * ZAP also detected got there from another engine, a CVSS score or a human.
+ * Worth knowing before wondering why a ZAP-only target has none.
+ */
+const ZAP_RISK: Readonly<Record<string, Severity>> = Object.freeze({
+  '3': 'high',
+  '2': 'medium',
+  '1': 'low',
+  '0': 'advisory',
+});
+
+/** The subset of a ZAP JSON report this importer reads. */
+interface ZapReport {
+  site?: unknown;
+}
+
+interface ZapSite {
+  '@name'?: unknown;
+  alerts?: unknown;
+}
+
+interface ZapAlert {
+  pluginid?: unknown;
+  alertRef?: unknown;
+  alert?: unknown;
+  name?: unknown;
+  riskcode?: unknown;
+  desc?: unknown;
+  solution?: unknown;
+  reference?: unknown;
+  cweid?: unknown;
+  instances?: unknown;
+}
+
+interface ZapInstance {
+  uri?: unknown;
+  param?: unknown;
+  evidence?: unknown;
+}
+
+const str = (v: unknown): string | undefined => {
+  if (typeof v === 'number') return String(v);
+  return typeof v === 'string' && v.trim() !== '' ? v.trim() : undefined;
+};
+
+/** ZAP embeds HTML in its description and solution fields. */
+const stripHtml = (v: string): string =>
+  v
+    .replace(/<[^>]*>/gu, ' ')
+    .replace(/\s+/gu, ' ')
+    .trim();
+
+/** ZAP's reference field is one string of newline-separated URLs. */
+const splitReferences = (v: unknown): string[] | undefined => {
+  const text = str(v);
+  if (text === undefined) return undefined;
+  const urls = stripHtml(text)
+    .split(/\s+/u)
+    .filter((token) => token.startsWith('http'));
+  return urls.length > 0 ? urls : undefined;
+};
+
+/**
+ * Turns a ZAP JSON report into {@link Finding}s.
+ *
+ * **One finding per instance, not per alert.** ZAP groups every occurrence of a
+ * weakness under a single alert with an `instances` array, so an alert is a
+ * class and an instance is a detection. Flattening is what lets two URLs
+ * affected by the same rule become two issues, and lets one of them be fixed
+ * without closing the other.
+ *
+ * An alert with no instances still produces one finding, against the site — a
+ * detection with no location is still a detection.
+ *
+ * Severity comes from ZAP's `riskcode`; see {@link ZAP_RISK} for why nothing
+ * here is ever `critical`.
+ *
+ * @param json - The contents of a ZAP JSON report.
+ * @param options - Ownership, and the injected clock and id source.
+ * @returns One finding per instance, in report order.
+ * @throws SyntaxError If the report is not valid JSON. Unlike Nuclei's JSONL,
+ * where one bad line costs one record, a ZAP report is a single document: if it
+ * will not parse there is nothing to salvage and silence would be a lie.
+ */
+export function importZap(json: string, options: ImportOptions): Finding[] {
+  const report = JSON.parse(json) as ZapReport;
+  const sites = Array.isArray(report.site) ? (report.site as ZapSite[]) : [];
+  const findings: Finding[] = [];
+
+  for (const site of sites) {
+    const siteName = str(site['@name']);
+    const alerts = Array.isArray(site.alerts) ? (site.alerts as ZapAlert[]) : [];
+
+    for (const alert of alerts) {
+      const pluginId = str(alert.pluginid);
+      const title = str(alert.alert) ?? str(alert.name);
+      if (pluginId === undefined || title === undefined) continue;
+
+      // ZAP writes `0` for "no CWE", which is not a CWE.
+      const rawCwe = str(alert.cweid);
+      const cwe =
+        rawCwe !== undefined && rawCwe !== '0' && rawCwe !== '-1' ? `CWE-${rawCwe}` : undefined;
+
+      const key = vulnKey({
+        sourceEngine: 'zap',
+        sourceRuleId: pluginId,
+        ...(cwe === undefined ? {} : { cwe }),
+      });
+
+      const instances = Array.isArray(alert.instances) ? (alert.instances as ZapInstance[]) : [];
+      const targets: ZapInstance[] = instances.length > 0 ? instances : [{ uri: siteName }];
+
+      for (const instance of targets) {
+        const location = str(instance.uri) ?? siteName;
+        if (location === undefined) continue;
+        const parameter = str(instance.param);
+
+        findings.push({
+          id: options.newId(),
+          orgId: options.orgId,
+          runId: options.runId,
+          fingerprint: fingerprint({
+            targetId: options.targetId,
+            vulnKey: key,
+            location,
+            ...(parameter === undefined ? {} : { parameter }),
+          }),
+          fingerprintVersion: FINGERPRINT_VERSION,
+          title,
+          ...(str(alert.desc) === undefined ? {} : { description: stripHtml(str(alert.desc)!) }),
+          detectedSeverity: ZAP_RISK[str(alert.riskcode) ?? ''] ?? 'advisory',
+          severitySource: 'engine_default',
+          ...(cwe === undefined ? {} : { cwe }),
+          vulnKey: key,
+          location,
+          ...(parameter === undefined ? {} : { parameter }),
+          ...(str(alert.solution) === undefined
+            ? {}
+            : { recommendation: stripHtml(str(alert.solution)!) }),
+          ...(splitReferences(alert.reference) === undefined
+            ? {}
+            : { references: splitReferences(alert.reference)! }),
+          sourceEngine: 'zap',
+          sourceRuleId: pluginId,
+          createdAt: options.now,
+        });
+      }
+    }
+  }
+
+  return findings;
+}

package/src/index.ts

@@ -1,2 +1,56 @@
-export * from './issue.js';
-export * from './reconcile.js';
+/**
+ * The Secureport domain model.
+ *
+ * The tracked entity is the **issue**, not the finding. A {@link Run} produces
+ * {@link Finding}s, which are immutable evidence. Findings are fingerprinted
+ * and reconciled into {@link Issue}s, which persist across runs and carry
+ * status, severity, age and history. A {@link Snapshot} is issue state as of a
+ * run, and is the only thing a report ever reads.
+ *
+ * Zero runtime dependencies, by design: this package is imported by the hosted
+ * API and by third parties on equal terms, and a domain model should not drag
+ * anything in with it.
+ *
+ * @packageDocumentation
+ */
+
+export type { Finding } from './finding.js';
+export type { FingerprintInput, VulnKeyInput } from './fingerprint.js';
+export {
+  FINGERPRINT_VERSION,
+  PATH_PLACEHOLDER,
+  VULN_KEY_MAP,
+  fingerprint,
+  normaliseLocation,
+  vulnKey,
+} from './fingerprint.js';
+export type {
+  IgnoreReason,
+  IgnoreScope,
+  Issue,
+  IssueEvent,
+  IssueEventType,
+  IssueOrigin,
+  IssueStatus,
+} from './issue.js';
+export { coversLocation } from './coverage.js';
+export type { ImportOptions } from './import/nuclei.js';
+export { importNuclei } from './import/nuclei.js';
+export { importZap } from './import/zap.js';
+export type { BuildSnapshotInput } from './snapshot-builder.js';
+export { buildSnapshot, parseSnapshot } from './snapshot-builder.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 { IssueChange, Snapshot, SnapshotIssue, SuppressedIssue, Target } from './snapshot.js';
+export type { Severity, SeveritySource, SlaPolicy, SlaStatus } from './severity.js';
+export {
+  DEFAULT_SLA_POLICY,
+  SEVERITY_ORDER,
+  SEVERITY_SOURCE_PRECEDENCE,
+  SEVERITY_WEIGHTS,
+  severityFromCvss,
+  severityRank,
+  slaDueAt,
+  slaStatus,
+} from './severity.js';

package/src/issue.ts

@@ -1,17 +1,250 @@
-/** Severity of an {@link Issue}, ordered from most to least urgent by convention. */
-export type Severity = 'critical' | 'high' | 'medium' | 'low' | 'info';
+import type { Severity } from './severity.js';
+import type { RunKind } from './run.js';
 
-/** Lifecycle state of an {@link Issue}. */
-export type IssueStatus = 'open' | 'triaging' | 'accepted' | 'resolved';
+/**
+ * Where an issue is in its lifecycle.
+ *
+ * - `open` — currently detected, or detected recently enough not to be resolved.
+ * - `resolved` — no longer detected by runs that covered it.
+ * - `regressed` — was resolved, and has come back. Distinct from `open` because
+ *   a returning issue is a different and more interesting event than a new one.
+ * - `ignored` — deliberately suppressed, with a reason and an author.
+ *
+ * There is no `triaging` state. Triage is a person's activity, not an issue's
+ * condition, and a status nobody can define precisely is a status nobody
+ * filters on correctly.
+ */
+export type IssueStatus = 'open' | 'resolved' | 'regressed' | 'ignored';
+
+/**
+ * How an issue came into existence.
+ *
+ * Matters because **manual-origin issues never auto-resolve** (invariant 6): a
+ * human closes what a human opened.
+ */
+export type IssueOrigin = RunKind;
+
+/**
+ * Why an issue was suppressed.
+ *
+ * A fixed set rather than free text because this list is what a
+ * suppressed-findings appendix is grouped by, and an auditor reading it needs
+ * categories that mean the same thing every time.
+ */
+export type IgnoreReason = 'false_positive' | 'accepted_risk' | 'out_of_scope' | 'duplicate';
+
+/**
+ * How widely an ignore applies.
+ *
+ * - `target` — this issue on this target only. The default.
+ * - `org` — the same weakness anywhere in the organisation, matched on
+ *   `vulnKey` and normalised location, ignoring the parameter.
+ */
+export type IgnoreScope = 'target' | 'org';
 
 /**
- * A tracked issue — the entity Secureport reports on. One or more findings
- * from one or more scanners can be merged into a single issue; the issue,
- * not the finding, is what carries status and severity through review.
+ * The tracked record that findings reconcile into, and the entity the product
+ * is actually about.
+ *
+ * An issue persists across runs. It carries status, severity, age, ownership
+ * and history; findings are the evidence beneath it. The distinction is the
+ * whole point of the model: two scanners reporting the same weakness produce
+ * one issue with two sources, not two rows, and an issue that comes back after
+ * being fixed is the same issue regressing rather than a new discovery.
+ *
+ * Unique on `(orgId, targetId, fingerprint)`.
+ *
+ * **Issue state changes only through reconciliation or an issue-service
+ * method, and every change emits an {@link IssueEvent}** (invariant 2).
  */
 export interface Issue {
-  id: string;
-  title: string;
-  severity: Severity;
-  status: IssueStatus;
+  /** Unique id. */
+  readonly id: string;
+
+  /** Organisation this issue belongs to. */
+  readonly orgId: string;
+
+  /**
+   * Target this issue is on.
+   *
+   * Part of the identity, and deliberately so: because the fingerprint includes
+   * the target, **the same weakness in staging and in production is two
+   * issues**. They are two systems, fixed separately, and verifying one must
+   * never authorise the other.
+   */
+  readonly targetId: string;
+
+  /** Content address of the weakness. Stable across runs and engines. */
+  readonly fingerprint: string;
+
+  /** Which algorithm produced {@link Issue.fingerprint}. */
+  readonly fingerprintVersion: string;
+
+  /** Human-readable name. Seeded from the first finding; editable afterwards. */
+  readonly title: string;
+
+  /** Engine-independent key for the weakness class. */
+  readonly vulnKey: string;
+
+  /** CWE identifier, where one applies. */
+  readonly cwe?: string;
+
+  /** Where the weakness is. */
+  readonly location: string;
+
+  /** The specific parameter implicated, where there is one. */
+  readonly parameter?: string;
+
+  /** Lifecycle state. */
+  readonly status: IssueStatus;
+
+  /**
+   * Severity as most recently detected.
+   *
+   * Follows the evidence. Changing it emits `severity_detected_changed`.
+   */
+  readonly detectedSeverity: Severity;
+
+  /**
+   * Severity that reports show, and that the SLA deadline derives from.
+   *
+   * Follows {@link Issue.detectedSeverity} unless a human has overridden it. A
+   * null override means the two move together.
+   */
+  readonly effectiveSeverity: Severity;
+
+  /** Why the severity was overridden. Present only when it was. */
+  readonly severityOverrideReason?: string;
+
+  /** Who overrode it. */
+  readonly severityOverriddenBy?: string;
+
+  /** When it was overridden. */
+  readonly severityOverriddenAt?: Date;
+
+  /**
+   * When this issue was first seen.
+   *
+   * **Never reset** (invariant 4) — not by a regression, not by a severity
+   * change, not by anything. It is what "how long has this been open" means,
+   * and resetting it would quietly erase the age of the oldest problems.
+   */
+  readonly firstSeen: Date;
+
+  /** When it was most recently detected. Keeps updating even while ignored. */
+  readonly lastSeen: Date;
+
+  /** When it was resolved, if it has been. */
+  readonly resolvedAt?: Date;
+
+  /** When it most recently regressed, if it has. */
+  readonly reopenedAt?: Date;
+
+  /**
+   * Consecutive covering runs that did not detect this issue.
+   *
+   * The auto-resolve counter, and the flapping guard: a single missed
+   * detection from a timeout or a rate limit should not close an issue. Reset
+   * to zero the moment the issue is seen again.
+   */
+  readonly consecutiveMisses: number;
+
+  /** How the issue came into existence. */
+  readonly origin: IssueOrigin;
+
+  /** Who it is assigned to, if anyone. */
+  readonly assignee?: string;
+
+  /** Key in an external tracker, set by the export. */
+  readonly externalRef?: string;
+
+  /** Why it is suppressed. Present only while `status` is `ignored`. */
+  readonly ignoreReason?: IgnoreReason;
+
+  /** Free-text justification for the suppression. Required when ignoring. */
+  readonly ignoreComment?: string;
+
+  /** How widely the suppression applies. */
+  readonly ignoreScope?: IgnoreScope;
+
+  /** When the suppression lapses, after which the issue re-surfaces. */
+  readonly ignoreExpiresAt?: Date;
+
+  /** Who suppressed it. */
+  readonly ignoredBy?: string;
+
+  /**
+   * Detected severity at the moment it was ignored.
+   *
+   * Recorded so that a *detected increase* re-surfaces the issue
+   * automatically: accepting the risk of a medium is not accepting the risk of
+   * the critical it later turns out to be.
+   */
+  readonly severityAtIgnore?: Severity;
+
+  /**
+   * When remediation is due, derived from {@link Issue.effectiveSeverity}.
+   *
+   * Recomputed whenever the effective severity changes. `null` where the
+   * severity carries no deadline.
+   */
+  readonly slaDueAt?: Date | null;
+}
+
+/**
+ * Something that happened to an issue.
+ *
+ * The audit trail and the source of every analytic. Nothing scans findings at
+ * request time: "issues resolved this quarter" and "regressions caught" are
+ * both counts over this log.
+ */
+export type IssueEventType =
+  | 'created'
+  | 'seen'
+  | 'severity_detected_changed'
+  | 'severity_overridden'
+  | 'resolved'
+  | 'reopened'
+  | 'ignored'
+  | 'unignored'
+  | 'commented'
+  | 'assigned'
+  | 'merged'
+  | 'exported';
+
+/**
+ * An append-only record of a single change to an issue.
+ *
+ * Append-only is load-bearing rather than stylistic: it is what makes the
+ * history trustworthy as evidence, and what lets analytics be a query rather
+ * than a recomputation.
+ */
+export interface IssueEvent {
+  /** Unique id. */
+  readonly id: string;
+
+  /** Organisation this event belongs to. */
+  readonly orgId: string;
+
+  /** The issue it happened to. */
+  readonly issueId: string;
+
+  /** The run that caused it, where a run did. Absent for human actions. */
+  readonly runId?: string;
+
+  /** What happened. */
+  readonly type: IssueEventType;
+
+  /**
+   * Who or what did it — a user id, an API key id, or the reconciler.
+   *
+   * Never optional: an audit trail that cannot say who is not one.
+   */
+  readonly actor: string;
+
+  /** Type-specific detail, e.g. the old and new severity. */
+  readonly payload?: Readonly<Record<string, unknown>>;
+
+  /** When it happened. */
+  readonly createdAt: Date;
 }