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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ulises Gascón
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,313 @@
-# Temporary Holding Version
+# OpenJS CNA Tools
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/@ulisesgascon/openjs-cna-tools.svg?style=flat-square)](https://npmjs.org/package/@ulisesgascon/openjs-cna-tools)
+
+EXPERIMENTAL CLI and library for operating the [OpenJS Foundation CNA API](https://cna.openjsf.org/api.html).
+
+For project maintainers under the OpenJS CNA who need to reserve, publish, update, and inspect CVEs against the OpenJS CNA API (MITRE wrapper) without leaving their terminal.
+
+<!-- TOC -->
+
+- [Commands](#commands)
+- [Usage](#usage)
+  - [Install](#install)
+  - [Setting up CNA credentials](#setting-up-cna-credentials)
+  - [Protecting your credentials](#protecting-your-credentials)
+  - [Typical workflow](#typical-workflow)
+  - [Troubleshooting](#troubleshooting)
+- [Library](#library)
+- [Design](#design)
+- [License](#license)
+
+<!-- /TOC -->
+
+## Commands
+
+`openjs-cna-experimental` is a single binary that dispatches subcommands.
+
+| Command | Description |
+|---|---|
+| `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> [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. |
+| `openjs-cna-experimental config` | Read / write `openjs-cna-experimental` configuration. |
+
+Run `openjs-cna-experimental <command> --help` for command-specific options.
+
+## Usage
+
+### Install
+
+```sh
+pnpm add -g @ulisesgascon/openjs-cna-tools
+# or
+npm install -g @ulisesgascon/openjs-cna-tools
+```
+
+To build from source:
+
+```sh
+git clone https://github.com/UlisesGascon/openjs-cna-tools.git
+cd openjs-cna-tools
+pnpm install
+pnpm link --global
+```
+
+Requires Node.js **22.0.0** or newer. The package is ESM-only and uses native `fetch`, `node:util parseArgs`, and `node:readline/promises`. Runtime dependencies are [`ajv`](https://github.com/ajv-validator/ajv) and [`ajv-formats`](https://github.com/ajv-validator/ajv-formats), used solely for JSON Schema validation against MITRE's official v5.2 CNA Container schema.
+
+### Setting up CNA credentials
+
+`openjs-cna-experimental` needs two values to talk to the CNA API:
+
+- `openjs_cna_token` — bearer in `bucket:secret` form. Your CNA coordinator issues this.
+- `openjs_cna_base_url` — the API base URL (e.g. `https://cna.openjsf.org`).
+
+Configure them with `openjs-cna-experimental config`:
+
+```sh
+openjs-cna-experimental config set openjs_cna_token    "<bucket>:<hex-secret>"
+openjs-cna-experimental config set openjs_cna_base_url "https://cna.openjsf.org"
+```
+
+> **Stored values are not encrypted at rest.** They live as plaintext in `~/.config/openjs-cna/config.json` with file mode `0600`. If you'd rather not put a token on disk, pass them via environment variables instead:
+>
+> ```sh
+> export OPENJS_CNA_TOKEN="<bucket>:<hex-secret>"
+> export OPENJS_CNA_BASE_URL="https://cna.openjsf.org"
+> ```
+
+Configuration is layered. Precedence (highest first):
+
+1. CLI flag (`--token`, `--base-url`)
+2. Environment (`OPENJS_CNA_*`)
+3. Project config (`./.openjs-cna.json` in CWD)
+4. Global config (`~/.config/openjs-cna/config.json` or `$XDG_CONFIG_HOME/openjs-cna/config.json`)
+
+### Protecting your credentials
+
+Add the following to your [global `gitignore`](https://git-scm.com/docs/git-config#Documentation/git-config.txt-coreexcludesFile) (or the per-repo `.gitignore` if you only need it locally):
+
+```
+# openjs-cna-tools project-scope config
+.openjs-cna.json
+```
+
+The global config at `~/.config/openjs-cna/config.json` lives outside any repo, so it doesn't need a gitignore entry. The project-scope `.openjs-cna.json` does.
+
+If you ever commit a token, revoke it with your CNA coordinator and request a new one.
+
+### Typical workflow
+
+```sh
+# 1. Reserve a CVE id for an upcoming release.
+CVE=$(openjs-cna-experimental reserve)
+echo "Reserved $CVE"
+
+# 2. Draft a container from a published GitHub Security Advisory.
+#    `--cve` stamps cveMetadata.cveId into the container so step 5 can
+#    cross-check the CLI argument against it.
+openjs-cna-experimental convert https://github.com/owner/repo/security/advisories/GHSA-xxxx-xxxx-xxxx \
+  --cve "$CVE" > container.json
+
+# 3. (Optional) Editorial polish via an LLM. Pipes a prompt to your
+#    clipboard; paste it plus container.json into the LLM of your choice.
+openjs-cna-experimental llm-review-prompt container.json | pbcopy
+
+# 4. Review before you publish. The output renders a preview of the
+#    container plus the issues list (tip: edit visually at
+#    https://vulnogram.org/#source).
+openjs-cna-experimental review container.json
+
+# 5. Publish. Review runs again automatically (strict, warnings block);
+#    if `container.cveMetadata.cveId` is set, it must match "$CVE" or
+#    publish aborts before sending anything to MITRE.
+openjs-cna-experimental publish "$CVE" -f container.json
+```
+
+Useful flags:
+
+- `--no-strict` (on `review`, `publish`, `update`): let warnings pass as warnings. True blockers still abort.
+- `--skip-review` (on `publish`, `update`): bypass the reviewer entirely. Discouraged.
+- `--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
+
+- **Review reports schema blockers**: paste the container into <https://vulnogram.org/#source> to edit it visually; rerun `openjs-cna-experimental review` when done.
+- **Publish fails with a CVE-id mismatch**: the CLI argument and `container.cveMetadata.cveId` disagree. Re-check which container you meant to publish before retrying.
+- **An operation errors out**: the CLI prints `correlation_id` and `run_id`. Forward both to your CNA coordinator — that's everything they need to look up the underlying GitHub Actions run. (We deliberately don't surface the run URL because most operators don't have access to it.)
+
+## Library
+
+The same module powers the CLI and is importable for automation:
+
+```js
+import { CnaClient } from '@ulisesgascon/openjs-cna-tools/client'
+import { reviewRecord } from '@ulisesgascon/openjs-cna-tools/review'
+import { convertGhsaToRecord } from '@ulisesgascon/openjs-cna-tools/convert'
+
+const cna = new CnaClient({
+  token: process.env.OPENJS_CNA_TOKEN,
+  baseUrl: process.env.OPENJS_CNA_BASE_URL
+})
+
+const { cveId } = await cna.reserveCve()
+
+// `source` is a published GitHub advisory URL. References (including any
+// vendor-advisory blog post you want surfaced on the CVE record) come
+// from the advisory's own `references[]` — set them on GitHub, not via
+// any per-call override here. Pass `cveId` to stamp it into `cveMetadata`.
+const record = await convertGhsaToRecord({
+  source: 'https://github.com/owner/repo/security/advisories/GHSA-xxxx-xxxx-xxxx',
+  cveId
+})
+
+// reviewRecord is strict by default — warnings count as blockers.
+// Pass `{ strict: false }` to surface warnings as warnings.
+const report = reviewRecord(record)
+if (report.summary.blockers > 0) {
+  throw new Error('record is not ready to publish')
+}
+
+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>.
+- **Strict by default.** `review`, `publish`, and `update` treat warnings as blockers. Pass `--no-strict` only when you understand the warning is acceptable.
+- **CVE-id consistency.** When `container.cveMetadata.cveId` is set and the CLI argument differs, `publish` and `update` abort before touching MITRE.
+- **Multi-package advisories handled.** One CNA Container can carry every package an advisory affects (the lodash family of per-method packages is a common case). The converter expands GHSA's `vulnerabilities[]` array into MITRE's `affected[]` entries one-to-one.
+- **GHSA descriptions are Markdown.** The converter declares `descriptions[].supportingMedia[]` with `type: 'text/markdown'` so the formatting isn't lost on the way to MITRE.
+- **Identified at the source.** Every container the converter produces carries `cna.x_generator = { engine: '@ulisesgascon/openjs-cna-tools <version>' }`, and every outbound HTTP call uses the same string as `User-Agent`. A downstream reviewer can always trace a record back to the exact tool version that drafted it.
+- **Operator-friendly error surfacing.** Failures emit `correlation_id` and `run_id` (not opaque GitHub URLs) so operators can forward a single line to a coordinator.
+- **Stdout is data; stderr is the show.** Every command's primary output goes to stdout so `CVE=$(openjs-cna-experimental reserve)` works without flags. Spinners, prompts, and progress go to stderr.
+- **The constructor does no I/O.** `new CnaClient()` makes zero network calls. Credentials are validated lazily on the first operation that needs them.
+
+The design draws heavily on [`node-core-utils`](https://github.com/nodejs/node-core-utils) — lazy auth accessors, errors that double as setup instructions, yargs-as-router (`node:util parseArgs` here), stdout/stderr discipline, and no mocking library. A longer design write-up will land in `docs/` as the package matures.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/bin/openjs-cna.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+
+// Router. Autoloads components/<verb>.js and hands the remaining argv to its
+// `handler`.
+
+import { readdirSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import {
+  CnaAuthError,
+  CnaTimeoutError,
+  CnaOperationError,
+  CnaReviewBlockedError
+} from '../lib/errors.js'
+
+const require = createRequire(import.meta.url)
+const pkg = require('../package.json')
+
+const componentsDir = new URL('../components/', import.meta.url)
+const here = path.dirname(fileURLToPath(import.meta.url))
+
+function listVerbs () {
+  try {
+    return readdirSync(componentsDir)
+      .filter(name => name.endsWith('.js'))
+      .map(name => name.slice(0, -3))
+      .sort()
+  } catch {
+    return []
+  }
+}
+
+function showHelp () {
+  const verbs = listVerbs()
+  process.stderr.write(
+`openjs-cna-experimental — operate the OpenJS Foundation CNA API
+
+Usage:
+  openjs-cna-experimental <command> [options]
+
+Commands:
+${verbs.map(v => '  ' + v).join('\n')}
+
+Global flags:
+  --token <value>           override resolved token
+  --base-url <url>          override resolved base URL
+  --timeout <seconds>       per-operation timeout
+  --poll-interval <secs>    polling interval
+  --json                    force JSON output where applicable
+  --quiet                   suppress non-essential stderr
+  --yes                     accept all confirmation prompts
+  --no-color                disable color output
+  --version, -v
+  --help, -h
+
+Run 'openjs-cna-experimental <command> --help' for command-specific options.
+`
+  )
+}
+
+function showVersion () {
+  process.stdout.write(`${pkg.version}\n`)
+}
+
+function mapErrorToExit (e) {
+  if (e instanceof CnaAuthError) return 2
+  if (e instanceof CnaTimeoutError) return 3
+  if (e instanceof CnaReviewBlockedError) return 1
+  if (e instanceof CnaOperationError) return 1
+  return 1
+}
+
+async function main () {
+  const argv = process.argv.slice(2)
+  if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+    showHelp()
+    process.exit(argv.length === 0 ? 0 : 0)
+  }
+  if (argv[0] === '--version' || argv[0] === '-v') {
+    showVersion()
+    process.exit(0)
+  }
+
+  const verb = argv[0]
+  const rest = argv.slice(1)
+
+  let mod
+  try {
+    mod = await import(new URL(`../components/${verb}.js`, import.meta.url))
+  } catch (e) {
+    if (e.code === 'ERR_MODULE_NOT_FOUND') {
+      process.stderr.write(`Unknown command: ${verb}\n\n`)
+      showHelp()
+      process.exit(64) // EX_USAGE
+    }
+    throw e
+  }
+
+  try {
+    await mod.handler(rest)
+    process.exit(0)
+  } catch (e) {
+    // The CLI components already log structured error context; we just need
+    // to map the error class to an exit code here. Anything not in the
+    // CnaError family bubbles its stack so unexpected bugs aren't silent.
+    if (
+      e instanceof CnaAuthError ||
+      e instanceof CnaTimeoutError ||
+      e instanceof CnaOperationError ||
+      e instanceof CnaReviewBlockedError
+    ) {
+      process.stderr.write(`✖ ${e.message}\n`)
+      if (e.correlationId || e.runId) {
+        process.stderr.write(`  Forward to coordinator: correlation_id=${e.correlationId ?? '?'}, run_id=${e.runId ?? '?'}\n`)
+      }
+      process.exit(mapErrorToExit(e))
+    }
+    throw e
+  }
+}
+
+main()
+
+// Make the import order quiet for linters/tools that expect a non-empty
+// epilogue when this file is imported as a module (it never is, but keep
+// the symbol stable).
+export { here }

package/components/config.js

@@ -0,0 +1,92 @@
+// openjs-cna-experimental config <set|get|list|delete> ...
+
+import {
+  parseComponentArgs,
+  buildCli
+} from '../lib/component-utils.js'
+import {
+  getConfigValue,
+  setConfigValue,
+  deleteConfigValue,
+  listConfig
+} from '../lib/config.js'
+
+export const command = 'config'
+export const describe = 'Read / write openjs-cna-experimental configuration.'
+
+export async function handler (argv) {
+  const parsed = parseComponentArgs(argv, {
+    project: { type: 'boolean' }
+  }, { allowPositionals: true })
+  if (parsed.values.help) return printHelp()
+
+  const cli = buildCli(parsed)
+  const [subverb, ...rest] = parsed.positionals
+  const scope = parsed.values.project ? 'project' : 'global'
+
+  switch (subverb) {
+    case 'set': {
+      const [key, value] = rest
+      if (!key || value === undefined) {
+        process.stderr.write('✖ Usage: openjs-cna-experimental config set <key> <value> [--project]\n')
+        process.exit(64)
+      }
+      const target = setConfigValue(key, value, { scope })
+      cli.ok(`Wrote ${key} to ${target}`)
+      return
+    }
+    case 'get': {
+      const [key] = rest
+      if (!key) {
+        process.stderr.write('✖ Usage: openjs-cna-experimental config get <key>\n')
+        process.exit(64)
+      }
+      const value = getConfigValue(key)
+      if (value === undefined) {
+        cli.error(`No config value for '${key}'`)
+        process.exit(1)
+      }
+      process.stdout.write(`${value}\n`)
+      return
+    }
+    case 'list': {
+      const config = listConfig()
+      process.stdout.write(JSON.stringify(config, null, 2) + '\n')
+      return
+    }
+    case 'delete': {
+      const [key] = rest
+      if (!key) {
+        process.stderr.write('✖ Usage: openjs-cna-experimental config delete <key> [--project]\n')
+        process.exit(64)
+      }
+      const removed = deleteConfigValue(key, { scope })
+      if (removed) cli.ok(`Deleted ${key} from ${scope} config`)
+      else cli.warn(`Key '${key}' was not present in ${scope} config`)
+      return
+    }
+    default:
+      process.stderr.write(`✖ Unknown config subcommand: ${subverb ?? '(none)'}\n`)
+      printHelp()
+      process.exit(64)
+  }
+}
+
+function printHelp () {
+  process.stderr.write(
+`openjs-cna-experimental config <subcommand> [options]
+
+Subcommands:
+  set <key> <value>    write a value (plaintext at ~/.config/openjs-cna/config.json,
+                       file mode 0600). For tokens you don't want on disk, use the
+                       OPENJS_CNA_TOKEN environment variable instead.
+  get <key>            read a value
+  list                 print the merged config (secrets redacted)
+  delete <key>         remove a value
+
+Options:
+  --project    operate on the project config (./.openjs-cna.json)
+               default is the global config (~/.config/openjs-cna/config.json)
+`
+  )
+}

package/components/convert.js

@@ -0,0 +1,81 @@
+// openjs-cna-experimental convert <advisory-url> [--cve <CVE-...>]
+//
+// Reads a public GitHub Security Advisory and emits a v5.2 CNA Container
+// draft on stdout. Two URL shapes accepted: per-repository and global-
+// database. Pre-fetched JSON can be piped via stdin (`openjs-cna-experimental convert -`).
+// When `--cve` is provided, the produced container carries
+// `cveMetadata.cveId` so a downstream publish/update can cross-check the
+// id against its CLI argument.
+
+import { parseComponentArgs, buildCli, readFileOrStdin } from '../lib/component-utils.js'
+import { convertGhsaToRecord } from '../lib/convert/ghsa.js'
+
+export const command = 'convert'
+export const describe = 'Convert a GitHub Security Advisory into a v5.2 CNA Container draft.'
+
+export async function handler (argv) {
+  const parsed = parseComponentArgs(argv, {
+    cve: { type: 'string' }
+  }, { allowPositionals: true })
+  if (parsed.values.help) return printHelp()
+
+  const cli = buildCli(parsed)
+  const positional = parsed.positionals[0]
+
+  let source
+  if (positional === '-') {
+    // Read raw GHSA JSON from stdin and pass through as a pre-fetched object.
+    const raw = await readFileOrStdin('-')
+    try { source = JSON.parse(raw) } catch (e) {
+      process.stderr.write(`✖ stdin is not valid JSON: ${e.message}\n`)
+      process.exit(64)
+    }
+  } else if (typeof positional === 'string' && positional.length > 0) {
+    source = positional
+  } else {
+    process.stderr.write(
+      '✖ Missing advisory URL. Usage:\n' +
+      '    openjs-cna-experimental convert <advisory-url>\n' +
+      '    openjs-cna-experimental convert -                  (read raw GHSA JSON from stdin)\n'
+    )
+    process.exit(64)
+  }
+
+  cli.info('Converting → CVE Record')
+  const record = await convertGhsaToRecord({ source, cveId: parsed.values.cve })
+  cli.ok('Conversion complete')
+  process.stdout.write(JSON.stringify(record, null, 2) + '\n')
+}
+
+function printHelp () {
+  process.stderr.write(
+`openjs-cna-experimental convert <advisory-url>
+
+Convert a GitHub Security Advisory into a v5.2 CNA Container draft. The
+result is the CNA-container portion of a CVE Record (cveMetadata is
+supplied by 'openjs-cna-experimental publish' at publish time). Output is a starting
+point — run 'openjs-cna-experimental review' on it before publish.
+
+This tool only reads PUBLIC published advisories. Both URL shapes hit
+api.github.com anonymously.
+
+Input shapes:
+
+  openjs-cna-experimental convert https://github.com/<owner>/<repo>/security/advisories/<GHSA>
+    Per-repository advisory URL. Resolves via
+    GET https://api.github.com/repos/<owner>/<repo>/security-advisories/<GHSA>.
+
+  openjs-cna-experimental convert https://github.com/advisories/<GHSA>
+    Global advisory database URL. Resolves via
+    GET https://api.github.com/advisories/<GHSA>.
+
+  openjs-cna-experimental convert -
+    Read raw GHSA advisory JSON from stdin (for pre-fetched payloads
+    or private/draft advisories the operator has fetched themselves).
+
+References for the CNA Container are derived from the advisory's
+\`references[]\` array. Put your vendor-advisory URL there before
+converting.
+`
+  )
+}

package/components/get.js

@@ -0,0 +1,35 @@
+// openjs-cna-experimental get <cve-id>
+// Fetches the v5.2 container for a published CVE from MITRE via the CNA API.
+
+import { parseComponentArgs, buildClient, buildCli } from '../lib/component-utils.js'
+
+export const command = 'get'
+export const describe = 'Fetch the CNA Container for a published CVE.'
+
+export async function handler (argv) {
+  const parsed = parseComponentArgs(argv, {}, { allowPositionals: true })
+  if (parsed.values.help) return printHelp()
+  const cveId = parsed.positionals[0]
+  if (!cveId) {
+    process.stderr.write('✖ Missing CVE id. Usage: openjs-cna-experimental get <CVE-...>\n')
+    process.exit(64)
+  }
+  const cli = buildCli(parsed)
+  const client = buildClient(parsed)
+  cli.info(`Fetching ${cveId}…`)
+  const record = await client.getCve(cveId, {
+    onPoll: (run) => { if (run.status !== 'completed') cli.info(`run status: ${run.status}`) }
+  })
+  cli.ok(`Got ${cveId}`)
+  process.stdout.write(JSON.stringify(record, null, 2) + '\n')
+}
+
+function printHelp () {
+  process.stderr.write(
+`openjs-cna-experimental get <cve-id>
+
+Fetch a published CVE's v5.2 container from MITRE. Prints the container
+JSON on stdout.
+`
+  )
+}