@ulisesgascon/openjs-cna-tools 0.0.0-stage → 1.0.0-alpha.3

package/lib/convert/version-range.js

@@ -0,0 +1,251 @@
+// Parse GHSA-style `vulnerable_version_range` strings into MITRE v5.2
+// `affected[].versions[]` entries.
+//
+// GHSA is permissive: maintainers type freeform range expressions and we
+// see ~60 distinct shapes across the vulnerabilities tracked
+// (see test/fixtures/version-range-matrix.js for the canonical list).
+// MITRE is strict: every entry needs { version, status, versionType } plus
+// at most one of { lessThan, lessThanOrEqual, changes }.
+//
+// Strategy:
+//
+//   1. Split multi-line inputs on `; ` or `&&` first — each segment becomes
+//      its own entry in the output array.
+//   2. For each segment, strip incidental noise (package-name prefix,
+//      parenthetical annotations, leading/trailing whitespace, leading
+//      `v` on tokens like `v5.2.1`).
+//   3. Try a sequence of structural matchers most-specific first: hyphen
+//      range, caret range, bounded (lower + upper), single operator,
+//      implicit-lower-bound shape, bare semver, commit hash.
+//   4. Unparseable segments fall back to `versionType: 'custom'` carrying
+//      the original text, unless we extracted an embedded commit hash —
+//      in which case use that.
+//
+// Always emits at least one entry per non-empty input, or [] for empty
+// strings. The function never throws on input.
+
+const SEMVER_TOKEN = String.raw`v?\d+(?:\.\d+){0,2}(?:-[\w.]+)?`
+const HASH_TOKEN = '[0-9a-f]{7,40}'
+const COMMIT_HASH = new RegExp(`^${HASH_TOKEN}$`, 'i')
+
+const RX = {
+  bareSemver: new RegExp(`^${SEMVER_TOKEN}$`),
+  rangeHyphen: new RegExp(`^(${SEMVER_TOKEN})\\s*-\\s*(${SEMVER_TOKEN})$`),
+  caret: new RegExp(`^\\^(${SEMVER_TOKEN})$`),
+
+  // Single-operator forms. The optional whitespace lets `<4.0.0` and
+  // `< 4.0.0` both match.
+  opUpperEx: new RegExp(`^<\\s*(${SEMVER_TOKEN}|${HASH_TOKEN})$`, 'i'),
+  opUpperInc: new RegExp(`^(?:<=|=<)\\s*(${SEMVER_TOKEN})$`),
+  opLowerEx: new RegExp(`^>\\s*(${SEMVER_TOKEN})$`),
+  opLowerInc: new RegExp(`^>=\\s*(${SEMVER_TOKEN})$`),
+  opEquals: new RegExp(`^=\\s*(${SEMVER_TOKEN})$`),
+
+  // Bounded ranges: lower + upper, glued together with comma, whitespace,
+  // or nothing. `>=4.0.0, <4.18.0` / `>=4.0.0 <4.18.0` / `>=4.0.0,<4.18.0`
+  // / `>=4.0.0<4.18.0` all match.
+  bounded: new RegExp(
+    `^>=?\\s*(${SEMVER_TOKEN})\\s*(?:,\\s*|\\s+|)\\s*(<=?|=<)\\s*(${SEMVER_TOKEN})$`
+  ),
+
+  // Implicit lower bound: "7.0.0 < 7.24.0" — no leading operator, the
+  // bare version IS the lower bound.
+  implicitBounded: new RegExp(
+    `^(${SEMVER_TOKEN})\\s*(<=?|=<)\\s*(${SEMVER_TOKEN})$`
+  )
+}
+
+function stripV (s) {
+  return String(s).replace(/^v/, '')
+}
+
+// Remove incidental noise from a segment before structural matching:
+// parenthetical annotations, leading package-name prefixes, surrounding
+// whitespace.
+function clean (segment) {
+  let s = segment.trim()
+  // Strip parenthetical clarifications: "<=5.2.1 (includes all 4.x)".
+  s = s.replace(/\s*\([^)]*\)\s*/g, '').trim()
+  // Strip package-name prefix: "lodash <= 4.18.1" or "lodash<=4.18.1".
+  // We only fire this when the prefix is alphabetic AND followed by an
+  // OPERATOR (`<`, `>`, `=`). If we widened to digits we'd shred
+  // freeform inputs like "Leangheng2004" into the bare "4".
+  s = s.replace(/^[a-z@][\w@/.-]*\s*(?=[<>=])/i, '').trim()
+  return s
+}
+
+// Split multi-line inputs on `;` or `&&`. Each segment becomes its own
+// entry in the output.
+function splitMultiline (input) {
+  return input
+    .split(/\s*(?:;|&&)\s*/)
+    .map(s => s.trim())
+    .filter(Boolean)
+}
+
+// Try to parse a single segment. Returns the MITRE entry if a structural
+// matcher hits, or null if the segment cannot be understood.
+function parseSegment (raw) {
+  const segment = clean(raw)
+  if (!segment) return null
+
+  // Wildcards
+  if (segment === '*' || /^all$/i.test(segment)) {
+    return { version: '0', status: 'affected', versionType: 'semver' }
+  }
+
+  // Hyphen range: "4.0.0 - 4.17.23"
+  const hyphenMatch = segment.match(RX.rangeHyphen)
+  if (hyphenMatch) {
+    return {
+      version: stripV(hyphenMatch[1]),
+      lessThanOrEqual: stripV(hyphenMatch[2]),
+      status: 'affected',
+      versionType: 'semver'
+    }
+  }
+
+  // Caret range: "^4.19.2" → [4.19.2, 5.0.0)
+  const caretMatch = segment.match(RX.caret)
+  if (caretMatch) {
+    const base = stripV(caretMatch[1])
+    const major = base.split('.')[0]
+    return {
+      version: base,
+      lessThan: `${Number(major) + 1}.0.0`,
+      status: 'affected',
+      versionType: 'semver'
+    }
+  }
+
+  // Bounded: ">=4.0.0, <4.18.0" / ">= 4.0.0 <= 4.18.1" / ">=4.0.0<4.18.0"
+  const bounded = segment.match(RX.bounded)
+  if (bounded) {
+    const lower = stripV(bounded[1])
+    const upperOp = bounded[2]
+    const upper = stripV(bounded[3])
+    const entry = { version: lower, status: 'affected', versionType: 'semver' }
+    if (upperOp === '<') entry.lessThan = upper
+    else entry.lessThanOrEqual = upper
+    return entry
+  }
+
+  // Implicit lower: "7.0.0 < 7.24.0" — bare version followed by operator.
+  const implicit = segment.match(RX.implicitBounded)
+  if (implicit) {
+    const lower = stripV(implicit[1])
+    const upperOp = implicit[2]
+    const upper = stripV(implicit[3])
+    const entry = { version: lower, status: 'affected', versionType: 'semver' }
+    if (upperOp === '<') entry.lessThan = upper
+    else entry.lessThanOrEqual = upper
+    return entry
+  }
+
+  // Single-operator forms — try most specific (two-char ops) first.
+  const opUpperInc = segment.match(RX.opUpperInc)
+  if (opUpperInc) {
+    return {
+      version: '0',
+      lessThanOrEqual: stripV(opUpperInc[1]),
+      status: 'affected',
+      versionType: 'semver'
+    }
+  }
+  const opLowerInc = segment.match(RX.opLowerInc)
+  if (opLowerInc) {
+    return { version: stripV(opLowerInc[1]), status: 'affected', versionType: 'semver' }
+  }
+  const opUpperEx = segment.match(RX.opUpperEx)
+  if (opUpperEx) {
+    const value = opUpperEx[1]
+    if (COMMIT_HASH.test(value)) {
+      return { version: '0', lessThan: value, status: 'affected', versionType: 'git' }
+    }
+    return { version: '0', lessThan: stripV(value), status: 'affected', versionType: 'semver' }
+  }
+  const opLowerEx = segment.match(RX.opLowerEx)
+  if (opLowerEx) {
+    return { version: stripV(opLowerEx[1]), status: 'affected', versionType: 'semver' }
+  }
+  const opEquals = segment.match(RX.opEquals)
+  if (opEquals) {
+    return { version: stripV(opEquals[1]), status: 'affected', versionType: 'semver' }
+  }
+
+  // Bare semver: "4.6.2"
+  if (RX.bareSemver.test(segment)) {
+    return { version: stripV(segment), status: 'affected', versionType: 'semver' }
+  }
+
+  // Bare commit hash: "39fd9827942..."
+  if (COMMIT_HASH.test(segment)) {
+    return { version: segment, status: 'affected', versionType: 'git' }
+  }
+
+  return null
+}
+
+// Public entry. See module header.
+export function parseVersionRange (input) {
+  if (typeof input !== 'string') return []
+  const trimmed = input.trim()
+  if (!trimmed) return []
+
+  const segments = splitMultiline(trimmed)
+  const out = []
+  const fallbacks = [] // { kind: 'hash'|'custom', entry, hadDigits }
+
+  for (const seg of segments) {
+    const parsed = parseSegment(seg)
+    if (parsed) {
+      out.push(parsed)
+      continue
+    }
+    // Fall back: extract an embedded commit hash if present, otherwise
+    // pass the segment through verbatim under `versionType: 'custom'`.
+    // We stage fallbacks separately so that, in multi-segment inputs,
+    // pure-prose segments can be dropped when at least one other segment
+    // yielded something useful.
+    const hashMatch = seg.match(new RegExp(`\\b(${HASH_TOKEN})\\b`, 'i'))
+    if (hashMatch) {
+      fallbacks.push({
+        kind: 'hash',
+        entry: { version: hashMatch[1], status: 'affected', versionType: 'custom' },
+        hadDigits: true
+      })
+    } else {
+      const hadDigits = /\d/.test(seg)
+      fallbacks.push({
+        kind: 'custom',
+        entry: { version: seg, status: 'affected', versionType: 'custom' },
+        hadDigits
+      })
+    }
+  }
+
+  if (segments.length > 1 && out.length > 0) {
+    // Multi-segment: only keep fallbacks that surfaced a hash or had
+    // digits. Prose-only fallbacks are dropped because the structured
+    // segments already carry the load-bearing information.
+    for (const f of fallbacks) {
+      if (f.kind === 'hash' || f.hadDigits) out.push(f.entry)
+    }
+  } else if (segments.length > 1) {
+    // Multi-segment with zero structured hits: surface hashes if any,
+    // otherwise nothing — the input is pure prose.
+    for (const f of fallbacks) {
+      if (f.kind === 'hash') out.push(f.entry)
+    }
+    if (out.length === 0 && fallbacks.length > 0) {
+      // Truly nothing — surface the first segment so the operator sees
+      // what was there.
+      out.push(fallbacks[0].entry)
+    }
+  } else {
+    // Single segment: pass the fallback through verbatim.
+    for (const f of fallbacks) out.push(f.entry)
+  }
+
+  return out
+}

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/errors.js

