cra-audit 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -8,6 +8,19 @@ 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

package/README.md

@@ -95,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
@@ -142,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
@@ -161,6 +219,8 @@ cra-audit --help
 | `--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. |
@@ -234,7 +294,7 @@ Create a `.cra-audit.json` file at the project root to customize the rules (ther
 - `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`: package names or advisory ids (GHSA, CVE) accepted with documented justification, e.g. when the vulnerable code is not reachable in your product. Malicious packages (`MAL-*`) cannot be allowlisted.
+- `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.
 
@@ -251,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cra-audit",
-  "version": "2.0.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": {

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,7 +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',
+  '--fail-on-kev', '--no-fail-on-kev', '--init', '--verbose',
 ]);
 
 /**
@@ -75,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;
@@ -156,6 +165,9 @@ function setFlag(flags, name, value) {
     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;
@@ -178,6 +190,9 @@ ${c.bold('COMMANDS')}
   ${c.cyan('sbom check')}            Validate the SBOM against the TR-03183-2 v2.1 data fields.
   ${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')}
@@ -194,6 +209,7 @@ ${c.bold('OPTIONS')}
   ${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).
@@ -217,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
@@ -35,6 +36,9 @@ async function auditCommand(flags, only) {
   } 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;
 }

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/core/auditor.js

@@ -4,6 +4,7 @@ const { scanVulnerabilities, SEVERITY_ORDER } = require('./vuln-scanner');
 const { generateSbom } = require('./sbom-generator');
 const { validateSbom } = require('./sbom-validator');
 const { checkLicenses } = require('./license-checker');
+const { acceptance } = require('./vex');
 
 /**
  * @typedef {object} AuditResult
@@ -43,6 +44,7 @@ async function runAudit(projectRoot, policy, policySource, options = {}) {
         reasons.push({ label: warning, passed: true, warning: true });
       }
       reasons.push(...exploitationReasons(vulns, policy));
+      reasons.push(...justificationReasons(vulns, policy));
       const blocking = countBlocking(vulns, policy);
       reasons.push({
         label: blocking === 0
@@ -155,15 +157,25 @@ function countBlocking(vulns, policy) {
 }
 
 /**
- * A finding is accepted when the policy allowlist names the package, or every
- * advisory on it by id/alias (GHSA, CVE) or advisory URL.
+ * A finding is accepted when every advisory on it is assessed as not_affected
+ * (or false_positive) in the policy allowlist. See ./vex.js.
  */
 function isAllowlisted(vuln, policy) {
-  const allowlist = (policy.vulnerabilities && policy.vulnerabilities.allowlist) || [];
-  if (!allowlist.length) return false;
-  if (allowlist.includes(vuln.name)) return true;
-  return vuln.sources.every((src) => allowlist.some((id) =>
-    [src.id, ...(src.aliases || [])].includes(id) || (src.url && src.url.includes(id))));
+  return acceptance(vuln, policy).accepted;
+}
+
+/**
+ * Accepted vulnerabilities must be documented (CRA Annex I Part II): warn
+ * when an allowlist entry carries no justification or detail for the VEX.
+ */
+function justificationReasons(vulns, policy) {
+  const unjustified = vulns.vulnerabilities.reduce((n, v) => n + acceptance(v, policy).unjustified, 0);
+  if (!unjustified) return [];
+  return [{
+    label: `${unjustified} accepted vulnerability(ies) without a justification — add "justification"/"detail" to the allowlist entry for the VEX`,
+    passed: true,
+    warning: true,
+  }];
 }
 
 function getProject(projectRoot, sections) {

package/src/core/readiness.js

@@ -0,0 +1,231 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { readJson } = require('../utils/fs');
+const { parseLockfile } = require('./lockfile-parser');
+const { repositoryUrl } = require('./installed-metadata');
+
+/**
+ * Organisational CRA duties that can be checked from the repository itself:
+ * the vulnerability disclosure policy, a contact for vulnerability reports,
+ * the support period, a security.txt and the ability to produce an SBOM.
+ *
+ * `required` checks fail the command; `recommended` ones only warn.
+ */
+
+const SECURITY_MD_PATHS = ['SECURITY.md', '.github/SECURITY.md', 'docs/SECURITY.md'];
+const SECURITY_TXT_PATHS = [
+  '.well-known/security.txt',
+  'public/.well-known/security.txt',
+  'static/.well-known/security.txt',
+  'src/.well-known/security.txt',
+  'security.txt',
+];
+const DAY = 24 * 60 * 60 * 1000;
+
+const EMAIL = /[\w.+-]+@[\w-]+\.[\w.-]+/;
+const URL = /https?:\/\/\S+/;
+
+/**
+ * @param {string} projectRoot
+ * @param {{ now?: Date }} [options]
+ * @returns {{ checks: Array<object>, passed: boolean, files: object }}
+ */
+function checkReadiness(projectRoot, { now = new Date() } = {}) {
+  const checks = [];
+  const add = (id, label, level, passed, detail, reference) => checks.push({ id, label, level, passed: Boolean(passed), detail, reference });
+
+  const securityMdPath = firstExisting(projectRoot, SECURITY_MD_PATHS);
+  const securityMd = securityMdPath ? read(path.join(projectRoot, securityMdPath)) : '';
+  const readme = read(path.join(projectRoot, 'README.md'));
+  const pkg = readJson(path.join(projectRoot, 'package.json')) || {};
+
+  // --- Coordinated vulnerability disclosure policy --------------------------
+  add('security-policy', 'Vulnerability disclosure policy (SECURITY.md)', 'required', securityMdPath,
+    securityMdPath ? `Found ${securityMdPath}` : `None of ${SECURITY_MD_PATHS.join(', ')} exists`,
+    'CRA Annex I Part II (5)');
+
+  const reportingChannel = EMAIL.test(securityMd) || /security\/advisories|report[^\n]*vulnerabilit[^\n]*https?:\/\//i.test(securityMd) || URL.test(securityMd);
+  add('security-contact', 'Contact address for vulnerability reports', 'required', securityMdPath && reportingChannel,
+    !securityMdPath ? 'No SECURITY.md' : reportingChannel ? 'Email address or reporting URL found' : 'SECURITY.md has no email address or reporting URL',
+    'CRA Annex I Part II (6) · Annex II (2)');
+
+  // --- Support period ---------------------------------------------------------
+  const supportText = `${securityMd}\n${readme}`;
+  const supportMention = /support(ed)?\s+period|supported\s+until|end\s+of\s+(security\s+)?support|end[-\s]of[-\s]life|\bEOL\b/i.test(supportText);
+  const supportDate = supportMention && /\b(19|20)\d{2}-\d{2}(-\d{2})?\b|\b\d+\s+years?\b/i.test(supportText);
+  add('support-period', 'Support period and its end date stated', 'required', supportMention && supportDate,
+    !supportMention ? 'No mention of the support period in SECURITY.md or README.md'
+      : supportDate ? 'Support period with an end date or duration found' : 'Support period mentioned without an end date',
+    'CRA Art. 13(8) · Annex II (7)');
+
+  // --- Recommended content ------------------------------------------------------
+  add('supported-versions', 'Supported versions listed', 'recommended',
+    /supported\s+versions/i.test(securityMd), 'A "Supported Versions" section in SECURITY.md', 'CRA Annex II (7)');
+  add('response-timeline', 'Response timeline for reporters', 'recommended',
+    /\b\d+\s*(business\s+)?(hours?|days?|weeks?)\b/i.test(securityMd), 'Acknowledgement / fix time frames in SECURITY.md',
+    'CRA Annex I Part II (5)');
+  add('art14-process', 'Art. 14 reporting process (CSIRT / ENISA, 24 h / 72 h)', 'recommended',
+    /ENISA|CSIRT|single\s+reporting\s+platform|24\s*h(ours)?/i.test(securityMd),
+    'How actively exploited vulnerabilities and severe incidents are reported', 'CRA Art. 14');
+
+  // --- security.txt (RFC 9116) --------------------------------------------------
+  const securityTxtPath = firstExisting(projectRoot, SECURITY_TXT_PATHS);
+  const txt = parseSecurityTxt(securityTxtPath ? read(path.join(projectRoot, securityTxtPath)) : '');
+  if (!securityTxtPath) {
+    add('security-txt', 'security.txt published (RFC 9116)', 'recommended', false,
+      'No .well-known/security.txt found (recommended for products with a web presence)', 'RFC 9116 · CRA Annex II (2)');
+  } else {
+    const expires = txt.expires ? new Date(txt.expires) : null;
+    const validExpiry = expires && !Number.isNaN(expires.getTime());
+    add('security-txt', 'security.txt published (RFC 9116)', 'recommended', true, `Found ${securityTxtPath}`, 'RFC 9116');
+    add('security-txt-contact', 'security.txt has a Contact field', 'required', txt.contact.length > 0,
+      txt.contact.length ? txt.contact.join(', ') : 'Missing Contact:', 'RFC 9116 §2.5.3');
+    add('security-txt-expires', 'security.txt Expires is set and in the future', 'required', validExpiry && expires > now,
+      !txt.expires ? 'Missing Expires:' : !validExpiry ? `Invalid date: ${txt.expires}` : expires > now ? `Expires ${txt.expires}` : `Expired on ${txt.expires}`,
+      'RFC 9116 §2.5.5');
+    if (validExpiry && expires > now) {
+      add('security-txt-expiry-window', 'security.txt Expires is less than a year away', 'recommended',
+        expires - now <= 366 * DAY, `Expires in ${Math.round((expires - now) / DAY)} days`, 'RFC 9116 §2.5.5');
+    }
+  }
+
+  // --- Unfilled templates (`readiness --init`) ------------------------------------
+  const securityTxtText = securityTxtPath ? read(path.join(projectRoot, securityTxtPath)) : '';
+  const todo = [[securityMdPath, securityMd], [securityTxtPath, securityTxtText]]
+    .filter(([file, text]) => file && /\bTODO\b/.test(text))
+    .map(([file, text]) => `${file} (${text.match(/\bTODO\b/g).length})`);
+  if (securityMdPath || securityTxtPath) {
+    add('placeholders', 'No unfilled TODO placeholders', 'required', todo.length === 0,
+      todo.length ? `TODO placeholders left in ${todo.join(', ')}` : 'No placeholders', 'CRA Annex II');
+  }
+
+  // --- SBOM ---------------------------------------------------------------------
+  const parsed = parseLockfile(projectRoot);
+  add('sbom', 'A lockfile to generate the SBOM from', 'required', parsed.ok,
+    parsed.ok ? `${parsed.lockfileName} (${parsed.components.length} components)` : parsed.error, 'CRA Annex I Part II (1)');
+
+  add('package-repository', 'package.json links the source repository', 'recommended', Boolean(repositoryUrl(pkg.repository)),
+    repositoryUrl(pkg.repository) || 'No "repository" field', 'TR-03183-2 §5.2.4');
+
+  const failed = checks.filter((c) => c.level === 'required' && !c.passed);
+  return { checks, passed: failed.length === 0, files: { securityMd: securityMdPath, securityTxt: securityTxtPath } };
+}
+
+/** Parses the fields of a security.txt that the checks need. */
+function parseSecurityTxt(text) {
+  const out = { contact: [], expires: null, policy: [] };
+  for (const raw of String(text).split(/\r?\n/)) {
+    const m = raw.match(/^\s*([A-Za-z-]+)\s*:\s*(.+?)\s*$/);
+    if (!m) continue;
+    const field = m[1].toLowerCase();
+    if (field === 'contact') out.contact.push(m[2]);
+    else if (field === 'expires') out.expires = m[2];
+    else if (field === 'policy') out.policy.push(m[2]);
+  }
+  return out;
+}
+
+// --- Templates (`readiness --init`) --------------------------------------------
+
+/**
+ * Writes SECURITY.md and .well-known/security.txt templates prefilled from
+ * package.json. Existing files are never overwritten.
+ *
+ * @returns {Array<{ file: string, created: boolean }>}
+ */
+function writeTemplates(projectRoot, { now = new Date() } = {}) {
+  const pkg = readJson(path.join(projectRoot, 'package.json')) || {};
+  const repo = repositoryUrl(pkg.repository);
+  const advisories = repo && /github\.com/.test(repo) ? `${repo}/security/advisories/new` : null;
+  const name = pkg.name || path.basename(projectRoot);
+  const major = String(pkg.version || '1.0.0').split('.')[0];
+  const results = [];
+
+  const existingMd = firstExisting(projectRoot, SECURITY_MD_PATHS);
+  if (existingMd) {
+    results.push({ file: existingMd, created: false });
+  } else {
+    fs.writeFileSync(path.join(projectRoot, 'SECURITY.md'), securityMdTemplate({ name, major, advisories }));
+    results.push({ file: 'SECURITY.md', created: true });
+  }
+
+  const existingTxt = firstExisting(projectRoot, SECURITY_TXT_PATHS);
+  if (existingTxt) {
+    results.push({ file: existingTxt, created: false });
+  } else {
+    const base = fs.existsSync(path.join(projectRoot, 'public')) ? 'public/.well-known' : '.well-known';
+    fs.mkdirSync(path.join(projectRoot, base), { recursive: true });
+    const expires = new Date(now.getTime() + 364 * DAY).toISOString().replace(/\.\d{3}Z$/, 'Z');
+    fs.writeFileSync(path.join(projectRoot, base, 'security.txt'), securityTxtTemplate({ advisories, repo, expires }));
+    results.push({ file: `${base}/security.txt`, created: true });
+  }
+  return results;
+}
+
+function securityMdTemplate({ name, major, advisories }) {
+  const channel = advisories
+    ? `Report it privately through [GitHub Security Advisories](${advisories}), or by email to TODO: security@example.com.`
+    : 'Report it privately by email to TODO: security@example.com.';
+  return `# Security Policy
+
+## Supported Versions
+
+| Version | Supported | End of security support |
+| ------- | --------- | ----------------------- |
+| ${major}.x     | ✅        | TODO: YYYY-MM-DD        |
+| < ${major}.0   | ❌        | —                       |
+
+**Support period:** security updates for ${name} ${major}.x are provided until TODO: YYYY-MM-DD
+(the EU Cyber Resilience Act expects at least 5 years, or the expected time of use of the product).
+
+## Reporting a Vulnerability
+
+Please do **not** open a public issue for security problems.
+
+${channel}
+
+Include the affected version, a description of the issue and, if possible, steps to reproduce it.
+
+## Our Process (Coordinated Vulnerability Disclosure)
+
+- We acknowledge reports within **3 business days** and send a first assessment within **10 business days**.
+- We agree a disclosure date with the reporter, normally within **90 days**, and credit reporters who wish to be named.
+- Fixes are released as security updates, separate from feature updates where possible, and announced in the release notes and a GitHub Security Advisory.
+
+## EU Cyber Resilience Act — Reporting (Art. 14)
+
+When we become aware of an actively exploited vulnerability in ${name}, or a severe incident affecting its security,
+we notify the coordinating CSIRT and ENISA through the Single Reporting Platform:
+
+- an **early warning within 24 hours**,
+- a **notification within 72 hours**,
+- a **final report within 14 days** after a corrective measure is available (one month for severe incidents).
+
+Affected users are informed of the issue and of the corrective measures to take.
+`;
+}
+
+function securityTxtTemplate({ advisories, repo, expires }) {
+  const lines = ['# RFC 9116 — https://securitytxt.org', 'Contact: mailto:TODO-security@example.com'];
+  if (advisories) lines.push(`Contact: ${advisories}`);
+  lines.push(`Expires: ${expires}`);
+  if (repo) lines.push(`Policy: ${repo}/blob/HEAD/SECURITY.md`);
+  lines.push('Preferred-Languages: en', '');
+  return lines.join('\n');
+}
+
+function firstExisting(root, candidates) {
+  return candidates.find((rel) => fs.existsSync(path.join(root, rel))) || null;
+}
+
+function read(file) {
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+module.exports = { checkReadiness, writeTemplates, parseSecurityTxt };

package/src/core/vex.js

@@ -0,0 +1,264 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const { buildPurl } = require('./lockfile-parser');
+
+const TOOL_NAME = 'cra-audit';
+const TOOL_VERSION = require('../../package.json').version;
+
+/**
+ * VEX (Vulnerability Exploitability eXchange) states the exploitability of
+ * each known vulnerability in the product. TR-03183-2 keeps vulnerability data
+ * out of the SBOM and points to VEX for it, and the CRA asks manufacturers to
+ * document how each vulnerability was assessed.
+ *
+ * The assessments come from the policy allowlist
+ * (`vulnerabilities.allowlist` in .cra-audit.json). Entries can be plain ids
+ * or package names (legacy), or objects:
+ *
+ *   { "id": "CVE-2021-23337", "package": "lodash",
+ *     "status": "not_affected", "justification": "code_not_reachable",
+ *     "detail": "We never call _.template with user input." }
+ */
+
+/** Statuses, as written in the policy, and whether they accept the finding. */
+const STATUSES = {
+  not_affected: { accepts: true, cdx: 'not_affected', openvex: 'not_affected' },
+  false_positive: { accepts: true, cdx: 'false_positive', openvex: 'not_affected' },
+  affected: { accepts: false, cdx: 'exploitable', openvex: 'affected' },
+  under_investigation: { accepts: false, cdx: 'in_triage', openvex: 'under_investigation' },
+};
+
+/**
+ * Justifications accepted in the policy (CycloneDX or OpenVEX vocabulary) and
+ * their equivalent in the other format.
+ */
+const JUSTIFICATIONS = {
+  code_not_present: { cdx: 'code_not_present', openvex: 'vulnerable_code_not_present' },
+  code_not_reachable: { cdx: 'code_not_reachable', openvex: 'vulnerable_code_not_in_execute_path' },
+  requires_configuration: { cdx: 'requires_configuration', openvex: 'vulnerable_code_cannot_be_controlled_by_adversary' },
+  requires_dependency: { cdx: 'requires_dependency', openvex: 'vulnerable_code_not_in_execute_path' },
+  requires_environment: { cdx: 'requires_environment', openvex: 'vulnerable_code_cannot_be_controlled_by_adversary' },
+  protected_by_compiler: { cdx: 'protected_by_compiler', openvex: 'inline_mitigations_already_exist' },
+  protected_at_runtime: { cdx: 'protected_at_runtime', openvex: 'inline_mitigations_already_exist' },
+  protected_at_perimeter: { cdx: 'protected_at_perimeter', openvex: 'inline_mitigations_already_exist' },
+  protected_by_mitigating_control: { cdx: 'protected_by_mitigating_control', openvex: 'inline_mitigations_already_exist' },
+  component_not_present: { cdx: 'code_not_present', openvex: 'component_not_present' },
+  vulnerable_code_not_present: { cdx: 'code_not_present', openvex: 'vulnerable_code_not_present' },
+  vulnerable_code_not_in_execute_path: { cdx: 'code_not_reachable', openvex: 'vulnerable_code_not_in_execute_path' },
+  vulnerable_code_cannot_be_controlled_by_adversary: { cdx: 'requires_environment', openvex: 'vulnerable_code_cannot_be_controlled_by_adversary' },
+  inline_mitigations_already_exist: { cdx: 'protected_by_mitigating_control', openvex: 'inline_mitigations_already_exist' },
+};
+
+/**
+ * Normalizes the policy allowlist into assessment objects.
+ * @returns {Array<{ id: string|null, package: string|null, status: string, justification: string|null, detail: string|null }>}
+ */
+function normalizeAllowlist(policy) {
+  const list = (policy && policy.vulnerabilities && policy.vulnerabilities.allowlist) || [];
+  return list.map((entry) => {
+    if (typeof entry === 'string') {
+      // Legacy form: a package name, an advisory id/alias or an advisory URL fragment.
+      return { id: entry, package: null, status: 'not_affected', justification: null, detail: null, legacy: true };
+    }
+    const status = STATUSES[entry.status] ? entry.status : 'not_affected';
+    return {
+      id: entry.id || null,
+      package: entry.package || null,
+      status,
+      justification: JUSTIFICATIONS[entry.justification] ? entry.justification : null,
+      detail: entry.detail || null,
+    };
+  });
+}
+
+/** Does an assessment apply to one advisory of a finding? */
+function entryMatches(entry, finding, source) {
+  if (entry.legacy && entry.id === finding.name) return true;
+  if (entry.package && entry.package !== finding.name) return false;
+  if (!entry.id) return Boolean(entry.package);
+  const ids = [source.id, ...(source.aliases || [])].filter(Boolean);
+  return ids.includes(entry.id) || Boolean(source.url && source.url.includes(entry.id));
+}
+
+/** The assessment recorded for one advisory of a finding, if any. */
+function assessmentFor(finding, source, entries) {
+  return entries.find((e) => entryMatches(e, finding, source)) || null;
+}
+
+/**
+ * A finding is accepted when every advisory on it has an accepting assessment
+ * (not_affected / false_positive). Malicious packages are never accepted.
+ *
+ * @returns {{ accepted: boolean, unjustified: number }}
+ */
+function acceptance(finding, policy) {
+  const entries = normalizeAllowlist(policy);
+  if (!entries.length || finding.malicious) return { accepted: false, unjustified: 0 };
+  const assessments = finding.sources.map((s) => assessmentFor(finding, s, entries));
+  const accepted = assessments.every((a) => a && STATUSES[a.status].accepts);
+  const unjustified = accepted ? assessments.filter((a) => !a.justification && !a.detail).length : 0;
+  return { accepted, unjustified };
+}
+
+// --- Documents -------------------------------------------------------------
+
+/**
+ * Builds a VEX document for the vulnerability findings of an audit.
+ *
+ * @param {{ name: string, version: string }} product
+ * @param {object} vulnSection Result of scanVulnerabilities().
+ * @param {object} policy
+ * @param {{ format?: 'cyclonedx'|'openvex', author?: string|null }} [options]
+ */
+function buildVex(product, vulnSection, policy, { format = 'cyclonedx', author = null } = {}) {
+  const entries = normalizeAllowlist(policy);
+  const productPurl = buildPurl(product.name, product.version);
+  const statements = [];
+
+  for (const finding of vulnSection.vulnerabilities || []) {
+    const purl = buildPurl(finding.name, finding.version);
+    for (const source of finding.sources) {
+      const assessment = finding.malicious ? null : assessmentFor(finding, source, entries);
+      statements.push({ finding, source, purl, assessment });
+    }
+  }
+
+  return format === 'openvex'
+    ? buildOpenVex(productPurl, statements, author)
+    : buildCycloneDxVex(product, productPurl, statements);
+}
+
+function buildCycloneDxVex(product, productPurl, statements) {
+  const vulnerabilities = statements.map(({ finding, source, purl, assessment }) => {
+    const { primary, others } = identifiers(source);
+    const analysis = { state: cdxState(finding, assessment) };
+    if (assessment && assessment.justification) analysis.justification = JUSTIFICATIONS[assessment.justification].cdx;
+    const detail = analysisDetail(finding, source, assessment);
+    if (detail) analysis.detail = detail;
+    if (analysis.state === 'exploitable' || analysis.state === 'in_triage') {
+      analysis.response = finding.malicious ? ['update'] : finding.fixAvailable ? ['update'] : ['can_not_fix'];
+    }
+
+    const vuln = {
+      'bom-ref': `${primary}@${purl}`,
+      id: primary,
+      source: { name: 'OSV', url: `https://osv.dev/vulnerability/${source.id}` },
+      references: others.map((id) => ({ id, source: { name: sourceName(id), url: advisoryUrl(id) } })),
+      ratings: [{
+        source: { name: 'OSV' },
+        severity: cdxSeverity(source.severity),
+        ...(source.cvss !== null && source.cvss !== undefined ? { score: source.cvss, method: 'CVSSv31' } : {}),
+      }],
+      cwes: (source.cwe || []).map((c) => parseInt(String(c).replace(/^CWE-/i, ''), 10)).filter(Number.isFinite),
+      description: source.title || undefined,
+      advisories: source.url ? [{ url: source.url }] : undefined,
+      affects: [{ ref: purl }],
+      analysis,
+    };
+    if (source.kev) {
+      vuln.properties = [
+        { name: 'cra-audit:kev', value: 'true' },
+        { name: 'cra-audit:kev:dateAdded', value: String(source.kev.dateAdded) },
+      ];
+    }
+    if (!vuln.references.length) delete vuln.references;
+    if (!vuln.cwes.length) delete vuln.cwes;
+    return vuln;
+  });
+
+  return {
+    bomFormat: 'CycloneDX',
+    specVersion: '1.6',
+    serialNumber: `urn:uuid:${crypto.randomUUID()}`,
+    version: 1,
+    metadata: {
+      timestamp: new Date().toISOString(),
+      tools: { components: [{ type: 'application', name: TOOL_NAME, version: TOOL_VERSION }] },
+      component: { type: 'application', 'bom-ref': productPurl, name: product.name, version: product.version, purl: productPurl },
+    },
+    vulnerabilities,
+  };
+}
+
+function buildOpenVex(productPurl, statements, author) {
+  return {
+    '@context': 'https://openvex.dev/ns/v0.2.0',
+    '@id': `https://openvex.dev/docs/public/cra-audit-${crypto.randomUUID()}`,
+    author: author || TOOL_NAME,
+    timestamp: new Date().toISOString(),
+    version: 1,
+    tooling: `${TOOL_NAME}/${TOOL_VERSION}`,
+    statements: statements.map(({ finding, source, purl, assessment }) => {
+      const { primary, others } = identifiers(source);
+      const status = finding.malicious ? 'affected' : assessment ? STATUSES[assessment.status].openvex : 'under_investigation';
+      const statement = {
+        vulnerability: { name: primary, ...(others.length ? { aliases: others } : {}) },
+        products: [{ '@id': productPurl, subcomponents: [{ '@id': purl }] }],
+        status,
+      };
+      const detail = analysisDetail(finding, source, assessment);
+      if (status === 'not_affected') {
+        if (assessment.justification) statement.justification = JUSTIFICATIONS[assessment.justification].openvex;
+        // OpenVEX requires a justification or an impact statement.
+        statement.impact_statement = detail || 'Assessed as not affected; justification not recorded in the cra-audit policy.';
+      } else if (status === 'affected') {
+        statement.action_statement = actionStatement(finding);
+      } else if (detail) {
+        statement.status_notes = detail;
+      }
+      return statement;
+    }),
+  };
+}
+
+function cdxState(finding, assessment) {
+  if (finding.malicious) return 'exploitable';
+  return assessment ? STATUSES[assessment.status].cdx : 'in_triage';
+}
+
+function analysisDetail(finding, source, assessment) {
+  const parts = [];
+  if (finding.malicious) parts.push('Malicious package (OpenSSF malicious-packages): remove it and rotate exposed credentials.');
+  if (source.kev) parts.push(`Listed in CISA KEV (actively exploited) since ${source.kev.dateAdded}.`);
+  if (assessment && assessment.detail) parts.push(assessment.detail);
+  if (assessment && !assessment.detail && !assessment.justification && STATUSES[assessment.status].accepts) {
+    parts.push('Accepted in the cra-audit policy without a recorded justification.');
+  }
+  return parts.join(' ') || undefined;
+}
+
+function actionStatement(finding) {
+  if (finding.malicious) return `Remove ${finding.name}@${finding.version}, reinstall from a clean lockfile and rotate exposed credentials.`;
+  if (finding.fixAvailable && typeof finding.fixAvailable === 'object') {
+    return `Update ${finding.name} to ${finding.fixAvailable.version} or later.`;
+  }
+  return `No fixed version of ${finding.name} is available: remove or replace the dependency, or mitigate.`;
+}
+
+/** Prefer the CVE as the VEX id; keep the rest as references/aliases. */
+function identifiers(source) {
+  const all = [source.id, ...(source.aliases || [])].filter(Boolean);
+  const primary = all.find((id) => /^CVE-/i.test(id)) || all[0] || 'UNKNOWN';
+  return { primary, others: all.filter((id) => id !== primary) };
+}
+
+function sourceName(id) {
+  if (/^CVE-/i.test(id)) return 'NVD';
+  if (/^GHSA-/i.test(id)) return 'GitHub';
+  return 'OSV';
+}
+
+function advisoryUrl(id) {
+  if (/^CVE-/i.test(id)) return `https://nvd.nist.gov/vuln/detail/${id}`;
+  if (/^GHSA-/i.test(id)) return `https://github.com/advisories/${id}`;
+  return `https://osv.dev/vulnerability/${id}`;
+}
+
+/** CycloneDX uses "medium" where npm/GHSA say "moderate". */
+function cdxSeverity(severity) {
+  if (severity === 'moderate') return 'medium';
+  return ['critical', 'high', 'medium', 'low', 'info', 'none'].includes(severity) ? severity : 'unknown';
+}
+
+module.exports = { buildVex, normalizeAllowlist, assessmentFor, acceptance, STATUSES, JUSTIFICATIONS };

package/src/index.js

@@ -18,6 +18,9 @@ const { checkLicenses } = require('./core/license-checker');
 const { parseLockfile } = require('./core/lockfile-parser');
 const { enrichComponents } = require('./core/enrich');
 const { buildHtml } = require('./reporters/html');
+const { buildSarif } = require('./reporters/sarif');
+const { buildVex } = require('./core/vex');
+const { checkReadiness } = require('./core/readiness');
 
 module.exports = {
   runAudit,
@@ -30,4 +33,7 @@ module.exports = {
   parseLockfile,
   enrichComponents,
   buildHtml,
+  buildSarif,
+  buildVex,
+  checkReadiness,
 };

package/src/reporters/sarif.js

@@ -0,0 +1,238 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { writeJson } = require('../utils/fs');
+const { logger } = require('../utils/logger');
+const { parseLockfile } = require('../core/lockfile-parser');
+const { normalizeAllowlist, assessmentFor, STATUSES } = require('../core/vex');
+
+const TOOL_VERSION = require('../../package.json').version;
+const INFO_URI = 'https://github.com/migohe14/cra-audit';
+
+/** GitHub code scanning ranks alerts by this 0-10 score. */
+const SECURITY_SEVERITY = { critical: 9.5, high: 8.0, moderate: 5.5, low: 2.0, info: 0.5, unknown: 5.0 };
+
+/**
+ * Converts an audit report to SARIF 2.1.0, the format GitHub code scanning
+ * ingests (`github/codeql-action/upload-sarif`). Each advisory on each
+ * vulnerable component becomes one result, located on the component's entry
+ * in the lockfile; license problems become results too.
+ *
+ * Advisories assessed as not_affected in the policy are kept as suppressed
+ * `note` results carrying the justification, so the decision stays visible.
+ *
+ * @param {import('../core/auditor').AuditResult} report
+ * @param {string} projectRoot
+ * @param {object} [policy]
+ */
+function buildSarif(report, projectRoot, policy = {}) {
+  const rules = new Map();
+  const results = [];
+  const lock = lockfileLocator(projectRoot);
+  const assessments = normalizeAllowlist(policy);
+
+  const vulns = report.sections.vulnerabilities;
+  if (vulns && vulns.ok) {
+    for (const finding of vulns.vulnerabilities) {
+      for (const source of finding.sources) {
+        const ruleId = source.id || (source.url ? source.url.split('/').pop() : `${finding.name}-vulnerability`);
+        if (!rules.has(ruleId)) rules.set(ruleId, vulnerabilityRule(ruleId, finding, source));
+        const assessment = finding.malicious ? null : assessmentFor(finding, source, assessments);
+        const accepted = Boolean(assessment && STATUSES[assessment.status].accepts);
+        const result = {
+          ruleId,
+          level: accepted ? 'note'
+            : finding.malicious || source.kev || ['critical', 'high'].includes(source.severity || finding.severity) ? 'error'
+              : (source.severity || finding.severity) === 'moderate' ? 'warning' : 'note',
+          message: { text: vulnerabilityMessage(finding, source) },
+          locations: [lock.locate(finding.name, finding.version)],
+          partialFingerprints: { 'craAudit/v1': `${ruleId}:${finding.name}@${finding.version || ''}` },
+        };
+        if (accepted) {
+          result.suppressions = [{
+            kind: 'external',
+            status: 'accepted',
+            justification: [assessment.status, assessment.justification, assessment.detail].filter(Boolean).join(' — '),
+          }];
+        }
+        results.push(result);
+      }
+    }
+  }
+
+  const licenses = report.sections.licenses;
+  if (licenses && licenses.ok) {
+    const s = licenses.summary;
+    const groups = [
+      ['cra-audit/license-denied', s.denied, 'error', (c) => `${c.name}@${c.version} is licensed under ${c.license}, which the policy denies.`],
+      ['cra-audit/license-not-allowed', s.notAllowed, 'warning', (c) => `${c.name}@${c.version} is licensed under ${c.license}, which is not in the policy allowlist.`],
+      ['cra-audit/license-missing', s.missing, 'warning', (c) => `${c.name}@${c.version} has no documented license (TR-03183-2 §5.2.2).`],
+    ];
+    for (const [ruleId, list, level, text] of groups) {
+      if (!list.length) continue;
+      rules.set(ruleId, licenseRule(ruleId));
+      for (const c of list) {
+        results.push({
+          ruleId,
+          level,
+          message: { text: text(c) },
+          locations: [lock.locate(c.name, c.version)],
+          partialFingerprints: { 'craAudit/v1': `${ruleId}:${c.name}@${c.version}` },
+        });
+      }
+    }
+  }
+
+  return {
+    $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+    version: '2.1.0',
+    runs: [{
+      tool: {
+        driver: {
+          name: 'cra-audit',
+          version: TOOL_VERSION,
+          semanticVersion: TOOL_VERSION,
+          informationUri: INFO_URI,
+          rules: [...rules.values()],
+        },
+      },
+      originalUriBaseIds: { '%SRCROOT%': { uri: toFileUri(lock.repoRoot) } },
+      results,
+    }],
+  };
+}
+
+function vulnerabilityRule(ruleId, finding, source) {
+  const severity = source.severity || finding.severity;
+  const score = finding.malicious ? 10 : source.cvss || SECURITY_SEVERITY[severity] || 5;
+  const tags = ['security', 'vulnerability', 'supply-chain', 'cra'];
+  if (finding.malicious) tags.push('malicious');
+  if (source.kev) tags.push('actively-exploited');
+  const cves = (source.aliases || []).filter((a) => /^CVE-/i.test(a));
+  const title = finding.malicious ? `Malicious package: ${finding.name}` : source.title || ruleId;
+
+  return {
+    id: ruleId,
+    name: ruleId.replace(/[^A-Za-z0-9]/g, ''),
+    shortDescription: { text: title },
+    fullDescription: { text: [title, cves.length ? `(${cves.join(', ')})` : ''].join(' ').trim() },
+    helpUri: source.url || INFO_URI,
+    help: {
+      text: finding.malicious
+        ? 'This release was published by an attacker. Remove it, reinstall from a clean lockfile, and rotate every credential available to machines that installed it.'
+        : 'Update the dependency to a fixed version, or record in .cra-audit.json why it is not exploitable in your product (the assessment goes to the VEX document).',
+    },
+    properties: {
+      tags,
+      precision: 'very-high',
+      'security-severity': String(Math.min(10, Number(score)).toFixed(1)),
+    },
+  };
+}
+
+function vulnerabilityMessage(finding, source) {
+  const pkg = `${finding.name}${finding.version ? `@${finding.version}` : ''}`;
+  if (finding.malicious) {
+    return `[MALICIOUS] ${pkg} is a known compromised release (${source.id}). Remove it and rotate exposed credentials.`;
+  }
+  const parts = [];
+  if (source.kev) parts.push(`[ACTIVELY EXPLOITED — CISA KEV since ${source.kev.dateAdded}; CRA Art. 14 reporting may apply]`);
+  parts.push(`${pkg}: ${source.title || source.id}`);
+  const cves = (source.aliases || []).filter((a) => /^CVE-/i.test(a));
+  if (cves.length) parts.push(`(${cves.join(', ')})`);
+  const fixed = source.fixed || (finding.fixAvailable && finding.fixAvailable.version);
+  parts.push(fixed ? `Fixed in ${fixed}.` : 'No fixed version available.');
+  if (!finding.direct) parts.push('Transitive dependency.');
+  return parts.join(' ');
+}
+
+function licenseRule(ruleId) {
+  const texts = {
+    'cra-audit/license-denied': 'Dependency license denied by the policy',
+    'cra-audit/license-not-allowed': 'Dependency license outside the policy allowlist',
+    'cra-audit/license-missing': 'Dependency without a documented license',
+  };
+  return {
+    id: ruleId,
+    name: ruleId.replace(/[^A-Za-z0-9]/g, ''),
+    shortDescription: { text: texts[ruleId] },
+    helpUri: INFO_URI,
+    properties: { tags: ['license', 'compliance', 'cra'], precision: 'high' },
+  };
+}
+
+/**
+ * Finds the line of `name@version` in the project lockfile so each alert
+ * points at the exact entry. Falls back to package.json line 1.
+ */
+function lockfileLocator(projectRoot) {
+  const repoRoot = findRepoRoot(projectRoot);
+  const parsed = parseLockfile(projectRoot);
+  const file = parsed.lockfileName ? path.join(projectRoot, parsed.lockfileName) : path.join(projectRoot, 'package.json');
+  let lines = [];
+  try {
+    lines = fs.readFileSync(file, 'utf8').split(/\r?\n/);
+  } catch {
+    // Unreadable lockfile: every result points at line 1.
+  }
+  const uri = path.relative(repoRoot, file).split(path.sep).join('/');
+
+  const locate = (name, version) => {
+    const line = findEntryLine(lines, name, version);
+    return {
+      physicalLocation: {
+        artifactLocation: { uri, uriBaseId: '%SRCROOT%' },
+        region: { startLine: line },
+      },
+    };
+  };
+  return { repoRoot, locate };
+}
+
+function findEntryLine(lines, name, version) {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
+  // npm: "node_modules/name": { | yarn: name@range: / "name@npm:range": | pnpm: name@version: / /name/version:
+  const header = new RegExp(`(node_modules/${escaped}"\\s*:|^\\s*["']?/?${escaped}(@|/)[^\\s]*:?\\s*$|^\\s*["']?/?${escaped}@)`);
+  for (let i = 0; i < lines.length; i++) {
+    if (!header.test(lines[i])) continue;
+    if (!version) return i + 1;
+    // The entry's version is on the key itself (pnpm) or within the next lines.
+    if (lines[i].includes(version)) return i + 1;
+    for (let j = i + 1; j < Math.min(lines.length, i + 8); j++) {
+      if (lines[j].includes(`"version": "${version}"`) || lines[j].includes(`version "${version}"`) ||
+        new RegExp(`^\\s*version:\\s*["']?${version.replace(/\./g, '\\.')}["']?\\s*$`).test(lines[j])) {
+        return i + 1;
+      }
+    }
+  }
+  return 1;
+}
+
+/** Nearest folder with a .git entry: SARIF paths must be repository-relative. */
+function findRepoRoot(start) {
+  let dir = path.resolve(start);
+  for (;;) {
+    if (fs.existsSync(path.join(dir, '.git'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return path.resolve(start);
+    dir = parent;
+  }
+}
+
+function toFileUri(dir) {
+  const normalized = dir.split(path.sep).join('/');
+  return `file://${normalized.startsWith('/') ? '' : '/'}${normalized}/`;
+}
+
+/**
+ * Writes the SARIF report to disk. `quiet` keeps stdout clean when it
+ * carries the JSON report.
+ */
+function reportSarif(report, projectRoot, outputPath, { quiet = false, policy } = {}) {
+  const outPath = path.isAbsolute(outputPath) ? outputPath : path.join(process.cwd(), outputPath);
+  writeJson(outPath, buildSarif(report, projectRoot, policy));
+  if (!quiet) logger.success(`SARIF report written to: ${outPath}`);
+}
+
+module.exports = { buildSarif, reportSarif, findEntryLine };