cra-audit 1.1.0 → 2.1.0

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
@@ -21,21 +22,29 @@ const { checkLicenses } = require('./license-checker');
  * @param {object} policy
  * @param {string|null} policySource
  * @param {{ only?: 'vulnerabilities'|'sbom'|'licenses' }} [options]
- * @returns {AuditResult}
+ * @returns {Promise<AuditResult>}
  */
-function runAudit(projectRoot, policy, policySource, options = {}) {
+async function runAudit(projectRoot, policy, policySource, options = {}) {
   const { only } = options;
   const sections = {};
   const reasons = [];
 
   // --- 1. Vulnerabilities -------------------------------------------------
   if (!only || only === 'vulnerabilities') {
-    const vulns = scanVulnerabilities(projectRoot, { production: policy.productionOnly });
+    const vulns = await scanVulnerabilities(projectRoot, {
+      production: policy.productionOnly,
+      source: policy.vulnerabilitySource,
+    });
     sections.vulnerabilities = vulns;
 
     if (!vulns.ok) {
       reasons.push({ label: `Vulnerabilities could not be analyzed: ${vulns.error}`, passed: false });
     } else {
+      for (const warning of vulns.warnings || []) {
+        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
@@ -97,22 +106,78 @@ function runAudit(projectRoot, policy, policySource, options = {}) {
   };
 }
 
+/**
+ * Gate reasons for the OSV source: malicious packages always block (they are
+ * compromised releases, not bugs, so the allowlist cannot accept them), and
+ * actively exploited vulnerabilities (CISA KEV) block unless `failOnKev` is off.
+ */
+function exploitationReasons(vulns, policy) {
+  if (vulns.source !== 'osv') return [];
+  const reasons = [];
+
+  const malicious = vulns.vulnerabilities.filter((v) => v.malicious);
+  reasons.push({
+    label: malicious.length === 0
+      ? 'No malicious packages (OpenSSF malicious-packages via OSV.dev)'
+      : `${malicious.length} malicious package(s): ${malicious.map((v) => `${v.name}@${v.version}`).join(', ')}`,
+    passed: malicious.length === 0,
+  });
+
+  if (!vulns.kev || !vulns.kev.checked) {
+    reasons.push({
+      label: `Actively exploited vulnerabilities not checked: ${(vulns.kev && vulns.kev.error) || 'CISA KEV unavailable'}`,
+      passed: true,
+      warning: true,
+    });
+    return reasons;
+  }
+
+  const exploited = vulns.vulnerabilities.filter((v) => v.kev && !isAllowlisted(v, policy));
+  reasons.push({
+    label: exploited.length === 0
+      ? 'No actively exploited vulnerabilities (CISA KEV)'
+      : `${exploited.length} component(s) with actively exploited vulnerabilities (CISA KEV) — CRA Art. 14 reporting may apply`,
+    passed: exploited.length === 0 || policy.failOnKev === false,
+    warning: exploited.length > 0 && policy.failOnKev === false,
+  });
+  return reasons;
+}
+
 function countBlocking(vulns, policy) {
   const threshold = SEVERITY_ORDER.indexOf(policy.failOn);
   if (threshold === -1) return 0;
-  const allowlist = new Set((policy.vulnerabilities && policy.vulnerabilities.allowlist) || []);
 
   let count = 0;
   for (const vuln of vulns.vulnerabilities) {
     if (SEVERITY_ORDER.indexOf(vuln.severity) < threshold) continue;
-    const isAllowlisted = vuln.sources.some(
-      (src) => src.url && [...allowlist].some((id) => src.url.includes(id))
-    ) || allowlist.has(vuln.name);
-    if (!isAllowlisted) count++;
+    if (!vuln.malicious && isAllowlisted(vuln, policy)) continue;
+    count++;
   }
   return count;
 }
 
+/**
+ * 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) {
+  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) {
   // Derive project identity from any section that parsed the lockfile/root.
   if (sections.sbom && sections.sbom.ok && sections.sbom.document) {

package/src/core/kev.js

@@ -0,0 +1,44 @@
+'use strict';
+
+const { fetchJson } = require('../utils/http');
+
+/**
+ * CISA Known Exploited Vulnerabilities catalogue: the most complete public
+ * list of vulnerabilities with evidence of active exploitation. Under CRA
+ * Art. 14 (applicable since 11 September 2026) manufacturers must report
+ * actively exploited vulnerabilities in their products within 24 hours.
+ *
+ * The GitHub mirror maintained by CISA is used when the primary feed fails.
+ */
+const KEV_SOURCES = [
+  'https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json',
+  'https://raw.githubusercontent.com/cisagov/kev-data/develop/known_exploited_vulnerabilities.json',
+];
+
+/**
+ * @returns {Promise<{ ok: true, catalogVersion: string|null, count: number, byCve: Map<string, object> }
+ *   | { ok: false, error: string }>}
+ */
+async function loadKev({ timeout = 20000 } = {}) {
+  for (const url of KEV_SOURCES) {
+    const res = await fetchJson(url, { timeout });
+    const list = res && res.ok && res.json && res.json.vulnerabilities;
+    if (!Array.isArray(list)) continue;
+
+    const byCve = new Map();
+    for (const entry of list) {
+      if (!entry || !entry.cveID) continue;
+      byCve.set(entry.cveID.toUpperCase(), {
+        cve: entry.cveID,
+        name: entry.vulnerabilityName || null,
+        dateAdded: entry.dateAdded || null,
+        dueDate: entry.dueDate || null,
+        knownRansomwareCampaignUse: entry.knownRansomwareCampaignUse || null,
+      });
+    }
+    return { ok: true, catalogVersion: res.json.catalogVersion || null, count: byCve.size, byCve };
+  }
+  return { ok: false, error: 'CISA KEV catalogue unreachable' };
+}
+
+module.exports = { loadKev };

package/src/core/osv.js

@@ -0,0 +1,211 @@
+'use strict';
+
+const { fetchJson, mapLimit } = require('../utils/http');
+
+const OSV_API = 'https://api.osv.dev/v1';
+const BATCH_SIZE = 1000; // OSV querybatch limit
+
+/**
+ * Queries OSV.dev (https://osv.dev) for the advisories affecting each exact
+ * `name@version`. OSV aggregates the GitHub Advisory Database (GHSA) and the
+ * OpenSSF malicious-packages feed (MAL-*), which lists compromised releases
+ * such as the ones published by the Shai-Hulud worm.
+ *
+ * Only package names and versions leave the machine.
+ *
+ * @param {Array<{ name: string, version: string }>} components
+ * @param {{ timeout?: number, concurrency?: number }} [options]
+ * @returns {Promise<{ ok: true, byComponent: Map<string, object[]> } | { ok: false, error: string }>}
+ *   `byComponent` is keyed by `name@version` and holds full OSV records.
+ */
+async function queryOsv(components, { timeout = 30000, concurrency = 8 } = {}) {
+  const idsByKey = new Map();
+
+  for (let i = 0; i < components.length; i += BATCH_SIZE) {
+    const chunk = components.slice(i, i + BATCH_SIZE);
+    const res = await fetchJson(`${OSV_API}/querybatch`, {
+      timeout,
+      body: { queries: chunk.map((c) => ({ package: { name: c.name, ecosystem: 'npm' }, version: c.version })) },
+    });
+    if (!res || !res.ok || !res.json || !Array.isArray(res.json.results)) {
+      return { ok: false, error: `OSV.dev query failed${res ? ` (HTTP ${res.status})` : ' (network unreachable)'}` };
+    }
+
+    for (let j = 0; j < chunk.length; j++) {
+      const result = res.json.results[j] || {};
+      const ids = (result.vulns || []).map((v) => v.id);
+      // A package with many advisories is paginated: follow the token.
+      let pageToken = result.next_page_token;
+      while (pageToken) {
+        const page = await fetchJson(`${OSV_API}/query`, {
+          timeout,
+          body: { package: { name: chunk[j].name, ecosystem: 'npm' }, version: chunk[j].version, page_token: pageToken },
+        });
+        if (!page || !page.ok || !page.json) break;
+        ids.push(...(page.json.vulns || []).map((v) => v.id));
+        pageToken = page.json.next_page_token;
+      }
+      if (ids.length) idsByKey.set(`${chunk[j].name}@${chunk[j].version}`, ids);
+    }
+  }
+
+  // querybatch only returns ids: fetch each distinct record once.
+  const uniqueIds = [...new Set([].concat(...idsByKey.values()))];
+  const records = new Map();
+  let failed = 0;
+  await mapLimit(uniqueIds, async (id) => {
+    const res = await fetchJson(`${OSV_API}/vulns/${encodeURIComponent(id)}`, { timeout });
+    if (res && res.ok && res.json) records.set(id, res.json);
+    else failed++;
+  }, concurrency);
+  if (failed) {
+    return { ok: false, error: `Could not download ${failed} advisory record(s) from OSV.dev` };
+  }
+
+  const byComponent = new Map();
+  for (const [key, ids] of idsByKey) {
+    const list = ids.map((id) => records.get(id)).filter((r) => r && !r.withdrawn);
+    // The same advisory can appear under two ids (e.g. GHSA and its CVE).
+    const seen = new Set();
+    const unique = [];
+    for (const record of list) {
+      if (seen.has(record.id)) continue;
+      [record.id, ...(record.aliases || [])].forEach((a) => seen.add(a));
+      unique.push(record);
+    }
+    byComponent.set(key, unique);
+  }
+  return { ok: true, byComponent };
+}
+
+/**
+ * Severity of an OSV record in npm-audit terms. Malicious packages are always
+ * critical; GHSA records carry a reviewed rating; otherwise the CVSS v3 base
+ * score is computed from the vector.
+ *
+ * @returns {'low'|'moderate'|'high'|'critical'|'unknown'}
+ */
+function osvSeverity(record) {
+  if (isMalicious(record)) return 'critical';
+
+  const rated = record.database_specific && record.database_specific.severity;
+  if (typeof rated === 'string') {
+    const s = rated.toLowerCase();
+    if (s === 'medium') return 'moderate';
+    if (['low', 'moderate', 'high', 'critical'].includes(s)) return s;
+  }
+
+  const score = cvssScore(record);
+  if (score === null) return 'unknown';
+  if (score >= 9) return 'critical';
+  if (score >= 7) return 'high';
+  if (score >= 4) return 'moderate';
+  return 'low';
+}
+
+/** CVSS v3 base score of the record, or null when it has no v3 vector. */
+function cvssScore(record) {
+  const v3 = (record.severity || []).find((s) => s.type === 'CVSS_V3');
+  return v3 ? cvss3BaseScore(v3.score) : null;
+}
+
+/** OpenSSF malicious-packages advisories use the MAL- prefix. */
+function isMalicious(record) {
+  return typeof record.id === 'string' && record.id.startsWith('MAL-');
+}
+
+/**
+ * Lowest version that fixes the advisory for the installed version, taken from
+ * the OSV `affected[].ranges[].events` of this package.
+ *
+ * @returns {string|null}
+ */
+function fixedVersion(record, name, version) {
+  let best = null;
+  for (const affected of record.affected || []) {
+    if (!affected.package || affected.package.name !== name) continue;
+    for (const range of affected.ranges || []) {
+      if (range.type !== 'SEMVER' && range.type !== 'ECOSYSTEM') continue;
+      let introduced = null;
+      for (const event of range.events || []) {
+        if (event.introduced !== undefined) introduced = event.introduced;
+        if (event.fixed === undefined) continue;
+        const inRange = (introduced === '0' || introduced === null || compareSemver(version, introduced) >= 0) &&
+          compareSemver(version, event.fixed) < 0;
+        if (inRange && (!best || compareSemver(event.fixed, best) < 0)) best = event.fixed;
+      }
+    }
+  }
+  return best;
+}
+
+/**
+ * Compares two semver strings (major.minor.patch[-prerelease]).
+ * Build metadata is ignored.
+ */
+function compareSemver(a, b) {
+  const parse = (v) => {
+    const [core, pre] = String(v).split('+')[0].split(/-(.*)/s);
+    return { nums: core.split('.').map((n) => parseInt(n, 10) || 0), pre: pre ? pre.split('.') : [] };
+  };
+  const pa = parse(a);
+  const pb = parse(b);
+  for (let i = 0; i < 3; i++) {
+    const diff = (pa.nums[i] || 0) - (pb.nums[i] || 0);
+    if (diff) return diff;
+  }
+  // A version without prerelease is greater than one with it.
+  if (!pa.pre.length || !pb.pre.length) return pb.pre.length - pa.pre.length;
+  for (let i = 0; i < Math.max(pa.pre.length, pb.pre.length); i++) {
+    const x = pa.pre[i];
+    const y = pb.pre[i];
+    if (x === undefined) return -1;
+    if (y === undefined) return 1;
+    const nx = /^\d+$/.test(x);
+    const ny = /^\d+$/.test(y);
+    if (nx && ny && Number(x) !== Number(y)) return Number(x) - Number(y);
+    if (nx !== ny) return nx ? -1 : 1;
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
+const CVSS3_WEIGHTS = {
+  AV: { N: 0.85, A: 0.62, L: 0.55, P: 0.2 },
+  AC: { L: 0.77, H: 0.44 },
+  UI: { N: 0.85, R: 0.62 },
+  C: { H: 0.56, L: 0.22, N: 0 },
+  I: { H: 0.56, L: 0.22, N: 0 },
+  A: { H: 0.56, L: 0.22, N: 0 },
+};
+
+/** CVSS v3.0/v3.1 base score from a vector string (FIRST specification). */
+function cvss3BaseScore(vector) {
+  const m = {};
+  for (const part of String(vector).split('/')) {
+    const [k, v] = part.split(':');
+    m[k] = v;
+  }
+  const scopeChanged = m.S === 'C';
+  const pr = { N: 0.85, L: scopeChanged ? 0.68 : 0.62, H: scopeChanged ? 0.5 : 0.27 }[m.PR];
+  const w = CVSS3_WEIGHTS;
+  const values = [w.AV[m.AV], w.AC[m.AC], pr, w.UI[m.UI], w.C[m.C], w.I[m.I], w.A[m.A]];
+  if (values.some((x) => x === undefined)) return null;
+  const [av, ac, , ui, c, i, a] = values;
+
+  const iss = 1 - (1 - c) * (1 - i) * (1 - a);
+  const impact = scopeChanged ? 7.52 * (iss - 0.029) - 3.25 * Math.pow(iss - 0.02, 15) : 6.42 * iss;
+  if (impact <= 0) return 0;
+  const exploitability = 8.22 * av * ac * pr * ui;
+  const raw = scopeChanged ? Math.min(1.08 * (impact + exploitability), 10) : Math.min(impact + exploitability, 10);
+  return roundUp(raw);
+}
+
+function roundUp(value) {
+  const int = Math.round(value * 100000);
+  return int % 10000 === 0 ? int / 100000 : (Math.floor(int / 10000) + 1) / 10;
+}
+
+module.exports = {
+  queryOsv, osvSeverity, cvssScore, isMalicious, fixedVersion, compareSemver, cvss3BaseScore,
+};

package/src/core/policy.js

@@ -18,6 +18,11 @@ const DEFAULT_POLICY = {
   // Email or URL of the SBOM creator (TR-03183-2 §5.2.1). Defaults to the
   // project's package.json author, homepage or repository.
   sbomCreator: null,
+  // Vulnerability source: `osv` (OSV.dev + CISA KEV) or `npm` (npm audit).
+  vulnerabilitySource: 'osv',
+  // Fail when a dependency has an actively exploited vulnerability (CISA KEV),
+  // the trigger of the CRA Art. 14 reporting obligation.
+  failOnKev: true,
   // Audit only production dependencies (recommended for shipped products).
   productionOnly: false,
   vulnerabilities: {

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 };