@blamejs/exceptd-skills 0.19.34 → 0.19.36

package/lib/collectors/sbom.js

@@ -172,13 +172,24 @@ function captureLockfile(p, ecosystem, parser, label) {
       path: p,
       size_bytes: Buffer.byteLength(content, "utf8"),
       ...stats,
+      // A parser that could not decode the structure returns `error`; the read
+      // itself succeeded, so the two failures carry different kinds downstream.
+      ...(stats && stats.error ? { error_kind: "lockfile_parse_failed" } : {}),
     };
   } catch (e) {
-    return { file: label, ecosystem, path: p, error: e.message };
+    return { file: label, ecosystem, path: p, error: e.message, error_kind: "lockfile_read_failed" };
   }
 }
 
-function findLockfiles(cwd) {
+// `errors` is the collector_errors channel: a directory the walk could not read
+// is a scan gap the operator has to see, not a silent zero. Required, not
+// defaulted: a default array would restore the discard-into-the-void behaviour
+// for any caller that forgets it, and neither this function nor
+// findSbomDocuments is exported, so no test could reach that caller.
+function findLockfiles(cwd, errors) {
+  if (!Array.isArray(errors)) {
+    throw new TypeError("findLockfiles: `errors` must be the collector_errors array — scan gaps have nowhere else to go");
+  }
   const found = [];
   for (const lf of LOCKFILES) {
     const p = path.join(cwd, lf.file);
@@ -196,7 +207,13 @@ function findLockfiles(cwd) {
         }
       }
     }
-  } catch { /* swallow */ }
+  } catch (e) {
+    errors.push({
+      artifact_id: "lockfile-inventory",
+      kind: "readdir_failed",
+      reason: `cwd root: ${e.message} — requirements*.txt variants were not enumerated`,
+    });
+  }
 
   for (const sub of SUBDIR_PROBE_PATHS) {
     const subDir = path.join(cwd, sub);
@@ -204,7 +221,18 @@ function findLockfiles(cwd) {
     try {
       if (!fs.statSync(subDir).isDirectory()) continue;
       entries = fs.readdirSync(subDir, { withFileTypes: true });
-    } catch { continue; }
+    } catch (e) {
+      // An absent probe dir is the normal case, not a gap. A permission or I/O
+      // failure on one that IS there means the subtree went unscanned.
+      if (e.code !== "ENOENT") {
+        errors.push({
+          artifact_id: "lockfile-inventory",
+          kind: "readdir_failed",
+          reason: `${sub}/: ${e.message} — subtree not scanned for lockfiles`,
+        });
+      }
+      continue;
+    }
     for (const e of entries) {
       if (e.isDirectory()) {
         // packages/* gets one more level for monorepo workspaces, no deeper.
@@ -242,7 +270,11 @@ function findLockfiles(cwd) {
   return found;
 }
 
-function findSbomDocuments(cwd) {
+// `errors` is required for the same reason it is on findLockfiles above.
+function findSbomDocuments(cwd, errors) {
+  if (!Array.isArray(errors)) {
+    throw new TypeError("findSbomDocuments: `errors` must be the collector_errors array — scan gaps have nowhere else to go");
+  }
   const found = [];
   for (const s of SBOM_FORMATS) {
     const p = path.join(cwd, s.file);
@@ -250,24 +282,41 @@ function findSbomDocuments(cwd) {
     // Open once and fstat the descriptor rather than existsSync→statSync→read:
     // ENOENT still skips, and there is no TOCTOU window.
     try { fd = fs.openSync(p, "r"); }
-    catch (e) { if (e.code === "ENOENT") continue; found.push({ file: s.file, format: s.format, error: e.message }); continue; }
+    catch (e) { if (e.code === "ENOENT") continue; found.push({ file: s.file, format: s.format, error: e.message, error_kind: "open_failed" }); continue; }
     try {
       const stat = fs.fstatSync(fd);
       let content;
       // Read from the open descriptor, never by path again. readFileSync(fd) loops
       // to EOF; a single readSync can return short on a network or FUSE mount,
       // NUL-padding the buffer and truncating otherwise-valid JSON.
-      try { content = fs.readFileSync(fd, "utf8"); } catch { content = null; }
+      try { content = fs.readFileSync(fd, "utf8"); } catch (e) {
+        content = null;
+        errors.push({
+          artifact_id: "sbom-document",
+          kind: "read_failed",
+          reason: `${s.file}: ${e.message} — component count not derived`,
+        });
+      }
       let component_count = null;
       if (content && s.format === "cyclonedx-1.x") {
         try {
           const j = JSON.parse(content);
           component_count = (j.components || []).length;
-        } catch {}
+        } catch (e) {
+          // A present-but-unparseable SBOM reported `null components` with no
+          // explanation, which reads as "no components" rather than "not read".
+          errors.push({
+            artifact_id: "sbom-document",
+            kind: "parse_failed",
+            reason: `${s.file}: ${e.message} — component count unavailable`,
+          });
+        }
       }
       found.push({ file: s.file, format: s.format, size_bytes: stat.size, component_count });
     } catch (e) {
-      found.push({ file: s.file, format: s.format, error: e.message });
+      // The descriptor opened; fstat is what failed here. Reporting it as an
+      // open failure sends the operator after the wrong thing.
+      found.push({ file: s.file, format: s.format, error: e.message, error_kind: "stat_failed" });
     } finally {
       if (fd !== undefined) { try { fs.closeSync(fd); } catch { /* non-fatal */ } }
     }
@@ -281,10 +330,31 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
   const root = path.resolve(cwd);
 
   // sbom-tool-available: a lockfile or an SBOM document is a sufficient proxy.
-  const lockfiles = findLockfiles(root);
-  const sbomDocuments = findSbomDocuments(root);
+  const lockfiles = findLockfiles(root, errors);
+  const sbomDocuments = findSbomDocuments(root, errors);
   const hasAnything = lockfiles.length > 0 || sbomDocuments.length > 0;
 
+  // A lockfile that was found but not read contributes no component count, so
+  // the inventory under-reports; the operator sees which one and why.
+  for (const l of lockfiles) {
+    if (!l.error) continue;
+    errors.push({
+      artifact_id: "lockfile-inventory",
+      kind: l.error_kind || "lockfile_read_failed",
+      reason: `${l.file}: ${l.error}`,
+    });
+  }
+  for (const s of sbomDocuments) {
+    if (!s.error) continue;
+    errors.push({
+      artifact_id: "sbom-document",
+      // Carried from the push site, mirroring the lockfile loop above: an
+      // fstat failure and an open failure are different operator actions.
+      kind: s.error_kind || "open_failed",
+      reason: `${s.file}: ${s.error}`,
+    });
+  }
+
   const artifacts = {
     "lockfile-inventory": {
       value: lockfiles.length
@@ -346,8 +416,13 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
       }
       npmLockfile.integrity_present_count = withIntegrity;
       npmLockfile.integrity_missing_count = withoutIntegrity;
-    } catch {
+    } catch (e) {
       // A malformed lockfile leaves the indicator unflipped: inconclusive, not miss.
+      errors.push({
+        artifact_id: "lockfile-inventory",
+        kind: "lockfile_parse_failed",
+        reason: `${npmLockfile.file}: ${e.message} — lockfile-no-integrity left undecided (inconclusive, not miss)`,
+      });
     }
   }
 
@@ -378,6 +453,15 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
       lockfiles_found: lockfiles.length,
       sbom_documents_found: sbomDocuments.length,
       ecosystems_detected: [...new Set(lockfiles.map(l => l.ecosystem))],
+      // Magnitude behind the lockfile-no-integrity verdict: "hit" alone does not
+      // say whether one entry or nine hundred resolve without a hash. Present
+      // only when an npm lockfile was found AND parsed.
+      ...(npmLockfile && npmLockfile.integrity_present_count != null
+        ? {
+          npm_integrity_present_count: npmLockfile.integrity_present_count,
+          npm_integrity_missing_count: npmLockfile.integrity_missing_count,
+        }
+        : {}),
     },
     collector_errors: errors,
   };

package/lib/collectors/scan-excludes.js

@@ -85,8 +85,9 @@ function walkTree(root, opts = {}) {
         }
         walk(full, depth + 1);
       } else if (entry.isSymbolicLink()) {
-        // A symlink Dirent is neither isDirectory() nor isFile(): never emitted.
-        try { fs.realpathSync(full); } catch { /* dangling link — ignore */ }
+        // A symlink Dirent is neither isDirectory() nor isFile(), so it is
+        // never traversed and never emitted — including a dangling one.
+        continue;
       } else if (entry.isFile()) {
         // A regular file cannot introduce a directory cycle, so no realpath /
         // `seen` check. Windows path.relative returns backslashes, so rel is

package/lib/cve-regression-watcher.js

@@ -7,9 +7,6 @@
  * it never mutates the catalog; each candidate is triage input.
  */
 
-const path = require('path');
-const fs = require('fs');
-
 const CVE_ID_RE = /^CVE-((?:19|20)\d{2})-\d{4,7}$/;
 
 /**

package/lib/framework-gap.js

@@ -159,6 +159,11 @@ function lagScore(frameworkId, controlGaps, globalFrameworks) {
  * free text. Omitting `opts.lessons` (parsed zeroday-lessons.json) yields a
  * report with no new-control section rather than an error. Returns
  * { frameworks, universal_gaps, new_control_requirements, theater_risks, summary }.
+ *
+ * `cveCatalog` is positional surface this function does not read — the scenario
+ * matches against `controlGaps` alone. It holds the fourth slot so `opts` stays
+ * fifth, and mirrors theaterCheck(), which does read its catalog. Dropping the
+ * parameter would silently bind every caller's `opts` argument to it instead.
  */
 function gapReport(frameworkIds, threatScenario, controlGaps, cveCatalog = {}, opts = {}) {
   const scenario = threatScenario.toLowerCase();

package/lib/lint-skills.js

@@ -100,8 +100,20 @@ function isStrictIsoCalendarDate(s) {
 const KEBAB_RE = /^[a-z0-9][a-z0-9-]*[a-z0-9]$/;
 const JSON_FILENAME_RE = /^[A-Za-z0-9._-]+\.json$/;
 
+// `helpExitCode` is null unless the run is over before linting starts: 0 after
+// --help, 2 after an unknown argument. parseArgs never terminates the process —
+// it returns the code and the caller must honour it and stop.
+//
+// The invariant this keeps: every exit in this file goes through safeExit(), so
+// no path here can write to stdout and then terminate synchronously. That is the
+// `process-exit-after-stdout-write` shape, and it is a convention held file-wide
+// rather than a repair of an observed truncation: Node writes pipe stdout
+// synchronously on Windows and Linux (asynchronously on macOS), and the help
+// block is a few hundred bytes, so process.exit() did not in fact truncate it
+// here. Holding the invariant means a future help block that grows, or a run on
+// a platform with async pipe writes, cannot reintroduce the class.
 function parseArgs(argv) {
-  const opts = { skill: null, quiet: false, strict: false };
+  const opts = { skill: null, quiet: false, strict: false, helpExitCode: null };
   for (let i = 2; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--skill') {
@@ -115,11 +127,13 @@ function parseArgs(argv) {
       opts.strict = true;
     } else if (a === '--help' || a === '-h') {
       printHelp();
-      process.exit(0);
+      opts.helpExitCode = 0;
+      return opts;
     } else {
       console.error(`Unknown argument: ${a}`);
       printHelp();
-      process.exit(2);
+      opts.helpExitCode = 2;
+      return opts;
     }
   }
   return opts;
@@ -798,6 +812,10 @@ function lintPlaybookAirGap() {
 
 function main() {
   const opts = parseArgs(process.argv);
+  if (opts.helpExitCode !== null) {
+    safeExit(opts.helpExitCode);
+    return;
+  }
   const manifest = readJson(MANIFEST_PATH);
 
   let skills = manifest.skills;
@@ -805,7 +823,8 @@ function main() {
     skills = skills.filter((s) => s.name === opts.skill);
     if (skills.length === 0) {
       console.error(`No skill named "${opts.skill}" in manifest.json`);
-      process.exit(2);
+      safeExit(2);
+      return;
     }
   }
 
@@ -888,6 +907,7 @@ function main() {
 
 // The frontmatter parser is exported so `watchlist` does not grow a second one.
 module.exports = {
+  parseArgs,
   parseFrontmatter,
   extractFrontmatterBlock,
   unquote,

package/lib/playbook-runner.js

@@ -1292,6 +1292,60 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
     analyze_complete: !!(analyzeResult && typeof analyzeResult === 'object'),
     validate_complete: !!(validateResult && typeof validateResult === 'object'),
   };
+
+  // Nothing downstream guards the analyze result's container shape: every
+  // bundle format maps over `analyze.matched_cves` directly, and so does
+  // analyzeFindingShape, so a non-object result or a non-array matched_cves
+  // throws before phase 7 produces any output at all. Normalizing once, here,
+  // is what makes the whole phase survive it — the run still emits an evidence
+  // bundle and the shape failure is readable on runtime_errors. The container
+  // and its elements are both normalized: every bundle builder dereferences an
+  // element, so one null inside an otherwise well-formed array aborts the phase
+  // exactly as a non-array container does.
+  const shapeOf = (v) => (v === null ? 'null' : Array.isArray(v) ? 'array' : typeof v);
+  const analyzeIsObject = !!analyzeResult && typeof analyzeResult === 'object' && !Array.isArray(analyzeResult);
+  if (!analyzeIsObject || !Array.isArray(analyzeResult.matched_cves)) {
+    pushRunError(runOpts._runErrors, {
+      kind: 'analyze_shape',
+      message: analyzeIsObject
+        ? `analyze.matched_cves is ${shapeOf(analyzeResult.matched_cves)}, expected an array; treated as empty`
+        : `analyze result is ${shapeOf(analyzeResult)}, expected an object; treated as empty`,
+    }, { dedupeKey: x => x.message || '' });
+    // A copy, so close() reports the caller's malformed result without
+    // rewriting it underneath them.
+    analyzeResult = { ...(analyzeIsObject ? analyzeResult : {}), matched_cves: [] };
+  } else {
+    // Dropped rather than repaired: a consumer cannot read a CVE id off a null,
+    // and inventing a placeholder entry would put a finding in the evidence
+    // bundle that the analyze phase never produced.
+    const usable = (e) => !!e && typeof e === 'object' && !Array.isArray(e);
+    const dropped = analyzeResult.matched_cves.filter((e) => !usable(e));
+    if (dropped.length) {
+      pushRunError(runOpts._runErrors, {
+        kind: 'analyze_shape',
+        message: `analyze.matched_cves holds ${dropped.length} malformed element(s) (${[...new Set(dropped.map(shapeOf))].join(', ')}); they are dropped and the remaining ${analyzeResult.matched_cves.length - dropped.length} are used`,
+      }, { dedupeKey: x => x.message || '' });
+      analyzeResult = { ...analyzeResult, matched_cves: analyzeResult.matched_cves.filter(usable) };
+    }
+  }
+
+  // The residual guard for the four sites that interpolate the finding shape —
+  // the notification draft, the auditor-ready exception language, the
+  // learning-loop lesson and the feeds_into finding context. The normalization
+  // above removes the shapes analyzeFindingShape is known to throw on; this
+  // catches anything it still throws on, degrading those four fields to
+  // `<MISSING:…>` and putting the throw on runtime_errors rather than aborting
+  // the phase.
+  const safeFindingShape = () => {
+    try { return analyzeFindingShape(analyzeResult); }
+    catch (e) {
+      pushRunError(runOpts._runErrors,
+        { kind: 'analyze_shape', message: (e && e.message) ? String(e.message) : String(e) },
+        { dedupeKey: x => x.message || '' });
+      return {};
+    }
+  };
+
   const enrichNotification = (na) => {
     const obligation = (g.jurisdiction_obligations || []).find(o =>
       o && typeof o === 'object' &&
@@ -1359,16 +1413,9 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
       // Which template vars failed to resolve; empty when all rendered.
       ...(function () {
         const missing = [];
-        // Wrapped so a malformed analyze result cannot bring down close();
-        // the failure surfaces through runOpts._runErrors instead.
-        let findingShape;
-        try { findingShape = analyzeFindingShape(analyzeResult); }
-        catch (e) {
-          if (Array.isArray(runOpts._runErrors)) {
-            pushRunError(runOpts._runErrors, { kind: 'analyze_shape', message: (e && e.message) ? String(e.message) : String(e) }, { dedupeKey: e => e.message || '' });
-          }
-          findingShape = {};
-        }
+        // safeFindingShape, not analyzeFindingShape: a malformed analyze result
+        // must not bring down close(); the failure surfaces on runtime_errors.
+        const findingShape = safeFindingShape();
         const draft = interpolate(
           na.draft_notification,
           { ...agentSignals, ...findingShape },
@@ -1416,7 +1463,11 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
       // does not supply, so the auditor-ready language routinely renders
       // `<MISSING:…>`. missing_interpolation_vars names which.
       const exMissing = [];
-      const findingShape = (() => { try { return analyzeFindingShape(analyzeResult); } catch { return {}; } })();
+      // safeFindingShape, like the other three shape consumers. The feeds_into
+      // context below reports the same throw on every close(), so this site's
+      // own disposition is not separately observable — it is uniform so a
+      // future reader does not read the bare catch as a deliberate exemption.
+      const findingShape = safeFindingShape();
       exception = {
         scope: interpolate(t.scope, { ...agentSignals, ...findingShape }, exMissing),
         duration: t.duration,
@@ -1492,7 +1543,7 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
 
   const lesson = c.learning_loop?.enabled ? {
     enabled: true,
-    attack_vector: interpolate(c.learning_loop.lesson_template.attack_vector, analyzeFindingShape(analyzeResult)),
+    attack_vector: interpolate(c.learning_loop.lesson_template.attack_vector, safeFindingShape()),
     control_gap: c.learning_loop.lesson_template.control_gap,
     framework_gap: c.learning_loop.lesson_template.framework_gap,
     new_control_requirement: c.learning_loop.lesson_template.new_control_requirement,
@@ -1542,7 +1593,7 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
     analyze: analyzeResult,
     validate: validateResult,
     // Same two-sourced finding.* shape and guards as the escalation context.
-    finding: { ...(agentSignals.finding && typeof agentSignals.finding === 'object' && !Array.isArray(agentSignals.finding) ? agentSignals.finding : {}), ...analyzeFindingShape(analyzeResult) },
+    finding: { ...(agentSignals.finding && typeof agentSignals.finding === 'object' && !Array.isArray(agentSignals.finding) ? agentSignals.finding : {}), ...safeFindingShape() },
     // Without the accumulator, a feeds_into condition failure never reaches
     // analyze.runtime_errors[].
     ...(runOpts._runErrors ? { _runErrors: runOpts._runErrors } : {})
@@ -2356,7 +2407,10 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
       '@id': productPurl,
       subcomponents: [{ '@id': productPurl }],
     };
-    const remediationId = validate.selected_remediation?.id || (validate.remediation_paths?.[0]?.id) || null;
+    // validate() selects the priority-1 path as its last rung, so a null
+    // selected_remediation means the phase declares no remediation paths at all
+    // and remediation_options_considered is empty too — there is no id to name.
+    const remediationId = validate.selected_remediation?.id || null;
     const remediationDescription = validate.selected_remediation?.description || null;
     const actionStatementFor = (fallback) => {
       if (remediationId && remediationDescription) {

package/lib/prefetch.js

@@ -487,8 +487,9 @@ function isFresh(idx, source, id, maxAgeMs) {
 
 function authHeadersForSource(source) {
   if (source === "nvd" && process.env.NVD_API_KEY) return { apiKey: process.env.NVD_API_KEY };
-  // `pins` is the registered source name; `github` is accepted too, so
-  // GITHUB_TOKEN reaches the header whichever spelling an operator uses.
+  // `pins` is the registered name for the MITRE GitHub releases feed. The
+  // `github` alias is defensive: no registered source emits it, and prefetch()
+  // refuses `--source github` before any header is built.
   if ((source === "pins" || source === "github") && process.env.GITHUB_TOKEN) {
     return { Authorization: `Bearer ${process.env.GITHUB_TOKEN}` };
   }

package/lib/refresh-external.js

@@ -1701,12 +1701,6 @@ async function main() {
   process.exitCode = cacheIntegrityFailure ? 4 : (hadFailure ? 1 : 0);
 }
 
-async function sequential(items, fn) {
-  const out = [];
-  for (const it of items) out.push(await fn(it));
-  return out;
-}
-
 if (require.main === module) {
   main().catch((err) => {
     // A hinted error prints its message plus a JSON line, never a stack trace.

package/lib/refresh-network.js

@@ -116,10 +116,9 @@ function getBufferOnce(url, timeoutMs) {
     if (!isAllowedTarballHost(url)) {
       return reject(new Error(`refusing to fetch tarball from non-allowlisted host: ${u.hostname}`));
     }
-    const cap = (() => {
-      const env = parseInt(process.env.EXCEPTD_TARBALL_SIZE_CAP_BYTES, 10);
-      return Number.isFinite(env) && env > 0 ? env : 200 * 1024 * 1024;
-    })();
+    // Same reader as the buffered-length check, so the streaming cap and the
+    // post-download cap cannot drift apart when the default changes.
+    const cap = tarballSizeCap();
     const req = https.get({
       host: u.host, path: u.pathname + u.search,
       headers: { "User-Agent": "exceptd/refresh-network" },

package/lib/scoring.js

@@ -431,10 +431,17 @@ function validate(catalog) {
   const errors = [];
   for (const [cveId, entry] of Object.entries(catalog)) {
     if (cveId.startsWith('_')) continue;
+    // A null or non-object entry cannot be walked field by field: `field in
+    // entry` throws, taking down validation of the whole catalog. Report it as
+    // the error it is, so the remaining entries are still checked.
+    if (!entry || typeof entry !== 'object') {
+      errors.push(`${cveId}: entry is ${entry === null ? 'null' : typeof entry}, expected an object`);
+      continue;
+    }
     // Drafts carry a conservative-default rwep_score beside null-until-curated
     // factor fields, so the divergence check below fires on every one. They are
     // reviewed through `_auto_imported_meta.curation_needed` instead.
-    if (entry && entry._auto_imported === true) continue;
+    if (entry._auto_imported === true) continue;
     for (const field of CVE_SCHEMA_REQUIRED) {
       if (!(field in entry)) {
         errors.push(`${cveId}: missing required field '${field}'`);

package/lib/ttp-mapper.js

@@ -28,7 +28,20 @@ function map(controlId, gapCatalog) {
   };
 }
 
+// The single source of gapsFor()'s no-match answer. Both routes to it — an
+// absent catalog and a present one that matched nothing — are the same answer
+// to the operator, so they must carry the same words.
+const noDocumentedGaps = (attackPattern) => ({
+  attack_pattern: attackPattern,
+  found_gaps: false,
+  message: 'No documented gaps for this pattern — verify manually'
+});
+
 function gapsFor(attackPattern, gapCatalog, atlasCatalog) {
+  // Object.entries(null) throws. An absent catalog is "nothing documented",
+  // which is the same answer an empty one gives — as in map(), the caller gets
+  // the module's no-data shape rather than an exception.
+  if (!gapCatalog || typeof gapCatalog !== 'object') return noDocumentedGaps(attackPattern);
   const results = [];
   for (const [controlId, entry] of Object.entries(gapCatalog)) {
     if (controlId.startsWith('_')) continue;
@@ -36,9 +49,7 @@ function gapsFor(attackPattern, gapCatalog, atlasCatalog) {
       results.push({ control_id: controlId, framework: entry.framework, control_name: entry.control_name, gap: entry.misses });
     }
   }
-  if (results.length === 0) {
-    return { attack_pattern: attackPattern, found_gaps: false, message: 'No documented gaps for this pattern — verify manually' };
-  }
+  if (results.length === 0) return noDocumentedGaps(attackPattern);
   return { attack_pattern: attackPattern, found_gaps: true, controls_with_gap: results };
 }
 

package/lib/upstream-check-cli.js

@@ -16,14 +16,25 @@ const { safeExit } = require("./exit-codes");
 const ROOT = path.resolve(__dirname, "..");
 const { fetchLatestPublished, buildFreshnessReport } = require("./upstream-check.js");
 
+// --flag base names this CLI accepts; drives the unknown-flag error message.
+const KNOWN_FLAGS = Object.freeze(["--timeout", "--raw", "--air-gap"]);
+
 function parseArgs(argv) {
-  const out = { timeoutMs: 5000, raw: false, airGap: false };
+  const out = { timeoutMs: 5000, raw: false, airGap: false, unknownFlags: [] };
   for (let i = 2; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--timeout") { out.timeoutMs = parseInt(argv[++i], 10) || 5000; }
     else if (a.startsWith("--timeout=")) { out.timeoutMs = parseInt(a.slice("--timeout=".length), 10) || 5000; }
     else if (a === "--raw") out.raw = true;
     else if (a === "--air-gap") out.airGap = true;
+    // Any remaining --flag is a typo; refused below, before any network work.
+    // Only `--`-prefixed tokens are collected, matching lib/prefetch.js: a
+    // single-dash `-air-gap` or an en-dashed `–air-gap` is not recognized here
+    // and still reaches the registry probe.
+    else if (a.startsWith("--")) {
+      const eq = a.indexOf("=");
+      out.unknownFlags.push(eq === -1 ? a : a.slice(0, eq));
+    }
   }
   return out;
 }
@@ -42,6 +53,20 @@ function readManifest() {
 
 (async () => {
   const opts = parseArgs(process.argv);
+  // Usage errors exit 2 on stderr, keeping stdout reserved for the one report
+  // line callers parse. Checked before the air-gap branch and the probe.
+  if (opts.unknownFlags.length > 0) {
+    const uniq = [...new Set(opts.unknownFlags)];
+    process.stderr.write(JSON.stringify({
+      ok: false,
+      source: "upstream-check",
+      error: `upstream-check: unknown flag(s): ${uniq.join(", ")}`,
+      unknown_flags: uniq,
+      known_flags: KNOWN_FLAGS,
+    }) + "\n");
+    process.exitCode = 2;
+    return;
+  }
   // The registry probe is a network call, so air-gap mode answers with a
   // `skipped` envelope instead. `ok: null` is neither pass nor fail.
   if (process.env.EXCEPTD_AIR_GAP === "1" || opts.airGap) {

package/lib/validate-cve-catalog.js

@@ -393,7 +393,11 @@ function main() {
           (missingFromSchema.length ? `  Missing from schema: ${JSON.stringify(missingFromSchema)}\n` : '') +
           `  Reconcile by updating one or the other so they agree exactly.\n`,
       );
-      process.exit(1);
+      // safeExit, not process.exit(): stderr is an async pipe under CI log
+      // capture, and exiting synchronously discards the diagnostic above while
+      // still failing the gate — a red run with no reason printed.
+      safeExit(1);
+      return;
     }
   }
 
@@ -415,7 +419,10 @@ function main() {
         `!= actual entry count (${f.actual}). Update _meta.entry_count to ${f.actual}.\n`,
       );
     }
-    process.exit(1);
+    // Same reason as the enum-mismatch exit above: the drift lines are the whole
+    // value of the failure, so the process must unwind rather than exit here.
+    safeExit(1);
+    return;
   }
 
   let failed = 0;

package/lib/validate-playbooks.js

@@ -98,11 +98,6 @@ function readJson(p) {
   return JSON.parse(fs.readFileSync(p, 'utf8'));
 }
 
-function readJsonIfExists(p) {
-  if (!fs.existsSync(p)) return null;
-  return readJson(p);
-}
-
 function typeOf(value) {
   if (value === null) return 'null';
   if (Array.isArray(value)) return 'array';
@@ -239,6 +234,9 @@ function loadContext() {
   const d3 = readJson(D3FEND_PATH);
   // Required, not optional: an optional load skips attack_ref validation silently.
   const attack = readJson(ATTACK_PATH);
+  if (!attack || typeof attack !== 'object' || Array.isArray(attack)) {
+    throw new Error(`validate-playbooks: ${ATTACK_PATH} did not parse to a technique map (got ${attack === null ? 'null' : typeof attack}). Refusing to validate with the attack_ref checks silently disabled.`);
+  }
 
   // Sourced from the schema so the hard-error checks in checkCrossRefs stay in
   // lockstep with its enum lists.
@@ -266,9 +264,9 @@ function loadContext() {
     cveKeys: new Set(Object.keys(cve).filter((k) => !k.startsWith('_'))),
     cweKeys: new Set(Object.keys(cwe).filter((k) => !k.startsWith('_'))),
     d3fendKeys: new Set(Object.keys(d3).filter((k) => !k.startsWith('_'))),
-    attackKeys: attack
-      ? new Set(Object.keys(attack).filter((k) => !k.startsWith('_')))
-      : null,
+    // Never nullable: a null here silently disables every attack_ref check, the
+    // exact failure the required load above exists to prevent.
+    attackKeys: new Set(Object.keys(attack).filter((k) => !k.startsWith('_'))),
     clockStartsEnum: clockStartsEnum ? new Set(clockStartsEnum) : null,
     frameworksEnum: frameworksEnum ? new Set(frameworksEnum) : null,
   };
@@ -347,7 +345,7 @@ function checkCrossRefs(playbook, ctx, playbookIds) {
   }
   // Hard Rule #4: domain-level TTPs resolve against the ATT&CK catalog.
   for (const a of domain.attack_refs || []) {
-    if (ctx.attackKeys && !ctx.attackKeys.has(a)) {
+    if (!ctx.attackKeys.has(a)) {
       warn(`domain.attack_refs: unresolved "${a}" (not in data/attack-techniques.json)`);
     }
   }
@@ -381,7 +379,7 @@ function checkCrossRefs(playbook, ctx, playbookIds) {
       }
       indIds.add(ind.id);
     }
-    if (ind.attack_ref && ctx.attackKeys && !ctx.attackKeys.has(ind.attack_ref)) {
+    if (ind.attack_ref && !ctx.attackKeys.has(ind.attack_ref)) {
       warn(
         `phases.detect.indicators[${i}].attack_ref: unresolved "${ind.attack_ref}" (not in data/attack-techniques.json)`,
       );
@@ -581,7 +579,7 @@ function checkCrossRefs(playbook, ctx, playbookIds) {
       if (at.atlas_ttp && !ctx.atlasKeys.has(at.atlas_ttp)) {
         warn(`${label}.applies_to.atlas_ttp: unresolved "${at.atlas_ttp}" (not in data/atlas-ttps.json)`);
       }
-      if (at.attack_technique && ctx.attackKeys && !ctx.attackKeys.has(at.attack_technique)) {
+      if (at.attack_technique && !ctx.attackKeys.has(at.attack_technique)) {
         warn(`${label}.applies_to.attack_technique: unresolved "${at.attack_technique}" (not in data/attack-techniques.json)`);
       }
     }