@blamejs/exceptd-skills 0.11.15 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,79 @@
 # Changelog
 
+## 0.12.0 — 2026-05-13
+
+**Minor: catalog freshness from minutes-old disclosures, not days.**
+
+Today's refresh sources (KEV / NVD / EPSS / IETF / MITRE) don't see a fresh-disclosure npm worm. KEV listing takes days; NVD takes ~10 days. The CVE-2026-45321 TanStack worm was caught publicly within 20 minutes — but the only feed that fired in that window was the GitHub Advisory Database. v0.12.0 adds GHSA as a refresh source, plus operator-driven single-advisory seeding, plus an editorial-enrichment helper.
+
+### GHSA as a refresh source
+
+`exceptd refresh` now pulls from GitHub Advisory Database (covers npm, PyPI, RubyGems, Maven, NuGet, Go, Composer, Swift, Erlang, Pub, Rust). Unauthenticated 60 req/hr; authenticated 5000 req/hr via `GITHUB_TOKEN` env var. New CVE IDs land as **drafts** flagged `_auto_imported: true` + `_draft: true`. The strict catalog validator treats drafts as warnings, not errors — so the nightly auto-PR pipeline can ship them without blocking on editorial review. Framework gaps + IoCs + ATLAS/ATT&CK refs are explicit nulls awaiting human or AI-assisted enrichment.
+
+(Note: npm Inc. does not publish a standalone JSON advisory feed; npm advisories are surfaced via GHSA. Adding `npm-advisories` as a separate source would duplicate GHSA data with no fidelity gain.)
+
+### `exceptd refresh --advisory <id>`
+
+Operator-driven single-advisory seeding. Accepts CVE-* or GHSA-* identifiers. Fetches the advisory from GHSA, normalizes to the catalog draft shape, prints (default) or writes (`--apply`). Always exits **3** ("draft prepared, editorial review pending") so CI pipelines surface the next step.
+
+```
+exceptd refresh --advisory CVE-2026-45321               # dry-run, prints draft
+exceptd refresh --advisory CVE-2026-45321 --apply       # writes draft into data/cve-catalog.json
+exceptd refresh --advisory GHSA-xxxx-xxxx-xxxx --json   # JSON output
+```
+
+Refuses to overwrite a human-curated entry. Honors `EXCEPTD_GHSA_FIXTURE` env var for offline tests.
+
+### `exceptd refresh --curate <CVE-ID>`
+
+Editorial-enrichment helper. Reads the draft entry from `data/cve-catalog.json`, cross-references against `data/atlas-ttps.json` + `data/attack-ttps.json` + `data/cwe-catalog.json` + `data/framework-control-gaps.json`, and emits structured **editorial questions** — one per null field — each with ranked candidates and a specific ASK for the reviewer.
+
+```
+{
+  "editorial_questions": [
+    {
+      "field": "atlas_refs",
+      "current_value": [],
+      "candidates": [{"id": "AML.T0010", "score": 68, "reason": "..."}],
+      "ask": "Which MITRE ATLAS techniques are present in the attack chain?"
+    },
+    {
+      "field": "framework_control_gaps",
+      "ask": "Which framework controls CLAIM to cover this CVE's category, and where do they fall short? Per AGENTS.md Hard Rule #6, every framework finding must include a test that distinguishes paper compliance from actual security."
+    },
+    ...
+  ]
+}
+```
+
+Pure heuristic — deterministic keyword-overlap scoring against existing catalogs. The reviewer (human or AI assistant) makes the final call on each candidate. Always exits **3** because editorial review is, by definition, pending.
+
+(The natural-language form `exceptd run cve-curation --advisory <id>` — wrapping this helper in a full seven-phase playbook with GRC closure — is scoped for v0.13. The helper itself ships in v0.12 so operators can use it now.)
+
+### Catalog schema
+
+- `data/cve-catalog.json` entries may now carry `_auto_imported`, `_draft`, `_draft_reason`, `_source_ghsa_id`, `_source_published_at` fields.
+- `lib/validate-cve-catalog.js` recognizes drafts: prints them as `DRAFT` lines (not `FAIL`), does not exit-fail. The summary line includes a `<N> draft(s) (auto-imported)` count.
+- `lib/schemas/cve-catalog.schema.json` is unchanged; the draft fields are absorbed by `additionalProperties: true`.
+
+### Tests
+
+7 new regression cases. 366 total. Coverage: ghsa fixture fetch, advisory normalization (draft shape + cisa_kev_pending heuristic for critical), `refresh --advisory` dry-run + apply paths, `refresh --curate` editorial-question generation, refusal-on-human-curated, validator draft-tolerance.
+
+### Operator workflow
+
+The end-to-end flow for a fresh-disclosure CVE the nightly job hasn't caught yet:
+
+```
+$ exceptd refresh --advisory CVE-2026-XXXXX --apply       # seeds draft from GHSA
+$ exceptd refresh --curate CVE-2026-XXXXX                  # surfaces editorial questions + candidates
+# review the questions, fill the catalog entry, add a zeroday-lessons.json entry,
+# remove _auto_imported and _draft flags, then:
+$ npm run predeploy                                        # strict gate now passes
+```
+
+The nightly auto-PR mechanism handles the GHSA pull automatically; this surface is for "I want this CVE today, not tomorrow."
+
 ## 0.11.15 — 2026-05-13
 
 **Patch: CVE-2026-45321 (Mini Shai-Hulud TanStack npm worm) — catalog + playbook + IoC sweep.**

