cra-audit 1.1.0 → 2.1.0

package/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/) and the project uses
+[Semantic Versioning](https://semver.org/).
+
+Releases are automated: pushing a `vX.Y.Z` tag publishes the package to npm
+(with provenance) and creates the GitHub Release from the matching section
+below, so add the section before running `npm version`.
+
+## [2.1.0] — VEX, SARIF & GitHub Action, CRA readiness
+
+### Highlights
+
+- **VEX** (`cra-audit vex`): writes a CycloneDX 1.6 or OpenVEX 0.2.0 document with the exploitability of every known vulnerability. Assessments live in `.cra-audit.json` (`status`, `justification`, `detail`) and are also honoured by the audit gate; accepting a vulnerability without a justification now raises a warning.
+- **SARIF 2.1.0** (`--sarif <path>`): findings appear in GitHub code scanning at the exact lockfile line, with GitHub severities; malicious and CISA KEV findings are errors and `not_affected` assessments are shown as suppressed with their justification.
+- **GitHub Action** (`uses: migohe14/cra-audit@v2`): runs the audit, uploads the SARIF to code scanning and can write the SBOM and VEX as build evidence.
+- **CRA readiness** (`cra-audit readiness`): checks SECURITY.md, the vulnerability contact, the support period, security.txt (RFC 9116) and the Art. 14 reporting process. `--init` creates prefilled SECURITY.md and security.txt templates.
+
+### Compatibility
+
+- Plain-string allowlist entries keep working as before.
+
+## [2.0.0] — OSV.dev, CISA KEV & malicious package detection
+
+### Highlights
+
+**Known, actively exploited and malicious dependencies — in one check**
+
+- **OSV.dev** is now the default vulnerability source: every dependency is checked at the exact version pinned in the lockfile (npm, Yarn, pnpm), with severity, CVE aliases and the version that fixes it. `npm` is no longer required.
+- **Malicious packages**: compromised releases from the OpenSSF malicious-packages feed (`MAL-*`, e.g. the Shai-Hulud worm versions) always fail the audit and cannot be allowlisted.
+- **CISA KEV**: vulnerabilities with evidence of active exploitation fail the audit by default and print the **CRA Art. 14 reporting clock** (24 h / 72 h / 14 days). Use `--no-fail-on-kev` to report them as a warning.
+- `--production` now follows the dependency graph, so it works for Yarn and pnpm projects too.
+- The allowlist accepts GHSA and CVE identifiers.
+
+### New options
+
+- `--vuln-source osv|npm` / policy `vulnerabilitySource` (default `osv`)
+- `--no-fail-on-kev` / policy `failOnKev` (default `true`)
+
+### ⚠️ Breaking changes
+
+- **CLI / CI usage is unchanged** (`npx cra-audit`), but the audit is stricter: malicious packages and actively exploited (KEV) vulnerabilities now fail it.
+- **Programmatic API**: `runAudit()` and `scanVulnerabilities()` are now async — add `await`.
+- Requires network access to `api.osv.dev` and `cisa.gov`. If OSV.dev is unreachable, the audit falls back to `npm audit` and says so.
+
+## [1.1.0] — TR-03183-2 v2.1 SBOM
+
+### Highlights
+
+**CycloneDX 1.6 SBOM conforming to BSI TR-03183-2 v2.1.0**
+
+- Full dependency graph from npm (v1–v3), Yarn classic/Berry and pnpm (v5–v9) lockfiles, with completeness declared in `compositions`
+- SBOM creator (`--creator` flag or `sbomCreator` policy, defaulting to package.json) and component creators read from installed packages
+- `bsi:component:filename` / `executable` / `archive` / `structured` properties, SHA-512 on the distribution reference, declared/concluded licenses, source code URI
+- `sbom check` validates every TR-03183-2 v2.1 required field
+
+### Fixes
+
+- Licenses of Yarn/pnpm projects now reach the SBOM
+- Yarn Berry workspace entries are no longer listed as third-party components
+- pnpm v5 lockfile keys with peer suffixes are parsed correctly
+- Malformed integrity digests no longer produce schema-invalid hashes
+
+### ⚠️ Stricter validation
+
+- CycloneDX < 1.6 and SPDX < 3.0.1 are flagged (use the default CycloneDX output)
+- Yarn Berry projects fail the SHA-512 check (the lockfile doesn't store the npm tarball hash)
+- Run it after installing dependencies: component creators and licenses are read from `node_modules`
+
+## [1.0.0]
+
+- Yarn (classic and Berry) and pnpm lockfile support
+- CRA audit for npm projects: SBOM (CycloneDX/SPDX), `npm audit` vulnerabilities, licenses and an interactive HTML maintenance report

package/README.md

@@ -47,11 +47,29 @@ Known limits: Yarn Berry lockfiles only store Yarn's own cache checksum, not the
 
 > CRA Annex I · TR-03183 Part 2 — *"Transparency through SBOM"*.
 
-### 2. "Zero known vulnerabilities" audit
+### 2. Known, actively exploited and malicious dependencies
 
-Scans **direct and transitive** dependencies (from the lockfile) with `npm audit` and blocks the audit if there are exploitable vulnerabilities above the configured threshold. For Yarn/pnpm projects (which have no npm lockfile), `cra-audit` synthesizes a temporary `package-lock.json` from the exact versions pinned in `yarn.lock` / `pnpm-lock.yaml` and runs `npm audit --package-lock-only` against it, so the scanned versions match what the package manager actually resolved.
+Checks every **direct and transitive** dependency, at the exact version pinned in the lockfile, against:
 
-> CRA Art. 13 — *products must be placed on the market without known exploitable vulnerabilities*.
+| Source | What it finds | Effect on the audit |
+| --- | --- | --- |
+| [OSV.dev](https://osv.dev) — GitHub Advisory Database | Known vulnerabilities, with severity, CVE aliases and the version that fixes them | Fails at or above `--fail-on` (default `high`) |
+| OSV.dev — [OpenSSF malicious packages](https://github.com/ossf/malicious-packages) | Compromised releases (`MAL-*`), e.g. the Shai-Hulud worm versions | **Always fails**; cannot be allowlisted |
+| [CISA KEV](https://www.cisa.gov/known-exploited-vulnerabilities-catalog) | Vulnerabilities with evidence of **active exploitation** | Fails by default (`--no-fail-on-kev` to only warn) and prints the CRA Art. 14 reporting clock |
+
+```text
+  HIGH     [KEV] vite@6.2.3  (fix: vite@6.4.3)
+    GHSA-4r4m-qw57-chr8 / CVE-2025-31125 Vite has a `server.fs.deny` bypassed … [KEV since 2026-01-22]
+
+⚠ CRA Art. 14 — actively exploited vulnerability in a dependency
+    • Early warning ........ within 24 hours of becoming aware
+    • Notification ......... within 72 hours
+    • Final report ......... within 14 days after a corrective measure is available
+```
+
+Only package names and versions are sent to `api.osv.dev`; the KEV catalogue is downloaded from cisa.gov (or CISA's GitHub mirror). If KEV cannot be reached the report says so instead of silently passing, and if OSV.dev is unreachable the audit falls back to `npm audit`. `--vuln-source npm` uses `npm audit` directly.
+
+> CRA Annex I Part I (2)(a) — *placed on the market without known exploitable vulnerabilities*. Art. 14 — *actively exploited vulnerabilities must be reported within 24 hours*.
 
 ### 3. Third-party component check
 
@@ -77,6 +95,62 @@ Generates an **interactive, self-contained HTML report** (no external CDNs, work
 
 The report includes summary cards, search, filters (vulnerable, outdated, license issues, at risk) and column sorting.
 
+### 6. VEX — documenting exploitability (`vex`)
+
+A known vulnerability in a dependency is not always exploitable in your product. Record your assessment in `.cra-audit.json` and `cra-audit` both **accepts** it in the audit and writes it to a **VEX** document (CycloneDX 1.6 or OpenVEX 0.2.0) — the place TR-03183-2 reserves for vulnerability data, outside the SBOM:
+
+```json
+{
+  "vulnerabilities": {
+    "allowlist": [
+      {
+        "id": "CVE-2020-11023",
+        "package": "jquery",
+        "status": "not_affected",
+        "justification": "code_not_reachable",
+        "detail": "We never pass untrusted HTML to jQuery DOM methods; content is rendered via textContent."
+      },
+      { "id": "GHSA-35jh-r3h4-6jhm", "status": "affected", "detail": "_.template used in the exporter; upgrade planned for 3.2.1." }
+    ]
+  }
+}
+```
+
+| `status` | Accepted by the audit | CycloneDX `analysis.state` | OpenVEX `status` |
+| --- | --- | --- | --- |
+| `not_affected` (default) | ✔ | `not_affected` | `not_affected` |
+| `false_positive` | ✔ | `false_positive` | `not_affected` |
+| `affected` | ✖ | `exploitable` | `affected` |
+| `under_investigation` | ✖ | `in_triage` | `under_investigation` |
+
+`justification` accepts the CycloneDX values (`code_not_present`, `code_not_reachable`, `requires_configuration`, `requires_dependency`, `requires_environment`, `protected_by_compiler`, `protected_at_runtime`, `protected_at_perimeter`, `protected_by_mitigating_control`) or the OpenVEX ones, and is translated for each format. Findings without an assessment are written as *in triage* / *under investigation*; malicious packages are always *exploitable* / *affected*. Accepting a vulnerability without `justification` or `detail` works, but the audit warns about it.
+
+```bash
+npx cra-audit vex -o vex.cdx.json                    # CycloneDX 1.6 VEX
+npx cra-audit vex --format openvex -o vex.openvex.json
+```
+
+### 7. CRA readiness (`readiness`)
+
+Checks the vulnerability-handling duties that live in the repository itself:
+
+| Check | Level | Reference |
+| --- | --- | --- |
+| `SECURITY.md` (root, `.github/` or `docs/`) | required | CRA Annex I Part II (5) |
+| Email address or reporting URL for vulnerabilities | required | Annex I Part II (6) · Annex II (2) |
+| Support period with an end date or duration | required | Art. 13(8) · Annex II (7) |
+| No unfilled `TODO` placeholders | required | Annex II |
+| `security.txt` `Contact` and a future `Expires` (when present) | required | RFC 9116 |
+| A lockfile to build the SBOM from | required | Annex I Part II (1) |
+| Supported versions, response times, Art. 14 process (CSIRT/ENISA), `security.txt`, `repository` link | recommended | Annex II · Art. 14 |
+
+```bash
+npx cra-audit readiness          # exit code 1 when a required check fails
+npx cra-audit readiness --init   # creates SECURITY.md and .well-known/security.txt templates (never overwrites)
+```
+
+`--init` prefills the templates from `package.json` (GitHub private vulnerability reporting link, supported major version, a coordinated disclosure process and the Art. 14 24 h / 72 h / 14 days reporting commitments); fill in the `TODO` placeholders and run it again.
+
 ---
 
 ## Usage
@@ -124,6 +198,8 @@ cra-audit --help
 | `cra-audit sbom check` | Validate the SBOM against the TR-03183-2 v2.1 data fields. |
 | `cra-audit vulnerabilities` (alias `vuln`) | Vulnerability analysis only. |
 | `cra-audit licenses` | License analysis only. |
+| `cra-audit vex` | Write a VEX document (CycloneDX, or `--format openvex`) from the policy assessments. |
+| `cra-audit readiness` | Check SECURITY.md, vulnerability contact, support period and security.txt (`--init` for templates). |
 | `cra-audit help` | Show help. |
 
 ## Options
@@ -138,9 +214,13 @@ cra-audit --help
 | `--format <fmt>` | SBOM format: `cyclonedx` (default) or `spdx`. |
 | `--creator <contact>` | Email or URL of the SBOM creator (TR-03183-2 §5.2.1). Defaults to the project's `package.json` `author` / `homepage` / `repository`. |
 | `--fail-on <sev>` | Minimum severity that fails the audit: `info`, `low`, `moderate`, `high`, `critical`. |
+| `--vuln-source <src>` | `osv` (default: OSV.dev + CISA KEV) or `npm` (`npm audit`). |
+| `--no-fail-on-kev` | Report actively exploited (CISA KEV) vulnerabilities as a warning instead of failing. |
 | `--production`, `--prod` | Audit production dependencies only. |
 | `--no-sbom` | Do not require an SBOM in the full audit. |
 | `--json` | Machine-readable JSON output. |
+| `--sarif <path>` | Also write the audit as SARIF 2.1.0 for GitHub code scanning. |
+| `--init` | With `readiness`: create SECURITY.md and security.txt templates. |
 | `--output`, `-o <path>` | Write the result / SBOM / HTML to a file. |
 | `--input`, `-i <path>` | Existing SBOM to validate (for `sbom check`). |
 | `--config`, `-c <path>` | Path to the security policy. |
@@ -190,6 +270,8 @@ Create a `.cra-audit.json` file at the project root to customize the rules (ther
 ```json
 {
   "failOn": "high",
+  "failOnKev": true,
+  "vulnerabilitySource": "osv",
   "requireSbom": true,
   "sbomFormat": "cyclonedx",
   "sbomCreator": "security@example.com",
@@ -206,11 +288,13 @@ Create a `.cra-audit.json` file at the project root to customize the rules (ther
 ```
 
 - `failOn`: minimum severity that blocks the audit.
+- `failOnKev`: fail when a dependency has an actively exploited vulnerability (CISA KEV). Default `true`.
+- `vulnerabilitySource`: `osv` (OSV.dev + CISA KEV) or `npm` (`npm audit`).
 - `requireSbom`: require the SBOM to meet the TR-03183-2 required data fields.
 - `sbomFormat`: `cyclonedx` or `spdx`.
 - `sbomCreator`: email or URL of the entity that creates the SBOM (usually the manufacturer).
 - `productionOnly`: audit production dependencies only.
-- `vulnerabilities.allowlist`: advisory/CVE identifiers accepted with documented justification.
+- `vulnerabilities.allowlist`: exploitability assessments (see [VEX](#6-vex--documenting-exploitability-vex)). Plain strings (a package name or a GHSA/CVE id) are still accepted. Malicious packages (`MAL-*`) cannot be allowlisted.
 - `licenses.allow` / `licenses.deny`: allowed / denied lists (SPDX id).
 - `licenses.failOnMissing`: treat undocumented licenses as a failure.
 
@@ -227,12 +311,54 @@ Command-line options take precedence over the policy file.
 
 Suitable for CI/CD: a non-`0` code blocks the pipeline.
 
+## GitHub Action
+
 ```yaml
-# Example in GitHub Actions
-- name: CRA compliance audit
-  run: npx cra-audit --fail-on high --production --json -o cra-report.json
+name: CRA audit
+on: [push, pull_request]
+
+permissions:
+  contents: read
+  security-events: write   # upload the SARIF report to code scanning
+
+jobs:
+  cra:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+      - run: npm ci                # installed packages give the SBOM its creators/licenses
+      - uses: migohe14/cra-audit@v2
+        with:
+          fail-on: high
+          sbom: sbom.cdx.json
+          vex: vex.cdx.json
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: cra-evidence
+          path: |
+            sbom.cdx.json
+            vex.cdx.json
+            cra-audit.sarif
 ```
 
+Every finding shows up in **Security → Code scanning**, pointing at the exact line of the lockfile; malicious packages and CISA KEV findings are errors, and advisories assessed as `not_affected` in the policy are shown as suppressed with their justification.
+
+| Input | Default | Description |
+| --- | --- | --- |
+| `working-directory` | `.` | Project to audit. |
+| `fail-on` | `high` | Minimum severity that fails the job. |
+| `fail-on-kev` | `true` | Fail on actively exploited (CISA KEV) vulnerabilities. |
+| `production` | `false` | Production dependencies only. |
+| `sarif` | `cra-audit.sarif` | SARIF path (empty to skip). |
+| `upload-sarif` | `true` | Upload to code scanning (needs `security-events: write`; private repos need GitHub Advanced Security). |
+| `sbom` / `vex` | — | Also write the SBOM / VEX to these paths. |
+| `args` | — | Extra `cra-audit audit` arguments. |
+
+Outputs: `exit-code`, `sarif`, `sbom`, `vex`. Without the action, `npx cra-audit --sarif cra-audit.sarif` does the same in any CI.
+
 ---
 
 ## Programmatic API
@@ -245,7 +371,7 @@ const {
 } = require('cra-audit');
 
 const { policy, source } = loadPolicy(process.cwd());
-const report = runAudit(process.cwd(), policy, source);
+const report = await runAudit(process.cwd(), policy, source);
 console.log(report.gate.passed ? 'OK' : 'FAILED');
 
 // Maintenance data + custom HTML report
@@ -258,9 +384,13 @@ const signals = await enrichComponents(components, { network: true, github: true
 ## Requirements
 
 - Node.js >= 18 (uses native `fetch` and `node --test`).
-- `npm` available on the `PATH` (for `npm audit`).
+- Network access to `api.osv.dev` and `cisa.gov` (or `raw.githubusercontent.com` for the KEV mirror). `npm` on the `PATH` is only needed for `--vuln-source npm` or the offline fallback.
 - A lockfile present: `package-lock.json` / `npm-shrinkwrap.json` (npm), `yarn.lock` (Yarn classic or Berry) or `pnpm-lock.yaml` (pnpm). Run `npm install` / `yarn` / `pnpm install` if missing.
 
+## See also
+
+- [hulud-party-scanner](https://www.npmjs.com/package/hulud-party-scanner) — incident response for a machine that may have installed a compromised package: lifecycle-hook analysis, malicious code patterns and Shai-Hulud artifacts in the home directory.
+
 ## Legal notice
 
 `cra-audit` is a technical support tool. It helps verify controls associated with the CRA and TR-03183, but it **does not constitute legal advice** nor does it guarantee regulatory compliance on its own.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cra-audit",
-  "version": "1.1.0",
+  "version": "2.1.0",
   "description": "Audits npm, yarn, and pnpm projects for compliance with the European Cyber Resilience Act (CRA, EU Regulation 2024/2847) and BSI TR-03183: SBOM (CycloneDX/SPDX), known vulnerabilities, third-party components, and licenses.",
   "homepage": "https://github.com/migohe14/cra-audit#readme",
   "repository": {
@@ -43,6 +43,7 @@
     "bin",
     "src",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {

package/src/cli.js

@@ -4,6 +4,8 @@ const { logger, color } = require('./utils/logger');
 const { auditCommand } = require('./commands/audit');
 const { sbomCommand } = require('./commands/sbom');
 const { visualizeCommand } = require('./commands/visualize');
+const { vexCommand } = require('./commands/vex');
+const { readinessCommand } = require('./commands/readiness');
 
 const VERSION = require('../package.json').version;
 
@@ -20,6 +22,7 @@ const BOOLEAN_FLAGS = new Set([
   '--help', '--version', '--json', '--sbom', '--no-sbom',
   '--production', '--prod', '--no-color',
   '--visualize', '--offline', '--github', '--no-open',
+  '--fail-on-kev', '--no-fail-on-kev', '--init', '--verbose',
 ]);
 
 /**
@@ -74,6 +77,13 @@ async function main(argv) {
     case 'license':
       return auditCommand(flags, 'licenses');
 
+    case 'vex':
+      return vexCommand(flags);
+
+    case 'readiness':
+    case 'ready':
+      return readinessCommand(flags);
+
     case 'help':
       printHelp();
       return 0;
@@ -152,6 +162,12 @@ function setFlag(flags, name, value) {
     case '--fail-on': flags.failOn = String(value).toLowerCase(); break;
     case '--cwd': flags.cwd = value; break;
     case '--creator': flags.creator = value; break;
+    case '--vuln-source': flags.vulnSource = String(value).toLowerCase(); break;
+    case '--fail-on-kev': flags.failOnKev = value; break;
+    case '--no-fail-on-kev': flags.noFailOnKev = value; break;
+    case '--sarif': flags.sarif = value; break;
+    case '--init': flags.init = value; break;
+    case '--verbose': flags.verbose = value; break;
     default:
       // Unknown flag stored under its raw name for forward compatibility.
       flags[name.replace(/^--/, '')] = value;
@@ -172,8 +188,11 @@ ${c.bold('COMMANDS')}
   ${c.cyan('visualize')}             Generate an interactive HTML report (SBOM, licenses, versions and maintenance).
   ${c.cyan('sbom generate')}         Generate an SBOM (CycloneDX or SPDX) and print or save it.
   ${c.cyan('sbom check')}            Validate the SBOM against the TR-03183-2 v2.1 data fields.
-  ${c.cyan('vulnerabilities')}       Analyze known vulnerabilities only (alias: vuln).
+  ${c.cyan('vulnerabilities')}       Known, actively exploited (KEV) and malicious packages only (alias: vuln).
   ${c.cyan('licenses')}              Analyze dependency licenses only.
+  ${c.cyan('vex')}                   Write a VEX document (CycloneDX or --format openvex) from the policy assessments.
+  ${c.cyan('readiness')}             Check SECURITY.md, vulnerability contact, support period and security.txt.
+                        --init creates SECURITY.md and security.txt templates.
   ${c.cyan('help')}                  Show this help.
 
 ${c.bold('OPTIONS')}
@@ -185,9 +204,12 @@ ${c.bold('OPTIONS')}
   ${c.cyan('--format <fmt>')}        SBOM format: cyclonedx (default) | spdx.
   ${c.cyan('--creator <contact>')}   Email or URL of the SBOM creator (default: package.json author/homepage).
   ${c.cyan('--fail-on <sev>')}       Minimum severity that fails the audit: info|low|moderate|high|critical.
+  ${c.cyan('--vuln-source <src>')}   Vulnerability source: osv (default: OSV.dev + CISA KEV) | npm (npm audit).
+  ${c.cyan('--no-fail-on-kev')}      Report actively exploited (CISA KEV) vulnerabilities without failing.
   ${c.cyan('--production, --prod')}  Audit production dependencies only (skips devDependencies).
   ${c.cyan('--no-sbom')}             Do not require an SBOM in the full audit.
   ${c.cyan('--json')}                Machine-readable JSON output.
+  ${c.cyan('--sarif <path>')}        Also write the audit as SARIF 2.1.0 (GitHub code scanning).
   ${c.cyan('--output, -o <path>')}   Write the result/SBOM/HTML to a file.
   ${c.cyan('--input, -i <path>')}    Existing SBOM to validate (for "sbom check").
   ${c.cyan('--config, -c <path>')}   Path to the security policy (.cra-audit.json).
@@ -211,6 +233,12 @@ ${c.bold('EXAMPLES')}
   ${c.gray('# Generate a CycloneDX SBOM on disk')}
   npx cra-audit sbom generate -o sbom.cdx.json
 
+  ${c.gray('# VEX with the exploitability assessments recorded in .cra-audit.json')}
+  npx cra-audit vex -o vex.cdx.json
+
+  ${c.gray('# Security policy, contact and support period checks')}
+  npx cra-audit readiness --init
+
   ${c.gray('# Fail only on critical vulnerabilities, in CI')}
   npx cra-audit --fail-on critical --production --json -o cra-report.json
 `);

package/src/commands/audit.js

@@ -6,6 +6,7 @@ const { loadPolicy } = require('../core/policy');
 const { runAudit } = require('../core/auditor');
 const { reportConsole } = require('../reporters/console');
 const { reportJson } = require('../reporters/json');
+const { reportSarif } = require('../reporters/sarif');
 
 /**
  * `cra-audit [audit]` — runs the full compliance audit (vulnerabilities + SBOM
@@ -13,9 +14,9 @@ const { reportJson } = require('../reporters/json');
  *
  * @param {object} flags Parsed CLI flags.
  * @param {'vulnerabilities'|'sbom'|'licenses'} [only]
- * @returns {number} Process exit code.
+ * @returns {Promise<number>} Process exit code.
  */
-function auditCommand(flags, only) {
+async function auditCommand(flags, only) {
   const projectRoot = resolveRoot(flags);
   if (!projectRoot) return 1;
 
@@ -28,13 +29,16 @@ function auditCommand(flags, only) {
   }
 
   const policy = applyFlagOverrides(policyResult.policy, flags);
-  const report = runAudit(projectRoot, policy, policyResult.source, { only });
+  const report = await runAudit(projectRoot, policy, policyResult.source, { only });
 
   if (flags.json) {
     reportJson(report, { outputPath: flags.output });
   } else {
     reportConsole(report);
   }
+  if (typeof flags.sarif === 'string') {
+    reportSarif(report, projectRoot, flags.sarif, { quiet: flags.json && !flags.output, policy });
+  }
 
   return report.gate.passed ? 0 : 1;
 }
@@ -56,6 +60,9 @@ function applyFlagOverrides(policy, flags) {
   if (flags.production) merged.productionOnly = true;
   if (flags.format) merged.sbomFormat = flags.format;
   if (flags.noSbom) merged.requireSbom = false;
+  if (flags.vulnSource) merged.vulnerabilitySource = flags.vulnSource;
+  if (flags.failOnKev) merged.failOnKev = true;
+  if (flags.noFailOnKev) merged.failOnKev = false;
   return merged;
 }
 

package/src/commands/readiness.js

@@ -0,0 +1,59 @@
+'use strict';
+
+const { findProjectRoot } = require('../utils/fs');
+const { logger, color } = require('../utils/logger');
+const { checkReadiness, writeTemplates } = require('../core/readiness');
+
+/**
+ * `cra-audit readiness [--init]` — checks the organisational CRA duties that
+ * live in the repository (disclosure policy, vulnerability contact, support
+ * period, security.txt, SBOM). `--init` writes SECURITY.md and security.txt
+ * templates first; existing files are never overwritten.
+ *
+ * @returns {number} exit code: 1 when a required check fails.
+ */
+function readinessCommand(flags) {
+  const projectRoot = findProjectRoot(flags.cwd || process.cwd());
+  if (!projectRoot) {
+    logger.error('No package.json found. Run the command inside an npm project.');
+    return 1;
+  }
+
+  if (flags.init) {
+    for (const { file, created } of writeTemplates(projectRoot)) {
+      if (created) logger.success(`Created ${file} — fill in the TODO placeholders.`);
+      else logger.info(`${file} already exists; left untouched.`);
+    }
+  }
+
+  const result = checkReadiness(projectRoot);
+
+  if (flags.json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    return result.passed ? 0 : 1;
+  }
+
+  logger.heading('CRA readiness · vulnerability handling and user information');
+  for (const check of result.checks) {
+    const mark = check.passed ? color.green('✔') : check.level === 'required' ? color.red('✖') : color.yellow('!');
+    const level = check.level === 'required' ? '' : color.gray(' (recommended)');
+    logger.log(`  ${mark} ${check.label}${level} ${color.gray(`— ${check.reference}`)}`);
+    if (!check.passed || flags.verbose) logger.detail(`    ${check.detail}`);
+  }
+  logger.log('');
+
+  const failed = result.checks.filter((c) => c.level === 'required' && !c.passed).length;
+  const warned = result.checks.filter((c) => c.level === 'recommended' && !c.passed).length;
+  if (result.passed) {
+    logger.success(color.bold(`READY — all required checks pass${warned ? ` (${warned} recommendation(s))` : ''}.`));
+  } else {
+    logger.error(color.bold(`NOT READY — ${failed} required check(s) failed.`));
+    if (!flags.init && !result.files.securityMd) {
+      logger.detail(`Run ${color.cyan('cra-audit readiness --init')} to create SECURITY.md and security.txt templates.`);
+    }
+  }
+  logger.detail('This checks what the repository documents; it is not legal advice.');
+  return result.passed ? 0 : 1;
+}
+
+module.exports = { readinessCommand };

package/src/commands/vex.js

@@ -0,0 +1,70 @@
+'use strict';
+
+const path = require('node:path');
+const { findProjectRoot, readJson, writeJson } = require('../utils/fs');
+const { logger } = require('../utils/logger');
+const { loadPolicy } = require('../core/policy');
+const { scanVulnerabilities } = require('../core/vuln-scanner');
+const { buildVex } = require('../core/vex');
+const { creatorFromManifest } = require('../core/installed-metadata');
+
+/**
+ * `cra-audit vex` — writes a VEX document (CycloneDX 1.6 or OpenVEX 0.2.0)
+ * stating the exploitability of every known vulnerability in the dependency
+ * tree, from the assessments recorded in the policy allowlist.
+ *
+ * @returns {Promise<number>} exit code
+ */
+async function vexCommand(flags) {
+  const projectRoot = findProjectRoot(flags.cwd || process.cwd());
+  if (!projectRoot) {
+    logger.error('No package.json found. Run the command inside an npm project.');
+    return 1;
+  }
+
+  let policy;
+  try {
+    policy = loadPolicy(projectRoot, flags.config).policy;
+  } catch (err) {
+    logger.error(err.message);
+    return 1;
+  }
+
+  const format = flags.format === 'openvex' ? 'openvex' : 'cyclonedx';
+  if (flags.format && !['openvex', 'cyclonedx', 'cdx'].includes(flags.format)) {
+    logger.error(`Unsupported VEX format: "${flags.format}". Use "cyclonedx" or "openvex".`);
+    return 1;
+  }
+
+  const vulns = await scanVulnerabilities(projectRoot, {
+    production: flags.production || policy.productionOnly,
+    source: flags.vulnSource || policy.vulnerabilitySource,
+  });
+  if (!vulns.ok) {
+    logger.error(vulns.error);
+    return 1;
+  }
+  // Without -o the document goes to stdout: keep warnings on stderr.
+  for (const warning of vulns.warnings || []) {
+    if (flags.output) logger.warn(warning);
+    else process.stderr.write(`${warning}\n`);
+  }
+
+  const pkg = readJson(path.join(projectRoot, 'package.json')) || {};
+  const creator = creatorFromManifest(pkg);
+  const author = policy.sbomCreator || (creator && (creator.email || creator.url)) || null;
+  const product = { name: pkg.name || path.basename(projectRoot), version: pkg.version || '0.0.0' };
+  const document = buildVex(product, vulns, policy, { format, author });
+
+  const count = format === 'openvex' ? document.statements.length : document.vulnerabilities.length;
+  if (flags.output) {
+    const outPath = path.isAbsolute(flags.output) ? flags.output : path.join(projectRoot, flags.output);
+    writeJson(outPath, document);
+    logger.success(`VEX (${format}) with ${count} statement(s) written to: ${outPath}`);
+  } else {
+    process.stdout.write(JSON.stringify(document, null, 2) + '\n');
+  }
+  return 0;
+}
+
+module.exports = { vexCommand };

package/src/commands/visualize.js

@@ -44,8 +44,11 @@ async function visualizeCommand(flags) {
 
   logger.info(`Analyzing ${parsed.components.length} components from ${parsed.root.name}@${parsed.root.version}…`);
 
-  // Vulnerabilities + licenses run locally (no network).
-  const vulns = scanVulnerabilities(projectRoot, { production: policy.productionOnly });
+  // --offline keeps the previous behaviour: npm audit instead of OSV.dev/KEV.
+  const vulns = await scanVulnerabilities(projectRoot, {
+    production: policy.productionOnly,
+    source: flags.offline ? 'npm' : policy.vulnerabilitySource,
+  });
   const licenses = checkLicenses(projectRoot, policy.licenses || {});
 
   // Maintenance enrichment over the network (opt-out with --offline).
@@ -87,9 +90,10 @@ async function visualizeCommand(flags) {
 
 /** Merges all data sources into the view model consumed by the HTML reporter. */
 function buildModel(parsed, vulns, licenses, enrichment) {
+  // OSV findings are per name@version; npm audit findings only per name.
   const vulnByName = new Map();
   if (vulns.ok) {
-    for (const v of vulns.vulnerabilities) vulnByName.set(v.name, v);
+    for (const v of vulns.vulnerabilities) vulnByName.set(v.version ? `${v.name}@${v.version}` : v.name, v);
   }
   const licByKey = new Map();
   if (licenses.ok) {
@@ -98,7 +102,7 @@ function buildModel(parsed, vulns, licenses, enrichment) {
 
   const components = parsed.components.map((c) => {
     const key = `${c.name}@${c.version}`;
-    const vuln = vulnByName.get(c.name) || null;
+    const vuln = vulnByName.get(key) || vulnByName.get(c.name) || null;
     const lic = licByKey.get(key) || null;
     const enr = enrichment.get(key) || {};