@blamejs/exceptd-skills 0.19.32 → 0.19.34

package/lib/source-osv.js

@@ -1,70 +1,33 @@
 "use strict";
 
 /**
- * lib/source-osv.js
- *
- * OSV.dev fetcher. OSV aggregates OSSF Malicious Packages (MAL-*), Snyk
- * (SNYK-*), GitHub Advisory Database (GHSA-*), RustSec (RUSTSEC-*),
- * Mageia (MGASA-*), Go Vuln DB (GO-*), Ubuntu USN (USN-*), and several
- * other ecosystems into a single unauthenticated API.
- *
- * Endpoints:
- *   GET  https://api.osv.dev/v1/vulns/{id}
- *     Fetch by OSV id. CVE-* is NOT a primary key — CVE numbers live
- *     under `aliases` on records whose primary id is GHSA-*, MAL-*, etc.
- *   POST https://api.osv.dev/v1/query
- *     Body { "package": { "name": "...", "ecosystem": "..." }
- *          [,"version": "..."] }
- *     Lists vulns for a package (optionally filtered to a version).
- *
- * Why this matters: MAL-* (OSSF Malicious Packages) is the canonical
- * namespace for package-compromise events that don't have a CVE yet.
- * The elementary-data PyPI worm (MAL-2026-3083) is the catalog's
- * reference example of that class.
- *
- * Returns drafts — every imported entry carries `_auto_imported: true`
- * + `_draft: true` so the strict catalog validator treats them as
- * warnings, not errors. Editorial fields (framework_control_gaps,
- * atlas_refs, attack_refs, rwep_factors) remain null until a human or
- * AI assistant fills them in via the cve-curation skill / seven-phase
- * playbook flow.
- *
- * Honors EXCEPTD_OSV_FIXTURE env var for offline testing — value is a
- * path to a JSON file containing either a single OSV record or an
- * array of OSV records. Matches the GHSA fixture pattern.
- *
- * Zero npm deps. Node 24 stdlib only.
+ * OSV.dev fetcher. CVE-* is NOT a primary key there — CVE numbers live under
+ * `aliases` on records whose id is GHSA-*, MAL-*, etc.; MAL-* is the canonical
+ * namespace for a package compromise with no CVE. Every imported entry is a
+ * draft (`_auto_imported` + `_draft`), so the strict validator warns rather than
+ * errors and editorial fields stay null. EXCEPTD_OSV_FIXTURE points at a JSON
+ * file of one record or an array of them, for offline runs.
  */
 
 const https = require("https");
 const fs = require("fs");
 const { withRetry } = require("../vendor/blamejs/retry.js");
 
-// Production OSV endpoint. Requests land here over HTTPS unless a test
-// harness sets OSV_HOST_OVERRIDE, whose parsing and host/port/transport
-// substitution are documented at osvTransport() below.
+// Production endpoint; OSV_HOST_OVERRIDE substitutes host/port/transport — see osvTransport().
 const OSV_HOST = "api.osv.dev";
 const REQUEST_TIMEOUT_MS = 10000;
 const USER_AGENT = "exceptd-security/source-osv (+https://exceptd.com)";
 
-// Cap the streamed response so a hostile or misconfigured endpoint (a hijacked
-// DNS / compromised CDN / OSV_HOST_OVERRIDE pointed at a malicious server)
-// can't stream unbounded bytes into RAM. A real /v1/vulns/{id} or /v1/query
-// response is a few KB; 16 MB is generous headroom. Symmetric with the JSON
-// cap getJsonOnce enforces in lib/refresh-network.js. Tunable via
-// EXCEPTD_OSV_RESPONSE_CAP_BYTES for future API growth.
+// Caps the streamed response so a hostile endpoint cannot stream unbounded bytes
+// into RAM. Symmetric with the JSON cap getJsonOnce enforces in lib/refresh-network.js.
 function osvResponseCapBytes() {
   const env = parseInt(process.env.EXCEPTD_OSV_RESPONSE_CAP_BYTES, 10);
   return Number.isFinite(env) && env > 0 ? env : 16 * 1024 * 1024;
 }
 