package/bin/exceptd.js

@@ -72,6 +72,7 @@ const COMMANDS = {
   prefetch:        () => path.join(PKG_ROOT, "lib", "prefetch.js"),
   refresh:         () => path.join(PKG_ROOT, "lib", "refresh-external.js"),
   "refresh-network": () => path.join(PKG_ROOT, "lib", "refresh-network.js"),
+  "refresh-curate":  () => path.join(PKG_ROOT, "lib", "cve-curation.js"),
   "build-indexes": () => path.join(PKG_ROOT, "scripts", "build-indexes.js"),
   verify:          () => path.join(PKG_ROOT, "lib", "verify.js"),
   scan:            () => path.join(PKG_ROOT, "orchestrator", "index.js"),
@@ -252,9 +253,19 @@ v0.11.0 canonical surface
                                                     catalog snapshot from npm registry,
                                                     verify against local keys/public.pem,
                                                     swap data/ in place (no CLI/lib reload)
+                             --advisory <id>        (v0.12.0) seed a catalog entry from a
+                                                    CVE-* or GHSA-* ID via GitHub Advisory
+                                                    Database. Writes draft with
+                                                    _auto_imported:true. Use --apply to
+                                                    write to disk.
+                             --curate <CVE-ID>      (v0.12.0) emit editorial questions +
+                                                    ranked candidates (ATLAS/ATT&CK/CWE/
+                                                    framework gaps) for a draft entry.
                              --prefetch             populate offline cache
                              --from-cache           consume offline cache
                              --indexes-only         rebuild indexes only
+                             Sources: kev|epss|nvd|rfc|pins|ghsa (v0.12.0).
+                                                    ghsa drafts pass validator as warnings.
 
 v0.10.x compatibility (will be removed in v0.12)
 ────────────────────────────────────────────────
@@ -414,6 +425,12 @@ function main() {
     // data slice without requiring a full package upgrade.
     effectiveCmd = "refresh-network";
     effectiveRest = rest.filter(a => a !== "--network");
+  } else if (cmd === "refresh" && rest.includes("--curate")) {
+    // v0.12.0: --curate <CVE-ID> emits editorial questions + ranked
+    // candidates (atlas/attack/cwe/framework) for a draft catalog entry.
+    // Operator or AI assistant fills the null editorial fields.
+    effectiveCmd = "refresh-curate";
+    effectiveRest = rest;
   }
 
   const resolver = COMMANDS[effectiveCmd];

package/data/_indexes/_meta.json

@@ -1,10 +1,10 @@
 {
   "schema_version": "1.1.0",
-  "generated_at": "2026-05-13T02:21:22.318Z",
+  "generated_at": "2026-05-13T02:34:42.448Z",
   "generator": "scripts/build-indexes.js",
   "source_count": 49,
   "source_hashes": {
-    "manifest.json": "8231ac5cd18201c56fd29b5925a86f279708e32eb8fcc8fff35823a7fec0ee3a",
+    "manifest.json": "31cfbef4aa2a73ae93de1837209c958f5318fadbfc4481f06459617048fec44c",
     "data/atlas-ttps.json": "1500b5830dab070c4252496964a8c0948e1052a656e2c7c6e1efaf0350645e13",
     "data/cve-catalog.json": "e9a3a4ce988caa051e50a467f1cd9c0dcbf9e8f6f3e9522610baf196217b7bdc",
     "data/cwe-catalog.json": "c3367d469b4b3d31e4c56397dd7a8305a0be338ecd85afa27804c0c9ce12157b",

package/keys/public.pem

@@ -1,3 +1,3 @@
 -----BEGIN PUBLIC KEY-----
-MCowBQYDK2VwAyEAc7dTqpdkqSacW3fFwlplSF3i9c845VcTA118wKCxuvE=
+MCowBQYDK2VwAyEA8r4wi/onMuK7+R3naEBpBUU8LDfUlt0D67FKS7IpRp4=
 -----END PUBLIC KEY-----

package/lib/cve-curation.js

@@ -0,0 +1,274 @@
+"use strict";
+
+/**
+ * lib/cve-curation.js
+ *
+ * Editorial-enrichment helper for auto-imported CVE catalog drafts. Given
+ * a CVE ID that exists in data/cve-catalog.json as a draft (flagged
+ * `_auto_imported: true`), this module cross-references the draft against
+ * the project's existing catalogs and produces STRUCTURED EDITORIAL
+ * QUESTIONS — candidate framework gaps, ATLAS techniques, ATT&CK techniques,
+ * CWE refs — that a human reviewer or AI assistant uses to fill in the
+ * null editorial fields.
+ *
+ * Not "AI-assisted" in the LLM sense. The cross-reference logic is
+ * deterministic pattern-matching against catalogs already in the install.
+ * The output is a checklist of "fields to answer, with candidates ranked
+ * by relevance" — the reviewer makes the final call on each.
+ *
+ * Output shape (one JSON object on stdout):
+ *   {
+ *     ok: true,
+ *     verb: "refresh",
+ *     mode: "cve-curation",
+ *     cve_id, draft_entry,
+ *     editorial_questions: [
+ *       { field, current_value, candidates: [{id, score, reason}], ask }
+ *     ],
+ *     next_steps: [...]
+ *   }
+ *
+ * Exits non-zero (3) so CI pipelines see "editorial review pending" even
+ * on a successful curation run.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const ROOT = path.resolve(__dirname, "..");
+
+function loadJson(rel) {
+  try { return JSON.parse(fs.readFileSync(path.join(ROOT, rel), "utf8")); }
+  catch { return null; }
+}
+
+/**
+ * Score a candidate by counting keyword overlap with the draft entry.
+ * Returns 0..100. Pure heuristic — reviewer makes the final call.
+ */
+function keywordOverlapScore(draftText, candidateText) {
+  if (!draftText || !candidateText) return 0;
+  const draftWords = new Set(
+    String(draftText).toLowerCase().split(/[^a-z0-9_]+/).filter(w => w.length > 3)
+  );
+  const candWords = new Set(
+    String(candidateText).toLowerCase().split(/[^a-z0-9_]+/).filter(w => w.length > 3)
+  );
+  let overlap = 0;
+  for (const w of candWords) if (draftWords.has(w)) overlap++;
+  const denom = Math.max(candWords.size, 1);
+  return Math.round((overlap / denom) * 100);
+}
+
+function pickCandidates(draftDigest, catalog, idField, descriptionField) {
+  if (!catalog || typeof catalog !== "object") return [];
+  const candidates = [];
+  for (const [key, entry] of Object.entries(catalog)) {
+    if (key.startsWith("_")) continue;
+    const id = entry?.[idField] || key;
+    const desc = entry?.[descriptionField] || entry?.name || entry?.description || "";
+    const score = keywordOverlapScore(draftDigest, desc + " " + id);
+    if (score > 0) {
+      candidates.push({ id, score, reason: `keyword overlap with: ${(desc || id).slice(0, 120)}` });
+    }
+  }
+  candidates.sort((a, b) => b.score - a.score);
+  return candidates.slice(0, 5);
+}
+
+/**
+ * Build the curation report for a single CVE ID.
+ */
+function curate(cveId, { catalogPath, opts = {} } = {}) {
+  const catalog = loadJson(catalogPath || "data/cve-catalog.json");
+  if (!catalog || !catalog[cveId]) {
+    return {
+      ok: false,
+      verb: "refresh",
+      mode: "cve-curation",
+      error: `CVE ${cveId} not in data/cve-catalog.json. Seed it first via \`exceptd refresh --advisory ${cveId} --apply\`.`,
+    };
+  }
+  const draft = catalog[cveId];
+
+  // Only curate drafts. Editing a human-curated entry is intentional and
+  // happens via direct file edit — refusing here prevents accidental
+  // suggestion-storms on entries that have already been reviewed.
+  if (!draft._auto_imported && !draft._draft) {
+    return {
+      ok: false,
+      verb: "refresh",
+      mode: "cve-curation",
+      error: `${cveId} is a human-curated entry (no _auto_imported flag). Curation only applies to drafts. Edit directly if changes are intended.`,
+      existing_last_updated: draft.last_updated,
+    };
+  }
+
+  // Digest of the draft — feed into keyword-overlap scoring.
+  const draftDigest = [
+    draft.name || "",
+    draft.affected || "",
+    (draft.affected_versions || []).join(" "),
+    draft.vector || "",
+    draft.type || "",
+  ].filter(Boolean).join(" ");
+
+  // Pull candidate catalogs. Each is optional — missing catalogs are skipped
+  // gracefully.
+  const atlas = loadJson("data/atlas-ttps.json");
+  const attack = loadJson("data/attack-ttps.json");
+  const cwe = loadJson("data/cwe-catalog.json");
+  const frameworkGaps = loadJson("data/framework-control-gaps.json");
+
+  const atlasCandidates = pickCandidates(draftDigest, atlas, "ttp_id", "description");
+  const attackCandidates = pickCandidates(draftDigest, attack, "ttp_id", "description");
+  const cweCandidates = pickCandidates(draftDigest, cwe, "cwe_id", "description");
+  const frameworkCandidates = pickCandidates(draftDigest, frameworkGaps, "control_id", "description");
+
+  // Build the editorial-questions list. Each entry names the catalog field,
+  // its current value (likely null on a draft), ranked candidates, and a
+  // specific ASK to surface what the reviewer needs to decide.
+  const questions = [];
+
+  if (!draft.atlas_refs || draft.atlas_refs.length === 0) {
+    questions.push({
+      field: "atlas_refs",
+      current_value: draft.atlas_refs || [],
+      candidates: atlasCandidates,
+      ask: "Which MITRE ATLAS techniques are present in the attack chain? (Adversarial ML technique mapping — relevant if any model, training pipeline, or AI agent is involved.)",
+    });
+  }
+
+  if (!draft.attack_refs || draft.attack_refs.length === 0) {
+    questions.push({
+      field: "attack_refs",
+      current_value: draft.attack_refs || [],
+      candidates: attackCandidates,
+      ask: "Which MITRE ATT&CK techniques are present in the attack chain? (Required for SOC integration and detection-engineering downstream.)",
+    });
+  }
+
+  if (!draft.framework_control_gaps) {
+    questions.push({
+      field: "framework_control_gaps",
+      current_value: null,
+      candidates: frameworkCandidates,
+      ask: "Which framework controls CLAIM to cover this CVE's category, and where do they fall short? Per AGENTS.md Hard Rule #6, every framework finding must include a test that distinguishes paper compliance from actual security. Cover NIST-800-53 + EU (NIS2/DORA/EU AI Act) + UK (CAF) + AU (ISM) + ISO 27001:2022 at minimum.",
+    });
+  }
+
+  if (!draft.iocs) {
+    questions.push({
+      field: "iocs",
+      current_value: null,
+      candidates: [],
+      ask: "What artifacts indicate compromise on a host running the affected version? Group by (a) payload_artifacts — file/process names the payload writes or runs, (b) persistence_artifacts — hooks, config entries, OS-level units that re-arm the payload, (c) behavioral — log / cache / network patterns, (d) destructive — any tripwire that destroys evidence on remediation. The sbom playbook's detect indicators feed off these.",
+    });
+  }
+
+  if (draft.poc_available === null) {
+    questions.push({
+      field: "poc_available",
+      current_value: null,
+      candidates: [],
+      ask: "Is a public PoC or in-the-wild exploitation evidence available? If yes, set poc_available: true + add poc_description summarizing capability (deterministic vs probabilistic, single-stage vs multi-stage, byte-size if known).",
+    });
+  }
+
+  if (draft.ai_discovered === null || draft.ai_assisted_weaponization === null) {
+    questions.push({
+      field: "ai_discovered + ai_assisted_weaponization",
+      current_value: { ai_discovered: draft.ai_discovered, ai_assisted_weaponization: draft.ai_assisted_weaponization },
+      candidates: [],
+      ask: "Was this vulnerability AI-discovered (per AGENTS.md Hard Rule #7, ~41% of 2025 zero-days were)? AI-assisted weaponization? Set both fields explicitly — null is not acceptable on a published entry.",
+    });
+  }
+
+  if (!draft.rwep_factors || draft.rwep_score === null) {
+    questions.push({
+      field: "rwep_score + rwep_factors",
+      current_value: { rwep_score: draft.rwep_score, rwep_factors: draft.rwep_factors },
+      candidates: [],
+      ask: "Compute RWEP using lib/scoring.js weights: cisa_kev(+25) + poc_available(+20) + ai_factor(+15) + active_exploitation(confirmed=+20 / suspected=+10) + blast_radius(0..30) + patch_available(-15) + live_patch_available(-10) + reboot_required(+5). The score field is the sum; the factors field shows the contributions.",
+    });
+  }
+
+  if (!draft.vector) {
+    questions.push({
+      field: "vector",
+      current_value: null,
+      candidates: [],
+      ask: "One-paragraph attack vector explanation. Distinguish (a) reachability (how attacker gets to the vulnerable surface), (b) primitive (what the bug actually gives them), (c) escalation (what they do with the primitive). For chained-primitives attacks (e.g. CVE-2026-45321 TanStack worm), enumerate each primitive separately.",
+    });
+  }
+
+  return {
+    ok: true,
+    verb: "refresh",
+    mode: "cve-curation",
+    cve_id: cveId,
+    draft_summary: {
+      name: draft.name,
+      type: draft.type,
+      cvss_score: draft.cvss_score,
+      severity: draft.cvss_score >= 9 ? "critical" : draft.cvss_score >= 7 ? "high" : draft.cvss_score >= 4 ? "medium" : "low",
+      affected: draft.affected,
+      published_at: draft._source_published_at || null,
+      auto_imported_from: draft._source_ghsa_id ? `GHSA: ${draft._source_ghsa_id}` : "unknown",
+    },
+    editorial_questions: questions,
+    questions_open: questions.length,
+    next_steps: [
+      `Answer each editorial question above. The catalog gate (lib/validate-cve-catalog.js) currently treats this entry as a DRAFT (warning, not error) — answers convert it to a full entry.`,
+      `Add a matching entry to data/zeroday-lessons.json (rule #6: zero-day learning loop must be live).`,
+      `Update last_threat_review and threat_currency_score on any playbook whose cve_refs includes ${cveId}.`,
+      `Remove the _auto_imported and _draft flags from the catalog entry once editorial review is complete.`,
+      `Run \`npm run predeploy\` — the strict gate should now pass without DRAFT warnings on this entry.`,
+    ],
+  };
+}
+
+/**
+ * CLI entry — wired from bin/exceptd.js via `refresh --curate <id>`.
+ */
+async function cli(argv) {
+  const opts = { advisory: null, json: false, catalogPath: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--json") opts.json = true;
+    else if (a === "--catalog") opts.catalogPath = argv[++i];
+    else if (a.startsWith("--catalog=")) opts.catalogPath = a.slice("--catalog=".length);
+    else if (a === "--curate") opts.advisory = argv[++i];
+    else if (a.startsWith("--curate=")) opts.advisory = a.slice("--curate=".length);
+    else if (!a.startsWith("--") && !opts.advisory) opts.advisory = a;
+  }
+  if (!opts.advisory) {
+    const err = { ok: false, verb: "refresh", mode: "cve-curation", error: "missing --curate <CVE-ID>" };
+    if (opts.json) process.stdout.write(JSON.stringify(err) + "\n");
+    else process.stderr.write(`[refresh --curate] ${err.error}\n`);
+    process.exitCode = 2;
+    return;
+  }
+  const result = curate(opts.advisory, { catalogPath: opts.catalogPath, opts });
+  if (opts.json || !result.ok) {
+    process.stdout.write(JSON.stringify(result) + "\n");
+  } else {
+    process.stdout.write(`[refresh --curate] ${result.cve_id} — ${result.questions_open} editorial question(s) open\n`);
+    for (const q of result.editorial_questions) {
+      process.stdout.write(`\n  ${q.field}:\n`);
+      process.stdout.write(`    ask: ${q.ask}\n`);
+      if (q.candidates && q.candidates.length > 0) {
+        process.stdout.write(`    top candidates: ${q.candidates.slice(0, 3).map(c => c.id).join(", ")}\n`);
+      }
+    }
+    process.stdout.write(`\n  Run with --json for the full structured output.\n`);
+  }
+  // Always non-zero on a successful curation — "editorial review pending."
+  process.exitCode = result.ok ? 3 : 2;
+}
+
+if (require.main === module) {
+  cli(process.argv.slice(2));
+}
+
+module.exports = { curate, keywordOverlapScore };

package/lib/refresh-external.js

@@ -50,15 +50,20 @@ function parseArgs(argv) {
     fromFixture: null,   // path to fixture dir
     fromCache: null,     // path to .cache/upstream dir (or default if --from-cache passed bare)
     swarm: false,        // fan-out sources across worker threads
+    advisory: null,      // v0.12.0: single-advisory seed (CVE-* or GHSA-*)
     help: false,
     quiet: false,
+    json: false,
   };
   for (let i = 2; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--apply") out.apply = true;
     else if (a === "--quiet") out.quiet = true;
     else if (a === "--swarm") out.swarm = true;
+    else if (a === "--json") out.json = true;
     else if (a === "--help" || a === "-h") out.help = true;
+    else if (a === "--advisory") { out.advisory = argv[++i]; }
+    else if (a.startsWith("--advisory=")) { out.advisory = a.slice("--advisory=".length); }
     else if (a === "--from-cache") {
       // accept either --from-cache <path> or --from-cache (default path)
       const next = argv[i + 1];
@@ -101,6 +106,26 @@ Modes:
   --indexes-only     rebuild data/_indexes/ only; no network. Equivalent to
                      \`exceptd refresh --indexes-only\`.
   --swarm            fan out sources across worker threads. Best with --from-cache.
+  --advisory <id>    (v0.12.0) seed a single catalog entry from a CVE or GHSA ID.
+                     Fetches from GitHub Advisory Database (covers npm + PyPI +
+                     Maven + Go + ...) and writes a DRAFT to data/cve-catalog.json
+                     marked with _auto_imported: true. Editorial fields
+                     (framework_control_gaps, iocs, atlas_refs, attack_refs)
+                     remain null pending review via:
+                       exceptd run cve-curation --advisory <id>
+                     Examples:
+                       exceptd refresh --advisory CVE-2026-45321
+                       exceptd refresh --advisory GHSA-xxxx-xxxx-xxxx --apply
+
+Sources (default = all):
+  kev   CISA Known Exploited Vulnerabilities
+  epss  FIRST EPSS exploit-prediction scores
+  nvd   NIST NVD per-CVE feed
+  rfc   IETF Datatracker per-RFC
+  pins  Upstream version-pin drift (MITRE ATLAS/ATT&CK/D3FEND/CWE) — report only
+  ghsa  (v0.12.0) GitHub Advisory Database — npm/PyPI/Maven/etc. Lands new CVE
+        IDs as DRAFTS (_auto_imported: true); catalog validator treats drafts
+        as warnings, not errors. Editorial review still required.
 
 Air-gap workflow:
   1. On a connected host:   \`exceptd refresh --prefetch\`
@@ -439,12 +464,58 @@ const PINS_SOURCE = {
   },
 };
 
+/**
+ * v0.12.0: GHSA (GitHub Advisory Database) source. Covers npm, PyPI,
+ * RubyGems, Maven, NuGet, Go, Composer, Swift, Erlang, Pub, Rust — all
+ * in one feed, updated within hours of disclosure. Much faster than KEV
+ * (variable, often days) or NVD (~10 days).
+ *
+ * Apply path: new CVE IDs from GHSA land in data/cve-catalog.json as
+ * DRAFTS (`_auto_imported: true` + `_draft: true`). The strict catalog
+ * validator treats drafts as warnings, not errors, so the nightly
+ * auto-PR pipeline can ship them without blocking on editorial review.
+ * Framework gaps + IoCs + ATLAS/ATT&CK refs require human or AI-assisted
+ * synthesis via `exceptd run cve-curation --advisory <id>`.
+ */
+const GHSA_SOURCE = {
+  name: "ghsa",
+  description: "GitHub Advisory Database — multi-ecosystem disclosure feed (npm, PyPI, Maven, Go, etc.)",
+  applies_to: "data/cve-catalog.json",
+  async fetchDiff(ctx) {
+    if (ctx.fixtures?.ghsa) return synthesizeFromFixture(ctx, "ghsa");
+    if (ctx.cacheDir) {
+      // Cache parity: ghsa cache layout is .cache/upstream/ghsa/<published-date>.json
+      // For v0.12.0 we fall through to live fetch — caching is a v0.13 follow-up.
+    }
+    const ghsa = require("./source-ghsa");
+    return ghsa.buildDiff(ctx);
+  },
+  async applyDiff(ctx, diffs) {
+    const ghsa = require("./source-ghsa");
+    let updated = 0;
+    const errors = [];
+    for (const d of diffs) {
+      if (d.field !== "_new_entry") continue;
+      if (!d.after || !d.id) continue;
+      if (ctx.cveCatalog[d.id]) continue; // never overwrite existing entries
+      try {
+        ctx.cveCatalog[d.id] = d.after;
+        updated++;
+      } catch (e) {
+        errors.push(`${d.id}: ${e.message}`);
+      }
+    }
+    return { updated, errors };
+  },
+};
+
 const ALL_SOURCES = {
   kev: KEV_SOURCE,
   epss: EPSS_SOURCE,
   nvd: NVD_SOURCE,
   rfc: RFC_SOURCE,
   pins: PINS_SOURCE,
+  ghsa: GHSA_SOURCE,
 };
 
 // --- Cache-mode helpers ------------------------------------------------
@@ -653,7 +724,7 @@ function loadCtx(opts) {
     cacheDir: null,
   };
   if (opts.fromFixture) {
-    ctx.fixtures = { dir: path.resolve(opts.fromFixture), kev: true, epss: true, nvd: true, rfc: true, pins: true };
+    ctx.fixtures = { dir: path.resolve(opts.fromFixture), kev: true, epss: true, nvd: true, rfc: true, pins: true, ghsa: true };
   } else if (opts.fromCache) {
     const abs = path.resolve(opts.fromCache);
     ctx.cacheDir = abs;
@@ -694,6 +765,97 @@ function chosenSources(opts) {
   return out;
 }
 
+/**
+ * v0.12.0: single-advisory seed. Operator types
+ *   exceptd refresh --advisory CVE-2026-45321
+ * or
+ *   exceptd refresh --advisory GHSA-xxxx-xxxx-xxxx --apply
+ *
+ * Tool fetches from GHSA (covers npm, PyPI, etc.), normalizes to the
+ * exceptd catalog draft shape, and either prints the seed (default) or
+ * writes it to data/cve-catalog.json (--apply). Always exits non-zero
+ * when a draft is produced, signaling that editorial review is needed.
+ */
+async function seedSingleAdvisory(opts) {
+  const ghsa = require("./source-ghsa");
+  const id = opts.advisory;
+  const result = await ghsa.fetchAdvisoryById(id, {});
+  if (!result.ok) {
+    const err = { ok: false, verb: "refresh", error: `--advisory ${id}: ${result.error}`, source: result.source, hint: "Verify the ID format (CVE-YYYY-NNNN or GHSA-*) and network reachability. Set EXCEPTD_GHSA_FIXTURE for offline testing." };
+    if (opts.json) process.stdout.write(JSON.stringify(err) + "\n");
+    else process.stderr.write(`[refresh --advisory] ${err.error}\n  hint: ${err.hint}\n`);
+    process.exitCode = 2;
+    return;
+  }
+  const advisory = result.advisories[0];
+  if (!advisory) {
+    const err = { ok: false, verb: "refresh", error: `--advisory ${id}: no matching advisory found`, source: result.source };
+    if (opts.json) process.stdout.write(JSON.stringify(err) + "\n");
+    else process.stderr.write(`[refresh --advisory] ${err.error}\n`);
+    process.exitCode = 2;
+    return;
+  }
+  const normalized = ghsa.normalizeAdvisory(advisory);
+  if (!normalized) {
+    const err = { ok: false, verb: "refresh", error: `--advisory ${id}: advisory has no CVE ID (GHSA-only entries are not imported into the CVE catalog in v0.12)`, ghsa_id: advisory.ghsa_id || null };
+    if (opts.json) process.stdout.write(JSON.stringify(err) + "\n");
+    else process.stderr.write(`[refresh --advisory] ${err.error}\n`);
+    process.exitCode = 2;
+    return;
+  }
+  const cveId = Object.keys(normalized)[0];
+
+  if (!opts.apply) {
+    // Print the draft to stdout — operator pipes to jq / inspects /
+    // commits manually. Exit 3 = "draft produced, not applied."
+    const output = {
+      ok: true,
+      verb: "refresh",
+      mode: "advisory-seed-dry-run",
+      advisory_id: id,
+      cve_id: cveId,
+      draft: normalized[cveId],
+      hint: "Re-run with --apply to write this draft into data/cve-catalog.json. After apply, run `exceptd run cve-curation --advisory " + cveId + "` to surface editorial proposals (framework gaps, IoCs, ATLAS/ATT&CK refs).",
+    };
+    if (opts.json) process.stdout.write(JSON.stringify(output) + "\n");
+    else {
+      process.stdout.write(`[refresh --advisory] ${cveId} draft prepared (not applied).\n`);
+      process.stdout.write(`  Run with --apply to write into data/cve-catalog.json.\n`);
+      process.stdout.write(`  Then: exceptd run cve-curation --advisory ${cveId}\n`);
+    }
+    process.exitCode = 3;
+    return;
+  }
+
+  // Apply: write to cve-catalog.json with the _auto_imported flag.
+  const catalogPath = ABS("data/cve-catalog.json");
+  const catalog = JSON.parse(fs.readFileSync(catalogPath, "utf8"));
+  if (catalog[cveId] && !catalog[cveId]._auto_imported && !catalog[cveId]._draft) {
+    // Refuse to overwrite a human-curated entry.
+    const err = { ok: false, verb: "refresh", error: `${cveId} already present in catalog and is human-curated (not a draft). Refusing to overwrite. Edit manually if intentional.`, existing_last_updated: catalog[cveId].last_updated };
+    if (opts.json) process.stdout.write(JSON.stringify(err) + "\n");
+    else process.stderr.write(`[refresh --advisory] ${err.error}\n`);
+    process.exitCode = 4;
+    return;
+  }
+  catalog[cveId] = normalized[cveId];
+  fs.writeFileSync(catalogPath, JSON.stringify(catalog, null, 2) + "\n", "utf8");
+  const output = {
+    ok: true,
+    verb: "refresh",
+    mode: "advisory-seed-applied",
+    advisory_id: id,
+    cve_id: cveId,
+    written_to: "data/cve-catalog.json",
+    is_draft: true,
+    hint: "Draft written. Required next steps before this entry passes the strict catalog gate: (1) `exceptd run cve-curation --advisory " + cveId + "` to surface editorial proposals; (2) human review + fill in framework_control_gaps, atlas_refs, attack_refs, iocs; (3) add matching entry to data/zeroday-lessons.json; (4) remove `_auto_imported` and `_draft` flags.",
+  };
+  if (opts.json) process.stdout.write(JSON.stringify(output) + "\n");
+  else process.stdout.write(`[refresh --advisory] ${cveId} draft written to data/cve-catalog.json.\n  Next: exceptd run cve-curation --advisory ${cveId}\n`);
+  // Exit 3 even on successful write — "draft applied, editorial step pending."
+  process.exitCode = 3;
+}
+
 async function main() {
   const opts = parseArgs(process.argv);
   if (opts.help) {
@@ -701,6 +863,15 @@ async function main() {
     process.exit(0);
   }
 
+  // v0.12.0: `--advisory <id>` short-circuits the normal source loop and
+  // seeds a single CVE catalog entry from GHSA. Exits non-zero ("draft
+  // written, please review") so CI pipelines surface the needed editorial
+  // step. Operator must run `--apply` for the write to land; without it,
+  // the seed is printed to stdout for review.
+  if (opts.advisory) {
+    return seedSingleAdvisory(opts);
+  }
+
   const ctx = loadCtx(opts);
   const sources = chosenSources(opts);
   const log = (s) => opts.quiet || console.log(s);