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

package/README.md

@@ -29,11 +29,12 @@ For project maintainers under the OpenJS CNA who need to reserve, publish, updat
 |---|---|
 | `openjs-cna-experimental reserve` | Reserve a CVE id and print it on stdout. |
 | `openjs-cna-experimental publish <cve-id> -f container.json` | Publish a v5.2 CNA Container. Runs the reviewer first by default. |
+| `openjs-cna-experimental publish -f a.json -f b.json …` | Batch publish. Reviews every record first and sends nothing unless all pass, then publishes each in order. `--skip-published` makes reruns idempotent, `--json` prints one result per record. |
 | `openjs-cna-experimental update <cve-id> -f container.json` | Update a published CVE record. Same review semantics as `publish`. |
 | `openjs-cna-experimental get <cve-id>` | Fetch a published CVE's container from MITRE. |
 | `openjs-cna-experimental list` | List every CVE id in the bucket. |
 | `openjs-cna-experimental convert <advisory-url>` | Turn a GitHub Security Advisory into a draft CNA Container. Accepts published per-repo URLs (`https://github.com/<owner>/<repo>/security/advisories/<GHSA>`) and global-database URLs (`https://github.com/advisories/<GHSA>`) for public ones. |
-| `openjs-cna-experimental review <container.json>` | Run the offline reviewer against a container. Defaults to showing a preview + issues. Exits non-zero on blockers. |
+| `openjs-cna-experimental review <container.json> [more.json …]` | Run the offline reviewer against one or more records. Defaults to showing a preview + issues. Exits non-zero on blockers. With several files `--json` emits an array. |
 | `openjs-cna-experimental preview <container.json>` | Print a compact summary of a container — title, description, affected, CVSS, CWE, credits, refs, etc. |
 | `openjs-cna-experimental llm-review-prompt <record.json>` | Print a prompt for an LLM-driven editorial review of the record's title and description. The tool does not call an LLM; paste the prompt into the LLM of your choice. |
 | `openjs-cna-experimental health` | Unauthenticated liveness check against the CNA API. |
@@ -138,6 +139,35 @@ Useful flags:
 - `--no-preview` (on `review`): drop the container summary; print issues only. Useful in CI.
 - `--tier mitre-common|openjs-extra` (on `review`): filter the printed issues to a single tier without changing the exit code.
 - `--yes` / `OPENJS_CNA_YES=1`: accept confirmation prompts non-interactively.
+- `--skip-published` (on batch `publish`): ask the CNA first (`get-cve`, one sequential call per id) and skip ids that already have a published record, so a rerun after a partial failure only sends what is missing. Only a record-shaped answer counts as published; a failed or empty lookup sends the record, since a second publish fails loudly at the CNA while a wrong skip would silently send nothing.
+
+Publishing a release with several CVEs from CI:
+
+```sh
+# Every record carries cveMetadata.cveId. Review all, send nothing on any
+# blocker, otherwise publish each in order; exit 1 if anything failed.
+openjs-cna-experimental review  records/*.json --no-preview
+openjs-cna-experimental publish -f records/*.json --yes --skip-published --json > publish-result.json
+```
+
+How a batch behaves, and what to expect on a retry:
+
+- **Everything is sequential.** Records are reviewed, checked and published
+  one at a time, in the order given. There is no concurrency against the
+  CNA API.
+- **Without `--skip-published` the batch assumes a green field.** No lookup
+  is made; every record is sent. An id that was already published fails at
+  the CNA with its `correlation_id` / `run_id`, the remaining records still
+  go out, and the exit code is 1. Nothing is ever published twice, MITRE
+  rejects the second publish.
+- **With `--skip-published` the batch is a safe retry.** Each id is looked
+  up first with `get-cve`; ids that already have a published record are
+  reported as `skipped`, the rest are sent, and the exit code only reflects
+  what was sent. Use it whenever a run may repeat a previous one: a manual
+  re-run after a partial failure, or a pipeline that triggers more than
+  once for the same release. The lookups roughly double the run time.
+- **Review blockers stop everything.** If any record has a blocker nothing
+  is sent, with or without `--skip-published`.
 
 ### Troubleshooting
 
@@ -182,9 +212,88 @@ await cna.publishCve(cveId, record.containers.cna)
 
 Error classes (`CnaAuthError`, `CnaTimeoutError`, `CnaOperationError`, `CnaReviewBlockedError`) are exported from the package root.
 