-// Identifier namespaces OSV uses as PRIMARY keys. GHSA-* is intentionally
-// NOT in this list — `seedSingleAdvisory` in lib/refresh-external.js routes
-// CVE-* and GHSA-* through `source-ghsa` because GHSA carries richer field
-// coverage (cvss object, vulnerable_version_range string, ghsa_id linkage)
-// than OSV's import of the same advisories. Keep this list in sync with the
-// dispatcher in lib/refresh-external.js — adding a new prefix here is not
-// enough; the dispatcher's --advisory regex must also accept it.
+// Identifier namespaces OSV uses as PRIMARY keys. GHSA-* is deliberately absent:
+// seedSingleAdvisory in lib/refresh-external.js routes CVE-* and GHSA-* through
+// `source-ghsa`. Adding a prefix here also needs that dispatcher's --advisory regex.
 const OSV_ID_PREFIXES = [
   "MAL-",     // OSSF Malicious Packages
   "SNYK-",    // Snyk
@@ -88,32 +51,20 @@ const OSV_ID_PREFIXES = [
 ];
 
 /**
- * Set of OSV draft fields the field-dropped detector watches. When a
- * previously-populated value goes to null on a refresh, surface it as a
- * `field_dropped` diff so curators can investigate the upstream regression
- * rather than silently losing signal. Keep this set small + intentional —
- * fields here MUST be ones the editorial review process can re-source.
+ * Draft fields the field-dropped detector watches. Keep the set small — a field
+ * here MUST be one the editorial review process can re-source.
  */
 const FIELD_DROPPED_WATCH = Object.freeze([
-  // Only fields the upstream feed actually populates can legitimately "drop"
-  // from populated -> null on a re-import. active_exploitation / ai_discovered /
-  // poc_available are EDITORIAL (curated by hand, never upstream-sourced), so
-  // the normalize step always nulls them — watching them flagged a field_dropped
-  // "regression" on every curated re-import. Restrict to upstream-sourced fields.
+  // Only upstream-populated fields: normalize nulls the editorial ones on every
+  // import, so watching them flags a false regression on each re-import.
   "cvss_score",
   "cisa_kev_pending",
 ]);
 
-/**
- * Return true when `id` looks like an OSV-native primary key (i.e. NOT a
- * CVE-* identifier and NOT a GHSA-* identifier). Both CVE-* and GHSA-*
- * route through `source-ghsa` for richer field coverage.
- */
+/** True when `id` is an OSV-native primary key; CVE-* and GHSA-* route to `source-ghsa`. */
 function isOsvId(id) {
   if (!id || typeof id !== "string") return false;
-  // F8 (finding 8): trim trailing/leading whitespace so operators pasting
-  // ids from clipboards / multi-line files don't see a surprising routing
-  // miss. Empty after trim → not an OSV id.
+  // Trimmed first, so a pasted id doesn't miss the routing.
   const trimmed = id.trim();
   if (!trimmed) return false;
   const up = trimmed.toUpperCase();
@@ -123,10 +74,8 @@ function isOsvId(id) {
 }
 
 /**
- * Return true when the runtime context requests air-gap mode. Sources MUST
- * refuse network calls when this is set — fall through to fixture or return
- * a structured `air-gap: no fixture available` error so the operator sees
- * an explicit refusal, not a silent network attempt.
+ * True when the runtime context requests air-gap mode. Sources MUST refuse the
+ * network then — a fixture, or a structured `air-gap` error; never a silent attempt.
  */
 function isAirGap(opts) {
   if (opts && opts.airGap) return true;
@@ -135,15 +84,9 @@ function isAirGap(opts) {
 }
 
 /**
- * Resolve the OSV transport target. When OSV_HOST_OVERRIDE is set the
- * request switches to plain HTTP on the override host:port so test
- * harnesses can stand up a local server without TLS. Production omits the
- * override entirely and lands on api.osv.dev over HTTPS.
- *
- * Finding 13: validate the override aggressively. Garbage env values
- * (random binary, embedded NUL, port > 65535) previously slipped through
- * into the http.request options and produced opaque ENOTFOUND / EADDRINUSE
- * errors far from the source. Reject with a structured error here instead.
+ * Resolve the OSV transport target. OSV_HOST_OVERRIDE switches the request to
+ * plain HTTP on the override host:port; production lands on api.osv.dev over
+ * HTTPS. The override is validated here, not left to surface as an ENOTFOUND.
  */
 function osvTransport() {
   const override = process.env.OSV_HOST_OVERRIDE;
@@ -176,11 +119,9 @@ function osvTransport() {
 }
 
 /**
- * Make one OSV request (HEAD/GET/POST). Throws on retryable conditions
- * (HTTP 429/503/5xx + ECONNRESET/ETIMEDOUT family) and resolves to a
- * structured `{ok:false}` envelope on permanent conditions (4xx other than
- * 408/425/429). The thrown errors carry `statusCode` so withRetry's default
- * classifier recognizes them as retryable.
+ * One OSV request. THROWS on retryable conditions (429/503/5xx, 408/425, the
+ * ECONNRESET/ETIMEDOUT family) and RESOLVES a structured `{ok:false}` envelope on
+ * permanent ones. A thrown error carries `statusCode` for withRetry's classifier.
  */
 function osvRequestOnce({ method, reqPath, body, timeoutMs }) {
   return new Promise((resolve, reject) => {
@@ -203,18 +144,13 @@ function osvRequestOnce({ method, reqPath, body, timeoutMs }) {
     const opts = { host, port, path: reqPath, method, headers, timeout: timeoutMs };
     const req = mod.request(opts, (res) => {
       const status = res.statusCode;
-      // 401/404 (and other 4xx aside from 408/425/429) are permanent.
-      // 429/503 + 5xx are retryable. Honor Retry-After when present.
       const retryAfterRaw = res.headers["retry-after"];
       if (status === 429 || status === 503 || (status >= 500 && status <= 599) ||
           status === 408 || status === 425) {
         res.resume();
         const err = new Error(`OSV returned HTTP ${status}`);
         err.statusCode = status;
-        // Surface Retry-After (seconds or HTTP-date). The retry caller
-        // doesn't currently consume this directly — withRetry's backoff is
-        // its own schedule — but exposing it lets future schedulers honor
-        // server-advertised delay.
+        // Retry-After is exposed for a scheduler; withRetry runs its own backoff.
         if (retryAfterRaw) {
           const secs = parseInt(retryAfterRaw, 10);
           if (Number.isFinite(secs)) err.retryAfterMs = secs * 1000;
@@ -240,8 +176,7 @@ function osvRequestOnce({ method, reqPath, body, timeoutMs }) {
         chunks.push(c);
       });
       res.on("end", () => {
-        // If the cap fired, req.destroy already routed through req.on("error");
-        // don't also resolve here (avoids a double-settle on the promise).
+        // The cap already routed through req.on("error"); resolving here settles twice.
         if (capped) return;
         try {
           const parsed = JSON.parse(Buffer.concat(chunks).toString("utf8"));
@@ -257,8 +192,7 @@ function osvRequestOnce({ method, reqPath, body, timeoutMs }) {
       req.destroy(err);
     });
     req.on("error", (e) => {
-      // Retryable network errors propagate up to withRetry; non-retryable
-      // resolve as structured offline.
+      // Retryable network errors propagate to withRetry; the rest resolve offline.
       if (e && e.code && /^(ECONNRESET|ECONNREFUSED|ECONNABORTED|ETIMEDOUT|EPIPE|EAGAIN|ENOTFOUND|ENETUNREACH)$/.test(e.code)) {
         return reject(e);
       }
@@ -269,11 +203,7 @@ function osvRequestOnce({ method, reqPath, body, timeoutMs }) {
   });
 }
 
-/**
- * Low-level GET against OSV. Resolves to { ok, record|error, source }.
- * Honors OSV_HOST_OVERRIDE for offline tests. Wraps the request in
- * withRetry so 429/503/5xx + transient net errors back off automatically.
- */
+/** GET against OSV → { ok, record|error, source }; withRetry backs off 429/503/5xx. */
 async function osvGet(reqPath, timeoutMs = REQUEST_TIMEOUT_MS) {
   try {
     return await withRetry(() => osvRequestOnce({ method: "GET", reqPath, timeoutMs }), {
@@ -283,8 +213,7 @@ async function osvGet(reqPath, timeoutMs = REQUEST_TIMEOUT_MS) {
       jitterFactor: 0.5,
     });
   } catch (e) {
-    // After exhaustion of retries, return a structured envelope rather
-    // than letting the throw escape into the caller's promise chain.
+    // Once retries are exhausted, return an envelope; never let the throw escape.
     const status = typeof e?.statusCode === "number" ? e.statusCode : null;
     const error = status === 429
       ? `OSV rate-limited (HTTP 429)`
@@ -295,10 +224,7 @@ async function osvGet(reqPath, timeoutMs = REQUEST_TIMEOUT_MS) {
   }
 }
 
-/**
- * Low-level POST against OSV. Body is JSON-stringified. Same retry policy
- * as osvGet — 429/503/5xx + transient net errors back off automatically.
- */
+/** POST against OSV; the body is JSON-stringified. Same retry policy as osvGet. */
 async function osvPost(reqPath, body, timeoutMs = REQUEST_TIMEOUT_MS) {
   try {
     return await withRetry(() => osvRequestOnce({ method: "POST", reqPath, body, timeoutMs }), {
@@ -319,16 +245,9 @@ async function osvPost(reqPath, body, timeoutMs = REQUEST_TIMEOUT_MS) {
 }
 
 /**
- * Read EXCEPTD_OSV_FIXTURE and return a structured envelope. Matches the
- * GHSA-source convention: on any failure (missing file, malformed JSON,
- * root not object/array) return `{ ok: false, error, source: "offline" }`
- * rather than throw — operators on the CLI surface get a structured error
- * instead of a Node stack trace.
- *
- * Returns:
- *   null                                          when env var is unset
- *   { ok: true, advisories: [...], source }       on success
- *   { ok: false, error, source: "offline" }       on any failure
+ * Read EXCEPTD_OSV_FIXTURE. Null when unset, `{ ok: true, advisories, source }`
+ * on success, `{ ok: false, error, source: "offline" }` on any failure — missing
+ * file, malformed JSON, root neither object nor array. Never throws.
  */
 function readFixture() {
   const fp = process.env.EXCEPTD_OSV_FIXTURE;
@@ -352,9 +271,7 @@ function readFixture() {
 }
 
 /**
- * Fetch a single OSV record by id (MAL-*, GHSA-*, SNYK-*, RUSTSEC-*, etc.).
- *
- * Returns shape matches source-ghsa.fetchAdvisoryById:
+ * Fetch one OSV record by id. Return shape matches source-ghsa.fetchAdvisoryById:
  *   { ok: true,  advisories: [<osv_record>], source: "osv-api" | "fixture" }
  *   { ok: false, error, source: "offline" | "fixture" }
  */
@@ -362,18 +279,15 @@ async function fetchAdvisoryById(id, opts = {}) {
   if (!id || typeof id !== "string") {
     return { ok: false, error: "id is required (MAL-*, SNYK-*, RUSTSEC-*, etc.)", source: "offline" };
   }
-  // OSV.dev's /v1/vulns/{id} is case-sensitive — `mal-2026-3083` 404s while
-  // `MAL-2026-3083` resolves. Uppercase + trim at entry so operators piping
-  // lowercase ids from grep/jq don't get a surprising 404 from the network
-  // path. Fixture lookup already case-folds, so this normalization is a
-  // no-op there but harmless.
+  // /v1/vulns/{id} is case-sensitive — `mal-2026-3083` 404s where `MAL-2026-3083`
+  // resolves — so uppercase and trim at entry.
   id = id.trim().toUpperCase();
   if (!id) {
     return { ok: false, error: "id is required (MAL-*, SNYK-*, RUSTSEC-*, etc.)", source: "offline" };
   }
   const fixture = readFixture();
   if (fixture) {
-    if (!fixture.ok) return fixture; // F1: structured error envelope
+    if (!fixture.ok) return fixture;
     const want = id;
     const match = fixture.advisories.find((rec) => {
       const recId = (rec && rec.id) ? String(rec.id).toUpperCase() : null;
@@ -384,9 +298,7 @@ async function fetchAdvisoryById(id, opts = {}) {
     if (!match) return { ok: false, error: `${id} not in fixture`, source: "fixture" };
     return { ok: true, advisories: [match], source: "fixture" };
   }
-  // Finding 7: air-gap mode hard-refuses network calls. Operators running
-  // `exceptd refresh --air-gap` without a fixture get a structured refusal,
-  // not an outbound DNS query.
+  // Air-gap hard-refuses: no fixture means a structured refusal, not a DNS query.
   if (isAirGap(opts)) {
     return { ok: false, error: "air-gap: no fixture available (set EXCEPTD_OSV_FIXTURE)", source: "offline" };
   }
@@ -395,21 +307,15 @@ async function fetchAdvisoryById(id, opts = {}) {
   return { ok: true, advisories: [result.record], source: "osv-api" };
 }
 
-/**
- * List advisories for a package, optionally filtered to a specific version.
- * The single-package network path is implemented; there is no bulk /
- * package-watchlist import caller — advisories are seeded one at a time via
- * `refresh --advisory <id>`.
- */
+/** List advisories for a package, optionally filtered to one version. */
 async function fetchAdvisoriesForPackage(name, ecosystem, version, opts = {}) {
   if (!name || !ecosystem) {
     return { ok: false, error: "name and ecosystem are required", source: "offline" };
   }
   const fixture = readFixture();
   if (fixture) {
-    if (!fixture.ok) return fixture; // F1: structured error envelope
-    // Best-effort fixture filtering: match any record whose `affected[]`
-    // contains the requested package + ecosystem (+ version when set).
+    if (!fixture.ok) return fixture;
+    // Best-effort: match on `affected[]` package + ecosystem, and version when given.
     const matches = fixture.advisories.filter((rec) => {
       const affected = Array.isArray(rec?.affected) ? rec.affected : [];
       return affected.some((a) => {
@@ -423,7 +329,7 @@ async function fetchAdvisoriesForPackage(name, ecosystem, version, opts = {}) {
     });
     return { ok: true, advisories: matches, source: "fixture" };
   }
-  // Finding 7: air-gap refusal applies to the package query path too.
+  // The air-gap refusal applies to the package-query path too.
   if (isAirGap(opts)) {
     return { ok: false, error: "air-gap: no fixture available (set EXCEPTD_OSV_FIXTURE)", source: "offline" };
   }
@@ -436,15 +342,9 @@ async function fetchAdvisoriesForPackage(name, ecosystem, version, opts = {}) {
 }
 
 /**
- * Pick the catalog key for an OSV record. If `aliases` contains a CVE-*
- * value, prefer that (preserving the existing CVE-keyed convention).
- * Otherwise return the OSV id verbatim — MAL-*, SNYK-*, RUSTSEC-*, etc.
- *
- * Finding 14: the non-CVE branch must String-coerce + uppercase so a
- * record with `id: 12345` (numeric) or `id: "mal-2026-3083"` (lowercase)
- * doesn't produce a catalog key that diverges from the canonical
- * uppercase-prefix convention. The CVE branch already upper-cases via
- * `String(cve).toUpperCase()`.
+ * Catalog key for an OSV record: a CVE-* alias when present, preserving the
+ * CVE-keyed convention, else the OSV id. Both branches String-coerce and
+ * uppercase, so a numeric or lowercase id cannot diverge from the convention.
  */
 function pickCatalogKey(rec) {
   if (!rec || rec.id == null) return null;
@@ -455,12 +355,9 @@ function pickCatalogKey(rec) {
 }
 
 /**
- * CVSS 3.1 base-score computation from a vector string. Implements Table 6
- * of the FIRST CVSS 3.1 specification. Used when an OSV record carries a
- * vector but no embedded numeric score (the common case for MAL-* records).
- * Returns null on malformed input.
- *
- * Reference: https://www.first.org/cvss/v3.1/specification-document
+ * CVSS 3.1 base score from a vector string, per Table 6 of the FIRST CVSS 3.1
+ * specification (https://www.first.org/cvss/v3.1/specification-document). Used
+ * when a record carries a vector but no numeric score. Null on malformed input.
  */
 function cvss3BaseScore(vector) {
   if (typeof vector !== "string") return null;
@@ -473,7 +370,6 @@ function cvss3BaseScore(vector) {
     if (!k || !v) return null;
     metrics[k] = v;
   }
-  // Required metrics — bail if any are missing.
   for (const k of ["AV", "AC", "PR", "UI", "S", "C", "I", "A"]) {
     if (!metrics[k]) return null;
   }
@@ -509,45 +405,30 @@ function cvss3BaseScore(vector) {
   } else {
     base = Math.min(1.08 * (impact + exploitability), 10);
   }
-  // roundUp1 per CVSS 3.1 §7.1: round up to one decimal place. The spec
-  // uses an integer-arithmetic formulation (Math.ceil(input * 100000) /
-  // 10000 / 10) to avoid floating-point off-by-ones (e.g. 5.55 -> 5.6,
-  // not 5.5 if naive `Math.ceil(base * 10) / 10` is applied to a value
-  // that lands at 5.5499999... after IEEE 754 rounding). Finding 11.
+  // roundUp1 per CVSS 3.1 §7.1. The spec's integer formulation avoids the IEEE-754
+  // off-by-one where Math.ceil(base * 10) / 10 turns 5.5499999… into 5.5, not 5.6.
   const rounded = Math.ceil(base * 100000) / 1000000 < 0
     ? null
     : (Math.ceil(base * 100000) / 100000); // intermediate at 5 decimals
   if (rounded == null) return null;
-  // Now round-up to 1 decimal from the high-precision intermediate.
   const out = Math.ceil(rounded * 10 - 1e-9) / 10;
   if (!Number.isFinite(out) || out < 0 || out > 10) return null;
   return Math.round(out * 10) / 10; // strip trailing fp noise
 }
 
 /**
- * Pull a numeric CVSS score + vector out of an OSV severity[] entry. CVSS
- * vectors start with "CVSS:3.x/" or "CVSS:4.0/". When multiple vectors are
- * present (e.g. both V3 and V4), the highest version wins — UNLESS the v4
- * vector cannot be scored (this module does not implement CVSS 4.0
- * derivation yet), in which case fall back to the highest computable
- * version below v4 so we don't silently lose a v3 9.8 (Finding 10).
- * Returns null components when nothing parseable is present.
- *
- * Finding 19: when `s.score` is an object (some Snyk records embed
- * `{ value: "CVSS:3.1/..." }`), accept `s.score.value` as the string
- * source rather than silently producing null.
+ * Pull a numeric CVSS score + vector out of an OSV severity[] entry. The highest
+ * version wins UNLESS it cannot be scored — CVSS 4.0 derivation is not implemented
+ * — in which case the highest computable version below it is used, so a v3 9.8 is
+ * not silently lost. `s.score` may be a string or an object carrying `.value`.
  */
 function extractCvss(rec) {
   const sev = Array.isArray(rec?.severity) ? rec.severity : [];
   let score = null;
-  // Collect all parseable vectors keyed by major version so we can fall
-  // back from v4 -> v3 if v4 fails to compute.
   const vectorsByVersion = new Map(); // version (number) -> vector string
   let bareScore = null;
-  // Computed score for a single CVSS vector string: its trailing /N.N score if
-  // present, else the derived CVSS 3.x base score, else null (e.g. an
-  // uncomputable v4 vector). Used to keep the HIGHEST-scoring vector per major
-  // version regardless of severity[] array order.
+  // Score for one vector: its trailing /N.N when present, else the derived CVSS 3.x
+  // base score, else null. Keeps the HIGHEST-scoring vector per major version.
   const vectorScore = (vec) => {
     const tail = vec.match(/\/(\d+(?:\.\d+)?)$/);
     if (tail) { const t = parseFloat(tail[1]); if (t >= 0 && t <= 10) return t; }
@@ -559,32 +440,26 @@ function extractCvss(rec) {
     let raw = null;
     if (typeof s.score === "string") raw = s.score;
     else if (typeof s.score === "object" && s.score && typeof s.score.value === "string") {
-      raw = s.score.value; // Finding 19
+      raw = s.score.value;
     }
     if (raw == null) continue;
     const v = raw.trim();
     // Bare numeric score (no vector prefix).
     const num = parseFloat(v);
     if (!Number.isNaN(num) && num >= 0 && num <= 10 && !v.includes("/")) {
-      // HIGHEST-wins, not first-wins: an OSV record legitimately carries
-      // multiple same-version severity entries (e.g. an NVD base score plus a
-      // CNA/vendor score) and the upstream array order is not guaranteed. A
-      // first-wins guard silently downgraded a 9.8 critical to a 5.3 medium
-      // purely because the lower score appeared earlier in severity[].
+      // HIGHEST-wins, not first-wins: several same-version entries arrive in no
+      // guaranteed order, and first-wins downgrades a 9.8 critical to a 5.3.
       if (bareScore == null || num > bareScore) bareScore = num;
       continue;
     }
     const m = v.match(/^CVSS:(\d+\.\d+)/);
     if (!m) continue;
     const ver = parseFloat(m[1]);
-    // Keep the HIGHEST-scoring vector within each major version (same rationale
-    // as the bare-score path above). Compare computed scores, not array order.
+    // Same within each major version: compare computed scores, not array order.
     const prev = vectorsByVersion.get(ver);
     if (!prev || (vectorScore(v) ?? -1) > (vectorScore(prev) ?? -1)) vectorsByVersion.set(ver, v);
   }
-  // Try versions in descending order. CVSS 4.0 derivation is not yet
-  // implemented here — if v4 was the highest but can't be computed, walk
-  // down to v3.x. Only return null when ALL versions fail.
+  // Descending; score stays null only when every version fails.
   const versions = Array.from(vectorsByVersion.keys()).sort((a, b) => b - a);
   let bestVector = null;
   for (const ver of versions) {
@@ -600,13 +475,9 @@ function extractCvss(rec) {
       const computed = cvss3BaseScore(candidate);
       if (computed != null) { score = computed; break; }
     }
-    // v4 has no in-module computer — keep walking down to the next
-    // version. The bestVector tracker holds whatever was tried last;
-    // overwrite it with the next computable on the loop iteration.
+    // v4 has no in-module computer — keep walking down.
   }
-  // If we landed on an uncomputable v4 vector but a lower-version vector
-  // was usable, prefer the lower-version one's vector string so callers
-  // don't get a v4 vector + null score combo when v3 was available.
+  // Prefer a lower-version vector when the highest was uncomputable, so no v4-with-null.
   if (score == null && versions.length > 0) {
     for (const ver of versions) {
       if (ver >= 4) continue;
@@ -614,19 +485,12 @@ function extractCvss(rec) {
       if (candidate) { bestVector = candidate; break; }
     }
   }
-  // F10 fix: if score is still null but we have a v4 vector + a bare
-  // score that came from a v3-only severity entry, prefer the v3 vector
-  // string when one exists. (Handles the case described in the audit:
-  // v4 is the highest version but uncomputable; a v3 vector with 9.8
-  // sits alongside. Without this fallback we lose the 9.8.)
+  // Last resort: a bare numeric score, when no vector was computable.
   if (score == null && bareScore != null) score = bareScore;
   return { score, vector: bestVector };
 }
 
-/**
- * Coarse package-ecosystem inference for the catalog `type` field. Mirrors
- * the same heuristic used by source-ghsa.
- */
+/** Coarse package-ecosystem inference for the catalog `type`. Mirrors source-ghsa. */
 function inferType(rec) {
   const ecos = new Set();
   const affected = Array.isArray(rec?.affected) ? rec.affected : [];
@@ -645,11 +509,8 @@ function inferType(rec) {
 }
 
 /**
- * Validate + slice a published/modified timestamp string. Findings 2 + 17:
- *  - typeof guard so non-string inputs (number, object, undefined) become
- *    null instead of throwing on .slice().
- *  - ISO-prefix regex + year sanity bound so garbage like "yesterday" or
- *    "0001-01-01" doesn't pollute downstream surfaces.
+ * Validate and slice a published/modified timestamp; a non-string, a non-ISO
+ * prefix or a year outside [1990, next year] all yield null rather than throwing.
  */
 function safeDateSlice(value) {
   if (typeof value !== "string") return null;
@@ -662,14 +523,10 @@ function safeDateSlice(value) {
 }
 
 /**
- * Normalize an OSV record into the exceptd catalog draft shape. Returns
- * `{ [catalogKey]: <draft-entry> }` so callers can spread it into the
- * catalog object directly. Returns null if the record is unusable.
- *
- * Editorial fields (framework_control_gaps, atlas_refs, attack_refs,
- * rwep_factors) are left null — the seven-phase playbook flow or a human
- * reviewer fills these in. `_auto_imported: true` + `_draft: true` flags
- * mark the entry for the strict catalog validator (warn, not error).
+ * Normalize an OSV record into the catalog draft shape, as
+ * `{ [catalogKey]: <draft-entry> }` so a caller can spread it into the catalog.
+ * Null when the record is unusable. Editorial fields are left null, and
+ * `_auto_imported` + `_draft` mark the entry warn-not-error for the validator.
  */
 function normalizeAdvisory(rec) {
   if (!rec || rec.id == null) return null;
@@ -680,15 +537,13 @@ function normalizeAdvisory(rec) {
   if (!catalogKey) return null;
 
   const aliases = Array.isArray(rec.aliases) ? rec.aliases.slice() : [];
-  // If the catalog key came from aliases (CVE-*), put the OSV id back into
-  // the aliases array so it stays discoverable.
+  // When the key came from aliases (CVE-*), the OSV id goes back into aliases.
   if (catalogKey !== rec.id && !aliases.includes(rec.id)) aliases.push(rec.id);
 
   const { score, vector } = extractCvss(rec);
 
   const affectedPackages = [];
   const affectedVersions = [];
-  // Finding 3: rec.affected might not be an array — guard before iterating.
   const affectedList = Array.isArray(rec.affected) ? rec.affected : [];
   for (const a of affectedList) {
     const pkg = a?.package || {};
@@ -699,13 +554,9 @@ function normalizeAdvisory(rec) {
     for (const v of versions) {
       affectedVersions.push(`${pkg.name || "?"} == ${v}`);
     }
-    // Finding 16: walk events sequentially. OSV emits a stream of
-    // introduced/fixed/last_affected events; the historical implementation
-    // collected the FIRST `introduced` + FIRST `fixed` per range and
-    // emitted one range, losing re-introduction cycles (an introduced ->
-    // fixed -> introduced -> fixed sequence collapsed to one range).
-    // Sequential pairing produces ONE entry per (introduced, fixed |
-    // last-known-vulnerable) pair instead.
+    // Events are walked sequentially, one entry per (introduced, fixed |
+    // last-known-vulnerable) pair. Pairing the FIRST introduced with the FIRST fixed
+    // collapses an introduced → fixed → introduced cycle and loses the re-introduction.
     const ranges = Array.isArray(a.ranges) ? a.ranges : [];
     for (const r of ranges) {
       const events = Array.isArray(r.events) ? r.events : [];
@@ -734,8 +585,7 @@ function normalizeAdvisory(rec) {
           lastKnownVulnerable = e.last_affected;
         }
       }
-      // Trailing open range — no `fixed` ever observed. Emit as
-      // `>= introduced` (optionally with last_known_vulnerable upper).
+      // Trailing open range — no `fixed` was ever observed.
       if (openIntro != null) {
         const upper = lastKnownVulnerable ? `, <= ${lastKnownVulnerable}` : "";
         affectedVersions.push(`${pkg.name || "?"} >= ${openIntro}${upper}`);
@@ -743,9 +593,8 @@ function normalizeAdvisory(rec) {
     }
   }
 
-  // IoC seeding from database_specific.iocs if present (some Snyk + StepSec
-  // imported records carry this). Domains + URLs land in c2_indicators so
-  // an operator scanning a repo has something to grep for immediately.
+  // IoC seeding from database_specific.iocs; domains and URLs land in c2_indicators
+  // so an operator has something to grep for immediately.
   const dsIocs = rec?.database_specific?.iocs || null;
   let iocs = null;
   if (dsIocs && (Array.isArray(dsIocs.domains) || Array.isArray(dsIocs.urls))) {
@@ -755,15 +604,13 @@ function normalizeAdvisory(rec) {
     iocs = { c2_indicators: c2 };
   }
 
-  // Reference URLs — OSV `references` is `[{ type, url }, ...]`.
-  // Finding 20: guard non-array references silently truncating to [].
+  // OSV `references` is `[{ type, url }, ...]`.
   const refUrls = [];
   const refList = Array.isArray(rec.references) ? rec.references : [];
   for (const r of refList) {
     if (r && typeof r.url === "string") refUrls.push(r.url);
   }
 
-  // Severity wording from CVSS / qualitative hint.
   const severityWord = score != null && score >= 9.0 ? "critical"
     : score != null && score >= 7.0 ? "high"
     : score != null && score >= 4.0 ? "medium"
@@ -773,25 +620,19 @@ function normalizeAdvisory(rec) {
   const pending = severityWord === "critical" || (score != null && score >= 9.0);
 
   const today = new Date().toISOString().slice(0, 10);
-  // Finding 2 + 17: type-safe + format-validated date slicing.
   const published = safeDateSlice(rec.published);
   const modified = safeDateSlice(rec.modified);
 
-  // OSV.dev canonical advisory URL — used as the primary vendor advisory.
+  // The canonical osv.dev URL, used as the primary vendor advisory.
   const osvUrl = `https://osv.dev/vulnerability/${encodeURIComponent(rec.id)}`;
 
-  // Dedupe verification_sources. OSV records frequently carry the
-  // canonical osv.dev URL in references[] as well, which would otherwise
-  // produce a duplicate alongside the prepended `osvUrl`.
+  // Deduped: references[] often carries the canonical osv.dev URL as well.
   const verification_sources = Array.from(new Set([
     osvUrl,
     ...(/^CVE-/i.test(catalogKey) ? [`https://nvd.nist.gov/vuln/detail/${catalogKey}`] : []),
     ...refUrls.slice(0, 10),
   ]));
 
-  // EPSS coverage does not extend to non-CVE identifiers. Surface this
-  // explicitly so curators know to re-query if MITRE later assigns a CVE
-  // id to the entry.
   const isCveKey = /^CVE-/i.test(catalogKey);
   const epss_note = isCveKey
     ? null
@@ -853,9 +694,8 @@ function normalizeAdvisory(rec) {
       _draft_reason: "Imported from OSV.dev on " + today + ". Editorial fields (framework_control_gaps, atlas_refs, attack_refs, iocs, vector, complexity, rwep_factors) require human review. Run `exceptd run sbom --evidence -` against an affected repo to gather IoCs; consult MITRE ATLAS + ATT&CK catalogs for refs.",
       _source_osv_id: rec.id,
       _source_published_at: rec.published || null,
-      // OSV sets a top-level `withdrawn` timestamp when a record is retracted.
-      // Surface it as structured status so a citation check (and the resolver)
-      // can flag a withdrawn advisory instead of importing it as if live.
+      // A retracted record carries a top-level `withdrawn` timestamp; surfaced as
+      // structured status so a citation check flags it instead of importing it live.
       ...(rec.withdrawn ? { status: "withdrawn", status_source: "osv:withdrawn", status_verified: today } : {}),
       last_updated: modified || today,
     },
@@ -863,15 +703,12 @@ function normalizeAdvisory(rec) {
 }
 
 /**
- * Build a refresh diff for the refresh-external orchestrator. v0.12.10
- * supports targeted seeding: when `ctx.osv_ids` is populated, fetch each
- * id and emit one `_new_entry` diff per record that isn't already in the
- * local catalog. Finding 9: when the record already exists and a watched
- * field has dropped from populated -> null, emit a `field_dropped` diff
- * so curators see the upstream regression instead of silently absorbing it.
+ * Build a refresh diff for the refresh-external orchestrator. With `ctx.osv_ids`
+ * populated, each id is fetched and emitted as a `_new_entry` diff unless its key
+ * is already in the local catalog — in which case a watched field that dropped to
+ * null emits a `field_dropped` diff instead.
  */
 async function buildDiff(ctx) {
-  // Finding 8: trim ids defensively at the entry seam.
   const rawIds = Array.isArray(ctx?.osv_ids) ? ctx.osv_ids : [];
   const ids = rawIds.map((x) => (typeof x === "string" ? x.trim() : "")).filter(Boolean);
   if (ids.length === 0) {
@@ -887,16 +724,12 @@ async function buildDiff(ctx) {
   const cveCatalog = ctx.cveCatalog || {};
   const existingKeys = new Set(Object.keys(cveCatalog));
   const diffs = [];
-  // Distinguish unreachable (fetch failed, network or 5xx) from
-  // normalize-rejected (record fetched but normalization produced null).
-  // Operators triaging a refresh-report want to know whether to chase a
-  // network outage or a malformed upstream record.
+  // Unreachable (fetch failed) and normalize-rejected (fetched, normalized to null)
+  // are counted apart, so triage knows a network outage from a malformed record.
   let unreachable = 0;
   let normalizeErrors = 0;
-  // Ids that ARE in the catalog but skipped because of overlap
-  // are not "errors"; surface them so the summary doesn't read as silently
-  // dropping work. Particularly useful when a curator dispatches the same
-  // batch twice and wonders why nothing happened.
+  // An id already in the catalog is skipped, not an error; counting it keeps a
+  // re-dispatched batch from reading as silently dropped work.
   let ghsaOnlySkipped = 0;
   for (const id of ids) {
     const r = await fetchAdvisoryById(id, { airGap: ctx.airGap });
@@ -907,9 +740,6 @@ async function buildDiff(ctx) {
     if (!normalized) { normalizeErrors++; continue; }
     const key = Object.keys(normalized)[0];
     if (existingKeys.has(key)) {
-      // Finding 9: field-dropped detection. Compare watched fields between
-      // the existing local entry and the freshly-normalized one. Emit a
-      // `field_dropped` diff per regression rather than a `_new_entry`.
       const before = cveCatalog[key] || {};
       const after = normalized[key];
       let dropped = false;
@@ -944,9 +774,7 @@ async function buildDiff(ctx) {
     });
   }
   const errors = unreachable + normalizeErrors;
-  // diffs holds BOTH _new_entry and field_dropped records — count them
-  // separately so the summary doesn't mislabel field-dropped regressions as
-  // brand-new entries.
+  // diffs holds both kinds; count separately so a field_dropped is not a new entry.
   const newCount = diffs.filter((d) => d.field === "_new_entry").length;
   const droppedCount = diffs.filter((d) => d.variant === "field_dropped").length;
   const summary = `OSV fetched ${ids.length} id(s); ${newCount} new entry diff(s), ${droppedCount} field-dropped regression(s), ${unreachable} unreachable, ${normalizeErrors} normalize-rejected, ${ghsaOnlySkipped} ghsa_only_skipped.`;