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

package/lib/preview.js

@@ -20,22 +20,23 @@ function getDescription (c) {
       ''
 }
 
+// Metric blocks the record format accepts, in display preference order.
+const CVSS_BLOCKS = [
+  { key: 'cvssV3_1', version: '3.1' },
+  { key: 'cvssV4_0', version: '4.0' },
+  { key: 'cvssV3_0', version: '3.0' }
+]
+
 function getCvss (c) {
   for (const m of c?.metrics ?? []) {
-    if (m?.cvssV3_1?.vectorString) {
-      return {
-        version: '3.1',
-        score: m.cvssV3_1.baseScore,
-        severity: m.cvssV3_1.baseSeverity,
-        vector: m.cvssV3_1.vectorString
-      }
-    }
-    if (m?.cvssV4_0?.vectorString) {
-      return {
-        version: '4.0',
-        score: m.cvssV4_0.baseScore,
-        severity: m.cvssV4_0.baseSeverity,
-        vector: m.cvssV4_0.vectorString
+    for (const { key, version } of CVSS_BLOCKS) {
+      if (m?.[key]?.vectorString) {
+        return {
+          version,
+          score: m[key].baseScore,
+          severity: m[key].baseSeverity,
+          vector: m[key].vectorString
+        }
       }
     }
   }

package/lib/prompt.js

@@ -43,15 +43,20 @@ function summarizeAffected (cna) {
   })
 }
 
+// Metric blocks the record format accepts, in display preference order.
+const CVSS_BLOCKS = [
+  { key: 'cvssV3_1', label: 'CVSS 3.1' },
+  { key: 'cvssV4_0', label: 'CVSS 4.0' },
+  { key: 'cvssV3_0', label: 'CVSS 3.0' }
+]
+
 function summarizeCvss (cna) {
   for (const m of cna?.metrics ?? []) {
-    if (m?.cvssV3_1?.vectorString) {
-      const { vectorString, baseScore, baseSeverity } = m.cvssV3_1
-      return { label: 'CVSS 3.1', body: `${baseScore ?? '?'} ${baseSeverity ?? ''} (${vectorString})`.replace(/\s+/g, ' ').trim() }
-    }
-    if (m?.cvssV4_0?.vectorString) {
-      const { vectorString, baseScore, baseSeverity } = m.cvssV4_0
-      return { label: 'CVSS 4.0', body: `${baseScore ?? '?'} ${baseSeverity ?? ''} (${vectorString})`.replace(/\s+/g, ' ').trim() }
+    for (const { key, label } of CVSS_BLOCKS) {
+      if (m?.[key]?.vectorString) {
+        const { vectorString, baseScore, baseSeverity } = m[key]
+        return { label, body: `${baseScore ?? '?'} ${baseSeverity ?? ''} (${vectorString})`.replace(/\s+/g, ' ').trim() }
+      }
     }
   }
   return null

package/lib/record.js

@@ -0,0 +1,173 @@
+// Helpers for the parts of a v5.2 CVE Record that are about the record
+// format rather than about where the data came from: the description, the
+// CVSS metric block, the problem type and the record envelope. Converters
+// (GHSA here, release trackers in downstream projects) build the container
+// fields they know about and use these so the format-level details are
+// written once.
+
+import { USER_AGENT } from './client.js'
+import { calculateBaseScore, severityFromScore } from './cvss.js'
+import { OPENJS_CNA_ORG_ID } from './review/schema.js'
+
+// MITRE schema version we emit on every Record. Matches what every CVE
+// published by the OpenJS CNA carries today.
+export const DATA_VERSION = '5.2'
+
+/**
+ * Strip Markdown formatting down to readable plain text. Generic: headers
+ * become "Label:" lines (the published OpenJS CVE convention), emphasis,
+ * code spans and links collapse to their text, list bullets and blockquote
+ * markers drop, line endings normalise to `\n`.
+ */
+export function stripMarkdown (md) {
+  if (typeof md !== 'string') return ''
+  let text = md.replace(/\r\n/g, '\n').replace(/\r/g, '\n')
+  // Headers → "Label:" (any ATX heading, level 1–6). [ \t]* rather than
+  // \s* so the blank lines around the heading survive.
+  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()
+}
+
+/**
+ * Build one `descriptions[]` entry from text that may carry Markdown.
+ *
+ * MITRE's `value` is plain text (NVD and cve.org show it verbatim), so the
+ * Markdown is stripped for `value` and the original is kept in
+ * `supportingMedia` as `text/markdown`, only when the two differ. Returns
+ * `null` for empty input so callers can leave `descriptions` out.
+ */
+export function buildDescription (text, { lang = 'en' } = {}) {
+  const raw = String(text ?? '').replace(/\r\n/g, '\n').replace(/\r/g, '\n').trim()
+  if (!raw) return null
+  const plain = stripMarkdown(raw) || raw
+  const description = { lang, value: plain }
+  if (raw !== plain) {
+    description.supportingMedia = [{ type: 'text/markdown', base64: false, value: raw }]
+  }
+  return description
+}
+
+// Metric block key per CVSS version prefix. v2 is not emitted by anything
+// the foundation publishes, so it is left out on purpose.
+const METRIC_KEYS = new Map([
+  ['3.0', 'cvssV3_0'],
+  ['3.1', 'cvssV3_1'],
+  ['4.0', 'cvssV4_0']
+])
+
+/**
+ * Build one `metrics[]` entry from a CVSS vector string.
+ *
+ * The block key (`cvssV3_0`, `cvssV3_1`, `cvssV4_0`) follows the vector's
+ * `CVSS:<version>/` prefix, which is what MITRE validates each block
+ * against. `baseScore` is taken from `options.baseScore` when given and
+ * computed from the vector otherwise (v3.x only; v4.0 has no bundled
+ * calculator). `baseSeverity` is always derived from the final score.
+ *
+ * A vector with an unknown prefix or one the calculator rejects is passed
+ * through under the closest key with no score, so the reviewer can report
+ * it instead of this helper guessing.
+ */
+export function buildCvssMetric (vectorString, { baseScore } = {}) {
+  const vector = String(vectorString ?? '').trim()
+  const version = vector.match(/^CVSS:(\d\.\d)\//)?.[1]
+  const key = METRIC_KEYS.get(version) ?? 'cvssV3_1'
+
+  let score = typeof baseScore === 'number' ? baseScore : undefined
+  if (score === undefined && (version === '3.0' || version === '3.1')) {
+    try {
+      score = calculateBaseScore(vector).baseScore
+    } catch {}
+  }
+
+  return {
+    format: 'CVSS',
+    [key]: {
+      version: version ?? '3.1',
+      vectorString: vector,
+      ...(score !== undefined ? { baseScore: score, baseSeverity: severityFromScore(score) } : {})
+    }
+  }
+}
+
+/**
+ * Build one `problemTypes[]` entry from one or more CWE references.
+ *
+ * Accepts a single `{ cweId, name? }` or an array of them. `cweId` may be
+ * given as `400`, `CWE-400` or `cwe-400` and is normalised to the
+ * `CWE-<number>` form MITRE's pattern requires; anything else throws so
+ * the mistake surfaces at build time. `description` is required by MITRE,
+ * so it is the CWE name when known and the id otherwise.
+ */
+export function buildProblemType (cwes) {
+  const list = Array.isArray(cwes) ? cwes : [cwes]
+  if (list.length === 0) {
+    throw new TypeError('buildProblemType: at least one CWE reference is required')
+  }
+  return {
+    descriptions: list.map(({ cweId, name } = {}) => {
+      const id = String(cweId ?? '').trim().match(/^(?:CWE-)?([1-9]\d*)$/i)?.[1]
+      if (!id) {
+        throw new TypeError(`buildProblemType: '${cweId}' is not a CWE id (expected CWE-<number>)`)
+      }
+      const text = String(name ?? '').trim()
+      return {
+        lang: 'en',
+        type: 'CWE',
+        cweId: `CWE-${id}`,
+        description: text || `CWE-${id}`
+      }
+    })
+  }
+}
+
+/**
+ * Wrap a CNA container in the v5.2 Record envelope.
+ *
+ * Sets `providerMetadata.orgId` and `x_generator.engine` on the container
+ * when the caller has not, so no consumer needs to know the OpenJS CNA org
+ * id or the generator string. `cveMetadata` is emitted only when `cveId` is
+ * given; without it the publisher's CLI argument is the sole source of
+ * truth for the id.
+ */
+export function buildRecordEnvelope ({
+  cna,
+  cveId,
+  assignerOrgId = OPENJS_CNA_ORG_ID,
+  engineId = USER_AGENT,
+  dataVersion = DATA_VERSION
+} = {}) {
+  if (!cna || typeof cna !== 'object') {
+    throw new TypeError('buildRecordEnvelope: `cna` must be the CNA container object')
+  }
+  const container = {
+    providerMetadata: { orgId: assignerOrgId },
+    ...cna,
+    // x_ prefixes are MITRE's extension namespace. x_generator is the
+    // canonical place to surface "this container was produced by …".
+    x_generator: cna.x_generator ?? { engine: engineId }
+  }
+  return {
+    dataType: 'CVE_RECORD',
+    dataVersion,
+    ...(cveId
+      ? { cveMetadata: { cveId, assignerOrgId, state: 'PUBLISHED' } }
+      : {}),
+    containers: { cna: container }
+  }
+}

package/lib/review/rules.js

@@ -16,6 +16,8 @@
 // See docs/mitre-schema-summary.md for the constraint inventory the tiers
 // are derived from.
 
+import { calculateBaseScore } from '../cvss.js'
+
 const isString = (v) => typeof v === 'string'
 const isNonEmptyArray = (v) => Array.isArray(v) && v.length > 0
 
@@ -26,13 +28,30 @@ function getDescription (c) {
       c?.descriptions?.[0]
 }
 
-function getCvssVector (c) {
-  return c?.metrics?.find(m => m?.cvssV3_1?.vectorString)?.cvssV3_1?.vectorString
+// CVSS v3 blocks the record format accepts, newest first. v3.0 and v3.1
+// share the same metrics and vector grammar; only the `CVSS:<version>/`
+// prefix differs, and MITRE validates each block against its own schema.
+const CVSS_V3_KEYS = [
+  { key: 'cvssV3_1', version: '3.1' },
+  { key: 'cvssV3_0', version: '3.0' }
+]
+
+// First CVSS v3 block (3.1 or 3.0) with a vector, plus the key it lives
+// under so issue paths and prefix checks can name the right version.
+function getCvssV3 (c) {
+  for (const m of c?.metrics ?? []) {
+    for (const { key, version } of CVSS_V3_KEYS) {
+      if (m?.[key]?.vectorString) return { key, version, block: m[key] }
+    }
+  }
+  return null
 }
 
 function getCvssScore (c) {
   for (const m of c?.metrics ?? []) {
-    if (typeof m?.cvssV3_1?.baseScore === 'number') return m.cvssV3_1.baseScore
+    for (const { key } of CVSS_V3_KEYS) {
+      if (typeof m?.[key]?.baseScore === 'number') return m[key].baseScore
+    }
   }
   return null
 }
@@ -196,38 +215,42 @@ export const RULES = [
     id: 'metrics-present',
     severity: 'warning',
     // MITRE doesn't require a metrics block, but every published OpenJS
-    // CVE carries at least one (v3.1 or v4.0). Without metrics the
+    // CVE carries at least one (v3.0, v3.1 or v4.0). Without metrics the
     // record looks half-finished to consumers parsing NVD/OSV.
     tier: 'openjs-extra',
     check (c) {
       const metrics = c?.metrics ?? []
-      const hasCvss = metrics.some(m => m?.cvssV3_1?.vectorString || m?.cvssV4_0?.vectorString)
+      const hasCvss = getCvssV3(c) != null || metrics.some(m => m?.cvssV4_0?.vectorString)
       if (hasCvss) return null
       return {
         path: 'metrics',
-        message: 'No CVSS metric present. Add at least one cvssV3_1 or cvssV4_0 block.'
+        message: 'No CVSS metric present. Add at least one cvssV3_1, cvssV3_0 or cvssV4_0 block.'
       }
     }
   },
   {
     id: 'cvss-vector-parseable',
     severity: 'blocker',
-    // MITRE imports the FIRST.org CVSS v3.1 schema, which constrains
-    // `vectorString` with a pattern that requires the `CVSS:3.1/` prefix and
-    // validates every KEY:VAL component. Same failure as this rule.
+    // MITRE imports the FIRST.org CVSS v3.x schemas, which constrain
+    // `vectorString` with a pattern that requires the `CVSS:3.1/` (or
+    // `CVSS:3.0/` in a cvssV3_0 block) prefix and validates every KEY:VAL
+    // component. Same failure as this rule.
     tier: 'mitre-common',
     check (c) {
-      const vec = getCvssVector(c)
-      if (!vec) return null
-      // Minimal CVSS v3.1 sanity check. Full parsing would need an external
-      // library; we just verify the prefix and that every component looks
-      // like KEY:VAL pairs.
-      if (!vec.startsWith('CVSS:3.1/')) {
-        return { path: 'metrics[].cvssV3_1.vectorString', message: 'CVSS vector does not start with CVSS:3.1/' }
+      const cvss = getCvssV3(c)
+      if (!cvss) return null
+      const vec = cvss.block.vectorString
+      const prefix = `CVSS:${cvss.version}/`
+      const path = `metrics[].${cvss.key}.vectorString`
+      // Minimal CVSS v3 sanity check. Full parsing would need an external
+      // library; we just verify the prefix matches the block's version and
+      // that every component looks like KEY:VAL pairs.
+      if (!vec.startsWith(prefix)) {
+        return { path, message: `CVSS vector does not start with ${prefix}` }
       }
-      const parts = vec.slice('CVSS:3.1/'.length).split('/')
+      const parts = vec.slice(prefix.length).split('/')
       if (parts.some(p => !/^[A-Z]+:[A-Z]+$/.test(p))) {
-        return { path: 'metrics[].cvssV3_1.vectorString', message: 'CVSS vector has malformed components' }
+        return { path, message: 'CVSS vector has malformed components' }
       }
       return null
     }
@@ -235,24 +258,52 @@ export const RULES = [
   {
     id: 'cvss-score-matches-band',
     severity: 'warning',
-    // MITRE's bundled CVSS v3.1 schema has an `anyOf` that pairs each score
+    // MITRE's bundled CVSS v3.x schemas have an `anyOf` that pairs each score
     // band (none/low/medium/high/critical) with the matching baseSeverity
     // enum, so a band mismatch is a schema violation upstream too.
     tier: 'mitre-common',
     check (c) {
       const score = getCvssScore(c)
-      const band = c?.metrics?.find(m => m?.cvssV3_1)?.cvssV3_1?.baseSeverity
+      const cvss = getCvssV3(c)
+      const band = cvss?.block.baseSeverity
       if (score == null || !band) return null
       const expected = expectedSeverityBand(score)
       if (expected !== band) {
         return {
-          path: 'metrics[].cvssV3_1',
+          path: `metrics[].${cvss.key}`,
           message: `baseSeverity is '${band}' but the score ${score} falls in band '${expected}'`
         }
       }
       return null
     }
   },
+  {
+    id: 'cvss-score-matches-vector',
+    severity: 'blocker',
+    // MITRE does not recompute scores, so a baseScore that disagrees with
+    // its vector is accepted upstream and then contradicts every consumer
+    // that scores the vector itself (NVD, OSV, scanners). The vector is the
+    // source of truth; the score must be the one FIRST.org's v3.x formula
+    // yields for it. Unparseable vectors are left to cvss-vector-parseable.
+    tier: 'openjs-extra',
+    check (c) {
+      const cvss = getCvssV3(c)
+      if (!cvss || typeof cvss.block.baseScore !== 'number') return null
+      let computed
+      try {
+        computed = calculateBaseScore(cvss.block.vectorString)
+      } catch {
+        return null
+      }
+      if (computed.baseScore !== cvss.block.baseScore) {
+        return {
+          path: `metrics[].${cvss.key}.baseScore`,
+          message: `baseScore is ${cvss.block.baseScore} but the vector scores ${computed.baseScore}`
+        }
+      }
+      return null
+    }
+  },
 
   // CWE
   {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ulisesgascon/openjs-cna-tools",
-  "version": "1.0.0-alpha.1",
+  "version": "1.0.0-alpha.4",
   "description": "EXPERIMENTAL fork of the OpenJS Foundation CNA tools: CLI and library for the OpenJS CNA API",
   "type": "module",
   "license": "MIT",
@@ -11,14 +11,18 @@
     "node": ">=22.0.0"
   },
   "bin": {
-    "openjs-cna-experimental": "./bin/openjs-cna.js"
+    "openjs-cna-experimental": "bin/openjs-cna.js"
   },
   "main": "./lib/index.js",
   "exports": {
     ".": "./lib/index.js",
     "./client": "./lib/client.js",
     "./review": "./lib/review/index.js",
-    "./convert": "./lib/convert/ghsa.js"
+    "./convert": "./lib/convert/ghsa.js",
+    "./cvss": "./lib/cvss.js",
+    "./record": "./lib/record.js",
+    "./batch": "./lib/batch.js",
+    "./hackerone": "./lib/hackerone/index.js"
   },
   "files": [
     "bin/",