@secureport/core 0.2.1 → 0.4.0

package/dist/fingerprint.js

@@ -0,0 +1,247 @@
+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) {
+    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) {
+    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) {
+    const trimmed = location.trim();
+    let url;
+    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) {
+    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;
+}
+/**
+ * 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 = 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) {
+    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');
+}
+/**
+ * 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) {
+    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');
+}
+//# sourceMappingURL=fingerprint.js.map

package/dist/fingerprint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.js","sourceRoot":"","sources":["../src/fingerprint.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,OAAO,CAAC;AAE3C,+EAA+E;AAC/E,MAAM,eAAe,GAAG,QAAQ,CAAC;AAEjC,sEAAsE;AACtE,MAAM,YAAY,GAAG,kEAAkE,CAAC;AAExF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAEvC;;;;;;;;;GASG;AACH,SAAS,UAAU,CAAC,KAAa;IAC/B,IAAI,CAAC;QACH,OAAO,kBAAkB,CAAC,KAAK,CAAC,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAS,eAAe,CAAC,OAAe;IACtC,IAAI,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,gBAAgB,CAAC;IACzF,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB;IAChD,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;IAEhC,IAAI,GAAoB,CAAC;IACzB,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,GAAG,GAAG,SAAS,CAAC;IAClB,CAAC;IAED,6EAA6E;IAC7E,mEAAmE;IACnE,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,QAAQ,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;QAC7C,OAAO,iBAAiB,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC;IAED,4EAA4E;IAC5E,2EAA2E;IAC3E,2EAA2E;IAC3E,MAAM,IAAI,GAAG,iBAAiB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAE7C,0EAA0E;IAC1E,uBAAuB;IACvB,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAChF,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAE5D,OAAO,GAAG,GAAG,CAAC,QAAQ,KAAK,GAAG,CAAC,IAAI,GAAG,IAAI,GAAG,KAAK,EAAE,CAAC;AACvD,CAAC;AAED;;GAEG;AACH,SAAS,iBAAiB,CAAC,IAAY;IACrC,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IACxC,IAAI,OAAO,KAAK,EAAE,IAAI,OAAO,KAAK,GAAG;QAAE,OAAO,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;IAExE,MAAM,SAAS,GAAG,OAAO;SACtB,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;SAC1C,IAAI,CAAC,GAAG,CAAC,CAAC;IAEb,OAAO,SAAS,CAAC,MAAM,GAAG,CAAC,IAAI,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC9F,CAAC;AAmBD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,CAAC,MAAM,YAAY,GAAqC,MAAM,CAAC,MAAM,CAAC;IAC1E,4EAA4E;IAC5E,WAAW,EAAE,eAAe;IAC5B,WAAW,EAAE,gBAAgB;IAC7B,WAAW,EAAE,eAAe;IAC5B,WAAW,EAAE,aAAa;IAC1B,WAAW,EAAE,cAAc;IAC3B,WAAW,EAAE,gCAAgC;IAC7C,WAAW,EAAE,yBAAyB;IAEtC,2EAA2E;IAC3E,8DAA8D;IAC9D,sBAAsB,EAAE,eAAe;IACvC,qBAAqB,EAAE,cAAc;CACtC,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,OAAO,CAAC,KAAmB;IACzC,MAAM,MAAM,GAAG,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACvD,MAAM,MAAM,GAAG,KAAK,CAAC,YAAY,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAExD,IAAI,MAAM,KAAK,EAAE,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,EAAE,EAAE,CAAC;QAC3D,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,MAAM,IAAI,MAAM,EAAE,CAAC,CAAC;QACnD,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,MAAM,CAAC;IAC1C,CAAC;IAED,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC5C,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAEtD,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,EAAE;QAAE,OAAO,GAAG,CAAC;IAChD,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,EAAE;QAAE,OAAO,QAAQ,CAAC;IAC/D,IAAI,MAAM,KAAK,EAAE,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,EAAE;QAAE,OAAO,GAAG,MAAM,IAAI,MAAM,EAAE,CAAC;IAEzF,MAAM,IAAI,SAAS,CACjB,kGAAkG,CACnG,CAAC;AACJ,CAAC;AAkCD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,WAAW,CAAC,KAAuB;IACjD,MAAM,IAAI,GAAG,KAAK,CAAC,SAAS,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACrF,MAAM,QAAQ,GAAG,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,OAAO,EAAE,iBAAiB,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC,CAAC,IAAI,CAC5F,GAAG,CACJ,CAAC;IAEF,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACrE,CAAC"}

package/dist/import/burp.d.ts

@@ -0,0 +1,19 @@
+import type { Finding } from '../finding.js';
+import type { ImportOptions } from './nuclei.js';
+/**
+ * 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 declare function importBurp(xml: string, options: ImportOptions): Finding[];
+//# sourceMappingURL=burp.d.ts.map

package/dist/import/burp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"burp.d.ts","sourceRoot":"","sources":["../../src/import/burp.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAI7C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAwCjD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,EAAE,CA0DzE"}

package/dist/import/burp.js

@@ -0,0 +1,114 @@
+import { fingerprint, vulnKey, FINGERPRINT_VERSION } from '../fingerprint.js';
+import { childText, findAll, parseXml } from './xml.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 = 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 = 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) {
+    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, options) {
+    const root = parseXml(xml);
+    const findings = [];
+    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) {
+    return value
+        .replace(/<[^>]*>/gu, ' ')
+        .replace(/\s+/gu, ' ')
+        .trim();
+}
+//# sourceMappingURL=burp.js.map

package/dist/import/burp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"burp.js","sourceRoot":"","sources":["../../src/import/burp.ts"],"names":[],"mappings":"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"}

package/dist/import/generic.d.ts

@@ -0,0 +1,90 @@
+import type { Finding } from '../finding.js';
+import type { Severity } from '../severity.js';
+import type { ImportOptions } from './nuclei.js';
+/**
+ * One finding in the generic Secureport format.
+ *
+ * **Written last, on purpose.** This is the shape the four scanner importers
+ * turned out to have in common, rather than a format designed in advance and
+ * then argued with. Everything an engine reliably supplies is here; everything
+ * only one of them had is not.
+ *
+ * Only `title` and `location` are required. A tool that knows nothing but "this
+ * is wrong, and it is here" can still produce a trackable finding — which is the
+ * point of having a generic format at all.
+ */
+export interface GenericFinding {
+    /** What is wrong. */
+    readonly title: string;
+    /** Where it is — a URL, a host, a `host:port`, or a file path. */
+    readonly location: string;
+    /** Fuller explanation. */
+    readonly description?: string;
+    /**
+     * Severity, if the tool rates it.
+     *
+     * Ignored when `cvssScore` is present: a score is more precise than a word,
+     * and `severitySource` records which was used.
+     */
+    readonly severity?: Severity;
+    /** CVSS base score, 0–10. Preferred over `severity` when both are given. */
+    readonly cvssScore?: number;
+    /** CVSS vector string. */
+    readonly cvssVector?: string;
+    /** CWE identifier, with or without the `CWE-` prefix. */
+    readonly cwe?: string;
+    /** CVE identifier. */
+    readonly cve?: string;
+    /** Broad grouping, e.g. `injection`. */
+    readonly category?: string;
+    /** The parameter implicated, where the weakness has one. */
+    readonly parameter?: string;
+    /** The port, for findings about a service rather than a path. */
+    readonly port?: number;
+    /** What produced it. Defaults to `generic`. */
+    readonly engine?: string;
+    /** The producing tool's own identifier for the rule. */
+    readonly ruleId?: string;
+    /** What to do about it. */
+    readonly recommendation?: string;
+    /** Further reading. */
+    readonly references?: readonly string[];
+    /** Pointers to stored evidence. */
+    readonly evidenceUri?: readonly string[];
+    /** The tool's confidence, 0–1. */
+    readonly confidence?: number;
+}
+/** A generic findings document. */
+export interface GenericDocument {
+    /**
+     * Format version.
+     *
+     * Present so this file can change shape later without guessing. An unknown
+     * version is refused rather than parsed optimistically.
+     */
+    readonly version: 1;
+    /** The findings. */
+    readonly findings: readonly GenericFinding[];
+}
+/**
+ * Turns the generic Secureport format into {@link Finding}s.
+ *
+ * The escape hatch for everything with no importer of its own: a manual test, an
+ * internal tool, a scanner nobody has written a parser for. Fingerprinting,
+ * reconciliation and reports then work identically — a finding that arrives this
+ * way is not a second-class finding.
+ *
+ * Refuses the document rather than salvaging part of it. Unlike Nuclei's JSONL,
+ * where one bad line costs one record, this is a single document a human or a
+ * script wrote deliberately: a field in the wrong shape is a mistake worth
+ * hearing about, not one to route around silently.
+ *
+ * @param json - The contents of a generic findings document.
+ * @param options - Ownership, and the injected clock and id source.
+ * @returns One finding per entry, in document order.
+ * @throws SyntaxError If the text is not valid JSON.
+ * @throws TypeError If the document is not the expected shape, naming the entry
+ * and field at fault.
+ */
+export declare function importGeneric(json: string, options: ImportOptions): Finding[];
+//# sourceMappingURL=generic.d.ts.map