+### CVSS
+
+Trackers such as HackerOne store only the CVSS vector, while MITRE requires
+`baseScore` and `baseSeverity` on every metric block. The package ships a
+dependency-free CVSS v3.0 / v3.1 base score calculator for that gap:
+
+```js
+import { calculateBaseScore } from '@ulisesgascon/openjs-cna-tools/cvss'
+
+calculateBaseScore('CVSS:3.0/AV:N/AC:H/PR:N/UI:N/S:U/C:L/I:H/A:N')
+// { version: '3.0', vectorString: 'CVSS:3.0/…', baseScore: 6.5, baseSeverity: 'MEDIUM' }
+```
+
+Only the base metric group is scored; temporal and environmental components
+are kept in the vector string and ignored. `parseCvssVector`, `roundUp` and
+`severityFromScore` are exported as well. CVSS 4.0 is not supported yet.
+
+### Batch review and publish
+
+The CLI's multi-file mode is a thin wrapper over two library functions:
+
+```js
+import { reviewRecords, publishRecords } from '@ulisesgascon/openjs-cna-tools/batch'
+
+const entries = files.map((file) => ({ file, record: JSON.parse(readFileSync(file, 'utf8')) }))
+
+// [{ file, cveId, ready, summary, issues }] — a record without
+// cveMetadata.cveId gets a `cve-id-present` blocker.
+const review = reviewRecords(entries, { strict: true })
+
+// Reviews again, sends nothing if any record has a blocker, then publishes
+// each one; `results` is [{ file, cveId, status, correlationId, runId, error }]
+// with status published | skipped | failed.
+const { blocked, results } = await publishRecords(entries, {
+  client: cna,
+  skipPublished: true,
+  onProgress: (event) => console.error(event.cveId, event.status)
+})
+```
+
+### Record helpers
+
+Converters only know their own source. The parts of a record that are about
+MITRE's format rather than the source live in one place, so no consumer
+hardcodes the OpenJS CNA org id, the generator string or the CVSS block
+layout:
+
+```js
+import { buildCvssMetric, buildProblemType, buildRecordEnvelope } from '@ulisesgascon/openjs-cna-tools/record'
+
+const record = buildRecordEnvelope({
+  cveId: 'CVE-2026-0001',
+  cna: {
+    title: '…',
+    descriptions: [{ lang: 'en', value: '…' }],
+    affected: [/* … */],
+    references: [/* … */],
+    // id normalised to CWE-<number>; description is the name, or the id
+    problemTypes: [buildProblemType({ cweId: 400, name: 'Uncontrolled Resource Consumption' })],
+    // key (cvssV3_0 / cvssV3_1 / cvssV4_0) follows the vector prefix;
+    // a missing v3.x score is computed, a v4.0 score must be passed in
+    metrics: [buildCvssMetric('CVSS:3.0/AV:N/AC:H/PR:N/UI:N/S:U/C:L/I:H/A:N')]
+  }
+})
+// record.dataType / dataVersion / cveMetadata set, providerMetadata.orgId
+// and x_generator.engine filled on the container unless already present.
+```
+
+The GHSA converter is built on the same helpers.
+
+The same calculator backs two behaviours:
+
+- the reviewer's `cvss-score-matches-vector` rule (blocker) recomputes the
+  score of every v3.x block and rejects a `baseScore` that disagrees with its
+  vector, since MITRE accepts the record as sent and never re-scores it;
+- the GHSA converter fills `baseScore` and `baseSeverity` from the vector when
+  the advisory carries a v3.1 vector without a score.
+
 ## Design
 
 - **Two runtime dependencies.** Built on Node.js 22+ built-ins (`fetch`, `node:test`, `node:util parseArgs`, `node:readline/promises`) with [`ajv`](https://github.com/ajv-validator/ajv) + [`ajv-formats`](https://github.com/ajv-validator/ajv-formats) — used only for validating containers against MITRE's official v5.2 schema before publish.
+- **Scores vectors itself.** A bundled CVSS v3.0 / v3.1 calculator (`lib/cvss.js`) lets the reviewer verify that every `baseScore` matches its vector and lets converters fill a missing score. No external calculator, no network.
 - **Validates against MITRE's official schema.** The CVE Record Format schema and its companion files (CVSS v2/v3/v4, CNA/ADP/reference tags) ship bundled from the [CVE Project](https://github.com/CVEProject/cve-schema). `openjs-cna-experimental review` and the default behavior of `openjs-cna-experimental publish` catch anything that would fail at MITRE.
 - **Two-tier rule classification.** Issues carry a `tier`: `mitre-common` (MITRE's schema itself would reject) or `openjs-extra` (OpenJS Foundation editorial preference, stricter than MITRE). The `--tier mitre-common` flag on `review` filters the printed list without changing the exit code.
 - **Preview before commit.** `openjs-cna-experimental preview` and the default `openjs-cna-experimental review` render a full summary of the container (title, full description, every affected package, CVSS, CWE, credits, references) so an operator can see *exactly* what they're about to send. The output includes a tip to edit the JSON visually at <https://vulnogram.org/#source>.

package/components/publish.js

@@ -1,11 +1,21 @@
-// openjs-cna-experimental publish <cve-id> [-f container.json] [--skip-review] [--no-strict]
+// openjs-cna-experimental publish <cve-id> [-f record.json] [--skip-review] [--no-strict]
+// openjs-cna-experimental publish -f a.json -f b.json … [--skip-published] [--json]
 //
-// Cross-checks the CLI <cve-id> against `container.cveMetadata.cveId` if
-// present (hard-error on mismatch); fills cveMetadata in when absent.
-// Then runs the reviewer (strict by default — warnings block too). On a
-// clean review (or `--skip-review`), prompts for confirmation and
-// publishes. Surfaces `correlation_id` + `run_id` after publish so the
-// operator can forward to a CNA coordinator if needed.
+// Single record: cross-checks the CLI <cve-id> against `record.cveMetadata.cveId`
+// if present (hard-error on mismatch); the CLI arg is the sole source of
+// truth when the record has none. Runs the reviewer (strict by default —
+// warnings block too). On a clean review (or `--skip-review`), prompts for
+// confirmation and publishes. Surfaces `correlation_id` + `run_id` after
+// publish so the operator can forward them to a CNA coordinator if needed.
+//
+// Batch (no <cve-id>, one or more -f): every record must carry
+// cveMetadata.cveId. All records are reviewed first and nothing is sent
+// unless all of them pass; then each one is published in order, a failure
+// is recorded and the rest still go out. One confirmation covers the whole
+// batch. --skip-published asks the CNA first and skips ids that already
+// have a published record, so reruns after a partial failure stay green.
+// --json prints one result per record on stdout. Exit code is 1 when the
+// review blocked or any record failed.
 
 import {
   parseComponentArgs,
@@ -14,36 +24,44 @@ import {
   readFileOrStdin
 } from '../lib/component-utils.js'
 import { reviewRecord } from '../lib/review/index.js'
+import { publishRecords } from '../lib/batch.js'
 import { CnaReviewBlockedError } from '../lib/errors.js'
 
 export const command = 'publish'
-export const describe = 'Publish a v5.2 CNA Container for a reserved CVE.'
+export const describe = 'Publish one or more v5.2 CVE Records for reserved CVE ids.'
 
 export async function handler (argv) {
   const parsed = parseComponentArgs(argv, {
-    file: { type: 'string', short: 'f' },
+    file: { type: 'string', short: 'f', multiple: true },
     'skip-review': { type: 'boolean' },
-    'no-strict': { type: 'boolean' }
+    'no-strict': { type: 'boolean' },
+    'skip-published': { type: 'boolean' }
   }, { allowPositionals: true })
   if (parsed.values.help) return printHelp()
 
   const cveId = parsed.positionals[0]
+  const files = parsed.values.file ?? []
+  const strict = !parsed.values['no-strict']
+  const skipReview = parsed.values['skip-review']
+
   if (!cveId) {
-    process.stderr.write('✖ Missing CVE id. Usage: openjs-cna-experimental publish <CVE-...> -f container.json\n')
+    if (files.length === 0) {
+      process.stderr.write('✖ Missing CVE id. Usage: openjs-cna-experimental publish <CVE-...> -f record.json\n' +
+        '  or, for a batch: openjs-cna-experimental publish -f a.json -f b.json\n')
+      process.exit(64)
+    }
+    return publishMany(files, {
+      parsed, strict, skipReview, skipPublished: parsed.values['skip-published']
+    })
+  }
+  if (files.length > 1) {
+    process.stderr.write('✖ Several -f files need batch mode: drop the <cve-id> argument.\n')
     process.exit(64)
   }
 
   const cli = buildCli(parsed)
   const client = buildClient(parsed)
-
-  const raw = await readFileOrStdin(parsed.values.file)
-  let record
-  try {
-    record = JSON.parse(raw)
-  } catch (e) {
-    process.stderr.write(`✖ File is not valid JSON: ${e.message}\n`)
-    process.exit(64)
-  }
+  const record = await readRecord(files[0])
 
   // CVE id consistency check. The Record's cveMetadata.cveId must match
   // the CLI arg; mismatch is a hard error (operator was probably about to
@@ -63,8 +81,7 @@ export async function handler (argv) {
   // assignerOrgId and dateUpdated MITRE injects).
   const container = record.containers.cna
 
-  if (!parsed.values['skip-review']) {
-    const strict = !parsed.values['no-strict']
+  if (!skipReview) {
     const report = reviewRecord(record, { strict })
     // Strict mode promotes warnings to blockers inside reviewRecord, so
     // the `summary.blockers` count already reflects strictness. We just
@@ -73,10 +90,7 @@ export async function handler (argv) {
       cli.error(
         `Review blocked publish: ${report.summary.blockers} blocker(s)`
       )
-      for (const issue of report.issues) {
-        const tag = issue.severity === 'blocker' ? '✖' : issue.severity === 'warning' ? '⚠' : '·'
-        cli.log(`  ${tag} [${issue.rule}] ${issue.message}`)
-      }
+      printIssues(cli, report.issues)
       cli.log('')
       cli.log('  Re-run with --skip-review to bypass.')
       throw new CnaReviewBlockedError(
@@ -95,7 +109,7 @@ export async function handler (argv) {
   // (and we got here without --skip-review). Honors --yes / OPENJS_CNA_YES.
   const confirmed = await cli.prompt(
     `Publish ${cveId}? This is irreversible.`,
-    { defaultAnswer: !parsed.values['skip-review'] }
+    { defaultAnswer: !skipReview }
   )
   if (!confirmed) {
     cli.info('Aborted.')
@@ -115,18 +129,109 @@ export async function handler (argv) {
   if (result) process.stdout.write(JSON.stringify(result, null, 2) + '\n')
 }
 
+async function publishMany (files, { parsed, strict, skipReview, skipPublished }) {
+  const cli = buildCli(parsed)
+  const entries = []
+  for (const file of files) {
+    entries.push({ file, record: await readRecord(file) })
+  }
+
+  // The reviewer runs inside publishRecords too; this early pass exists so
+  // the operator sees the ids before confirming, and so a missing id is
+  // caught before credentials are even resolved.
+  const ids = entries.map((entry) => entry.record?.cveMetadata?.cveId ?? `${entry.file} (no cveMetadata.cveId)`)
+  cli.info(`Publishing ${entries.length} record(s): ${ids.join(', ')}`)
+  const confirmed = await cli.prompt(
+    `Publish ${entries.length} record(s)? This is irreversible.`,
+    { defaultAnswer: !skipReview }
+  )
+  if (!confirmed) {
+    cli.info('Aborted.')
+    return
+  }
+
+  const client = buildClient(parsed)
+  const outcome = await publishRecords(entries, {
+    client,
+    strict,
+    skipReview,
+    skipPublished,
+    onProgress: (event) => {
+      const trace = traceOf(event)
+      if (event.status === 'published') cli.ok(`Published ${event.cveId}${trace}`)
+      else if (event.status === 'skipped') cli.info(`Skipped ${event.cveId}: ${event.reason}`)
+      else cli.error(`Failed ${event.cveId}: ${event.error}${trace}`)
+    }
+  })
+
+  if (outcome.blocked) {
+    const blocked = outcome.review.filter((item) => !item.ready)
+    cli.error(`Review blocked publish: ${blocked.length} of ${outcome.review.length} record(s) have blockers. Nothing was sent.`)
+    for (const item of blocked) {
+      cli.log(`  ${item.file}${item.cveId ? ` (${item.cveId})` : ''}`)
+      printIssues(cli, item.issues.filter((issue) => issue.severity === 'blocker'), '    ')
+    }
+    if (parsed.values.json) process.stdout.write(JSON.stringify(outcome.review, null, 2) + '\n')
+    process.exit(1)
+  }
+
+  if (parsed.values.json) process.stdout.write(JSON.stringify(outcome.results, null, 2) + '\n')
+  const failed = outcome.results.filter((item) => item.status === 'failed')
+  const published = outcome.results.filter((item) => item.status === 'published').length
+  const skipped = outcome.results.filter((item) => item.status === 'skipped').length
+  cli.log('')
+  cli.info(`${published} published · ${skipped} skipped · ${failed.length} failed`)
+  if (failed.length) {
+    cli.info('Forward the correlation_id / run_id pairs above to your CNA coordinator.')
+    process.exit(1)
+  }
+}
+
+function traceOf (event) {
+  const parts = []
+  if (event.correlationId) parts.push(`correlation_id=${event.correlationId}`)
+  if (event.runId) parts.push(`run_id=${event.runId}`)
+  return parts.length ? ` (${parts.join(', ')})` : ''
+}
+
+function printIssues (cli, issues, indent = '  ') {
+  for (const issue of issues) {
+    const tag = issue.severity === 'blocker' ? '✖' : issue.severity === 'warning' ? '⚠' : '·'
+    cli.log(`${indent}${tag} [${issue.rule}] ${issue.message}`)
+  }
+}
+
+async function readRecord (file) {
+  const raw = await readFileOrStdin(file)
+  try {
+    return JSON.parse(raw)
+  } catch (e) {
+    process.stderr.write(`✖ ${file ?? 'stdin'} is not valid JSON: ${e.message}\n`)
+    process.exit(64)
+  }
+}
+
 function printHelp () {
   process.stderr.write(
-`openjs-cna-experimental publish <cve-id> [-f container.json]
+`openjs-cna-experimental publish <cve-id> [-f record.json]
+openjs-cna-experimental publish -f a.json -f b.json … [--skip-published]
 
-Publish a v5.2 CNA Container against an already-reserved CVE id. Default
+Publish v5.2 CVE Records against already-reserved CVE ids. Default
 behavior runs the reviewer first (strict — warnings block too) and aborts
 on any issue.
 
+Without <cve-id> every -f record is published as a batch: each record must
+carry cveMetadata.cveId, all records are reviewed before anything is sent,
+then each is published in order (a failure does not stop the others). One
+confirmation covers the batch. Exit code is 1 if the review blocked or any
+record failed.
+
 Options:
-  -f, --file <path>     read the container from a file (default: stdin)
+  -f, --file <path>     read a record from a file (default: stdin); repeatable
   --skip-review         do not run the reviewer
   --no-strict           let warnings pass through (only true blockers abort)
+  --skip-published      batch only: skip ids the CNA already has published
+  --json                batch only: print one result per record on stdout
   [global flags]
 `
   )

package/components/review.js

@@ -1,17 +1,24 @@
-// openjs-cna-experimental review <container.json> [--no-strict] [--no-preview] [--tier <name>] [--json]
+// openjs-cna-experimental review <record.json> [<record.json>…] [--no-strict] [--no-preview] [--tier <name>] [--json]
 //
-// Runs the offline reviewer against a CNA Container. Strict by default
-// (warnings block); --no-strict surfaces them as warnings. Renders the
-// preview before the issues list unless --no-preview. --tier filters the
-// printed issues to a single severity tier (mitre-common / openjs-extra)
+// Runs the offline reviewer against one or more CVE Records. Strict by
+// default (warnings block); --no-strict surfaces them as warnings. Renders
+// the preview before the issues list unless --no-preview. --tier filters
+// the printed issues to a single severity tier (mitre-common / openjs-extra)
 // without changing the exit code, which always reflects the full review.
+//
+// With several files every record is reviewed (no early stop), each block
+// is headed by the file and CVE id, --json emits an array, and the exit
+// code is 1 when any record has a blocker. A record without
+// cveMetadata.cveId is a blocker in batch mode, since batch publish needs
+// the id from the record.
 
 import { parseComponentArgs, buildCli, readFileOrStdin } from '../lib/component-utils.js'
 import { reviewRecord } from '../lib/review/index.js'
+import { reviewRecords } from '../lib/batch.js'
 import { renderPreview } from '../lib/preview.js'
 
 export const command = 'review'
-export const describe = 'Review a v5.2 CNA Container against best-practice rules.'
+export const describe = 'Review one or more v5.2 CVE Records against best-practice rules.'
 
 const VALID_TIERS = new Set(['mitre-common', 'openjs-extra'])
 
@@ -24,7 +31,7 @@ export async function handler (argv) {
   if (parsed.values.help) return printHelp()
 
   const cli = buildCli(parsed)
-  const file = parsed.positionals[0]
+  const files = parsed.positionals
 
   // Validate the --tier filter early so a typo doesn't silently match
   // nothing and look like a clean review.
@@ -36,16 +43,15 @@ export async function handler (argv) {
     process.exit(64)
   }
 
-  const raw = await readFileOrStdin(file)
-  let container
-  try {
-    container = JSON.parse(raw)
-  } catch (e) {
-    process.stderr.write(`✖ Container is not valid JSON: ${e.message}\n`)
-    process.exit(64)
+  const strict = !parsed.values['no-strict']
+  const showPreview = !parsed.values['no-preview']
+
+  if (files.length > 1) {
+    return reviewMany(files, { cli, strict, showPreview, tierFilter, json: parsed.values.json })
   }
 
-  const report = reviewRecord(container, { strict: !parsed.values['no-strict'] })
+  const container = await readRecord(files[0])
+  const report = reviewRecord(container, { strict })
 
   if (parsed.values.json) {
     process.stdout.write(JSON.stringify(report, null, 2) + '\n')
@@ -53,7 +59,7 @@ export async function handler (argv) {
     // Preview goes first so the operator sees what they're about to ship
     // alongside what the reviewer caught. --no-preview drops it for
     // CI / pipeline use.
-    if (!parsed.values['no-preview']) renderPreview(container, cli)
+    if (showPreview) renderPreview(container, cli)
     printHumanReport(cli, report, { tierFilter })
   }
 
@@ -61,6 +67,44 @@ export async function handler (argv) {
   if (report.summary.blockers > 0) process.exit(1)
 }
 
+async function reviewMany (files, { cli, strict, showPreview, tierFilter, json }) {
+  const entries = []
+  for (const file of files) {
+    entries.push({ file, record: await readRecord(file) })
+  }
+  const review = reviewRecords(entries, { strict })
+
+  if (json) {
+    process.stdout.write(JSON.stringify(review, null, 2) + '\n')
+  } else {
+    review.forEach((item, index) => {
+      cli.log('')
+      cli.log(`── ${item.file}${item.cveId ? ` (${item.cveId})` : ''}`)
+      if (showPreview) renderPreview(entries[index].record, cli)
+      printHumanReport(cli, item, { tierFilter })
+    })
+    const blocked = review.filter((item) => !item.ready).length
+    cli.log('')
+    if (blocked) {
+      cli.error(`${blocked} of ${review.length} record(s) blocked`)
+    } else {
+      cli.ok(`${review.length} record(s) ready`)
+    }
+  }
+
+  if (review.some((item) => !item.ready)) process.exit(1)
+}
+
+async function readRecord (file) {
+  const raw = await readFileOrStdin(file)
+  try {
+    return JSON.parse(raw)
+  } catch (e) {
+    process.stderr.write(`✖ ${file ?? 'stdin'} is not valid JSON: ${e.message}\n`)
+    process.exit(64)
+  }
+}
+
 function printHumanReport (cli, report, { tierFilter } = {}) {
   const { summary, issues } = report
   const ratingLabel = {
@@ -105,16 +149,19 @@ function printHumanReport (cli, report, { tierFilter } = {}) {
 
 function printHelp () {
   process.stderr.write(
-`openjs-cna-experimental review <container.json>
+`openjs-cna-experimental review <record.json> [<record.json>…]
 
-Run the offline reviewer against a CNA Container. Strict by default —
-warnings are treated as blockers because publishing to MITRE is
+Run the offline reviewer against one or more CVE Records. Strict by
+default — warnings are treated as blockers because publishing to MITRE is
 irreversible. Pass --no-strict to surface warnings as warnings.
 
+With several files every record is reviewed, --json emits an array with
+one entry per file, and the exit code is 1 when any record has a blocker.
+
 Options:
   --no-strict        surface warnings as warnings (default treats them as blockers)
   --json             emit a structured JSON report instead of the human view
-  --no-preview       skip the container preview (for CI / pipelines)
+  --no-preview       skip the record preview (for CI / pipelines)
   --tier <tier>      filter the printed issue list to a single tier
                      (mitre-common | openjs-extra). Summary counts still
                      reflect the full review; exit code is unaffected.

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, 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.
@@ -234,26 +230,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 +248,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 +259,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 +421,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/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,123 @@
+// 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 CVSS metric block
+// 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'
+
+// 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.3",
   "description": "EXPERIMENTAL fork of the OpenJS Foundation CNA tools: CLI and library for the OpenJS CNA API",
   "type": "module",
   "license": "MIT",
@@ -11,14 +11,17 @@
     "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"
   },
   "files": [
     "bin/",