@secureport/core 0.3.0 → 1.0.0-rc.0

package/dist/report/model.js

@@ -0,0 +1,197 @@
+import { SEVERITY_ORDER } from '../severity.js';
+/** Works out what a run established about the issues carried into it. */
+function describeRetest(snapshot) {
+    const { baseline } = snapshot;
+    if (baseline === undefined)
+        return undefined;
+    const entries = snapshot.issues.map((issue) => ({
+        issue,
+        verdict: verdictFor(issue),
+    }));
+    // `SEVERITY_ORDER` rather than `severityRank`, which counts the other way:
+    // it returns 4 for `critical` so that a larger number is a worse problem.
+    // Sorting on it ascending put the advisories at the top of the table, which
+    // is how this shipped until a golden file showed it.
+    entries.sort((a, b) => {
+        const bySeverity = SEVERITY_ORDER.indexOf(a.issue.issue.effectiveSeverity) -
+            SEVERITY_ORDER.indexOf(b.issue.issue.effectiveSeverity);
+        return bySeverity === 0
+            ? b.issue.issue.lastSeen.getTime() - a.issue.issue.lastSeen.getTime()
+            : bySeverity;
+    });
+    const counts = {
+        fixed: 0,
+        still_present: 0,
+        returned: 0,
+        not_retested: 0,
+        new: 0,
+    };
+    for (const entry of entries)
+        counts[entry.verdict]++;
+    const checkable = counts.fixed + counts.still_present + counts.returned;
+    return {
+        baseline,
+        entries,
+        counts,
+        fixRate: checkable === 0 ? null : counts.fixed / checkable,
+    };
+}
+/**
+ * The verdict for one issue.
+ *
+ * Turns on whether this run produced evidence for it, not on its status alone:
+ * an issue left open because the run never covered it looks identical to one
+ * left open because the run found it again, and telling a reader those are the
+ * same thing is the failure this report exists to avoid.
+ */
+function verdictFor(entry) {
+    if (entry.change === 'resolved')
+        return 'fixed';
+    if (entry.change === 'regressed')
+        return 'returned';
+    if (entry.change === 'new')
+        return 'new';
+    return entry.findings.length > 0 ? 'still_present' : 'not_retested';
+}
+/** Works out what a report cannot establish, from the run rather than a template. */
+function describeLimitations(snapshot, basis) {
+    const limitations = [];
+    if (!basis.includesManual) {
+        limitations.push('This is evidence of automated security testing. It is not a human-led penetration ' +
+            'test and does not carry the assurance of one.');
+    }
+    limitations.push('Findings should be verified by a qualified technician before this document is relied ' +
+        'upon as audit evidence.');
+    limitations.push(`Testing covered only ${snapshot.run.coverage.paths.join(', ')}. Anything outside that ` +
+        'was not examined, and its absence from this document is not evidence that it is sound.');
+    limitations.push(`This reflects the state of the target as of ${snapshot.run.createdAt
+        .toISOString()
+        .slice(0, 10)}. It says nothing about the target before or after that date.`);
+    limitations.push('Automated testing cannot establish the absence of a vulnerability. A clean result means ' +
+        'nothing was detected, not that nothing is there.');
+    if (snapshot.suppressed.length > 0) {
+        limitations.push(`${snapshot.suppressed.length} finding${snapshot.suppressed.length === 1 ? ' has' : 's have'} been ` +
+            'suppressed and excluded from the counts above. They are listed in full in the appendix.');
+    }
+    limitations.push('This document does not certify compliance with any standard, framework or regulation.');
+    return limitations;
+}
+const DEFAULT_TITLES = Object.freeze({
+    pen: 'Penetration Test Report',
+    vap: 'Vulnerability Assessment Report',
+    exec: 'Executive Summary',
+    attest: 'Attestation of Security Testing',
+    retest: 'Retest Report',
+});
+/** Works out how the findings were produced, from the run rather than a claim. */
+function describeBasis(snapshot) {
+    const kind = snapshot.run.kind;
+    const engines = snapshot.run.engines;
+    const includesManual = snapshot.issues.some((i) => i.issue.origin === 'manual');
+    const automated = kind === 'scan';
+    const uploaded = kind === 'upload';
+    const parts = [];
+    if (automated) {
+        parts.push('Findings were produced by automated vulnerability scanning against the scope described below.');
+    }
+    if (uploaded) {
+        parts.push('Findings were imported from an external testing tool and reconciled against previous runs.');
+    }
+    if (kind === 'manual')
+        parts.push('Findings were recorded manually by a tester.');
+    if (includesManual && kind !== 'manual') {
+        parts.push('Some findings were recorded manually by a tester.');
+    }
+    if (!includesManual && kind !== 'manual') {
+        parts.push('No part of this assessment constitutes a manual penetration test.');
+    }
+    if (automated || uploaded) {
+        parts.push('Automated findings should be verified by a qualified technician before this report is ' +
+            'submitted as audit evidence.');
+    }
+    return { includesManual, automated, uploaded, engines, statement: parts.join(' ') };
+}
+/**
+ * Derives everything a report shows, once, from a snapshot.
+ *
+ * Both renderers consume this rather than the snapshot, so a number in the
+ * Markdown and the same number in the HTML cannot drift apart — they are the
+ * same value formatted twice.
+ *
+ * Suppressed issues are already separated by the snapshot and stay separated
+ * here: they never reach {@link ReportModel.sections}, are excluded from
+ * {@link ReportModel.outstanding} and from the exposure score, and appear only
+ * in the suppressed appendix (invariant 7).
+ *
+ * @param snapshot - Issue state as of a run.
+ * @param options - Title, attribution, and the render time.
+ * @returns The model both renderers format.
+ */
+export function buildReportModel(snapshot, options) {
+    const outstanding = {
+        critical: 0,
+        high: 0,
+        medium: 0,
+        low: 0,
+        advisory: 0,
+    };
+    const bySeverity = new Map();
+    const resolved = [];
+    let breached = 0;
+    for (const entry of snapshot.issues) {
+        if (entry.issue.status === 'resolved') {
+            resolved.push(entry);
+            continue;
+        }
+        const severity = entry.issue.effectiveSeverity;
+        const group = bySeverity.get(severity);
+        if (group)
+            group.push(entry);
+        else
+            bySeverity.set(severity, [entry]);
+        if (entry.issue.status === 'open' || entry.issue.status === 'regressed') {
+            outstanding[severity]++;
+            if (entry.slaStatus === 'breached')
+                breached++;
+        }
+    }
+    resolved.sort((a, b) => b.issue.lastSeen.getTime() - a.issue.lastSeen.getTime());
+    const sections = [];
+    for (const severity of SEVERITY_ORDER) {
+        const issues = bySeverity.get(severity);
+        if (issues === undefined || issues.length === 0)
+            continue;
+        sections.push({
+            severity,
+            // Most recently seen first: what a reader wants at the top of a section
+            // is what the latest run actually found.
+            issues: [...issues].sort((a, b) => b.issue.lastSeen.getTime() - a.issue.lastSeen.getTime()),
+        });
+    }
+    const outstandingTotal = SEVERITY_ORDER.reduce((sum, s) => sum + outstanding[s], 0);
+    const basis = describeBasis(snapshot);
+    const retest = describeRetest(snapshot);
+    // Rendering a retest of nothing is the over-claim §7 warns about: the
+    // document's whole content is a comparison, and one run does not have one.
+    if (options.kind === 'retest' && retest === undefined) {
+        throw new TypeError('a retest report needs a baseline: build the snapshot with `previous` set to the run being retested');
+    }
+    return {
+        kind: options.kind,
+        title: options.title ?? DEFAULT_TITLES[options.kind],
+        snapshot,
+        generatedAt: options.now,
+        ...(options.preparedBy === undefined ? {} : { preparedBy: options.preparedBy }),
+        ...(options.preparedFor === undefined ? {} : { preparedFor: options.preparedFor }),
+        basis,
+        limitations: describeLimitations(snapshot, basis),
+        sections,
+        resolved,
+        outstanding,
+        outstandingTotal,
+        exposureScore: snapshot.run.exposureScore,
+        breached,
+        ...(retest === undefined ? {} : { retest }),
+    };
+}
+//# sourceMappingURL=model.js.map

