@blamejs/exceptd-skills 0.19.32 → 0.19.34

package/lib/source-ghsa.js

@@ -1,27 +1,11 @@
 "use strict";
 
 /**
- * lib/source-ghsa.js
- *
- * GitHub Advisory Database fetcher. The GHSA covers npm, PyPI, RubyGems,
- * Maven, NuGet, Go, Composer, Swift, Erlang, Pub, and Rust ecosystems in
- * one feed and is updated within hours of disclosure — much faster than
- * NVD (~10 days) or KEV (variable, often days).
- *
- * Endpoint: GET https://api.github.com/advisories
- *   - Unauthenticated: 60 req/hr (sufficient for nightly refresh)
- *   - Authenticated:   5000 req/hr (set GITHUB_TOKEN env var)
- *
- * 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,
- * iocs, atlas_refs) are left null until a human or AI assistant
- * fills them in via the seven-phase playbook flow.
- *
- * Honors EXCEPTD_GHSA_FIXTURE env var for offline testing — value is a
- * path to a JSON array matching the api.github.com/advisories shape.
- *
- * Zero npm deps. Node 24 stdlib only.
+ * GitHub Advisory Database fetcher — GET https://api.github.com/advisories,
+ * rate-limited to 60 req/hr unauthenticated and 5000 with GITHUB_TOKEN set.
+ * EXCEPTD_GHSA_FIXTURE points at a JSON file of the same shape for offline runs.
+ * Everything imported is a draft: entries carry `_auto_imported` + `_draft`, so
+ * the strict validator warns rather than errors and editorial fields stay null.
  */
 
 const https = require("https");
@@ -33,37 +17,24 @@ const GHSA_PATH = "/advisories?per_page=50&type=reviewed&sort=published&directio
 const REQUEST_TIMEOUT_MS = 10000;
 const USER_AGENT = "exceptd-security/source-ghsa (+https://exceptd.com)";
 
-// Cap the streamed response so a hijacked DNS / compromised CDN / MITM serving
-// api.github.com can't stream unbounded bytes into RAM. A 50-advisory page is
-// well under a MB; 16 MB is generous headroom. Symmetric with the JSON cap
-// getJsonOnce enforces in lib/refresh-network.js and the OSV poller's cap.
-// Tunable via EXCEPTD_GHSA_RESPONSE_CAP_BYTES for future API growth.
+// Caps the streamed response so anything impersonating api.github.com cannot push
+// unbounded bytes into RAM. Symmetric with getJsonOnce in lib/refresh-network.js.
 function ghsaResponseCapBytes() {
   const env = parseInt(process.env.EXCEPTD_GHSA_RESPONSE_CAP_BYTES, 10);
   return Number.isFinite(env) && env > 0 ? env : 16 * 1024 * 1024;
 }
 
-/**
- * Field-dropped watch set — fields the buildDiff regression-detector
- * watches when the upstream still has an entry but a previously-populated
- * local value has gone null. Mirrors lib/source-osv.js. Finding 9.
- */
+/** Fields buildDiff watches going null while upstream still has the entry; mirrors lib/source-osv.js. */
 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 single curated re-import. Restrict the watch to the
