@blamejs/exceptd-skills 0.18.21 → 0.18.22

package/lib/auto-discovery.js

@@ -22,7 +22,7 @@
  * is tolerant of this annotation; the audit / stale-content index
  * surfaces uncurated entries so they don't sit indefinitely.
  *
- * Both discovery functions accept a `cap` (default 20) so a burst
+ * Both discovery functions accept a `cap` (default 100) so a burst
  * upstream addition doesn't generate an unreviewable PR. Items past
  * the cap spill to the next run.
  */
@@ -30,8 +30,9 @@
 const fs = require("fs");
 const path = require("path");
 const crypto = require("crypto");
-const { scoreCustom, RWEP_WEIGHTS, ACTIVE_EXPLOITATION_LADDER } = require("./scoring");
+const { scoreCustom, postWeightFactors } = require("./scoring");
 const { selectNvdCvss } = require("./cvss");
+const { deriveMechanicalFields } = require("./cve-enrich");
 
 // Stored rwep_factors must reproduce the stored rwep_score.
 // `buildScoringInputs` is the single source of truth for both — it captures
@@ -65,30 +66,11 @@ function buildScoringInputs(kevEntry /*, nvdPayload */) {
 // builder stored the SHAPE-A (boolean + string-ladder) factor bag — semantically
 // fine because deriveRwepFromFactors handles either shape, but the strict
 // JSON-schema validator (and any downstream tooling that types-checks the
-// catalog field) rejected drafts as malformed. Convert the boolean inputs to
-// the schema-required post-weight shape so the curate-apply gate (which loads
-// the strict schema) doesn't reject KEV-discovered drafts post-promotion.
-//
-// `ai_factor` is the schema-required key name; auto-discovery's boolean
-// inputs are split across `ai_discovered` + `ai_assisted_weapon`, mirroring
-// scoreCustom's contract. The factor fires when either flag is true (same as
-// scoreCustom).
-function toPostWeightFactors(inputs) {
-  const aeMultiplier = ACTIVE_EXPLOITATION_LADDER[inputs.active_exploitation] ?? 0;
-  const reboot = (inputs.reboot_required === true) || (inputs.patch_required_reboot === true);
-  const blastRaw = Number.isFinite(Number(inputs.blast_radius)) ? Number(inputs.blast_radius) : 0;
-  const blastClamped = Math.max(0, Math.min(RWEP_WEIGHTS.blast_radius, blastRaw));
-  return {
-    cisa_kev: inputs.cisa_kev ? RWEP_WEIGHTS.cisa_kev : 0,
-    poc_available: inputs.poc_available ? RWEP_WEIGHTS.poc_available : 0,
-    ai_factor: (inputs.ai_assisted_weapon || inputs.ai_discovered) ? RWEP_WEIGHTS.ai_factor : 0,
-    active_exploitation: RWEP_WEIGHTS.active_exploitation * aeMultiplier,
-    blast_radius: blastClamped,
-    patch_available: inputs.patch_available ? RWEP_WEIGHTS.patch_available : 0,
-    live_patch_available: inputs.live_patch_available ? RWEP_WEIGHTS.live_patch_available : 0,
-    reboot_required: reboot ? RWEP_WEIGHTS.reboot_required : 0,
-  };
-}
+// catalog field) rejected drafts as malformed. `scoring.postWeightFactors` (the
+// canonical home for this conversion, also consumed by lib/cve-enrich.js's
+// batch-curation path) now does the boolean -> schema-required post-weight
+// conversion, so the nightly draft builder and the batch tool can't drift on
+// the math.
 
 /**
  * O — diff severity nuance for KEV-discovered drafts.
@@ -125,7 +107,7 @@ function deriveKevSeverity(kevEntry) {
 const TODAY = new Date().toISOString().slice(0, 10);
 const TIMEOUT_MS = 10_000;
 const USER_AGENT = "exceptd-security/auto-discovery (+https://exceptd.com)";
-const DEFAULT_CAP = 20;
+const DEFAULT_CAP = 100;
 
 // IETF Datatracker codes → human-readable status strings used in
 // data/rfc-references.json.
@@ -208,6 +190,11 @@ function extractNvdMetrics(payload, id) {
       .map((d) => d.value)
       .filter((v) => /^CWE-\d+$/.test(v))
     ),
+    // Carry NVD's reference list (url + tags) so buildKevDraftEntry can feed
+    // real "Vendor Advisory"-tagged links into cve-enrich and a nightly
+    // draft's vendor_advisories reflects genuine advisories (empty otherwise,
+    // correctly tripping the cisa_kev-but-no-advisory curation-gap detector).
+    references: (vuln.references || []).map((r) => ({ url: r.url, tags: r.tags || [] })),
   };
 }
 
@@ -248,9 +235,6 @@ function buildKevDraftEntry(kevEntry, nvdPayload, epssPayload) {
   const nvd = nvdPayload ? extractNvdMetrics(nvdPayload, id) : null;
   const epss = epssPayload ? extractEpss(epssPayload, id) : null;
 
-  const knownRansomware =
-    String(kevEntry.knownRansomwareCampaignUse || "").toLowerCase() === "known";
-
   // Stored rwep_factors and computed rwep_score MUST agree.
   // Previously rwep_factors held nulls (for unknown poc/ai/reboot) but
   // rwep_score was computed from concrete defaults (poc=true, reboot=true).
@@ -263,7 +247,8 @@ function buildKevDraftEntry(kevEntry, nvdPayload, epssPayload) {
   // that scoreCustom consumes. Pre-fix the boolean shape was stored
   // verbatim, so curate-apply's strict-schema gate rejected KEV-discovered
   // drafts as soon as anyone tried to promote them — they were
-  // permanently unpromotable.
+  // permanently unpromotable. `scoring.postWeightFactors` (shared with the
+  // batch-curation path in lib/cve-enrich.js) does the conversion now.
   //
   // The curation flow rewrites these once an operator answers the editorial
   // questions; until then, the post-weight numeric shape on rwep_factors
@@ -271,31 +256,59 @@ function buildKevDraftEntry(kevEntry, nvdPayload, epssPayload) {
   // blast_radius weight=30 matches the raw-cap convention documented in
   // scoring.js header).
   const scoringInputs = buildScoringInputs(kevEntry, nvdPayload);
-  const rwep_factors = toPostWeightFactors(scoringInputs);
+  const rwep_factors = postWeightFactors(scoringInputs);
   const rwep_score = scoreCustom(scoringInputs);
 
   const product = [kevEntry.vendorProject, kevEntry.product]
     .filter(Boolean)
     .join(" ");
 
+  // Mechanical fields (name, cvss_score/vector, cwe_refs, cisa_kev +
+  // cisa_kev_date/due_date, known_ransomware_use, complexity, vector, epss_*,
+  // vendor_advisories, verification_sources, source_verified/last_updated)
+  // are derived through the SAME cve-enrich module the `--curate-batch`
+  // tool uses, so the nightly auto-PR path and the batch tool never drift on
+  // how a raw KEV/NVD/EPSS fact set becomes a mechanical field. See
+  // lib/cve-enrich.js:deriveMechanicalFields — this module maps the already-
+  // extracted `nvd`/`epss` payloads (see extractNvdMetrics/extractEpss above)
+  // and the raw `kevEntry` into that module's `facts` shape.
+  const facts = {
+    id,
+    nvd_desc: nvd && nvd.description,
+    cvss: nvd && nvd.cvss_score != null
+      ? { version: "3.1", base_score: nvd.cvss_score, vector: nvd.cvss_vector, severity: null }
+      : null,
+    cwe_nvd: (nvd && nvd.cwe_refs) || [],
+    references: (nvd && nvd.references) || [],
+    kev: {
+      name: kevEntry.vulnerabilityName,
+      vendor: kevEntry.vendorProject,
+      product: kevEntry.product,
+      dateAdded: kevEntry.dateAdded,
+      dueDate: kevEntry.dueDate,
+      ransomware: kevEntry.knownRansomwareCampaignUse,
+      shortDescription: kevEntry.shortDescription,
+    },
+    epss: epss && { score: epss.score, percentile: epss.percentile, date: epss.date },
+  };
+  const mech = deriveMechanicalFields(facts, TODAY);
+
   return {
-    name: String(kevEntry.vulnerabilityName || "TBD — verify against vendor advisory"),
+    ...mech,
     type: "TBD",
-    cvss_score: nvd?.cvss_score ?? null,
-    cvss_vector: nvd?.cvss_vector ?? null,
-    cisa_kev: true,
-    cisa_kev_date: kevEntry.dateAdded || null,
-    cisa_kev_due_date: kevEntry.dueDate || null,
     poc_available: null,
     poc_description: null,
     ai_discovered: null,
     ai_discovery_notes: null,
     ai_assisted_weaponization: null,
+    // Conservative pre-curation default — overrides deriveMechanicalFields'
+    // 'confirmed' (mechanically derived from "this CVE has a KEV listing").
+    // A nightly draft must not claim CONFIRMED active exploitation before a
+    // human has reviewed it; 'suspected' is the honest starting posture even
+    // though KEV listing alone already implies exploitation is real.
     active_exploitation: "suspected",
     affected: product || "See vendor advisory",
     affected_versions: [],
-    vector: nvd?.description || kevEntry.shortDescription || "TBD",
-    complexity: null,
     complexity_notes: null,
     patch_available: null,
     patch_required_reboot: null,
@@ -305,34 +318,8 @@ function buildKevDraftEntry(kevEntry, nvdPayload, epssPayload) {
     framework_control_gaps: {},
     atlas_refs: [],
     attack_refs: [],
-    cwe_refs: nvd?.cwe_refs || [],
-    known_ransomware_use: knownRansomware,
-    epss_score: epss?.score ?? null,
-    epss_percentile: epss?.percentile ?? null,
-    epss_date: epss?.date ?? null,
     rwep_score,
     rwep_factors,
-    verification_sources: [
-      "https://www.cisa.gov/known-exploited-vulnerabilities-catalog",
-      kevEntry.notes ? String(kevEntry.notes) : null,
-    ].filter(Boolean),
-    // v0.12.15 (B): schema requires source_verified to be a
-    // YYYY-MM-DD string; the prior `false` boolean (then null) produced
-    // entries that failed strict catalog validation.
-    //
-    // the CISA KEV listing IS the verification source for a
-    // KEV-discovered draft — the entry's `verification_sources` array
-    // already points to the KEV catalog URL, and KEV's appearance is what
-    // triggered the auto-import. Pre-fix the field stayed null, which
-    // (a) blocked curate-apply's strict-schema check (which requires a
-    // YYYY-MM-DD string) and (b) left operators no signal that the
-    // upstream HAD in fact verified the entry's authoritative listing.
-    // Now we date-stamp it as TODAY (the import day). Operators may
-    // overwrite during full curation if they revalidate from a fresher
-    // KEV pull — the field always semantically means "the date a
-    // verification source confirmed this CVE id."
-    source_verified: TODAY,
-    last_updated: TODAY,
     last_verified: TODAY,
     // v0.12.15 (D): `_auto_imported` must be the boolean `true`
     // for lib/validate-cve-catalog.js's draft-recognition check (strict
@@ -351,7 +338,7 @@ function buildKevDraftEntry(kevEntry, nvdPayload, epssPayload) {
         "active_exploitation upgrade from 'suspected' to 'confirmed' once a campaign is documented",
         "framework_control_gaps mapping (NIST/ISO/PCI/SOC 2 controls this defeats)",
         "atlas_refs + attack_refs categorization",
-        "complexity assessment + complexity_notes",
+        "complexity_notes (complexity auto-derived from CVSS AC when NVD data present)",
         "patch_available + live_patch_available + live_patch_tools",
         "blast_radius numeric in rwep_factors (currently default 15)",
         "RWEP score recompute after the above land",

package/lib/cve-batch.js

@@ -0,0 +1,216 @@
+'use strict';
+
+// Batch curation orchestration: read a facts file + a judgments file, run
+// each pair through cve-enrich.assembleEntry, refuse to write when any
+// entry has an orphaned reference or an assembly error, and otherwise
+// write the catalog (targeted string surgery — never round-tripped),
+// zeroday-lessons.json (canonical writer, it DOES round-trip), and one
+// tests/cve-<id>.test.js per curated CVE. Wired to the CLI as
+// `refresh --curate-batch --facts <path> --judgments <path> [--apply]`.
+
+const fs = require('fs');
+const path = require('path');
+const enrich = require('./cve-enrich.js');
+
+// ---------------------------------------------------------------------
+// Catalog string-surgery insert + _meta recompute (Task 6)
+// ---------------------------------------------------------------------
+
+// Find the insertion point just after the top-level "_meta" member. Brace-
+// matches from the "_meta" key. The catalog is 2-space-indented; new members
+// are emitted at that indent.
+function _metaEnd(text) {
+  const m = /\n {2}"_meta"\s*:/.exec(text);
+  if (!m) throw new Error('cve-batch: could not locate top-level "_meta" member');
+  let i = text.indexOf('{', m.index);
+  let depth = 0;
+  for (; i < text.length; i++) {
+    const c = text[i];
+    if (c === '{') depth++;
+    else if (c === '}') { depth--; if (depth === 0) { i++; break; } }
+    else if (c === '"') { i++; while (i < text.length && text[i] !== '"') { if (text[i] === '\\') i++; i++; } }
+  }
+  const comma = text.indexOf(',', i);
+  // A comma whose gap from _meta's closing brace is whitespace-only is _meta's
+  // member separator → insert after it (a member follows). Otherwise _meta is
+  // the only/last member (no separator) → insert right after its brace with a
+  // leading comma and no trailing comma.
+  if (comma !== -1 && text.slice(i, comma).trim() === '') return { at: comma + 1, leadingComma: false };
+  return { at: i, leadingComma: true };
+}
+
+function insertEntries(catalogText, entriesById) {
+  const { at, leadingComma } = _metaEnd(catalogText);
+  const blocks = Object.entries(entriesById).map(([id, obj]) => {
+    const body = JSON.stringify(obj, null, 2).split('\n').map((l, idx) => idx === 0 ? l : '  ' + l).join('\n');
+    return `\n  ${JSON.stringify(id)}: ${body}`;
+  });
+  const insert = leadingComma ? (',' + blocks.join(',')) : blocks.map(b => b + ',').join('');
+  return catalogText.slice(0, at) + insert + catalogText.slice(at);
+}
+
+function recomputeAiMeta(catalogText, aiCount, total) {
+  // current_rate is the ROUNDED rate (a separate test asserts it equals
+  // round(observed, 3)). The floor, however, is enforced against the RAW rate
+  // (the catalog test checks `rawRate >= floor`), so the floor must be lowered
+  // to the raw rate FLOORED to 3 decimals — using the rounded rate here let a
+  // raw rate of 0.02262 (rounds to 0.023) leave a 0.023 floor the raw rate
+  // cannot clear. Never raise the floor; only lower it when the rate dilutes.
+  const rawRate = aiCount / total;
+  const rate = Math.round(rawRate * 1000) / 1000;
+  let out = catalogText.replace(/("current_rate"\s*:\s*)[0-9.]+/, `$1${rate}`);
+  const floorM = /("current_floor_enforced_by_test"\s*:\s*)([0-9.]+)/.exec(out);
+  if (floorM) {
+    const curFloor = Number(floorM[2]);
+    const rawFloor = Math.floor(rawRate * 1000) / 1000;
+    if (rawFloor < curFloor) {
+      out = out.replace(/("current_floor_enforced_by_test"\s*:\s*)[0-9.]+/, `$1${rawFloor}`);
+      out = out.replace(/("floor_correction_note"\s*:\s*")([^"]*)(")/,
+        (_m, a, note, z) => `${a}${note} batch curation: floor ${curFloor} → ${rawFloor} tracking the diluted honest rate (${aiCount}/${total} AI-discovered) after a bulk KEV curation pass.${z}`);
+    }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------
+// zeroday-lessons.json writer (Task 7) — this file DOES round-trip.
+// ---------------------------------------------------------------------
+
+function addLessons(lessonsObj, lessonsById) {
+  const out = { ...lessonsObj };
+  let added = 0;
+  for (const [id, lesson] of Object.entries(lessonsById)) {
+    if (!(id in out)) added++;
+    out[id] = lesson;
+  }
+  out._meta = { ...(out._meta || {}) };
+  out._meta.entry_count = (out._meta.entry_count || 0) + added;
+  return out;
+}
+
+// ---------------------------------------------------------------------
+// Per-CVE test-file generator (Task 8)
+// ---------------------------------------------------------------------
+
+function renderTest(cveId) {
+  return `const test = require('node:test');
+const assert = require('node:assert');
+const catalog = require('../data/cve-catalog.json');
+const lessons = require('../data/zeroday-lessons.json');
+
+test('${cveId}: curated KEV entry is complete and self-consistent', () => {
+  const e = catalog['${cveId}'];
+  assert.ok(e, '${cveId} present in catalog');
+  assert.notStrictEqual(e._auto_imported, true, 'not a draft');
+  assert.strictEqual(e.cisa_kev, true);
+  assert.strictEqual(typeof e.cvss_score, 'number');
+  assert.ok(Array.isArray(e.cwe_refs) && e.cwe_refs.length > 0, 'has cwe_refs');
+  assert.ok(Array.isArray(e.attack_refs) && e.attack_refs.length > 0, 'has attack_refs');
+  const sum = Object.values(e.rwep_factors).reduce((a, b) => a + b, 0);
+  assert.strictEqual(sum, e.rwep_score, 'Σ rwep_factors === rwep_score');
+  if (e.poc_available === true) {
+    assert.ok(e.iocs && Object.keys(e.iocs).length > 0, 'poc_available → iocs populated');
+  }
+  assert.ok(lessons['${cveId}'], 'has a matching zeroday lesson');
+});
+`;
+}
+
+// ---------------------------------------------------------------------
+// curateBatch orchestration + CLI (Task 9)
+// ---------------------------------------------------------------------
+
+function _loadIds(root, file, key) {
+  const p = path.join(root, 'data', file);
+  if (!fs.existsSync(p)) return new Set();
+  const obj = JSON.parse(fs.readFileSync(p, 'utf8'));
+  if (key) return new Set(Object.keys(obj[key] || {}));
+  return new Set(Object.keys(obj).filter((k) => k !== '_meta'));
+}
+
+async function curateBatch({ factsPath, judgmentsPath, apply, catalogRoot, today }) {
+  const facts = JSON.parse(fs.readFileSync(factsPath, 'utf8'));
+  const judgments = JSON.parse(fs.readFileSync(judgmentsPath, 'utf8'));
+  const catalogs = {
+    cwe: _loadIds(catalogRoot, 'cwe-catalog.json'),
+    attack: _loadIds(catalogRoot, 'attack-techniques.json'),
+    atlas: _loadIds(catalogRoot, 'atlas-ttps.json'),
+    frameworkGaps: _loadIds(catalogRoot, 'framework-control-gaps.json'),
+  };
+  const entries = {}; const lessons = {}; const orphans = []; const errors = [];
+  for (const id of Object.keys(facts)) {
+    const { entry, errors: e } = enrich.assembleEntry(facts[id], judgments[id] || {}, today);
+    entry.id = id; // for orphan messages
+    errors.push(...e);
+    orphans.push(...enrich.findOrphans({ ...entry, id }, catalogs));
+    delete entry.id;
+    entries[id] = entry;
+    if (judgments[id] && judgments[id].lesson) lessons[id] = judgments[id].lesson;
+    else errors.push(`${id}: missing lesson in judgments.`);
+  }
+  const ok = orphans.length === 0 && errors.length === 0;
+  if (!apply || !ok) return { ok, entries, orphans, errors, written: false };
+
+  // WRITE
+  const catPath = path.join(catalogRoot, 'data', 'cve-catalog.json');
+  let text = fs.readFileSync(catPath, 'utf8');
+  text = insertEntries(text, entries);
+  const parsed = JSON.parse(text);
+  const ids = Object.keys(parsed).filter((k) => k !== '_meta');
+  const aiCount = ids.filter((k) => parsed[k].ai_discovered === true).length;
+  text = recomputeAiMeta(text, aiCount, ids.length);
+  fs.writeFileSync(catPath, text);
+
+  const lesPath = path.join(catalogRoot, 'data', 'zeroday-lessons.json');
+  const lesObj = addLessons(JSON.parse(fs.readFileSync(lesPath, 'utf8')), lessons);
+  fs.writeFileSync(lesPath, JSON.stringify(lesObj, null, 2) + '\n');
+
+  // id is already "CVE-2025-0108" — lowercasing alone yields the repo's
+  // existing tests/cve-<year>-<num>.test.js convention; prepending another
+  // "cve-" would double the prefix (tests/cve-cve-2025-0108.test.js).
+  for (const id of Object.keys(entries))
+    fs.writeFileSync(path.join(catalogRoot, 'tests', `${id.toLowerCase()}.test.js`), renderTest(id));
+
+  return { ok: true, entries, orphans, errors, written: true };
+}
+
+async function cli(argv) {
+  const opts = { facts: null, judgments: null, apply: false, catalogRoot: path.join(__dirname, '..') };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--facts') opts.facts = argv[++i];
+    else if (a === '--judgments') opts.judgments = argv[++i];
+    else if (a === '--apply') opts.apply = true;
+  }
+  // Guard missing/unreadable inputs before touching curateBatch — without
+  // this, fs.readFileSync(null) / a nonexistent path throws out of the
+  // async function and crashes the CLI instead of returning a structured
+  // {ok:false} envelope like every other refresh-curate error path.
+  if (!opts.facts || !opts.judgments || !fs.existsSync(opts.facts) || !fs.existsSync(opts.judgments)) {
+    const missing = [];
+    if (!opts.facts) missing.push('--facts <path>');
+    else if (!fs.existsSync(opts.facts)) missing.push(`--facts ${opts.facts} (not found)`);
+    if (!opts.judgments) missing.push('--judgments <path>');
+    else if (!fs.existsSync(opts.judgments)) missing.push(`--judgments ${opts.judgments} (not found)`);
+    const err = { ok: false, verb: 'refresh', mode: 'cve-batch',
+      error: `missing or unreadable required input(s): ${missing.join(', ')}` };
+    process.stdout.write(JSON.stringify(err) + '\n');
+    process.exitCode = 2;
+    return;
+  }
+  const today = new Date().toISOString().slice(0, 10);
+  let r;
+  try {
+    r = await curateBatch({ factsPath: opts.facts, judgmentsPath: opts.judgments, apply: opts.apply, catalogRoot: opts.catalogRoot, today });
+  } catch (e) {
+    const err = { ok: false, verb: 'refresh', mode: 'cve-batch', error: String((e && e.message) || e) };
+    process.stdout.write(JSON.stringify(err) + '\n');
+    process.exitCode = 2;
+    return;
+  }
+  process.stdout.write(JSON.stringify({ ok: r.ok, count: Object.keys(r.entries).length,
+    orphans: r.orphans, errors: r.errors, written: r.written }, null, 2) + '\n');
+  if (!r.ok) process.exitCode = 1;
+}
+
+module.exports = { insertEntries, recomputeAiMeta, addLessons, renderTest, curateBatch, cli };

package/lib/cve-curation.js

@@ -738,6 +738,10 @@ function writeJsonAtomic(p, obj) {
  * `refresh --curate <id> --answers <path> [--apply]`.
  */
 async function cli(argv) {
+  // Batch curation (facts file + judgments file → gate-passing catalog
+  // entries) is a distinct workflow from the single-CVE questionnaire
+  // below; delegate before the --curate opts loop touches argv.
+  if (argv.includes("--curate-batch")) return require("./cve-batch.js").cli(argv);
   const opts = { advisory: null, json: false, catalogPath: null, answersPath: null, apply: false };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];

package/lib/cve-enrich.js

@@ -0,0 +1,172 @@
+'use strict';
+
+const scoring = require('./scoring.js');
+
+const AV = { N: 'network', A: 'adjacent', L: 'local', P: 'physical' };
+const AC = { L: 'low', H: 'high' };
+
+function parseCvssVector(vectorString) {
+  if (typeof vectorString !== 'string') return { complexity: null, attack_vector: null };
+  const av = /\bAV:([NALP])\b/.exec(vectorString);
+  const ac = /\bAC:([LH])\b/.exec(vectorString);
+  return {
+    complexity: ac ? AC[ac[1]] : null,
+    attack_vector: av ? AV[av[1]] : null,
+  };
+}
+
+// Extract REAL vendor advisories from a reference list — only references
+// explicitly tagged "Vendor Advisory" by NVD. Returns [] when none are
+// present. NVD itself is an aggregator, not a vendor, so it is deliberately
+// NOT synthesized in here — its detail URL lives in `verification_sources`
+// (see deriveMechanicalFields). Fabricating an NVD "vendor advisory" for
+// every KEV entry would silently satisfy the "cisa_kev:true but
+// vendor_advisories empty" curation-gap detector in lib/gap-detectors.js,
+// hiding entries that genuinely lack a vendor advisory. An empty array is the
+// honest signal that a curator still needs to attach the real advisory.
+// `cveId` is retained in the signature for callers/back-compat; it is not used
+// now that no synthetic NVD entry is appended.
+function extractVendorAdvisories(references, kevVendor, cveId) {
+  void cveId;
+  const out = [];
+  for (const r of references || []) {
+    if (Array.isArray(r.tags) && r.tags.includes('Vendor Advisory')) {
+      out.push({ vendor: kevVendor || 'Vendor', advisory_id: r.url.split('/').pop() || r.url,
+        url: r.url, severity: 'unknown', published_date: null });
+    }
+  }
+  return out;
+}
+
+function _num(x) { const n = Number(x); return Number.isFinite(n) ? n : null; }
+
+function deriveMechanicalFields(facts, today) {
+  const f = facts || {};
+  const kev = f.kev || {};
+  const cvss = f.cvss || null;
+  const parsed = parseCvssVector(cvss && cvss.vector);
+  const cweRefs = (f.cwe_nvd || []).filter((c) => /^CWE-\d+$/.test(c));
+  const vendorAdv = extractVendorAdvisories(f.references, kev.vendor, f.id);
+  const verification = [...new Set([
+    `https://nvd.nist.gov/vuln/detail/${f.id}`,
+    'https://www.cisa.gov/known-exploited-vulnerabilities-catalog',
+    ...vendorAdv.map((a) => a.url),
+  ])];
+  const epss = f.epss || null;
+  return {
+    name: String(kev.name || f.id),
+    cvss_score: cvss ? _num(cvss.base_score) : null,
+    cvss_vector: cvss ? cvss.vector : null,
+    cwe_refs: cweRefs,
+    cisa_kev: !!f.kev,
+    cisa_kev_date: kev.dateAdded || null,
+    cisa_kev_due_date: kev.dueDate || null,
+    known_ransomware_use: String(kev.ransomware || '').toLowerCase() === 'known',
+    active_exploitation: f.kev ? 'confirmed' : 'none',
+    complexity: parsed.complexity,
+    vector: String(f.nvd_desc || kev.shortDescription || '').trim() || `${f.id} — see vendor advisory`,
+    epss_score: epss ? _num(epss.score) : null,
+    epss_percentile: epss ? _num(epss.percentile) : null,
+    epss_date: epss ? (epss.date || null) : null,
+    epss_source: epss ? `https://api.first.org/data/v1/epss?cve=${f.id}` : null,
+    vendor_advisories: vendorAdv,
+    verification_sources: verification,
+    source_verified: today,
+    last_updated: today,
+    _kev_short_description: kev.shortDescription || null,
+  };
+}
+
+const JUDGMENT_KEYS = ['type','blast_radius','poc_available','poc_description','iocs','ai_discovered',
+  'ai_discovery_notes','ai_discovery_source','discovery_attribution_note','ai_assisted_weaponization',
+  'active_exploitation_notes','attack_refs','atlas_refs','framework_control_gaps','patch_available',
+  'patch_required_reboot','live_patch_available','live_patch_tools','live_patch_notes','affected',
+  'affected_versions','vendor_update_paths',
+  // A curator/research agent can supply the real vendor advisories when NVD's
+  // refs carry no "Vendor Advisory"-tagged link; this overlays (replaces) the
+  // auto-derived array via the JUDGMENT_KEYS spread loop below.
+  'vendor_advisories'];
+
+function assembleEntry(facts, judgment, today) {
+  const errors = [];
+  const j = judgment || {};
+  const entry = deriveMechanicalFields(facts, today);
+  for (const k of JUDGMENT_KEYS) if (k in j && j[k] !== undefined) entry[k] = j[k];
+  if (typeof j.vector === 'string' && j.vector.trim()) entry.vector = j.vector.trim();
+
+  // cwe_refs: mechanical (from NVD) wins when present; fall back to a curator-
+  // supplied list (e.g. when NVD only returns NVD-CWE-noinfo). Kept out of the
+  // blanket JUDGMENT_KEYS loop so facts take precedence over judgment here.
+  if ((!entry.cwe_refs || entry.cwe_refs.length === 0) && Array.isArray(j.cwe_refs))
+    entry.cwe_refs = j.cwe_refs;
+
+  // Defaults + intake markers.
+  if (entry.ai_discovery_source === undefined)
+    entry.ai_discovery_source = entry.ai_discovered ? 'unknown' : 'vendor_research';
+  if (entry.live_patch_tools === undefined) entry.live_patch_tools = [];
+  entry._auto_imported = false;
+  entry._intake_method = 'batch-curated';
+
+  // RWEP via canonical scoring — Σ factors must equal score AND agree with scoreCustom.
+  const inputs = {
+    cisa_kev: entry.cisa_kev === true,
+    poc_available: entry.poc_available === true,
+    ai_discovered: entry.ai_discovered === true,
+    ai_assisted_weaponization: entry.ai_assisted_weaponization === true,
+    active_exploitation: entry.active_exploitation,
+    blast_radius: entry.blast_radius,
+    patch_available: entry.patch_available === true,
+    live_patch_available: entry.live_patch_available === true,
+    reboot_required: entry.patch_required_reboot === true,
+  };
+  const factors = scoring.postWeightFactors(inputs);
+  const sum = Object.values(factors).reduce((a, b) => a + b, 0);
+  entry.rwep_factors = factors;
+  entry.rwep_score = sum;
+  if (sum < 0 || sum > 100)
+    errors.push(`${facts.id}: rwep sum ${sum} outside [0,100] — lower blast_radius so Σfactors stays in range (clamp would break the Σ===score invariant).`);
+
+  // Hard Rule #14: poc_available true → iocs populated.
+  const iocsOk = entry.iocs && typeof entry.iocs === 'object' && !Array.isArray(entry.iocs) && Object.keys(entry.iocs).length > 0;
+  if (entry.poc_available === true && !iocsOk)
+    errors.push(`${facts.id}: poc_available=true requires a populated iocs block (Hard Rule #14).`);
+
+  // Required judgment fields — populated, not merely present. A key that is
+  // present-but-empty (empty string / empty array / empty object / non-boolean)
+  // fails the same §7 gate as a missing key, so an under-specified judgment
+  // cannot slip an incomplete entry past the writer.
+  if (typeof j.type !== 'string' || j.type.trim() === '')
+    errors.push(`${facts.id}: required judgment field "type" missing or not a non-empty string.`);
+  if (typeof j.blast_radius !== 'number' || !Number.isFinite(j.blast_radius))
+    errors.push(`${facts.id}: required judgment field "blast_radius" missing or not a finite number.`);
+  if (typeof j.poc_available !== 'boolean')
+    errors.push(`${facts.id}: required judgment field "poc_available" missing (must be a boolean).`);
+  if (!Array.isArray(j.attack_refs) || j.attack_refs.length === 0)
+    errors.push(`${facts.id}: required judgment field "attack_refs" missing or empty (every KEV CVE maps to ≥1 ATT&CK TTP).`);
+  if (!j.framework_control_gaps || typeof j.framework_control_gaps !== 'object' || Array.isArray(j.framework_control_gaps) || Object.keys(j.framework_control_gaps).length === 0)
+    errors.push(`${facts.id}: required judgment field "framework_control_gaps" missing or empty.`);
+  if (typeof j.discovery_attribution_note !== 'string' || j.discovery_attribution_note.trim() === '')
+    errors.push(`${facts.id}: required judgment field "discovery_attribution_note" missing or not a non-empty string.`);
+
+  // blast_radius range [0,30]. Surfaces a unit typo (e.g. 250) as an error
+  // rather than letting postWeightFactors silently clamp it inside rwep_factors.
+  if (typeof entry.blast_radius === 'number' && Number.isFinite(entry.blast_radius) &&
+      (entry.blast_radius < 0 || entry.blast_radius > 30))
+    errors.push(`${facts.id}: blast_radius ${entry.blast_radius} outside [0,30].`);
+
+  entry.rwep_notes = `RWEP ${sum}. ` + Object.entries(factors).filter(([, v]) => v !== 0)
+    .map(([k, v]) => `${k} ${v > 0 ? '+' : ''}${v}`).join(', ') + '. Σ factors === rwep_score.';
+  return { entry, errors };
+}
+
+function findOrphans(entry, catalogs) {
+  const out = [];
+  const chk = (ids, set, label) => { for (const id of ids || []) if (!set.has(id)) out.push(`${entry.id || entry.name}: ${label} "${id}" not in catalog — add it before --apply.`); };
+  chk(entry.cwe_refs, catalogs.cwe, 'cwe_refs');
+  chk(entry.attack_refs, catalogs.attack, 'attack_refs');
+  chk(entry.atlas_refs, catalogs.atlas, 'atlas_refs');
+  chk(Object.keys(entry.framework_control_gaps || {}), catalogs.frameworkGaps, 'framework_control_gaps');
+  return out;
+}
+
+module.exports = { parseCvssVector, extractVendorAdvisories, deriveMechanicalFields, assembleEntry, findOrphans };