package/dist/report/model.js.map

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

package/dist/snapshot-builder.d.ts

@@ -62,9 +62,17 @@ export declare function buildSnapshot(input: BuildSnapshotInput): Snapshot;
  *
  * Use this rather than `JSON.parse` for any snapshot read back from disk.
  *
+ * **It checks the shape, because this is where untrusted JSON enters.** A
+ * snapshot arrives from a file somebody chose, and the signature promises a
+ * `Snapshot` — so returning whatever parsed and letting the caller discover
+ * the difference is the function lying about its own return type. The check is
+ * deliberately shallow: the top-level shape, which is enough to tell a
+ * snapshot from any other JSON document and to make the failure say so.
+ *
  * @param json - The contents of a snapshot file.
  * @returns The snapshot, with dates revived.
  * @throws SyntaxError If the text is not valid JSON.
+ * @throws TypeError If the JSON parsed but is not a snapshot.
  */
 export declare function parseSnapshot(json: string): Snapshot;
 //# sourceMappingURL=snapshot-builder.d.ts.map

package/dist/snapshot-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"snapshot-builder.d.ts","sourceRoot":"","sources":["../src/snapshot-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,KAAK,EAAe,QAAQ,EAAkC,MAAM,EAAE,MAAM,eAAe,CAAC;AACnG,OAAO,EAAiC,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAG9E;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,6BAA6B;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAElB,gCAAgC;IAChC,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IAEtC;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAE7B,oCAAoC;IACpC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC;IAEnB,0CAA0C;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,MAAM,CAAC;IAE7B,2BAA2B;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAE/B,4DAA4D;IAC5D,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAEvC,6BAA6B;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAuBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,QAAQ,CAyEjE;AAiBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAQpD"}
+{"version":3,"file":"snapshot-builder.d.ts","sourceRoot":"","sources":["../src/snapshot-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,KAAK,EAAe,QAAQ,EAAkC,MAAM,EAAE,MAAM,eAAe,CAAC;AACnG,OAAO,EAAiC,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAG9E;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,6BAA6B;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAElB,gCAAgC;IAChC,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IAEtC;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAE7B,oCAAoC;IACpC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC;IAEnB,0CAA0C;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,MAAM,CAAC;IAE7B,2BAA2B;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAE/B,4DAA4D;IAC5D,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAEvC,6BAA6B;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAuBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,QAAQ,CAyEjE;AAiBD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CA0BpD"}

package/dist/snapshot-builder.js

@@ -131,12 +131,20 @@ const DATE_FIELDS = new Set([
  *
  * Use this rather than `JSON.parse` for any snapshot read back from disk.
  *
+ * **It checks the shape, because this is where untrusted JSON enters.** A
+ * snapshot arrives from a file somebody chose, and the signature promises a
+ * `Snapshot` — so returning whatever parsed and letting the caller discover
+ * the difference is the function lying about its own return type. The check is
+ * deliberately shallow: the top-level shape, which is enough to tell a
+ * snapshot from any other JSON document and to make the failure say so.
+ *
  * @param json - The contents of a snapshot file.
  * @returns The snapshot, with dates revived.
  * @throws SyntaxError If the text is not valid JSON.
+ * @throws TypeError If the JSON parsed but is not a snapshot.
  */
 export function parseSnapshot(json) {
-    return JSON.parse(json, (key, value) => {
+    const parsed = JSON.parse(json, (key, value) => {
         if (DATE_FIELDS.has(key) && typeof value === 'string') {
             const parsed = new Date(value);
             if (!Number.isNaN(parsed.getTime()))
@@ -144,5 +152,21 @@ export function parseSnapshot(json) {
         }
         return value;
     });
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new TypeError('not a snapshot: expected a JSON object');
+    }
+    const record = parsed;
+    for (const field of ['run', 'target']) {
+        const value = record[field];
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+            throw new TypeError(`not a snapshot: \`${field}\` is missing`);
+        }
+    }
+    for (const field of ['issues', 'suppressed']) {
+        if (!Array.isArray(record[field])) {
+            throw new TypeError(`not a snapshot: \`${field}\` is missing`);
+        }
+    }
+    return parsed;
 }
 //# sourceMappingURL=snapshot-builder.js.map

package/dist/snapshot-builder.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@secureport/core",
-  "version": "0.3.0",
+  "version": "1.0.0-rc.0",
   "description": "Shared domain model for Secureport. Imported by the hosted API the same way a third party would.",
   "keywords": [
     "security",
@@ -18,9 +18,9 @@
     "nessus",
     "security-reporting"
   ],
-  "homepage": "https://github.com/agbjordan/secureport/tree/main/packages/core#readme",
+  "homepage": "https://secureport.io/",
   "bugs": {
-    "url": "https://github.com/agbjordan/secureport/issues"
+    "email": "hello@secureport.io"
   },
   "type": "module",
   "main": "./dist/index.js",

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();
+}