-  // upstream-sourced fields.
+  // Only upstream-populated fields: normalize nulls the editorial ones on every
+  // import, so watching them reports a regression on each re-import.
   "cvss_score",
   "cisa_kev_pending",
 ]);
 
 /**
- * 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. Mirrors source-osv.
+ * True when air-gap mode is requested; a source must then fall through to a
+ * fixture or return the structured `air-gap: no fixture available` error.
  */
 function isAirGap(opts) {
   if (opts && opts.airGap) return true;
@@ -72,16 +43,9 @@ function isAirGap(opts) {
 }
 
 /**
- * Read EXCEPTD_GHSA_FIXTURE and return a structured envelope. Finding 5:
- * mirror the OSV-source convention so a fixture file containing `null`,
- * a number, or a string at its root doesn't slip through as an empty
- * advisories array — the strict catalog validator would later swallow the
- * resulting drift as "no advisories returned" instead of surfacing it as
- * a fixture configuration error. Returns:
- *
- *   null                                          when env var is unset
- *   { ok: true, advisories: [...], source }       on success
- *   { ok: false, error, source: "offline" }       on any failure
+ * Read EXCEPTD_GHSA_FIXTURE. Null when unset, `{ ok: true, advisories, source }`
+ * on success, `{ ok: false, error, source }` on any failure — including a
+ * non-object root, which would otherwise pass as an empty advisory list.
  */
 function readFixture() {
   const fp = process.env.EXCEPTD_GHSA_FIXTURE;
@@ -105,9 +69,8 @@ function readFixture() {
 }
 
 /**
- * One HTTPS GET against api.github.com. Throws on retryable conditions so
- * withRetry's default classifier (HTTP 408/425/429/5xx + ECONNRESET et al)
- * picks them up; resolves to a structured envelope on permanent conditions.
+ * One HTTPS GET against api.github.com. Rejects on retryable conditions so
+ * withRetry's classifier picks them up, resolves an envelope on permanent ones.
  */
 function ghsaRequestOnce({ path, headers, timeoutMs }) {
   return new Promise((resolve, reject) => {
@@ -149,8 +112,7 @@ function ghsaRequestOnce({ path, headers, 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 body = JSON.parse(Buffer.concat(chunks).toString("utf8"));
@@ -184,18 +146,13 @@ function ghsaRequestOnce({ path, headers, timeoutMs }) {
 }
 
 /**
- * Fetch a page of advisories (default: latest 50). Wraps the underlying
- * HTTPS request in withRetry so transient 429/503/5xx + net errors back off
- * automatically.
- *
- * Returns:
- *   { ok: true,  advisories: [...], source: "github-api" | "fixture", rate_limit?: { remaining, reset } }
- *   { ok: false, error, source: "offline" }
+ * Fetch a page of advisories, backing off through withRetry on transient
+ * failures. `{ ok: true, advisories, source: "github-api" | "fixture",
+ * rate_limit? }` or `{ ok: false, error, source: "offline" }`.
  */
 async function fetchAdvisories({ timeoutMs = REQUEST_TIMEOUT_MS, path = GHSA_PATH, token = null, airGap = false } = {}) {
   const fixture = readFixture();
   if (fixture) return fixture;
-  // Finding 7: air-gap hard-refuses network when no fixture is configured.
   if (isAirGap({ airGap })) {
     return { ok: false, error: "air-gap: no fixture available (set EXCEPTD_GHSA_FIXTURE)", source: "offline" };
   }
@@ -224,16 +181,13 @@ async function fetchAdvisories({ timeoutMs = REQUEST_TIMEOUT_MS, path = GHSA_PAT
 }
 
 /**
- * Fetch a single advisory by ID — accepts CVE-* or GHSA-* identifiers.
- *
- * GHSA-IDs hit /advisories/<ghsa-id> directly. CVE-IDs require a search
- * since the API is keyed by GHSA. We fall back to a query-string search.
+ * Fetch a single advisory by CVE-* or GHSA-* id. A GHSA id addresses
+ * /advisories/<ghsa-id>; the API is keyed by GHSA, so a CVE id goes via search.
  */
 async function fetchAdvisoryById(id, opts = {}) {
   if (!id || typeof id !== "string") {
     return { ok: false, error: "id is required (CVE-* or GHSA-*)", source: "offline" };
   }
-  // Finding 8: trim whitespace at the entry seam.
   id = id.trim();
   if (!id) {
     return { ok: false, error: "id is required (CVE-* or GHSA-*)", source: "offline" };
@@ -249,33 +203,21 @@ async function fetchAdvisoryById(id, opts = {}) {
     if (!match) return { ok: false, error: `${id} not in fixture`, source: "fixture" };
     return { ok: true, advisories: [match], source: "fixture" };
   }
-  // Validate the FULL GHSA token shape (GHSA-xxxx-xxxx-xxxx) before building the
-  // request path, and encodeURIComponent the segment — symmetric with the CVE
-  // branch below. A prefix-only `/^GHSA-/i` left the remainder unconstrained, so
-  // an operator-supplied id like `GHSA-aaaa/../../meta` survived verbatim into
-  // `/advisories/...` as path-control segments; the strict shape now routes a
-  // malformed id to the unrecognized-id error envelope instead.
+  // The full GHSA token shape, not a `/^GHSA-/` prefix: `GHSA-aaaa/../../meta`
+  // would otherwise reach `/advisories/` as path-control segments.
   if (/^GHSA-[0-9a-z]{4}-[0-9a-z]{4}-[0-9a-z]{4}$/i.test(id)) {
     return fetchAdvisories({ ...opts, path: `/advisories/${encodeURIComponent(id.toLowerCase())}` });
   }
   if (/^CVE-\d{4}-\d+$/i.test(id)) {
     return fetchAdvisories({ ...opts, path: `/advisories?cve_id=${encodeURIComponent(id.toUpperCase())}` });
   }
-  // v0.12.11: widen the error to enumerate OSV-native prefixes — operators
-  // running `exceptd refresh --advisory FOO-BAR` previously got an error
-  // mentioning only CVE / GHSA, even though MAL-*, SNYK-*, RUSTSEC-*,
-  // USN-*, PYSEC-*, GO-*, MGASA-*, UVI- are also valid id shapes routed
-  // through source-osv. The hint here mirrors lib/refresh-external.js
-  // seedSingleAdvisory's documented acceptance set.
+  // The accepted set mirrors seedSingleAdvisory in lib/refresh-external.js.
   return { ok: false, error: `unrecognized id format: ${id}. Expected one of: CVE-YYYY-NNNN, GHSA-* (routed through source-ghsa); MAL-* / SNYK-* / RUSTSEC-* / USN-* / PYSEC-* / GO-* / MGASA-* / UVI- (routed through source-osv).`, source: "offline" };
 }
 
 /**
- * Validate + slice a published_at timestamp. Findings 2 + 17:
- *  - typeof guard so non-string inputs (number, object, undefined) become
- *    null instead of throwing on .slice().
- *  - ISO-prefix + year sanity bound so garbage timestamps don't pollute
- *    downstream surfaces.
+ * The YYYY-MM-DD head of an upstream timestamp, or null — a non-string, a
+ * non-ISO prefix or a year outside [1990, next year] all yield null.
  */
 function safeDateSlice(value) {
   if (typeof value !== "string") return null;
@@ -288,16 +230,9 @@ function safeDateSlice(value) {
 }
 
 /**
- * Normalize a GHSA advisory object to the exceptd catalog draft shape.
- * Fields the GHSA carries authoritatively: cve_id, ghsa_id, summary,
- * severity, cvss, vulnerabilities (package + version range), published_at,
- * references. Editorial fields (framework_control_gaps, iocs, atlas_refs,
- * attack_refs, rwep_factors) are LEFT NULL — drafts. The seven-phase
- * playbook flow OR a human reviewer fills these in.
- *
- * Returns null if the advisory lacks a CVE ID (we don't import GHSA-only
- * advisories into the CVE catalog — they belong in a separate GHSA index
- * which is a v0.13 design).
+ * Normalize a GHSA advisory into the catalog draft shape. Only what GHSA carries
+ * authoritatively is populated; editorial fields stay null for a curator. Null
+ * for an advisory with no CVE id — a GHSA-only advisory is not a CVE entry.
  */
 function normalizeAdvisory(adv) {
   if (!adv || !adv.cve_id) return null;
@@ -305,7 +240,6 @@ function normalizeAdvisory(adv) {
   const ecosystems = new Set();
   const affected = [];
   const ecosystemPackages = [];
-  // Finding 3: vulnerabilities may not be an array — guard before iterating.
   const vulnList = Array.isArray(adv.vulnerabilities) ? adv.vulnerabilities : [];
   for (const v of vulnList) {
     if (v?.package?.ecosystem) ecosystems.add(v.package.ecosystem);
@@ -317,9 +251,7 @@ function normalizeAdvisory(adv) {
     }
   }
 
-  // Finding 4: cvss.score may arrive as a string ("9.8") rather than a
-  // number. Number-coerce + finite-check so the catalog field stays
-  // numeric across upstream shape drift.
+  // cvss.score arrives as a string often enough to need coercion + a finite check.
   let cvssScore = null;
   if (adv.cvss != null && adv.cvss.score !== undefined && adv.cvss.score !== null) {
     const n = Number(adv.cvss.score);
@@ -334,11 +266,8 @@ function normalizeAdvisory(adv) {
     : ecosystems.has("rubygems") ? "supply-chain-gem"
     : "supply-chain-other";
 
-  // Finding 2 + 17: type-safe + format-validated published_at slicing.
   const publishedDate = safeDateSlice(adv.published_at);
 
-  // Finding 20: references may not be an array — guard the spread before
-  // it silently truncates to an empty list.
   const refList = Array.isArray(adv.references) ? adv.references : [];
 
   return {
@@ -397,8 +326,7 @@ function normalizeAdvisory(adv) {
       _draft_reason: "Imported from GHSA on " + new Date().toISOString().slice(0, 10) + ". 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_ghsa_id: adv.ghsa_id || null,
       _source_published_at: adv.published_at || null,
-      // GitHub sets `withdrawn_at` when an advisory is retracted. Surface it as
-      // structured status so a withdrawn advisory is flagged, not imported as live.
+      // `withdrawn_at` marks a retracted advisory; carried as status, not imported live.
       ...(adv.withdrawn_at ? { status: "withdrawn", status_source: "ghsa:withdrawn_at", status_verified: new Date().toISOString().slice(0, 10) } : {}),
       last_updated: new Date().toISOString().slice(0, 10),
     },
@@ -406,17 +334,9 @@ function normalizeAdvisory(adv) {
 }
 
 /**
- * Build a refresh diff for the existing refresh-external orchestrator.
- * Compares the latest 50 advisories' CVE IDs against the local catalog;
- * any CVE ID not in the catalog becomes an "add" diff.
- *
- * Finding 9: when the advisory is already in the catalog but a watched
- * field has dropped from populated -> null, surface a `field_dropped`
- * diff so curators don't silently lose signal.
- *
- * Finding 18: count + surface GHSA-only advisories (no CVE id) that were
- * skipped, so the summary explains why N upstream advisories produced
- * fewer than N diffs.
+ * Build a refresh diff for the refresh-external orchestrator. A CVE id absent
+ * from the local catalog becomes a `_new_entry` diff; one already present whose
+ * FIELD_DROPPED_WATCH value has gone null becomes a `field_dropped` diff.
  */
 async function buildDiff(ctx) {
   const result = await fetchAdvisories({ airGap: ctx?.airGap });
@@ -432,7 +352,6 @@ async function buildDiff(ctx) {
     const normalized = normalizeAdvisory(adv);
     if (!normalized) continue;
     if (existing.has(adv.cve_id)) {
-      // Finding 9: field-dropped detection on the existing entry.
       const before = cveCatalog[adv.cve_id] || {};
       const after = normalized[adv.cve_id];
       for (const field of FIELD_DROPPED_WATCH) {
@@ -463,9 +382,7 @@ async function buildDiff(ctx) {
       source: "ghsa",
     });
   }
-  // diffs holds BOTH _new_entry and field_dropped records — count them
-  // separately so the summary doesn't mislabel field-dropped regressions as
-  // brand-new CVE IDs.
+  // diffs holds both kinds; count separately so a field_dropped is not a new CVE.
   const newCount = diffs.filter((d) => d.field === "_new_entry").length;
   const droppedCount = diffs.filter((d) => d.variant === "field_dropped").length;
   return {