@ulisesgascon/openjs-cna-tools 1.0.0-alpha.1 → 1.0.0-alpha.4

package/lib/batch.js

@@ -0,0 +1,141 @@
+// Review and publish several CVE Records in one go.
+//
+// This is the "all or none" flow a release pipeline wants: every record is
+// reviewed first and nothing is sent unless all of them pass. Publication
+// itself is best effort per record, since MITRE has no batch operation and
+// the records are independent; a failed id is reported and the rest still
+// go out. `--skip-published` style reruns are supported by asking the CNA
+// whether an id already has a published container before sending it.
+//
+// Both functions take `entries`: an array of `{ record, file? }` where
+// `record` is a full v5.2 CVE Record (`containers.cna` plus `cveMetadata`)
+// and `file` is only used to label output. The CLI `review` and `publish`
+// commands are thin wrappers over them.
+
+import { reviewRecord } from './review/index.js'
+import { CnaOperationError } from './errors.js'
+
+function labelOf (entry) {
+  return entry.record?.cveMetadata?.cveId ?? entry.file ?? '<record>'
+}
+
+/**
+ * Review every entry. Never stops early, so the caller sees all problems at
+ * once. A record without `cveMetadata.cveId` gets an extra blocker: in a
+ * batch there is no CLI argument to fall back on for the id.
+ *
+ * Returns `[{ file, cveId, ready, summary, issues }]` in input order.
+ */
+export function reviewRecords (entries, { strict = true } = {}) {
+  return entries.map((entry) => {
+    const report = reviewRecord(entry.record, { strict })
+    const cveId = entry.record?.cveMetadata?.cveId
+    const issues = [...report.issues]
+    const summary = { ...report.summary }
+    if (!cveId) {
+      issues.unshift({
+        rule: 'cve-id-present',
+        tier: 'mitre-common',
+        severity: 'blocker',
+        path: 'cveMetadata.cveId',
+        message: 'Record carries no cveMetadata.cveId; batch publish needs one per record'
+      })
+      summary.blockers += 1
+      summary.rating = 'blocked'
+    }
+    return {
+      file: entry.file,
+      cveId,
+      ready: summary.blockers === 0,
+      summary,
+      issues
+    }
+  })
+}
+
+// `getCve` resolves with the container when MITRE has a published record.
+// For a RESERVED id there is nothing to fetch and the CNA either fails the
+// run or completes it with an empty result; neither is pinned down, so
+// only positive evidence counts: an operational failure, or a result that
+// does not look like a record, means "not published" and the id is sent.
+// Erring towards publishing is the safe side, since the CNA rejects a
+// second publish loudly while a wrong skip would exit 0 having sent
+// nothing. Auth and timeout errors propagate so a broken setup does not
+// look like a clean slate.
+async function isPublished (client, cveId) {
+  let result
+  try {
+    result = await client.getCve(cveId)
+  } catch (error) {
+    if (error instanceof CnaOperationError) return false
+    throw error
+  }
+  const cna = result?.containers?.cna ?? result
+  return result?.cveMetadata?.state === 'PUBLISHED' ||
+    Array.isArray(cna?.descriptions) ||
+    Array.isArray(cna?.affected)
+}
+
+/**
+ * Review every entry, then publish each one through `client.publishCve`.
+ *
+ * Options:
+ *   client        — a CnaClient (required unless every record is skipped)
+ *   strict        — reviewer strictness (default true, warnings block)
+ *   skipReview    — publish without reviewing (discouraged)
+ *   skipPublished — ask the CNA first and skip ids already published
+ *   onProgress    — called with `{ phase, cveId, file, status, ... }` as
+ *                   each step completes, for CLI progress lines
+ *
+ * Returns `{ blocked, review, results }`. When `blocked` is true the review
+ * found blockers, `results` is empty and nothing was sent. Otherwise
+ * `results` has one `{ file, cveId, status, ... }` per entry, with status
+ * `published`, `skipped` or `failed`, plus `correlationId` / `runId` when
+ * the CNA returned them and `error` for failures.
+ */
+export async function publishRecords (entries, {
+  client,
+  strict = true,
+  skipReview = false,
+  skipPublished = false,
+  onProgress = () => {}
+} = {}) {
+  const review = skipReview ? [] : reviewRecords(entries, { strict })
+  if (review.some((item) => !item.ready)) {
+    return { blocked: true, review, results: [] }
+  }
+  if (skipReview && entries.some((entry) => !entry.record?.cveMetadata?.cveId)) {
+    throw new Error('Every record needs cveMetadata.cveId to be published in a batch')
+  }
+
+  const results = []
+  for (const entry of entries) {
+    const cveId = labelOf(entry)
+    const base = { file: entry.file, cveId }
+    let result
+    if (skipPublished && await isPublished(client, cveId)) {
+      result = { ...base, status: 'skipped', reason: 'already published' }
+    } else {
+      try {
+        const response = await client.publishCve(cveId, entry.record.containers.cna)
+        result = {
+          ...base,
+          status: 'published',
+          correlationId: response.correlationId,
+          runId: response.runId
+        }
+      } catch (error) {
+        result = {
+          ...base,
+          status: 'failed',
+          error: error.message,
+          correlationId: error.correlationId,
+          runId: error.runId
+        }
+      }
+    }
+    results.push(result)
+    onProgress({ phase: 'publish', ...result })
+  }
+  return { blocked: false, review, results }
+}

