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

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,115 @@ 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)
+})
+```
+
+### HackerOne weaknesses
+
+HackerOne's REST API reports a finding's weakness as HackerOne's own numeric
+`weakness_id`, not as a CWE number (weakness 26 is "Improper Access Control",
+CWE-284). The taxonomy is shared by every program, so the mapping ships with
+the package as data:
+
+```js
+import { hackerOneWeakness, hackerOneWeaknessProblemType } from '@ulisesgascon/openjs-cna-tools/hackerone'
+
+hackerOneWeakness(26)
+// { cwe: 'CWE-284', name: 'Improper Access Control - Generic' }
+hackerOneWeakness(75)
+// { cwe: null, name: 'Privilege Escalation' }   (a CAPEC entry on HackerOne's side)
+hackerOneWeakness(999999)
+// null                                          (unknown id)
+
+// Ready-made problemTypes[] entry, or null when there is no CWE to put on the record.
+hackerOneWeaknessProblemType(26)
+```
+
+`lib/hackerone/weaknesses.json` is regenerated with
+`node scripts/build-hackerone-weaknesses.js <dump.json>` from the GraphQL
+response the HackerOne web app loads for a report's weakness picker; the
+script documents the shape it expects.
+
+### 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, buildDescription, buildProblemType, buildRecordEnvelope } from '@ulisesgascon/openjs-cna-tools/record'
+
+const record = buildRecordEnvelope({
+  cveId: 'CVE-2026-0001',
+  cna: {
+    title: '…',
+    // plain text in `value`; the Markdown, if any, kept in supportingMedia
+    descriptions: [buildDescription('A flaw in `dns.resolve()` allows **remote** attackers …')],
+    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.