@@ -0,0 +1,44 @@
+// Error classes for openjs-cna-tools.
+//
+// Each error carries enough structured context that a recovery flow (or the
+// CLI exit-code mapping) can act on it without parsing the message. Messages
+// themselves are written to teach the next operator how to fix the problem
+// (see "Errors that teach" — the NCU pattern this borrows from).
+
+export class CnaAuthError extends Error {
+  constructor (message, { status } = {}) {
+    super(message)
+    this.name = 'CnaAuthError'
+    this.status = status
+  }
+}
+
+export class CnaTimeoutError extends Error {
+  constructor (message, { correlationId, runId, timeoutMs } = {}) {
+    super(message)
+    this.name = 'CnaTimeoutError'
+    this.correlationId = correlationId
+    this.runId = runId
+    this.timeoutMs = timeoutMs
+  }
+}
+
+export class CnaOperationError extends Error {
+  constructor (message, { correlationId, runId, conclusion, result } = {}) {
+    super(message)
+    this.name = 'CnaOperationError'
+    this.correlationId = correlationId
+    this.runId = runId
+    this.conclusion = conclusion
+    this.result = result
+  }
+}
+
+export class CnaReviewBlockedError extends Error {
+  constructor (message, { report } = {}) {
+    super(message)
+    this.name = 'CnaReviewBlockedError'
+    this.report = report
+    this.blockers = report?.issues?.filter(i => i.severity === 'blocker') ?? []
+  }
+}