package/lib/convert/ghsa.js

@@ -24,6 +24,7 @@
 // shape-translation logic is testable without touching the network.
 
 import { USER_AGENT } from '../client.js'
+import { buildCvssMetric, buildDescription, buildProblemType, buildRecordEnvelope } from '../record.js'
 import { OPENJS_CNA_ORG_ID } from '../review/schema.js'
 import { parseVersionRange } from './version-range.js'
 
@@ -32,11 +33,6 @@ import { parseVersionRange } from './version-range.js'
 // the converter don't have to reach into the transport module.
 export const ENGINE_ID = USER_AGENT
 
-// MITRE schema version we emit on every Record. Matches what every CVE
-// the OpenJS CNA has published carries (5.2 — Vulnogram templates use
-// 5.1 but the on-the-wire format is 5.2).
-const DATA_VERSION = '5.2'
-
 // GHSA credit `type` values use underscores. MITRE's CVE Record Format
 // schema (cnaPublishedContainer → credits → type) requires the
 // space-separated forms. Map each known GHSA role to its MITRE spelling.
@@ -153,63 +149,15 @@ function stripReferencesSection (md) {
   return refIdx >= 0 ? normalized.slice(0, refIdx).trimEnd() : normalized
 }
 
-// Strip Markdown formatting down to readable plain text. Generic — no
-// hard-coded section names beyond the References block (which is dropped
-// upstream by stripReferencesSection because cna.references[] is its
-// structured home). Headers become "Label:" lines (matches the published
-// OpenJS CVE convention), emphasis/code/links collapse to their text
-// content, list bullets drop the bullet marker, blockquote markers drop.
-function stripMarkdown (md) {
-  if (typeof md !== 'string') return ''
-  // Normalize line endings — GitHub serves CRLF, every regex below uses
-  // `\n` as the line boundary.
-  let text = md.replace(/\r\n/g, '\n').replace(/\r/g, '\n')
-  // Headers → "Label:" (any ATX heading, level 1–6, generic). We use
-  // [ \t]* (not \s*) for leading/trailing whitespace so we don't eat the
-  // preceding/following blank lines — those are what visually separate
-  // the heading label from neighboring paragraphs.
-  text = text.replace(/^[ \t]*#{1,6}[ \t]+(.+?)[ \t]*$/gm, '$1:')
-  // **bold** / __bold__ / *italic* / _italic_ → inner text
-  text = text.replace(/\*\*(.+?)\*\*/g, '$1')
-  text = text.replace(/__(.+?)__/g, '$1')
-  text = text.replace(/(?<![*\w])\*(?!\s)(.+?)(?<!\s)\*(?![*\w])/g, '$1')
-  text = text.replace(/(?<![_\w])_(?!\s)(.+?)(?<!\s)_(?![_\w])/g, '$1')
-  // `inline code` → inner text
-  text = text.replace(/`(.+?)`/g, '$1')
-  // [link](url) → link
-  text = text.replace(/\[(.+?)\]\([^)]+\)/g, '$1')
-  // Bullet / ordered-list markers at line start → strip the marker
-  text = text.replace(/^\s*(?:[-*+]|\d+\.)\s+/gm, '')
-  // Blockquote markers
-  text = text.replace(/^\s*>\s?/gm, '')
-  // Collapse 3+ blank lines to a single blank line.
-  text = text.replace(/\n{3,}/g, '\n\n')
-  return text.trim()
-}
-
 function buildDescriptions (advisory) {
-  // GHSA advisory descriptions are authored in Markdown. MITRE's
-  // descriptions[0].value field is plain-text in every published OpenJS
-  // CVE on record, so we strip the Markdown for the value and put the
-  // (de-duplicated) original Markdown into supportingMedia[0]. The
-  // References block is removed from both representations because its
+  // GHSA advisory descriptions are authored in Markdown; buildDescription
+  // puts the plain text in `value` and keeps the Markdown in
+  // supportingMedia. The References block is removed first because its
   // URLs already live in cna.references[] as structured data.
   const original = (advisory.description ?? '').trim() || (advisory.summary ?? '').trim()
   if (!original) return []
-  const raw = stripReferencesSection(original).trim()
-  if (!raw) return []
-  const plain = stripMarkdown(raw) || raw
-  const description = {
-    lang: 'en',
-    value: plain
-  }
-  // Only attach supportingMedia when the raw Markdown still carries
-  // formatting after the References strip. If plain === raw the markdown
-  // form has nothing extra to offer.
-  if (raw !== plain) {
-    description.supportingMedia = [{ type: 'text/markdown', base64: false, value: raw }]
-  }
-  return [description]
+  const description = buildDescription(stripReferencesSection(original))
+  return description ? [description] : []
 }
 
 function buildAffected (advisory) {
@@ -234,26 +182,9 @@ function buildAffected (advisory) {
 function buildProblemTypes (advisory) {
   const cwes = advisory.cwes ?? []
   if (cwes.length === 0) return undefined
-  return [{
-    descriptions: cwes.map((cwe) => ({
-      lang: 'en',
-      cweId: cwe.cwe_id,
-      type: 'CWE',
-      description: cwe.name ?? cwe.cwe_id
-    }))
-  }]
-}
-
-// CVSS v3.1 and v4.0 share the same severity bands. The MITRE-bundled
-// CVSS schemas require `baseSeverity` whenever a baseScore is present,
-// so we derive it here when the GHSA payload only carries the score.
-function severityForScore (score) {
-  if (typeof score !== 'number') return null
-  if (score === 0) return 'NONE'
-  if (score < 4.0) return 'LOW'
-  if (score < 7.0) return 'MEDIUM'
-  if (score < 9.0) return 'HIGH'
-  return 'CRITICAL'
+  // GHSA lists every CWE of the advisory; MITRE groups them as the
+  // descriptions of one problemType entry.
+  return [buildProblemType(cwes.map((cwe) => ({ cweId: cwe.cwe_id, name: cwe.name })))]
 }
 
 function buildMetrics (advisory) {
@@ -269,7 +200,9 @@ function buildMetrics (advisory) {
   // Emit a `cvssV3_1` block whenever a v3.1 vector exists, and a
   // `cvssV4_0` block whenever a v4 vector exists. Both can appear; we
   // emit each in its own metric entry so the MITRE schema (which gates
-  // additional properties on cvssVx blocks) is happy.
+  // additional properties on cvssVx blocks) is happy. GHSA only issues
+  // 3.1 and 4.0 vectors; `buildCvssMetric` computes a missing v3.1 score
+  // and passes through a vector it cannot parse for the reviewer to flag.
   const metrics = []
   const v3Vector = advisory.cvss?.vector_string ??
     advisory.cvss_v3?.vector_string ??
@@ -278,32 +211,14 @@ function buildMetrics (advisory) {
     advisory.cvss_v3?.score ??
     advisory.cvss_severities?.cvss_v3?.score
   if (v3Vector) {
-    const v3Severity = severityForScore(v3Score)
-    metrics.push({
-      format: 'CVSS',
-      cvssV3_1: {
-        version: '3.1',
-        vectorString: v3Vector,
-        ...(typeof v3Score === 'number' ? { baseScore: v3Score } : {}),
-        ...(v3Severity ? { baseSeverity: v3Severity } : {})
-      }
-    })
+    metrics.push(buildCvssMetric(v3Vector, { baseScore: v3Score }))
   }
   const v4Vector = advisory.cvss_v4?.vector_string ??
     advisory.cvss_severities?.cvss_v4?.vector_string
   const v4Score = advisory.cvss_v4?.score ??
     advisory.cvss_severities?.cvss_v4?.score
   if (v4Vector) {
-    const v4Severity = severityForScore(v4Score)
-    metrics.push({
-      format: 'CVSS',
-      cvssV4_0: {
-        version: '4.0',
-        vectorString: v4Vector,
-        ...(typeof v4Score === 'number' ? { baseScore: v4Score } : {}),
-        ...(v4Severity ? { baseSeverity: v4Severity } : {})
-      }
-    })
+    metrics.push(buildCvssMetric(v4Vector, { baseScore: v4Score }))
   }
   return metrics.length > 0 ? metrics : undefined
 }
@@ -458,28 +373,22 @@ export function mapAdvisoryToRecord (advisory, {
   }
   const resolvedCveId = cveId ?? advisoryCveId
 
-  const cna = {
-    providerMetadata: { orgId: assignerOrgId },
-    title: advisory.summary,
-    descriptions: buildDescriptions(advisory),
-    affected: buildAffected(advisory),
-    problemTypes: buildProblemTypes(advisory),
-    metrics: buildMetrics(advisory),
-    credits: buildCredits(advisory),
-    references: buildReferences(advisory),
-    // x_ prefixes are MITRE's extension namespace. x_generator is the
-    // canonical place to surface "this container was produced by …".
-    x_generator: { engine: engineId }
-  }
-
-  return {
-    dataType: 'CVE_RECORD',
-    dataVersion: DATA_VERSION,
-    ...(resolvedCveId
-      ? { cveMetadata: { cveId: resolvedCveId, assignerOrgId, state: 'PUBLISHED' } }
-      : {}),
-    containers: { cna }
-  }
+  // The envelope, providerMetadata and x_generator come from
+  // buildRecordEnvelope so every converter emits them the same way.
+  return buildRecordEnvelope({
+    cveId: resolvedCveId,
+    assignerOrgId,
+    engineId,
+    cna: {
+      title: advisory.summary,
+      descriptions: buildDescriptions(advisory),
+      affected: buildAffected(advisory),
+      problemTypes: buildProblemTypes(advisory),
+      metrics: buildMetrics(advisory),
+      credits: buildCredits(advisory),
+      references: buildReferences(advisory)
+    }
+  })
 }
 
 // Fetch + map convenience. Returns the full CVE Record (Vulnogram-

package/lib/cvss.js

@@ -0,0 +1,113 @@
+// CVSS v3.0 / v3.1 base score calculator.
+//
+// Vulnerability trackers often store only the vector string, while MITRE's
+// record format requires `baseScore` and `baseSeverity` on every CVSS
+// block. This module derives both from the vector so converters never have
+// to guess or call out to a third-party calculator, and so the reviewer can
+// verify that a submitted score actually matches its vector.
+//
+// Only the base metric group is scored. Temporal and environmental metrics
+// that may follow in the vector are preserved in the string but ignored.
+
+const SUPPORTED_VERSIONS = new Set(['3.0', '3.1'])
+
+const WEIGHTS = {
+  AV: { N: 0.85, A: 0.62, L: 0.55, P: 0.2 },
+  AC: { L: 0.77, H: 0.44 },
+  // Privileges Required depends on Scope: [unchanged, changed].
+  PR: { N: [0.85, 0.85], L: [0.62, 0.68], H: [0.27, 0.5] },
+  UI: { N: 0.85, R: 0.62 },
+  S: { U: 'U', C: 'C' },
+  C: { H: 0.56, L: 0.22, N: 0 },
+  I: { H: 0.56, L: 0.22, N: 0 },
+  A: { H: 0.56, L: 0.22, N: 0 }
+}
+
+const BASE_METRICS = ['AV', 'AC', 'PR', 'UI', 'S', 'C', 'I', 'A']
+
+/**
+ * Parse a CVSS v3.x vector string into its version and metrics.
+ * Throws on unsupported versions and on missing or invalid base metrics.
+ */
+export function parseCvssVector (vectorString) {
+  const text = String(vectorString || '').trim()
+  const match = text.match(/^CVSS:(3\.[01])\/(.+)$/)
+  if (!match) {
+    throw new Error(`Unsupported CVSS vector: ${JSON.stringify(vectorString)}`)
+  }
+  const [, version, body] = match
+  if (!SUPPORTED_VERSIONS.has(version)) {
+    throw new Error(`Unsupported CVSS version ${version}`)
+  }
+  const metrics = {}
+  for (const part of body.split('/')) {
+    const [key, value] = part.split(':')
+    if (!key || value === undefined) {
+      throw new Error(`Malformed CVSS component ${JSON.stringify(part)}`)
+    }
+    metrics[key] = value
+  }
+  for (const key of BASE_METRICS) {
+    if (!metrics[key] || !Object.hasOwn(WEIGHTS[key], metrics[key])) {
+      throw new Error(`CVSS vector is missing or has an invalid ${key} metric`)
+    }
+  }
+  return { version, vectorString: text, metrics }
+}
+
+/**
+ * CVSS v3.1 "Roundup": smallest number, to one decimal place, that is equal
+ * to or higher than the input. v3.1 specified an integer-based algorithm to
+ * avoid floating-point surprises; it yields the same results as the v3.0
+ * definition for every realistic input, so it is used for both versions.
+ */
+export function roundUp (value) {
+  const scaled = Math.round(value * 100000)
+  if (scaled % 10000 === 0) return scaled / 100000
+  return (Math.floor(scaled / 10000) + 1) / 10
+}
+
+/** Qualitative severity band for a base score (shared by v3.0, v3.1 and v4.0). */
+export function severityFromScore (score) {
+  if (score === 0) return 'NONE'
+  if (score < 4) return 'LOW'
+  if (score < 7) return 'MEDIUM'
+  if (score < 9) return 'HIGH'
+  return 'CRITICAL'
+}
+
+/**
+ * Compute the base score and severity of a CVSS v3.0 / v3.1 vector.
+ * Returns `{ version, vectorString, baseScore, baseSeverity }`.
+ */
+export function calculateBaseScore (vectorString) {
+  const { version, metrics, vectorString: text } = parseCvssVector(vectorString)
+  const scopeChanged = metrics.S === 'C'
+  const iss = 1 - (
+    (1 - WEIGHTS.C[metrics.C]) *
+    (1 - WEIGHTS.I[metrics.I]) *
+    (1 - WEIGHTS.A[metrics.A])
+  )
+  const impact = scopeChanged
+    ? 7.52 * (iss - 0.029) - 3.25 * ((iss - 0.02) ** 15)
+    : 6.42 * iss
+  const exploitability = 8.22 *
+    WEIGHTS.AV[metrics.AV] *
+    WEIGHTS.AC[metrics.AC] *
+    WEIGHTS.PR[metrics.PR][scopeChanged ? 1 : 0] *
+    WEIGHTS.UI[metrics.UI]
+
+  let baseScore = 0
+  if (impact > 0) {
+    baseScore = scopeChanged
+      ? roundUp(Math.min(1.08 * (impact + exploitability), 10))
+      : roundUp(Math.min(impact + exploitability, 10))
+  }
+
+  return {
+    version,
+    vectorString: text,
+    baseScore,
+    baseSeverity: severityFromScore(baseScore)
+  }
+}

package/lib/hackerone/index.js

@@ -0,0 +1,42 @@
+// HackerOne weakness ids -> CWE.
+//
+// HackerOne identifies a report's weakness by its own numeric id, which is
+// what its REST API exposes as `weakness_id` and what projects end up
+// storing. It is not a CWE number: weakness 26 is "Improper Access Control"
+// (CWE-284), 48 is "Uncontrolled Resource Consumption" (CWE-400). The CWE
+// is a separate attribute of the weakness, and HackerOne's taxonomy is the
+// same for every program, so the mapping ships here as data
+// (./weaknesses.json, regenerated with scripts/build-hackerone-weaknesses.js).
+
+import { createRequire } from 'node:module'
+import { buildProblemType } from '../record.js'
+
+const require = createRequire(import.meta.url)
+const { weaknesses, _generated: generated } = require('./weaknesses.json')
+
+export const HACKERONE_WEAKNESSES_GENERATED = generated
+
+/**
+ * Look a HackerOne weakness id up. Accepts a number or a string.
+ *
+ * Returns `{ cwe, name }` where `cwe` is `CWE-<number>` or `null` for a
+ * weakness HackerOne maps to no CWE (CAPEC entries), or `null` when the id
+ * is unknown.
+ */
+export function hackerOneWeakness (id) {
+  const key = String(id ?? '').trim()
+  if (!/^\d+$/.test(key)) return null
+  const entry = weaknesses[key]
+  return entry ? { cwe: entry.cwe, name: entry.name } : null
+}
+
+/**
+ * The `problemTypes[]` entry for a HackerOne weakness id, or `null` when
+ * the id is unknown or has no CWE. The CWE name on the record is
+ * HackerOne's weakness name.
+ */
+export function hackerOneWeaknessProblemType (id) {
+  const entry = hackerOneWeakness(id)
+  if (!entry?.cwe) return null
+  return buildProblemType({ cweId: entry.cwe, name: entry.name })
+}