package/dist/import/generic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generic.d.ts","sourceRoot":"","sources":["../../src/import/generic.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,KAAK,EAAE,QAAQ,EAAkB,MAAM,gBAAgB,CAAC;AAG/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,cAAc;IAC7B,qBAAqB;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,0BAA0B;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAE9B;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAE7B,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B,0BAA0B;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B,yDAAyD;IACzD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAEtB,sBAAsB;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAEtB,wCAAwC;IACxC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B,4DAA4D;IAC5D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B,iEAAiE;IACjE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEvB,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEzB,wDAAwD;IACxD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEzB,2BAA2B;IAC3B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IAEjC,uBAAuB;IACvB,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAExC,mCAAmC;IACnC,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAEzC,kCAAkC;IAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,mCAAmC;AACnC,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IAEpB,oBAAoB;IACpB,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;CAC9C;AAuCD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,EAAE,CA8G7E"}

package/dist/import/generic.js

@@ -0,0 +1,159 @@
+import { SEVERITY_ORDER, severityFromCvss } from '../severity.js';
+import { fingerprint, vulnKey, FINGERPRINT_VERSION } from '../fingerprint.js';
+const SEVERITIES = new Set(SEVERITY_ORDER);
+/** A non-empty trimmed string, or nothing. */
+const str = (v) => typeof v === 'string' && v.trim() !== '' ? v.trim() : undefined;
+/** A finite number, or nothing. */
+const num = (v) => typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+/**
+ * A title reduced to something usable as a weakness key.
+ *
+ * The last resort, and only for the generic format. A tool that reports nothing
+ * but "this is wrong, and it is here" has no CWE, no category and no rule id —
+ * and `vulnKey` would rightly refuse, because there is nothing to key on.
+ * Refusing would mean the minimal case cannot be imported at all, which defeats
+ * the point of having a generic format.
+ *
+ * **Titles are a poor key and this is not pretending otherwise:** reword the
+ * title and the issue becomes a different issue, and two tools describing the
+ * same weakness differently never collide. Supplying a `ruleId`, a `cwe` or a
+ * `category` is strictly better and all three are preferred over this.
+ */
+const titleKey = (title) => title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/gu, '-')
+    .replace(/^-|-$/gu, '');
+/** An array of non-empty strings, or nothing. */
+const strArray = (v) => {
+    if (!Array.isArray(v))
+        return undefined;
+    const items = v.map(str).filter((x) => x !== undefined);
+    return items.length > 0 ? items : undefined;
+};
+/**
+ * Turns the generic Secureport format into {@link Finding}s.
+ *
+ * The escape hatch for everything with no importer of its own: a manual test, an
+ * internal tool, a scanner nobody has written a parser for. Fingerprinting,
+ * reconciliation and reports then work identically — a finding that arrives this
+ * way is not a second-class finding.
+ *
+ * Refuses the document rather than salvaging part of it. Unlike Nuclei's JSONL,
+ * where one bad line costs one record, this is a single document a human or a
+ * script wrote deliberately: a field in the wrong shape is a mistake worth
+ * hearing about, not one to route around silently.
+ *
+ * @param json - The contents of a generic findings document.
+ * @param options - Ownership, and the injected clock and id source.
+ * @returns One finding per entry, in document order.
+ * @throws SyntaxError If the text is not valid JSON.
+ * @throws TypeError If the document is not the expected shape, naming the entry
+ * and field at fault.
+ */
+export function importGeneric(json, options) {
+    const doc = JSON.parse(json);
+    if (typeof doc !== 'object' || doc === null) {
+        throw new TypeError('generic findings document must be an object');
+    }
+    const record = doc;
+    if (record['version'] !== 1) {
+        throw new TypeError(`unsupported generic findings version: ${String(record['version'])}`);
+    }
+    const raw = record['findings'];
+    if (!Array.isArray(raw)) {
+        throw new TypeError('generic findings document has no `findings` array');
+    }
+    return raw.map((item, index) => {
+        const where = `findings[${String(index)}]`;
+        if (typeof item !== 'object' || item === null) {
+            throw new TypeError(`${where} is not an object`);
+        }
+        const entry = item;
+        const title = str(entry['title']);
+        const location = str(entry['location']);
+        if (title === undefined)
+            throw new TypeError(`${where}.title is required`);
+        if (location === undefined)
+            throw new TypeError(`${where}.location is required`);
+        const stated = str(entry['severity']);
+        if (stated !== undefined && !SEVERITIES.has(stated)) {
+            throw new TypeError(`${where}.severity is not a severity: ${stated}`);
+        }
+        const score = num(entry['cvssScore']);
+        let detectedSeverity;
+        let severitySource;
+        if (score !== undefined && score >= 0 && score <= 10) {
+            detectedSeverity = severityFromCvss(score);
+            severitySource = 'cvss';
+        }
+        else if (stated !== undefined) {
+            detectedSeverity = stated;
+            // Somebody stated it for this finding specifically, which is the
+            // strongest provenance there is.
+            severitySource = 'explicit';
+        }
+        else {
+            detectedSeverity = 'advisory';
+            severitySource = 'engine_default';
+        }
+        const engine = str(entry['engine']) ?? 'generic';
+        const ruleId = str(entry['ruleId']);
+        const rawCwe = str(entry['cwe']);
+        const cwe = rawCwe === undefined ? undefined : `CWE-${rawCwe.replace(/^CWE-/iu, '')}`;
+        const category = str(entry['category']);
+        const parameter = str(entry['parameter']);
+        const port = num(entry['port']);
+        // Nothing classifies this finding, so key on the title rather than refuse
+        // it. `sourceRuleId` stays absent: the tool supplied none, and recording a
+        // slug as though it had would be a lie about provenance.
+        const key = cwe === undefined && category === undefined && ruleId === undefined
+            ? `${engine}:${titleKey(title)}`
+            : vulnKey({
+                sourceEngine: engine,
+                ...(ruleId === undefined ? {} : { sourceRuleId: ruleId }),
+                ...(cwe === undefined ? {} : { cwe }),
+                ...(category === undefined ? {} : { category }),
+            });
+        return {
+            id: options.newId(),
+            orgId: options.orgId,
+            runId: options.runId,
+            fingerprint: fingerprint({
+                targetId: options.targetId,
+                vulnKey: key,
+                location,
+                ...(parameter === undefined ? {} : { parameter }),
+                ...(port === undefined ? {} : { port }),
+            }),
+            fingerprintVersion: FINGERPRINT_VERSION,
+            title,
+            ...(str(entry['description']) === undefined
+                ? {}
+                : { description: str(entry['description']) }),
+            detectedSeverity,
+            severitySource,
+            ...(score === undefined ? {} : { cvssScore: score }),
+            ...(str(entry['cvssVector']) === undefined ? {} : { cvssVector: str(entry['cvssVector']) }),
+            ...(cwe === undefined ? {} : { cwe }),
+            ...(str(entry['cve']) === undefined ? {} : { cve: str(entry['cve']).toUpperCase() }),
+            vulnKey: key,
+            ...(category === undefined ? {} : { category: category.toLowerCase() }),
+            location,
+            ...(parameter === undefined ? {} : { parameter }),
+            ...(strArray(entry['evidenceUri']) === undefined
+                ? {}
+                : { evidenceUri: strArray(entry['evidenceUri']) }),
+            ...(str(entry['recommendation']) === undefined
+                ? {}
+                : { recommendation: str(entry['recommendation']) }),
+            ...(strArray(entry['references']) === undefined
+                ? {}
+                : { references: strArray(entry['references']) }),
+            sourceEngine: engine,
+            ...(ruleId === undefined ? {} : { sourceRuleId: ruleId }),
+            ...(num(entry['confidence']) === undefined ? {} : { confidence: num(entry['confidence']) }),
+            createdAt: options.now,
+        };
+    });
+}
+//# sourceMappingURL=generic.js.map