package/lib/index.js

@@ -0,0 +1,9 @@
+// Public package surface.
+
+export { CnaClient } from './client.js'
+export {
+  CnaAuthError,
+  CnaTimeoutError,
+  CnaOperationError,
+  CnaReviewBlockedError
+} from './errors.js'

package/lib/preview.js

@@ -0,0 +1,145 @@
+// Compact preview of a v5.2 CNA Container, designed for terminal output
+// before / instead of editing the JSON by hand.
+//
+// Shape goal: key/value rows, pipe-friendly (no boxes, no ANSI). Preview
+// is the operator's last chance to review before publish, so values are
+// rendered in full lenght
+
+const KEY_WIDTH = 14
+const SEPARATOR_WIDTH = 56
+const SEPARATOR = '·'.repeat(SEPARATOR_WIDTH)
+
+function pad (key) {
+  if (!key) return ' '.repeat(KEY_WIDTH)
+  return (key + ':').padEnd(KEY_WIDTH)
+}
+
+function getDescription (c) {
+  return c?.descriptions?.find(d => d?.lang === 'en')?.value ??
+      c?.descriptions?.[0]?.value ??
+      ''
+}
+
+// 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 ?? []) {
+    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
+        }
+      }
+    }
+  }
+  return null
+}
+
+function getCwes (c) {
+  const out = new Set()
+  for (const pt of c?.problemTypes ?? []) {
+    for (const d of pt?.descriptions ?? []) {
+      if (d?.cweId) out.add(d.cweId)
+    }
+  }
+  return [...out]
+}
+
+function summarizeAffected (entry) {
+  const product = `${entry.vendor ?? '?'}:${entry.product ?? '?'}`
+  const ranges = (entry.versions ?? []).map(v => {
+    if (v.lessThan) return `${v.version} → < ${v.lessThan}`
+    if (v.lessThanOrEqual) return `${v.version} → ≤ ${v.lessThanOrEqual}`
+    return v.version
+  })
+  return ranges.length === 0 ? product : `${product} (${ranges.join(', ')})`
+}
+
+function summarizeCredit (cr) {
+  const identity = cr.value ?? cr.user ?? '?'
+  return `${cr.type}: ${identity}`
+}
+
+// Render the preview into the given CLI. Stays sync and side-effect-free
+// apart from the cli writes. Callers can null-out cli to get a string
+// instead (useful for tests).
+export function renderPreview (record, cli) {
+  const lines = []
+  const out = (line = '') => {
+    if (cli) cli.log(line)
+    lines.push(line)
+  }
+
+  if (!record || typeof record !== 'object') {
+    out('Record preview: (no record provided)')
+    return lines.join('\n')
+  }
+
+  const container = record?.containers?.cna ?? {}
+  const cveId = record?.cveMetadata?.cveId
+
+  out('')
+  out('Record preview: (edit visually at https://vulnogram.org/#source)')
+
+  // Each field becomes a "row" via `row(key, value, ...extras)`. The
+  // helper emits a dotted separator before every row except the first
+  // so the operator can scan the preview as a stack of distinct fields.
+  let rowsEmitted = 0
+  const row = (key, value, ...extras) => {
+    if (rowsEmitted > 0) out(`  ${SEPARATOR}`)
+    out(`  ${pad(key)} ${value}`)
+    const continuation = ' '.repeat(2 + KEY_WIDTH + 1)
+    for (const line of extras) out(`${continuation}${line}`)
+    rowsEmitted += 1
+  }
+
+  if (cveId) row('CVE', cveId)
+  if (container.title) row('Title', container.title)
+
+  const description = getDescription(container)
+  if (description) {
+    const [firstLine, ...rest] = String(description).split('\n')
+    row('Description', firstLine, ...rest)
+  }
+
+  const affected = container.affected ?? []
+  if (affected.length > 0) {
+    const [first, ...rest] = affected
+    row('Affected', summarizeAffected(first), ...rest.map(summarizeAffected))
+  }
+
+  const cvss = getCvss(container)
+  if (cvss) {
+    const score = typeof cvss.score === 'number' ? cvss.score.toFixed(1) : '?'
+    row(`CVSS ${cvss.version}`, `${score} ${cvss.severity ?? ''} (${cvss.vector})`.trimEnd().replace(/^\s+/, ''))
+  }
+
+  const cwes = getCwes(container)
+  if (cwes.length > 0) row('CWE', cwes.join(', '))
+
+  const credits = container.credits ?? []
+  if (credits.length > 0) {
+    row('Credits', credits.map(summarizeCredit).join(', '))
+  }
+
+  const refs = container.references ?? []
+  if (refs.length > 0) {
+    const [first, ...rest] = refs.map(r => r?.url ?? '?')
+    row('References', first, ...rest)
+  }
+
+  if (container.x_generator?.engine) {
+    row('Generator', container.x_generator.engine)
+  }
+
+  out('')
+  return lines.join('\n')
+}