@blamejs/exceptd-skills 0.18.9 → 0.18.11

package/lib/schemas/playbook.schema.json

@@ -39,7 +39,7 @@
                             "properties": {
                               "source": {
                                 "type": "string",
-                                "pattern": "(https://|http://|gh api|gh release|curl |wget |fetch )"
+                                "pattern": "(https://|http://|gh api|gh release|curl |wget |fetch |GET /|POST /|PUT /|PATCH /|DELETE /|Graph|Okta|Entra ID|Microsoft Graph)"
                               }
                             },
                             "required": ["source"]

package/lib/scoring.js

@@ -151,6 +151,18 @@ const RECOGNISED_FACTOR_KEYS = new Set([
   'patch_required_reboot',
 ]);
 
+// Shape-B (catalog post-weight) keys deriveRwepFromFactors is allowed to sum.
+// The post-weight summation operates on the catalog field names — which include
+// `ai_factor`, the +15 AI weight every Shape-B catalog entry stores. `ai_factor`
+// is deliberately ABSENT from RECOGNISED_FACTOR_KEYS (that set carries the
+// Shape-A boolean inputs `ai_assisted_weapon` / `ai_discovered` /
+// `ai_assisted_weaponization`), so the Shape-B allowlist must add it back — a
+// plain `RECOGNISED_FACTOR_KEYS.has(k)` filter would silently drop the AI weight
+// from every derivation. Any key NOT in this set is a typo or unknown field; it
+// is excluded from the sum AND surfaced (see the Shape-B loop) rather than blindly
+// added, so a sub-5 typo can't corrupt the derived score with no diagnostic.
+const RECOGNISED_POST_WEIGHT_KEYS = new Set([...RECOGNISED_FACTOR_KEYS, 'ai_factor']);
+
 function score(cveId, catalog) {
   const entry = catalog[cveId];
   if (!entry) throw new Error(`CVE not in catalog: ${cveId}`);
@@ -380,6 +392,23 @@ function deriveRwepFromFactors(factors) {
   let sum = 0;
   for (const [k, v] of Object.entries(factors)) {
     if (typeof v !== 'number' || !Number.isFinite(v)) continue;
+    // Unrecognised key (a typo such as `cisa_kevv` / `reboot_requiredd`, or a
+    // field outside the post-weight vocabulary): do NOT add it to the sum, and
+    // surface it. scoreCustom/validateFactors already drop+warn on unknown
+    // keys; the Shape-B summation previously added ANY numeric value blindly, so
+    // the three scoring surfaces disagreed on what an unknown key means (a sub-5
+    // typo silently inflated the derived breakdown). Align them here. The
+    // warning mirrors the activeExploitationMultiplier precedent above — an
+    // observable diagnostic on the standard Node channel, not a silent skip, so
+    // the no-match path surfaces an error instead of defaulting (the file's own
+    // "out-of-vocab token -> must surface, not silent-default" rule).
+    if (!RECOGNISED_POST_WEIGHT_KEYS.has(k)) {
+      process.emitWarning(
+        `rwep_factors carries unrecognised key '${k}'; excluded from the derived sum`,
+        { type: 'RwepFactorUnrecognised', code: 'RWEP_FACTOR_UNRECOGNISED' },
+      );
+      continue;
+    }
     // reboot_required and patch_required_reboot are aliases for the SAME
     // post-weight contribution (scoreCustom collapses them). A block carrying
     // both must count it once; summing both double-counts the reboot weight,
@@ -495,7 +524,7 @@ function compare(cveId, catalog, opts) {
     cve_id: cveId,
     cvss: cvss,
     rwep: rwepValid ? rwep : null,
-    cvss_framework_sla: timeline(cvssEquivalent),
+    cvss_framework_sla: cvssAbsent ? { hours: null, label: 'CVSS unavailable — no framework SLA can be derived' } : timeline(cvssEquivalent),
     rwep_actual_sla: rwepValid ? timeline(rwep) : { hours: null, label: 'RWEP score unavailable' },
     delta,
     explanation,
@@ -735,4 +764,5 @@ module.exports = {
   RWEP_WEIGHTS,
   ACTIVE_EXPLOITATION_LADDER,
   RECOGNISED_FACTOR_KEYS,
+  RECOGNISED_POST_WEIGHT_KEYS,
 };

package/lib/source-advisories.js

@@ -204,10 +204,19 @@ function extractCveIds(text) {
  *
  * Returns [{ title, link, published, body }, ...].
  */
-const { parseFeed: tokenizerParseFeed } = require('./xml-tokenizer');
+const { parseFeedDetailed: tokenizerParseFeedDetailed } = require('./xml-tokenizer');
 
+// Parser errors are ALWAYS collected and surfaced — the tokenizer's loud-error
+// contract is no longer opt-in. The optional `errors` array is filled when a
+// caller passes one (so a reachable-but-unparsable feed reads 'partial' in the
+// refresh report instead of '0 new CVEs'). A caller that forgets the array
+// still triggers the always-on collection via parseFeedDetailed.
 function parseRssAtom(xml, errors = null) {
-  return tokenizerParseFeed(xml, errors);
+  const { items, errors: collected } = tokenizerParseFeedDetailed(xml);
+  if (Array.isArray(errors)) {
+    for (const e of collected) errors.push(e);
+  }
+  return items;
 }
 
 /**
@@ -291,9 +300,15 @@ function parseGitHubEvents(body, feed) {
  * GitHub account was removed — the .atom feed needs no API token and the
  * existing parseRssAtom tokenizer already handles its XML.
  */
-function parseGitLabActivity(body, feed) {
+function parseGitLabActivity(body, feed, errorsOut = null) {
   const errors = [];
   const entries = parseRssAtom(body, errors);
+  // Thread the Atom parse errors back to the caller's channel (checkFeed)
+  // instead of dropping them — a reachable-but-unparsable GitLab activity feed
+  // must read 'partial' in the refresh report, same as the RSS/Atom path.
+  if (Array.isArray(errorsOut)) {
+    for (const e of errors) errorsOut.push(e);
+  }
   const handle = feed.researcher_handle
     || (feed.url.match(/gitlab\.com\/([^/.]+)\.atom/) || [])[1]
     || null;
@@ -376,6 +391,11 @@ async function checkFeed(feed, ctx) {
   const res = await fetchFeed(feed, ctx);
   if (!res.ok) return { diffs: [], errors: 1, status: 'unreachable', _why: res.error };
   let items;
+  // Parse errors are collected on the XML-parsing feed kinds so a reachable-
+  // but-unparsable feed reads 'partial' in the report instead of silently
+  // returning 0 new CVEs (the loud-error contract was opt-in and the live
+  // path never opted in).
+  const parseErrors = [];
   if (feed.kind === 'csaf-index') {
     items = parseCsafIndex(res.body);
     // Flatten cves_from_filename onto cve_ids field uniformly.
@@ -384,10 +404,10 @@ async function checkFeed(feed, ctx) {
     items = parseGitHubEvents(res.body, feed);
     items = items.map((it) => ({ ...it, cve_ids: extractCveIds(`${it.title} ${it.body} ${it.link}`) }));
   } else if (feed.kind === 'gitlab-activity') {
-    items = parseGitLabActivity(res.body, feed);
+    items = parseGitLabActivity(res.body, feed, parseErrors);
     items = items.map((it) => ({ ...it, cve_ids: extractCveIds(`${it.title} ${it.body} ${it.link}`) }));
   } else {
-    items = parseRssAtom(res.body);
+    items = parseRssAtom(res.body, parseErrors);
     items = items.map((it) => ({ ...it, cve_ids: extractCveIds(`${it.title} ${it.body} ${it.link}`) }));
   }
   const diffs = [];
@@ -437,7 +457,18 @@ async function checkFeed(feed, ctx) {
       });
     }
   }
-  return { diffs, observations, errors: 0, status: 'ok' };
+  // Fold reachable-but-unparsable into a 'partial' status via a NEW channel.
+  // The integer `errors` field stays the unreachable count (0 here — the feed
+  // WAS reached) so the aggregate unreachable===FEEDS.length math and the
+  // refresh-* assertions that key off it keep working untouched.
+  return {
+    diffs,
+    observations,
+    errors: 0,
+    status: parseErrors.length ? 'partial' : 'ok',
+    parse_errors: parseErrors.length,
+    _parse_errors: parseErrors.slice(0, 5),
+  };
 }
 
 /**
@@ -452,10 +483,20 @@ const ADVISORIES_SOURCE = {
     const allDiffs = [];
     const allObservations = [];
     let unreachable = 0;
+    let parseErrorFeeds = 0;       // feeds reachable but with >=1 parse error
+    const parseErrorSamples = [];  // bounded sample of {message, position}
     for (const r of results) {
       allDiffs.push(...r.diffs);
       if (Array.isArray(r.observations)) allObservations.push(...r.observations);
       if (r.status === 'unreachable') unreachable++;
+      if (typeof r.parse_errors === 'number' && r.parse_errors > 0) {
+        parseErrorFeeds++;
+        if (Array.isArray(r._parse_errors)) {
+          for (const e of r._parse_errors) {
+            if (parseErrorSamples.length < 5) parseErrorSamples.push(e);
+          }
+        }
+      }
     }
     // Deduplicate by CVE-ID across feeds — multiple advisories for the
     // same CVE collapse to one entry with sources[] array of contributing
@@ -503,15 +544,23 @@ const ADVISORIES_SOURCE = {
       }
     }
     const observations = Array.from(obsByCve.values());
+    // Status ladder folds reachable-but-unparsable into 'partial'. The integer
+    // `errors` field stays the unreachable count (downstream refresh math keys
+    // off it); parse errors are surfaced via the separate parse_errors channel.
     const status =
-      unreachable === 0 ? 'ok' :
-      unreachable === FEEDS.length ? 'unreachable' : 'partial';
+      unreachable === FEEDS.length ? 'unreachable' :
+      (unreachable > 0 || parseErrorFeeds > 0) ? 'partial' :
+      'ok';
+    const summary = `${FEEDS.length - unreachable}/${FEEDS.length} feeds reachable; ${diffs.length} new CVE references found, ${observations.length} total CVE observations across primary advisory sources`
+      + (parseErrorFeeds > 0 ? `; ${parseErrorFeeds} feed${parseErrorFeeds === 1 ? '' : 's'} returned parse errors` : '');
     return {
       status,
       diffs,
       observations,
       errors: unreachable,
-      summary: `${FEEDS.length - unreachable}/${FEEDS.length} feeds reachable; ${diffs.length} new CVE references found, ${observations.length} total CVE observations across primary advisory sources`,
+      parse_errors: parseErrorFeeds,
+      _parse_errors: parseErrorSamples,
+      summary,
     };
   },
   // Report-only: no applyDiff. Operators route promising CVE IDs through

package/lib/ttp-mapper.js

@@ -36,6 +36,17 @@ function gapsFor(attackPattern, gapCatalog, atlasCatalog) {
 }
 
 function coverage(frameworkId, ttpId, gapCatalog, atlasCatalog) {
+  // Input guard before any deref — an empty / non-string frameworkId
+  // yielded frameworkPrefix='' which matched EVERY control via
+  // includes(''), and null/undefined threw on .split(). Match the
+  // { found:false } contract already used for an unknown TTP. Surface
+  // partially_covered_by / not_covered_by as an explicit null (not absent)
+  // so the no-match outcome is observable rather than a silent universal
+  // match.
+  if (typeof frameworkId !== 'string' || frameworkId.trim() === '') {
+    return { ttp_id: ttpId, found: false, error: 'frameworkId required', partially_covered_by: null, not_covered_by: null };
+  }
+
   const ttp = atlasCatalog[ttpId];
   if (!ttp) return { ttp_id: ttpId, found: false };
 
@@ -45,10 +56,27 @@ function coverage(frameworkId, ttpId, gapCatalog, atlasCatalog) {
   const gapDetail = ttp.framework_gap_detail || '';
   const hasFrameworkGap = ttp.framework_gap === true;
 
-  // Check if the requested framework has any coverage in the partially-helpful controls
+  // Check if the requested framework has any coverage in the partially-helpful
+  // controls. Match on the first hyphen-delimited segment of the control id
+  // (token-boundary), NOT bare substring containment: a bare includes() let
+  // 'IS' match 'NIST' and '' match everything. A control id matches when it
+  // begins with the prefix and the next char is a segment boundary (-, .) or
+  // end-of-string, so 'soc2' still matches 'soc2-z' but 'is' never matches
+  // 'nist-...'.
   const frameworkPrefix = frameworkId.split('-')[0].toLowerCase();
-  const partial = partialControls.find(c => c.toLowerCase().includes(frameworkPrefix));
-  const noHelp = noHelpControls.find(c => c.toLowerCase().includes(frameworkPrefix));
+  if (frameworkPrefix.length === 0) {
+    // frameworkId is a hyphen-led string (e.g. "-" or "-X") whose first
+    // segment is empty — same universal-match hazard, same fail-closed result.
+    return { ttp_id: ttpId, found: false, error: 'frameworkId required', partially_covered_by: null, not_covered_by: null };
+  }
+  const segMatch = (c) => {
+    const cl = String(c).toLowerCase();
+    if (!cl.startsWith(frameworkPrefix)) return false;
+    const next = cl.charAt(frameworkPrefix.length);
+    return next === '' || next === '-' || next === '.';
+  };
+  const partial = partialControls.find(segMatch);
+  const noHelp = noHelpControls.find(segMatch);
 
   return {
     ttp_id: ttpId,

package/lib/upstream-check-cli.js

@@ -80,4 +80,16 @@ function readManifest() {
     localManifest: readManifest(),
   });
   process.stdout.write(JSON.stringify(report) + "\n");
-})();
+})().catch((err) => {
+  // Any unexpected throw still yields one parseable JSON line on stdout and a
+  // clean exit, consistent with this probe's offline-degradation contract
+  // (missing freshness data is not an error for downstream callers, which parse
+  // res.stdout for the envelope). String(...) coerces the error to a primitive,
+  // so this JSON.stringify itself cannot throw. Exit 0 is the default — no prior
+  // non-zero exitCode is set on this path.
+  process.stdout.write(JSON.stringify({
+    ok: false,
+    error: String((err && err.message) || err),
+    source: "upstream-check",
+  }) + "\n");
+});

package/lib/validate-catalog-meta.js

@@ -85,6 +85,29 @@ function containsPlaceholder(s) {
   return PLACEHOLDER_TOKENS.some((re) => re.test(s));
 }
 
+// Round-trip ISO calendar-date check. Returns a Date for a real YYYY-MM-DD
+// calendar date, or null for anything malformed. Unlike a shape-only regex,
+// this rejects impossible dates (2026-13-99, 2026-04-31, 2026-02-29 in a
+// non-leap year): `new Date('2026-02-30T00:00:00Z')` does NOT throw — it rolls
+// over to March 2 with a valid getTime() — so the parsed Y-M-D must round-trip
+// back to the input components. Deliberately carries NO year-floor business
+// rule (a valid-but-old 1900-01-01 stays a valid date so the staleness branch,
+// not the validity branch, reports it).
+function parseIsoDateStrict(v) {
+  if (typeof v !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(v)) return null;
+  const d = new Date(v + 'T00:00:00Z');
+  if (Number.isNaN(d.getTime())) return null;
+  const [y, m, day] = v.split('-').map(Number);
+  if (
+    d.getUTCFullYear() !== y ||
+    d.getUTCMonth() + 1 !== m ||
+    d.getUTCDate() !== day
+  ) {
+    return null;
+  }
+  return d;
+}
+
 function validateMeta(catalogPath, opts) {
   const errors = [];
   const warnings = [];
@@ -92,7 +115,16 @@ function validateMeta(catalogPath, opts) {
   const meta = data._meta;
 
   if (!meta || typeof meta !== 'object') {
-    return ['missing _meta block'];
+    // Honor both return contracts. The rest of the body dereferences
+    // `meta.tlp` / `meta.source_confidence` / `meta.freshness_policy`, so it
+    // must NOT run when `meta` is absent or non-object. Return early in the
+    // SAME shape the caller asked for: includeWarnings callers (main()) get
+    // `{errors, warnings}` so `result.errors` is a real array and the loop
+    // reports a clean FAIL + continues; no-opts callers still get a non-empty
+    // `string[]`. This still FAILS — it only removes the uncaught TypeError.
+    errors.push('missing _meta block');
+    if (opts && opts.includeWarnings) return { errors, warnings };
+    return errors;
   }
 
   /* tlp */
@@ -176,14 +208,26 @@ function validateMeta(catalogPath, opts) {
      * the warning posture.
      */
     if (
-      typeof meta.last_updated === 'string' &&
+      meta.last_updated !== undefined &&
       typeof fp.stale_after_days === 'number' &&
       fp.stale_after_days > 0
     ) {
-      const lu = new Date(meta.last_updated + (
-        /^\d{4}-\d{2}-\d{2}$/.test(meta.last_updated) ? 'T00:00:00Z' : ''
-      ));
-      if (!Number.isNaN(lu.getTime())) {
+      const lu = parseIsoDateStrict(meta.last_updated);
+      if (lu === null) {
+        // Fail-closed on a malformed date instead of silently skipping the
+        // freshness gate. A NaN/impossible/wrong-shape last_updated is
+        // "invalid input" (error under --strict, warning by default), NOT
+        // "no opinion" — otherwise the staleness check fails open.
+        const msg =
+          `_meta.last_updated ${JSON.stringify(meta.last_updated)} is not a valid ISO date ` +
+          `(YYYY-MM-DD calendar date) — cannot evaluate freshness. ` +
+          `Promoted to an error under --strict.`;
+        if (opts && (opts.strict || opts.errorOnStale)) {
+          errors.push(msg);
+        } else {
+          warnings.push(msg);
+        }
+      } else {
         const ageDays = Math.floor((Date.now() - lu.getTime()) / 86400000);
         if (ageDays > fp.stale_after_days) {
           const msg =
@@ -255,4 +299,4 @@ if (require.main === module) {
   main();
 }
 
-module.exports = { validateMeta };
+module.exports = { validateMeta, parseIsoDateStrict };

package/lib/validate-cve-catalog.js

@@ -244,6 +244,16 @@ function isUsableDate(value) {
 function additionalChecks(key, entry, ctx) {
   const warnings = [];
 
+  // A non-object entry has no checkable sub-fields, and validate() already
+  // emits the top-level type error for it (lines 127-133). Guarding here turns
+  // the uncaught `entry.poc_available` TypeError on a null/array entry into a
+  // clean no-op so main() still prints that FAIL and continues to later
+  // entries instead of aborting the whole gate. The FAIL is preserved — it
+  // originates in validate(), not here.
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+    return [];
+  }
+
   // V1 — Hard Rule #14 conditional: poc + public-exploit URL → iocs required.
   if (entry.poc_available === true) {
     const sources = Array.isArray(entry.verification_sources)

package/lib/validate-playbooks.js

@@ -322,6 +322,16 @@ function obligationKey(o) {
 
 function checkCrossRefs(playbook, ctx, playbookIds) {
   const findings = [];
+  // A null/array/primitive playbook has no cross-refs to check, and validate()
+  // already emits the top-level `expected type "object", got null` error for
+  // it (main() line ~755). Guarding here turns the uncaught `playbook._meta`
+  // TypeError on a literal-null playbook file into a clean no-op so main()
+  // still reports the FAIL and continues to the remaining playbooks instead of
+  // aborting the whole gate. The FAIL is preserved — it originates in
+  // validate(), not here.
+  if (!playbook || typeof playbook !== 'object' || Array.isArray(playbook)) {
+    return findings;
+  }
   const meta = playbook._meta || {};
   const phases = playbook.phases || {};
   const domain = playbook.domain || {};
@@ -533,7 +543,15 @@ function checkCrossRefs(playbook, ctx, playbookIds) {
     // Case-insensitive + word-bounded so `HTTPS://`, `Curl`, and `fetch(` (no
     // trailing space) still flag a network source — otherwise an artifact could
     // ship under air_gap_mode with no offline alternative and run incomplete.
-    const netSourceRe = /(https?:\/\/|\bgh (?:api|release)\b|\bcurl\b|\bwget\b|\bfetch\b)/i;
+    // Network-source detection includes API-verb-phrased sources ("GET
+    // /directoryRoles via Graph", "Entra ID", "Okta", "Microsoft Graph") so a
+    // REST/Graph endpoint described in prose still flags under air_gap_mode and
+    // is not silently collected offline-incomplete. `api/v\d` is deliberately
+    // NOT a token — it false-positives on local code-scan artifacts that merely
+    // reference an API path. NOTE: lib/schemas/playbook.schema.json carries the
+    // same narrow `source` pattern and must be broadened in lockstep with this
+    // regex (main-thread item — that file is not edited here).
+    const netSourceRe = /(https?:\/\/|\bgh (?:api|release)\b|\bcurl\b|\bwget\b|\bfetch\b|\b(?:GET|POST|PUT|PATCH|DELETE)\s+\/|\bGraph\b|\b(?:Okta|Entra ID|Microsoft Graph)\b)/i;
     for (const [i, art] of (look.artifacts || []).entries()) {
       if (!art || typeof art !== 'object') continue;
       if (typeof art.source === 'string' && netSourceRe.test(art.source)) {