@secureport/core 0.2.1 → 0.4.0

package/src/coverage.ts

@@ -0,0 +1,65 @@
+import type { Coverage } from './run.js';
+
+/** Escapes a literal so it can sit inside a regular expression. */
+function escapeLiteral(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+}
+
+/**
+ * Compiles a coverage glob into a regular expression.
+ *
+ * `**` matches anything including `/`; `*` matches anything except `/`, so
+ * `https://a.example/*` covers `/orders` but not `/orders/123`; `?` matches one
+ * character. Everything else is literal.
+ */
+function globToRegExp(glob: string): RegExp {
+  let out = '';
+  for (let i = 0; i < glob.length; i++) {
+    const char = glob[i];
+    if (char === '*') {
+      if (glob[i + 1] === '*') {
+        out += '.*';
+        i++;
+      } else {
+        out += '[^/]*';
+      }
+    } else if (char === '?') {
+      out += '[^/]';
+    } else {
+      out += escapeLiteral(char);
+    }
+  }
+  return new RegExp(`^${out}$`, 'u');
+}
+
+/** The port in a location, where it states one. */
+function portOf(location: string): number | undefined {
+  const match = /^[a-z][a-z0-9+.-]*:\/\/[^/]*?:(\d+)(?:[/?#]|$)/iu.exec(location);
+  return match ? Number(match[1]) : undefined;
+}
+
+/**
+ * Whether a run could have found something at this location.
+ *
+ * **This is what makes auto-resolution safe.** A run only resolves what it
+ * could have found (invariant 5): a quick profile that skipped `/admin` must
+ * not close an `/admin` issue, because not looking is not the same as not
+ * finding. Anything outside coverage is left entirely alone — not resolved, and
+ * not counted as a miss either.
+ *
+ * A location matches when it matches at least one covered path glob, **and**,
+ * where both the location and the coverage state a port, that port was
+ * exercised. The port rule errs towards leaving issues open: a scan of `:443`
+ * says nothing about `:8443`.
+ *
+ * @param location - The issue's location.
+ * @param coverage - What the run exercised.
+ * @returns `true` if the run could have found it.
+ */
+export function coversLocation(location: string, coverage: Coverage): boolean {
+  const port = portOf(location);
+  if (port !== undefined && coverage.ports !== undefined && coverage.ports.length > 0) {
+    if (!coverage.ports.includes(port)) return false;
+  }
+  return coverage.paths.some((glob) => globToRegExp(glob).test(location));
+}

package/src/finding.ts

@@ -0,0 +1,112 @@
+import type { Severity, SeveritySource } from './severity.js';
+
+/**
+ * One detection, in one run.
+ *
+ * **Findings are immutable evidence.** A finding is never updated after it is
+ * recorded (invariant 1) and it carries no status: whether something is open,
+ * fixed or accepted is a property of the {@link Issue} it reconciles into, not
+ * of the evidence for it. If a field here would need to change as a human works
+ * on the problem, it belongs on the issue instead.
+ *
+ * Many findings, from many runs and many engines, fold into one issue by
+ * {@link Finding.fingerprint}.
+ */
+export interface Finding {
+  /** Unique id for this detection. */
+  readonly id: string;
+
+  /** Organisation this finding belongs to. Every query carries it. */
+  readonly orgId: string;
+
+  /** The run that produced it. */
+  readonly runId: string;
+
+  /**
+   * Content address of the underlying weakness, used to reconcile findings
+   * into a single issue across runs and engines.
+   *
+   * Derived from the target, the {@link Finding.vulnKey}, the normalised
+   * location and the parameter — never from volatile evidence such as tokens,
+   * timestamps or response bodies, which would make every run look new.
+   */
+  readonly fingerprint: string;
+
+  /**
+   * Which fingerprint algorithm produced {@link Finding.fingerprint}.
+   *
+   * **A public contract.** It travels with every fingerprint everywhere
+   * (invariant 8) so a stored fingerprint can always be interpreted, and
+   * changing the algorithm means a re-fingerprint migration that preserves
+   * history rather than a silent recomputation.
+   */
+  readonly fingerprintVersion: string;
+
+  /** Short human-readable name for the weakness. */
+  readonly title: string;
+
+  /** Fuller explanation of what was detected. */
+  readonly description?: string;
+
+  /**
+   * Severity as detected for this finding.
+   *
+   * What the evidence says. The issue's `effectiveSeverity` may differ, because
+   * a human may have overridden it.
+   */
+  readonly detectedSeverity: Severity;
+
+  /** Why {@link Finding.detectedSeverity} is what it is. */
+  readonly severitySource: SeveritySource;
+
+  /** CVSS base score, where the engine or advisory supplied one. */
+  readonly cvssScore?: number;
+
+  /** CVSS vector string, where one was supplied. */
+  readonly cvssVector?: string;
+
+  /** CWE identifier, e.g. `CWE-79`. */
+  readonly cwe?: string;
+
+  /** CVE identifier, e.g. `CVE-2026-1234`. */
+  readonly cve?: string;
+
+  /**
+   * Engine-independent key for the weakness class.
+   *
+   * This is what makes a Nuclei detection and a ZAP detection of the same
+   * weakness collide into one issue. Without it there is no cross-engine
+   * deduplication, only per-engine.
+   */
+  readonly vulnKey: string;
+
+  /** Broad grouping for reports, e.g. `injection`, `tls`, `access-control`. */
+  readonly category?: string;
+
+  /** Where it was found — a URL, host, port or file path. */
+  readonly location: string;
+
+  /** The specific parameter implicated, where the weakness has one. */
+  readonly parameter?: string;
+
+  /** Pointers to stored evidence: request/response captures, screenshots. */
+  readonly evidenceUri?: readonly string[];
+
+  /** What to do about it. */
+  readonly recommendation?: string;
+
+  /** External reading: advisories, vendor bulletins, standards. */
+  readonly references?: readonly string[];
+
+  /** Which engine detected it, e.g. `nuclei`, `zap`, `burp`, `nessus`. */
+  readonly sourceEngine: string;
+
+  /** The engine's own identifier for the rule that fired. */
+  readonly sourceRuleId?: string;
+
+  /** The engine's confidence, where it reports one, from 0 to 1. */
+  readonly confidence?: number;
+
+  /** When the finding was recorded. */
+  readonly createdAt: Date;
+}

package/src/fingerprint.ts

@@ -0,0 +1,315 @@
+import { createHash } from 'node:crypto';
+
+/**
+ * Which fingerprint algorithm this build of the package implements.
+ *
+ * **A public contract, and the most consequential string in the package.** It
+ * is stored on every finding and every issue, everywhere, so that a fingerprint
+ * recorded a year ago can still be interpreted. Changing the algorithm means
+ * bumping this *and* running a per-organisation re-fingerprint migration that
+ * preserves history — never a silent recomputation, which would orphan every
+ * issue whose evidence no longer hashes to the same value.
+ *
+ * If you are tempted to "just tweak" the normaliser, that is this constant's
+ * job to prevent.
+ */
+export const FINGERPRINT_VERSION = 'fp_v1';
+
+/** A path segment that is entirely digits, e.g. the `123` in `/orders/123`. */
+const NUMERIC_SEGMENT = /^\d+$/u;
+
+/** A path segment that is a UUID in the canonical 8-4-4-4-12 form. */
+const UUID_SEGMENT = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
+
+/**
+ * The placeholder that a variable path segment collapses to.
+ *
+ * Exported because it appears in normalised locations, which appear in reports
+ * and in support conversations: someone reading `/orders/{id}` should be able
+ * to find out what produced it.
+ */
+export const PATH_PLACEHOLDER = '{id}';
+
+/**
+ * Decodes percent-encoding exactly once, and never throws.
+ *
+ * Once, not repeatedly: decoding until stable would make `%2541` and `%41`
+ * collapse to the same thing, so a target that double-encodes could be made to
+ * collide with one that does not.
+ *
+ * Malformed encoding is left alone rather than rejected. A fingerprint that
+ * throws on strange input is a fingerprint that loses a finding.
+ */
+function decodeOnce(value: string): string {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+/**
+ * Collapses one path segment to {@link PATH_PLACEHOLDER} if it identifies a
+ * record rather than a route.
+ */
+function collapseSegment(segment: string): string {
+  if (NUMERIC_SEGMENT.test(segment) || UUID_SEGMENT.test(segment)) return PATH_PLACEHOLDER;
+  return segment;
+}
+
+/**
+ * Normalises a location so that the same weakness in the same place produces
+ * the same string, however the engine happened to write it down.
+ *
+ * This is the part of the fingerprint that decides whether `/orders/1` and
+ * `/orders/2` are one issue or two thousand. Applies, in order:
+ *
+ * - **Lowercases the host**, and converts an internationalised domain to
+ *   punycode, so `HTTPS://例え.テスト/x` and `https://xn--r8jz45g.xn--zckzah/x`
+ *   are one location.
+ * - **Drops a default port** (`:443` on https, `:80` on http) and keeps any
+ *   other, because `:8443` is a different service and `:443` is not.
+ * - **Decodes percent-encoding once.**
+ * - **Collapses numeric and UUID path segments** to `{id}`, so a per-record URL
+ *   does not open a per-record issue.
+ * - **Drops a trailing slash**, except on the root path where it is the path.
+ * - **Strips query values but keeps parameter names, sorted.** `?b=2&a=secret`
+ *   becomes `?a&b`. The names are structure and belong in identity; the values
+ *   are usually the payload that proved the weakness, which is evidence and
+ *   must never reach a fingerprint. Sorting means parameter order cannot split
+ *   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.
+ *
+ * @param location - Where the weakness was found.
+ * @returns The normalised location.
+ *
+ * @example
+ * ```ts
+ * normaliseLocation('HTTPS://API.Example.com:443/Orders/123/items/?b=2&a=secret#f');
+ * // 'https://api.example.com/Orders/{id}/items?a&b'
+ * ```
+ */
+export function normaliseLocation(location: string): string {
+  const trimmed = location.trim();
+
+  let url: URL | undefined;
+  try {
+    url = new URL(trimmed);
+  } catch {
+    url = undefined;
+  }
+
+  // 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);
+  }
+
+  // Not `decodeOnce` here: normalisePathOnly decodes, and decoding on the way
+  // in as well would decode twice — which would fold `%252F` into `%2F` into
+  // `/` and let a double-encoding target collide with a single-encoding one.
+  const path = normalisePathOnly(url.pathname);
+
+  // `url.host` already carries punycode and lower case, and omits a default
+  // port for the scheme.
+  const names = [...new Set([...url.searchParams.keys()].map(decodeOnce))].sort();
+  const query = names.length > 0 ? `?${names.join('&')}` : '';
+
+  return `${url.protocol}//${url.host}${path}${query}`;
+}
+
+/**
+ * Normalises a path with no scheme or host.
+ */
+function normalisePathOnly(path: string): string {
+  const decoded = decodeOnce(path.trim());
+  if (decoded === '' || decoded === '/') return decoded === '' ? '' : '/';
+
+  const collapsed = decoded
+    .split('/')
+    .map((segment) => collapseSegment(segment))
+    .join('/');
+
+  return collapsed.length > 1 && collapsed.endsWith('/') ? collapsed.slice(0, -1) : collapsed;
+}
+
+/**
+ * What a scanner said it found, in the terms needed to name the weakness.
+ */
+export interface VulnKeyInput {
+  /** Which engine detected it, e.g. `nuclei`, `zap`. */
+  readonly sourceEngine: string;
+
+  /** The engine's own identifier for the rule that fired. */
+  readonly sourceRuleId?: string;
+
+  /** CWE identifier, e.g. `CWE-79`. */
+  readonly cwe?: string;
+
+  /** Broad grouping, e.g. `injection`. */
+  readonly category?: string;
+}
+
+/**
+ * Maps `engine:ruleId` to a shared, engine-independent weakness key.
+ *
+ * **This table is the entire mechanism of cross-engine deduplication.** Without
+ * it a ZAP detection and a Nuclei detection of the same weakness fall back to
+ * CWE, and where either engine omits the CWE they never collide at all — you
+ * get per-engine tracking wearing the clothes of an issue tracker.
+ *
+ * **It is deliberately small, and that is not laziness.** A mapping asserts
+ * that a specific rule id means a specific weakness, and a wrong assertion
+ * silently merges two unrelated issues — worse than not mapping at all, because
+ * the merge is invisible. Rule ids cannot be known honestly until real scanner
+ * output has been parsed, which is what 4.4a and 4.4b do with committed
+ * fixtures. The table grows there, from evidence.
+ *
+ * **Entries must be added in pairs, per weakness, across engines — a half-filled
+ * table is worse than an empty one.** The mapping beats the CWE fallback, so
+ * mapping ZAP's HSTS rule while leaving Nuclei's unmapped gives them *different*
+ * keys, when falling back to `CWE-319` on both sides would have collided them
+ * correctly. Adding one engine's rule silently un-deduplicates the weakness.
+ * Found by importing a fixture from each engine and watching them stop
+ * agreeing.
+ *
+ * `00-DOMAIN.md` §10 leaves the eventual size open, leaning towards the top
+ * ~200 Nuclei templates plus ZAP's plugin list, with CWE fallback beyond.
+ *
+ * Keys are `${sourceEngine}:${sourceRuleId}`, both lowercased.
+ */
+export const VULN_KEY_MAP: Readonly<Record<string, string>> = Object.freeze({
+  // ZAP plugin ids are stable and documented, which is why the seed is ZAP's.
+  'zap:40012': 'xss-reflected',
+  'zap:40014': 'xss-persistent',
+  'zap:40018': 'sql-injection',
+  'zap:10038': 'csp-missing',
+  'zap:10035': 'hsts-missing',
+  'zap:10021': 'x-content-type-options-missing',
+  'zap:10020': 'x-frame-options-missing',
+
+  // Nuclei's side of the pairs above. Anything mapped for one engine and not
+  // the other stops the two agreeing, so these travel together.
+  'nuclei:xss-reflected': 'xss-reflected',
+  'nuclei:missing-hsts': 'hsts-missing',
+});
+
+/**
+ * The engine-independent key for a weakness class.
+ *
+ * Resolution order, per `00-DOMAIN.md` §4:
+ *
+ * 1. {@link VULN_KEY_MAP}, looked up by `engine:ruleId`.
+ * 2. `cwe` alone.
+ * 3. `category` alone.
+ * 4. `engine:ruleId` itself.
+ *
+ * **The spec says `cwe + '/' + category`, and that was tried and abandoned.**
+ * Engines do not share a category vocabulary: ZAP supplies no category at all,
+ * so reflected XSS there keys as `CWE-79`, while Nuclei tags the same finding
+ * `xss` and keys as `CWE-79/xss`. The two never collide — so the fallback
+ * actively prevented the cross-engine deduplication it exists to provide, which
+ * a fixture from each engine demonstrated immediately.
+ *
+ * CWE alone is coarser, and the coarseness is bounded: the fingerprint also
+ * carries the normalised location and the parameter, so two findings only merge
+ * when they share a weakness class *and* a place. Two genuinely different
+ * weaknesses under one CWE, at the same URL and parameter, is the case this
+ * gets wrong — and `POST /issues/{a}/merge/{b}` exists because something will.
+ *
+ * Steps 3 and 4 keep a finding trackable when there is no CWE at all. **Step 4
+ * never deduplicates across engines**, which is the honest outcome for a rule
+ * nobody has mapped: it tracks correctly and merges nothing it should not.
+ *
+ * @param input - What the engine reported.
+ * @returns The weakness key.
+ * @throws TypeError If nothing identifying is present at all.
+ */
+export function vulnKey(input: VulnKeyInput): string {
+  const engine = input.sourceEngine.trim().toLowerCase();
+  const ruleId = input.sourceRuleId?.trim().toLowerCase();
+
+  if (engine !== '' && ruleId !== undefined && ruleId !== '') {
+    const mapped = VULN_KEY_MAP[`${engine}:${ruleId}`];
+    if (mapped !== undefined) return mapped;
+  }
+
+  const cwe = input.cwe?.trim().toUpperCase();
+  const category = input.category?.trim().toLowerCase();
+
+  if (cwe !== undefined && cwe !== '') return cwe;
+  if (category !== undefined && category !== '') return category;
+  if (engine !== '' && ruleId !== undefined && ruleId !== '') return `${engine}:${ruleId}`;
+
+  throw new TypeError(
+    'cannot derive a vuln_key: a finding needs a mapped rule, a CWE, a category, or an engine rule id',
+  );
+}
+
+/**
+ * Everything the fingerprint is computed from.
+ *
+ * Note what is absent: no title, no description, no evidence, no timestamp, no
+ * severity. **Volatile evidence never enters a fingerprint** — a nonce or a
+ * response body in here would make every run look like a fresh discovery, and
+ * the product's whole claim is that it can tell you what changed.
+ */
+export interface FingerprintInput {
+  /**
+   * The target the finding is on.
+   *
+   * Part of identity, which has a surprising consequence worth stating: the
+   * same weakness in staging and in production is **two issues**. They are two
+   * systems, fixed separately, and a verification of one must never authorise
+   * the other.
+   */
+  readonly targetId: string;
+
+  /** The engine-independent weakness key, from {@link vulnKey}. */
+  readonly vulnKey: string;
+
+  /** Where it was found. Normalised by {@link normaliseLocation}. */
+  readonly location: string;
+
+  /** The parameter implicated, where the weakness has one. */
+  readonly parameter?: string;
+
+  /** The port, for findings that are about a service rather than a path. */
+  readonly port?: number;
+}
+
+/**
+ * The content address of a weakness: `sha256(targetId | vulnKey | normalised
+ * location | parameter ?? port ?? '')`.
+ *
+ * Deterministic and pure — the same input always gives the same digest, on any
+ * machine, in any order, at any time. That is what lets findings from different
+ * runs and different engines reconcile into one issue.
+ *
+ * Uses Node's `node:crypto`, which is a builtin rather than a dependency, so
+ * the package still installs nothing. It does mean fingerprinting requires
+ * Node; report rendering does not, and rendering is the only part of this
+ * package a browser was ever going to run.
+ *
+ * @param input - The identifying facts.
+ * @returns A lowercase hex SHA-256 digest.
+ *
+ * @example
+ * ```ts
+ * const key = vulnKey({ sourceEngine: 'zap', sourceRuleId: '40012' });
+ * fingerprint({ targetId: 'tgt_1', vulnKey: key, location: '/search', parameter: 'q' });
+ * ```
+ */
+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(
+    '|',
+  );
+
+  return createHash('sha256').update(material, 'utf8').digest('hex');
+}

package/src/import/burp.ts

@@ -0,0 +1,126 @@
+import type { Finding } from '../finding.js';
+import type { Severity } from '../severity.js';
+import { fingerprint, vulnKey, FINGERPRINT_VERSION } from '../fingerprint.js';
+import { childText, findAll, parseXml } from './xml.js';
+import type { ImportOptions } from './nuclei.js';
+
+/**
+ * Burp's severity vocabulary, mapped onto {@link Severity}.
+ *
+ * **Burp has no "critical" either.** Like ZAP it tops out at High, and
+ * `Information` is the bottom of the scale rather than a separate category.
+ */
+const BURP_SEVERITY: Readonly<Record<string, Severity>> = Object.freeze({
+  high: 'high',
+  medium: 'medium',
+  low: 'low',
+  information: 'advisory',
+  info: 'advisory',
+});
+
+/**
+ * Burp reports confidence in words. Mapped to a number so the model does not
+ * have to carry a second vocabulary for it.
+ */
+const BURP_CONFIDENCE: Readonly<Record<string, number>> = Object.freeze({
+  certain: 1,
+  firm: 0.7,
+  tentative: 0.4,
+});
+
+/**
+ * Burp writes the affected parameter into the location, not a field of its own.
+ *
+ * `/search [q parameter]` means the `q` parameter of `/search`. Pulling it out
+ * matters: the parameter is part of the fingerprint, so leaving it embedded in
+ * the path would make Burp's finding a different issue from ZAP's finding of the
+ * same weakness in the same place.
+ */
+function splitLocation(location: string): { path: string; parameter?: string } {
+  const match = /^(.*?)\s*\[\s*(.+?)\s+parameter\s*\]\s*$/iu.exec(location);
+  if (match) return { path: match[1].trim(), parameter: match[2].trim() };
+  return { path: location.trim() };
+}
+
+/**
+ * Turns a Burp Suite XML export into {@link Finding}s.
+ *
+ * Burp exports a flat `<issues>` document, one `<issue>` per detection, with the
+ * host and path in separate elements — so the location is assembled rather than
+ * read. Prose fields arrive as CDATA containing HTML, which is stripped.
+ *
+ * `<type>` is Burp's numeric issue type and is used as the rule id, because it
+ * is stable across versions where the human-readable `<name>` is not.
+ *
+ * @param xml - The contents of a Burp XML export.
+ * @param options - Ownership, and the injected clock and id source.
+ * @returns One finding per issue, in document order.
+ * @throws SyntaxError If the document is not well-formed XML.
+ */
+export function importBurp(xml: string, options: ImportOptions): Finding[] {
+  const root = parseXml(xml);
+  const findings: Finding[] = [];
+
+  for (const issue of findAll(root, 'issue')) {
+    const name = childText(issue, 'name');
+    const type = childText(issue, 'type');
+    if (name === undefined || type === undefined) continue;
+
+    const host = childText(issue, 'host') ?? '';
+    const raw = childText(issue, 'location') ?? childText(issue, 'path') ?? '';
+    const { path, parameter } = splitLocation(raw);
+    const location = path.startsWith('http') ? path : `${host}${path}`;
+    if (location === '') continue;
+
+    const cwe = childText(issue, 'vulnerabilityClassifications')
+      ?.match(/CWE-\d+/iu)?.[0]
+      ?.toUpperCase();
+
+    const key = vulnKey({
+      sourceEngine: 'burp',
+      sourceRuleId: type,
+      ...(cwe === undefined ? {} : { cwe }),
+    });
+
+    const confidence = BURP_CONFIDENCE[childText(issue, 'confidence')?.toLowerCase() ?? ''];
+    const background = childText(issue, 'issueBackground');
+    const remediation = childText(issue, 'remediationBackground');
+
+    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: name,
+      ...(background === undefined ? {} : { description: stripHtml(background) }),
+      detectedSeverity:
+        BURP_SEVERITY[childText(issue, 'severity')?.toLowerCase() ?? ''] ?? 'advisory',
+      severitySource: 'engine_default',
+      ...(cwe === undefined ? {} : { cwe }),
+      vulnKey: key,
+      location,
+      ...(parameter === undefined ? {} : { parameter }),
+      ...(remediation === undefined ? {} : { recommendation: stripHtml(remediation) }),
+      sourceEngine: 'burp',
+      sourceRuleId: type,
+      ...(confidence === undefined ? {} : { confidence }),
+      createdAt: options.now,
+    });
+  }
+
+  return findings;
+}
+
+/** Burp's prose fields are HTML inside CDATA. */
+function stripHtml(value: string): string {
+  return value
+    .replace(/<[^>]*>/gu, ' ')
+    .replace(/\s+/gu, ' ')
+    .trim();
+}