@secureport/core 0.2.1 → 0.4.0

package/src/import/generic.ts

@@ -0,0 +1,258 @@
+import type { Finding } from '../finding.js';
+import type { Severity, SeveritySource } from '../severity.js';
+import { SEVERITY_ORDER, severityFromCvss } from '../severity.js';
+import { fingerprint, vulnKey, FINGERPRINT_VERSION } from '../fingerprint.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[];
+}
+
+const SEVERITIES = new Set<string>(SEVERITY_ORDER);
+
+/** A non-empty trimmed string, or nothing. */
+const str = (v: unknown): string | undefined =>
+  typeof v === 'string' && v.trim() !== '' ? v.trim() : undefined;
+
+/** A finite number, or nothing. */
+const num = (v: unknown): number | undefined =>
+  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: string): string =>
+  title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/gu, '-')
+    .replace(/^-|-$/gu, '');
+
+/** An array of non-empty strings, or nothing. */
+const strArray = (v: unknown): string[] | undefined => {
+  if (!Array.isArray(v)) return undefined;
+  const items = (v as readonly unknown[]).map(str).filter((x): x is string => 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: string, options: ImportOptions): Finding[] {
+  const doc: unknown = JSON.parse(json);
+  if (typeof doc !== 'object' || doc === null) {
+    throw new TypeError('generic findings document must be an object');
+  }
+  const record = doc as Record<string, unknown>;
+
+  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 as readonly unknown[]).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 as Record<string, unknown>;
+
+    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: Severity;
+    let severitySource: SeveritySource;
+    if (score !== undefined && score >= 0 && score <= 10) {
+      detectedSeverity = severityFromCvss(score);
+      severitySource = 'cvss';
+    } else if (stated !== undefined) {
+      detectedSeverity = stated as Severity;
+      // 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,
+    } satisfies Finding;
+  });
+}

package/src/import/nessus.ts

@@ -0,0 +1,136 @@
+import type { Finding } from '../finding.js';
+import type { Severity, SeveritySource } from '../severity.js';
+import { severityFromCvss } from '../severity.js';
+import { fingerprint, vulnKey, FINGERPRINT_VERSION } from '../fingerprint.js';
+import { childText, findAll, parseXml } from './xml.js';
+import type { ImportOptions } from './nuclei.js';
+
+/**
+ * Nessus reports severity as a number on the `ReportItem`.
+ *
+ * `0` is Info, which is the bottom of the scale here rather than a separate
+ * category. Nessus does reach `4` (Critical), unlike ZAP and Burp.
+ */
+const NESSUS_SEVERITY: Readonly<Record<string, Severity>> = Object.freeze({
+  '4': 'critical',
+  '3': 'high',
+  '2': 'medium',
+  '1': 'low',
+  '0': 'advisory',
+});
+
+/**
+ * Turns a `.nessus` export into {@link Finding}s.
+ *
+ * Nessus is host-oriented: every `ReportItem` hangs off a `ReportHost`, and the
+ * port and protocol are attributes rather than part of a URL. The location is
+ * assembled as `host:port`, which is **the only place the port survives** —
+ * `00-DOMAIN.md` §3 defines no `port` on a finding, so anything not in the
+ * location is lost. A network finding with no path still fingerprints
+ * distinctly per service because the port is inside its location.
+ *
+ * A consequence worth knowing: the fingerprint's last component is
+ * `parameter ?? port ?? ''`, so a Nessus port is counted twice — once inside
+ * the location and once as that component. Harmless, but it means a port
+ * cannot be recovered from a finding except by parsing its location. Recorded
+ * as backlog **B42**.
+ *
+ * Severity comes from the CVSS v3 base score where Nessus supplies one, and from
+ * its own numeric rating otherwise.
+ *
+ * A `ReportItem` with severity `0` and no port — Nessus's host-inventory
+ * plugins — still imports: an advisory is still a finding, and dropping it here
+ * would make coverage look narrower than it was.
+ *
+ * @param xml - The contents of a `.nessus` file.
+ * @param options - Ownership, and the injected clock and id source.
+ * @returns One finding per report item, in document order.
+ * @throws SyntaxError If the document is not well-formed XML.
+ */
+export function importNessus(xml: string, options: ImportOptions): Finding[] {
+  const root = parseXml(xml);
+  const findings: Finding[] = [];
+
+  for (const host of findAll(root, 'ReportHost')) {
+    const hostName = host.attrs['name'] ?? '';
+
+    for (const item of findAll(host, 'ReportItem')) {
+      const pluginId = item.attrs['pluginID'];
+      const title = item.attrs['pluginName'];
+      if (pluginId === undefined || title === undefined) continue;
+
+      const portText = item.attrs['port'];
+      const port = portText !== undefined && portText !== '0' ? Number(portText) : undefined;
+      const location = port === undefined ? hostName : `${hostName}:${String(port)}`;
+      if (location === '') continue;
+
+      const scoreText = childText(item, 'cvss3_base_score') ?? childText(item, 'cvss_base_score');
+      const score = scoreText === undefined ? undefined : Number(scoreText);
+
+      let detectedSeverity: Severity;
+      let severitySource: SeveritySource;
+      if (score !== undefined && Number.isFinite(score) && score >= 0 && score <= 10) {
+        detectedSeverity = severityFromCvss(score);
+        severitySource = 'cvss';
+      } else {
+        detectedSeverity = NESSUS_SEVERITY[item.attrs['severity'] ?? ''] ?? 'advisory';
+        severitySource = 'engine_default';
+      }
+
+      // Nessus writes the bare number, e.g. `79`.
+      const rawCwe = childText(item, 'cwe');
+      const cwe = rawCwe === undefined ? undefined : `CWE-${rawCwe.replace(/^CWE-/iu, '')}`;
+      const family = item.attrs['pluginFamily'];
+
+      const key = vulnKey({
+        sourceEngine: 'nessus',
+        sourceRuleId: pluginId,
+        ...(cwe === undefined ? {} : { cwe }),
+        ...(family === undefined ? {} : { category: family }),
+      });
+
+      const references = childText(item, 'see_also')
+        ?.split(/\s+/u)
+        .filter((token) => token.startsWith('http'));
+
+      findings.push({
+        id: options.newId(),
+        orgId: options.orgId,
+        runId: options.runId,
+        fingerprint: fingerprint({
+          targetId: options.targetId,
+          vulnKey: key,
+          location,
+          ...(port === undefined ? {} : { port }),
+        }),
+        fingerprintVersion: FINGERPRINT_VERSION,
+        title,
+        ...(childText(item, 'description') === undefined
+          ? {}
+          : { description: childText(item, 'description')! }),
+        detectedSeverity,
+        severitySource,
+        ...(score === undefined || !Number.isFinite(score) ? {} : { cvssScore: score }),
+        ...(childText(item, 'cvss3_vector') === undefined
+          ? {}
+          : { cvssVector: childText(item, 'cvss3_vector')! }),
+        ...(cwe === undefined ? {} : { cwe }),
+        ...(childText(item, 'cve') === undefined
+          ? {}
+          : { cve: childText(item, 'cve')!.toUpperCase() }),
+        vulnKey: key,
+        ...(family === undefined ? {} : { category: family.toLowerCase() }),
+        location,
+        ...(childText(item, 'solution') === undefined
+          ? {}
+          : { recommendation: childText(item, 'solution')! }),
+        ...(references === undefined || references.length === 0 ? {} : { references }),
+        sourceEngine: 'nessus',
+        sourceRuleId: pluginId,
+        createdAt: options.now,
+      });
+    }
+  }
+
+  return findings;
+}

package/src/import/nuclei.ts

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