@secureport/core 0.2.1 → 0.4.0

package/src/import/xml.ts

@@ -0,0 +1,187 @@
+/**
+ * A parsed XML element.
+ *
+ * Deliberately minimal: a name, its attributes, its child elements and its
+ * text. No namespaces, no processing instructions, no mixed-content ordering —
+ * none of which appears in a Burp or Nessus export.
+ */
+export interface XmlNode {
+  /** The element name, as written. */
+  readonly name: string;
+
+  /** Attributes, with entities decoded. */
+  readonly attrs: Readonly<Record<string, string>>;
+
+  /** Child elements, in document order. */
+  readonly children: readonly XmlNode[];
+
+  /** All direct text and CDATA of this element, concatenated and trimmed. */
+  readonly text: string;
+}
+
+const ENTITIES: Readonly<Record<string, string>> = Object.freeze({
+  amp: '&',
+  lt: '<',
+  gt: '>',
+  quot: '"',
+  apos: "'",
+});
+
+/** Decodes the five XML entities and numeric character references. */
+function decodeEntities(text: string): string {
+  return text.replace(/&(#x?[0-9a-f]+|[a-z]+);/giu, (whole, body: string) => {
+    if (body.startsWith('#')) {
+      const code =
+        body[1]?.toLowerCase() === 'x' ? parseInt(body.slice(2), 16) : parseInt(body.slice(1), 10);
+      return Number.isFinite(code) && code >= 0 && code <= 0x10ffff
+        ? String.fromCodePoint(code)
+        : whole;
+    }
+    return ENTITIES[body.toLowerCase()] ?? whole;
+  });
+}
+
+interface MutableNode {
+  name: string;
+  attrs: Record<string, string>;
+  children: MutableNode[];
+  text: string;
+}
+
+/** Reads the attributes out of a start tag's body. */
+function parseAttrs(body: string): Record<string, string> {
+  const attrs: Record<string, string> = {};
+  const pattern = /([\w:.-]+)\s*=\s*("([^"]*)"|'([^']*)')/gu;
+  let match: RegExpExecArray | null;
+  while ((match = pattern.exec(body)) !== null) {
+    attrs[match[1]] = decodeEntities(match[3] ?? match[4] ?? '');
+  }
+  return attrs;
+}
+
+/**
+ * Parses the subset of XML that scanner exports actually use.
+ *
+ * **Deliberately narrow, and it throws rather than guesses.** Burp and Nessus
+ * both export machine-generated XML with a fixed shape: elements, attributes,
+ * text and CDATA. This handles exactly that, plus comments, the XML
+ * declaration, a DOCTYPE, self-closing tags and the five named entities with
+ * numeric character references.
+ *
+ * It does **not** handle namespaces, entity definitions or mixed-content
+ * ordering, and it has no opinion about schemas. Anything structurally
+ * unexpected — an unclosed element, a mismatched end tag, two root elements —
+ * is an error, because a parser that guesses at broken input produces findings
+ * that are quietly wrong, and a wrong finding is worse than a failed import.
+ *
+ * Hand-written rather than taken from a library because `@secureport/core` ships
+ * with zero runtime dependencies: it is imported by the hosted API and by third
+ * parties on equal terms, and a domain model that drags an XML parser in with it
+ * is a supply-chain decision made on everyone's behalf.
+ *
+ * @param source - The XML document.
+ * @returns The root element.
+ * @throws SyntaxError If the document is not well-formed, or has no root.
+ */
+export function parseXml(source: string): XmlNode {
+  const stack: MutableNode[] = [];
+  let root: MutableNode | undefined;
+  let i = 0;
+
+  while (i < source.length) {
+    const lt = source.indexOf('<', i);
+    if (lt === -1) break;
+
+    // Text before this tag belongs to the element currently open.
+    if (lt > i && stack.length > 0) {
+      stack[stack.length - 1].text += decodeEntities(source.slice(i, lt));
+    }
+
+    if (source.startsWith('<!--', lt)) {
+      const end = source.indexOf('-->', lt);
+      if (end === -1) throw new SyntaxError('unterminated comment');
+      i = end + 3;
+      continue;
+    }
+
+    if (source.startsWith('<![CDATA[', lt)) {
+      const end = source.indexOf(']]>', lt);
+      if (end === -1) throw new SyntaxError('unterminated CDATA section');
+      // CDATA is literal: no entity decoding, which is the whole point of it.
+      if (stack.length > 0) stack[stack.length - 1].text += source.slice(lt + 9, end);
+      i = end + 3;
+      continue;
+    }
+
+    if (source.startsWith('<?', lt) || source.startsWith('<!', lt)) {
+      const end = source.indexOf('>', lt);
+      if (end === -1) throw new SyntaxError('unterminated declaration');
+      i = end + 1;
+      continue;
+    }
+
+    const gt = source.indexOf('>', lt);
+    if (gt === -1) throw new SyntaxError('unterminated tag');
+    const raw = source.slice(lt + 1, gt);
+
+    if (raw.startsWith('/')) {
+      const name = raw.slice(1).trim();
+      const open = stack.pop();
+      if (open === undefined) throw new SyntaxError(`unexpected closing tag </${name}>`);
+      if (open.name !== name) {
+        throw new SyntaxError(`closing tag </${name}> does not match <${open.name}>`);
+      }
+      i = gt + 1;
+      continue;
+    }
+
+    const selfClosing = raw.endsWith('/');
+    const body = selfClosing ? raw.slice(0, -1) : raw;
+    const nameEnd = body.search(/[\s/]/u);
+    const name = (nameEnd === -1 ? body : body.slice(0, nameEnd)).trim();
+    if (name === '') throw new SyntaxError('tag with no name');
+
+    const node: MutableNode = {
+      name,
+      attrs: parseAttrs(nameEnd === -1 ? '' : body.slice(nameEnd)),
+      children: [],
+      text: '',
+    };
+
+    if (stack.length > 0) stack[stack.length - 1].children.push(node);
+    else if (root === undefined) root = node;
+    else throw new SyntaxError('more than one root element');
+
+    if (!selfClosing) stack.push(node);
+    i = gt + 1;
+  }
+
+  if (stack.length > 0) throw new SyntaxError(`unclosed element <${stack[stack.length - 1].name}>`);
+  if (root === undefined) throw new SyntaxError('no root element');
+
+  const finish = (node: MutableNode): XmlNode => ({
+    name: node.name,
+    attrs: node.attrs,
+    children: node.children.map(finish),
+    text: node.text.trim(),
+  });
+  return finish(root);
+}
+
+/** Every descendant with this name, at any depth. */
+export function findAll(node: XmlNode, name: string): XmlNode[] {
+  const found: XmlNode[] = [];
+  const walk = (current: XmlNode) => {
+    if (current.name === name) found.push(current);
+    for (const child of current.children) walk(child);
+  };
+  walk(node);
+  return found;
+}
+
+/** The text of the first direct child with this name, if it has any. */
+export function childText(node: XmlNode, name: string): string | undefined {
+  const child = node.children.find((c) => c.name === name);
+  const text = child?.text.trim();
+  return text === undefined || text === '' ? undefined : text;
+}

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 `ZAP_RISK` below 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,75 @@
-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 { importBurp } from './import/burp.js';
+export { importNessus } from './import/nessus.js';
+export type { GenericDocument, GenericFinding } from './import/generic.js';
+export { importGeneric } from './import/generic.js';
+export type { BuildSnapshotInput } from './snapshot-builder.js';
+export { buildSnapshot, parseSnapshot } from './snapshot-builder.js';
+export type {
+  ReportKind,
+  ReportModel,
+  ReportOptions,
+  ReportSection,
+  RetestEntry,
+  RetestOutcome,
+  RetestVerdict,
+  TestingBasis,
+} from './report/model.js';
+export { buildReportModel } from './report/model.js';
+export { renderMarkdown } from './report/markdown.js';
+export { renderHtml } from './report/html.js';
+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 { 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;
 }