@blamejs/exceptd-skills 0.14.10 → 0.14.12

package/lib/collectors/citation-hygiene.js

@@ -30,7 +30,7 @@
 const fs = require("node:fs");
 const path = require("node:path");
 
-const { codeExcludeSet, isLinkedWorktreeDir, buildEvidenceLocations } = require("./scan-excludes");
+const { codeExcludeSet, isLinkedWorktreeDir, buildEvidenceLocations, lineFromOffset } = require("./scan-excludes");
 
 const COLLECTOR_ID = "citation-hygiene";
 
@@ -334,12 +334,15 @@ function collect({ cwd = process.cwd() } = {}) {
     for (const m of content.matchAll(CVE_CITATION_RE)) {
       const full = m[0];
       totalCveCitations++;
+      // 1-based line of the citation so the evidence location carries a SARIF
+      // startLine region. Does not change any hit/miss verdict.
+      const cveLine = lineFromOffset(content, m.index);
       const canonical = CVE_CANONICAL_RE.test(full);
       if (!canonical) {
         // Fabricated / malformed. Illustrative surfaces (templates,
         // fixtures, the format-explaining docs) are demoted.
         if (!illustrative) {
-          hits["fabricated-cve-id"].push({ file: f.rel, citation: full });
+          hits["fabricated-cve-id"].push({ file: f.rel, citation: full, line: cveLine });
         }
         continue;
       }
@@ -347,7 +350,7 @@ function collect({ cwd = process.cwd() } = {}) {
       if (cveKeys.has(full)) {
         const note = cveNotes.get(full) || "";
         if (REJECT_DISPUTE_RE.test(note) && !illustrative) {
-          hits["rejected-or-disputed-cve"].push({ file: f.rel, citation: full });
+          hits["rejected-or-disputed-cve"].push({ file: f.rel, citation: full, line: cveLine });
         }
       } else if (catalogsLoaded && !illustrative) {
         // Absent from the curated catalog: needs an external lookup.
@@ -362,6 +365,7 @@ function collect({ cwd = process.cwd() } = {}) {
       const num = Number(m[1]);
       if (!Number.isFinite(num)) continue;
       const line = lineAround(content, m.index);
+      const rfcLineNo = lineFromOffset(content, m.index);
       if (rfcTitles.has(num)) {
         const verdict = classifyRfcTitle(line, rfcTitles.get(num));
         if (verdict === "mismatch" && !illustrative) {
@@ -369,6 +373,7 @@ function collect({ cwd = process.cwd() } = {}) {
             file: f.rel,
             citation: `RFC ${num}`,
             real_title: rfcTitles.get(num),
+            line: rfcLineNo,
           });
         }
       } else if (catalogsLoaded && !illustrative) {
@@ -449,8 +454,8 @@ function collect({ cwd = process.cwd() } = {}) {
 
   // Per-indicator file locations for the indicators flipped to "hit",
   // so SARIF results point at the source file that carries the bad
-  // citation. The hits record the file but not a line, so locations are
-  // file-level (no startLine).
+  // citation. The hits record a 1-based `line` (from the match offset),
+  // so locations include a startLine region.
   const evidence_locations = {};
   for (const id of Object.keys(hits)) {
     if (signal_overrides[id] === "hit") {

package/lib/collectors/crypto-codebase.js

@@ -16,7 +16,7 @@
 
 const fs = require("node:fs");
 const path = require("node:path");
-const { codeExcludeSet, isLinkedWorktreeDir, buildEvidenceLocations } = require("./scan-excludes");
+const { codeExcludeSet, isLinkedWorktreeDir, buildEvidenceLocations, lineFromOffset } = require("./scan-excludes");
 
 const COLLECTOR_ID = "crypto-codebase";
 
@@ -298,14 +298,17 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
       if (RSA_1024_RE.test(content)) {
         hits["rsa-1024-anywhere"].push({ file: f.rel });
       }
+      // Attach a 1-based `line` (from the match offset) so the evidence
+      // location carries a SARIF startLine region rather than pointing at
+      // the file. Does not change hit/miss — the same matches still fire.
       const mrHits = scanMathRandom(content);
-      for (const h of mrHits) hits["math-random-in-security-path"].push({ file: f.rel, offset: h.offset });
+      for (const h of mrHits) hits["math-random-in-security-path"].push({ file: f.rel, offset: h.offset, line: lineFromOffset(content, h.offset) });
 
       const pHits = scanPbkdf2(content);
-      for (const h of pHits) hits["pbkdf2-under-iterated"].push({ file: f.rel, iter: h.iter, threshold: h.threshold });
+      for (const h of pHits) hits["pbkdf2-under-iterated"].push({ file: f.rel, offset: h.offset, line: lineFromOffset(content, h.offset), iter: h.iter, threshold: h.threshold });
 
       const bHits = scanBcrypt(content);
-      for (const h of bHits) hits["bcrypt-cost-low"].push({ file: f.rel, cost: h.cost });
+      for (const h of bHits) hits["bcrypt-cost-low"].push({ file: f.rel, offset: h.offset, line: lineFromOffset(content, h.offset), cost: h.cost });
 
       if (PEM_RE.test(content)) {
         hits["hardcoded-key-material"].push({ file: f.rel });
@@ -460,8 +463,10 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
   // no-ml-kem-implementation, fips-claim-without-runtime-activation,
   // vendored-pqc-no-provenance) describe a whole-repo state rather than a
   // single offending file, so they carry no file-level location. The
-  // call-site scans record the file but not a line, so locations are
-  // file-level (no startLine).
+  // offset-bearing call-site scans (math-random / pbkdf2 / bcrypt) now record
+  // a 1-based `line`, so their locations include a startLine region; the
+  // remaining whole-file scans (weak-hash / weak-cipher / rsa-1024 /
+  // hardcoded-key / tls) stay file-level (no startLine).
   const evidence_locations = {};
   for (const id of Object.keys(hits)) {
     if (signal_overrides[id] === "hit") {

package/lib/collectors/sbom.js

@@ -356,8 +356,15 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
       let withoutIntegrity = 0;
       const walk = (obj) => {
         if (!obj || typeof obj !== "object") return;
-        if (obj.integrity != null) withIntegrity++;
-        else if (obj.resolved != null || obj.version != null) withoutIntegrity++;
+        // Only remote-tarball entries (those with a `resolved` URL) are
+        // expected to carry an `integrity` hash. The npm 7+ root entry
+        // `"": { name, version }` legitimately has no `resolved` and no
+        // `integrity`, so keying off `version` would false-positive on
+        // every clean lockfile. Mirror library-author.js's guard.
+        if (obj.resolved != null) {
+          if (obj.integrity != null) withIntegrity++;
+          else withoutIntegrity++;
+        }
         for (const v of Object.values(obj)) if (v && typeof v === "object") walk(v);
       };
       walk(j.packages || j.dependencies || {});

package/lib/collectors/secrets.js

@@ -18,7 +18,7 @@
 
 const fs = require("node:fs");
 const path = require("node:path");
-const { codeExcludeSet, isLinkedWorktreeDir, buildEvidenceLocations } = require("./scan-excludes");
+const { codeExcludeSet, isLinkedWorktreeDir, buildEvidenceLocations, lineFromOffset } = require("./scan-excludes");
 
 const COLLECTOR_ID = "secrets";
 
@@ -83,6 +83,18 @@ const IAC_GLOB_PREFIX = ["pulumi.", "arm."];
 // source of truth for what counts as a hit; the collector
 // implements the same patterns so its signal_overrides match what
 // the runner would compute.
+// AWS-published documentation/example access-key IDs. These appear verbatim
+// throughout AWS docs, SDK samples, and countless READMEs, so a literal match
+// is example material, not a leaked credential. `cred-stores` demotes the same
+// value (its FP[0]); secrets.js must too or it false-positives on any README
+// that quotes the AWS docs. The 40-char example secret
+// (`wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY`) carries the literal `EXAMPLE`
+// token, which the AWS-secret-access-key pattern already requires elsewhere;
+// the access-key ID is the one that needs an explicit allowlist.
+const AWS_EXAMPLE_ACCESS_KEY_IDS = new Set([
+  "AKIAIOSFODNN7EXAMPLE",
+]);
+
 const INDICATOR_PATTERNS = [
   { id: "aws-access-key-id",          re: /\bAKIA[0-9A-Z]{16}\b/g },
   { id: "aws-secret-access-key",      re: /\baws_secret_access_key\s*[=:]\s*['"]?([A-Za-z0-9/+=]{40})['"]?/gi },
@@ -199,10 +211,16 @@ function scanContent(full, rel) {
     const matches = buf.matchAll(p.re);
     let count = 0;
     for (const m of matches) {
+      // Demote AWS-published example access-key IDs (e.g. the docs' canonical
+      // AKIAIOSFODNN7EXAMPLE). A README quoting the AWS docs must not hit.
+      if (p.id === "aws-access-key-id" && AWS_EXAMPLE_ACCESS_KEY_IDS.has(m[0])) continue;
       hits.push({
         indicator_id: p.id,
         file: rel,
         offset: m.index,
+        // 1-based line of the match so buildEvidenceLocations emits a region
+        // (SARIF startLine) instead of a bare file-level location.
+        line: lineFromOffset(buf, m.index),
         redacted_match: redactMatch(m[0]),
       });
       if (++count >= 5) break; // cap per-indicator-per-file
@@ -264,6 +282,15 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
     if (r.hits) allHits.push(...r.hits);
     if (r.skipped === "read_error") {
       errors.push({ artifact_id: "secret-regex-scan-text-files", kind: "read_failed", reason: `${f.rel}: ${r.reason}` });
+    } else if (r.skipped === "file_too_large") {
+      // A secret in the first bytes of a large file would otherwise be
+      // dropped silently. Record the skip so the operator knows this file
+      // was NOT scanned (mirrors crypto-codebase's >1 MB read_failed entry).
+      errors.push({
+        artifact_id: "secret-regex-scan-text-files",
+        kind: "file_too_large_skipped",
+        reason: `${f.rel}: ${r.bytes} bytes exceeds ${MAX_FILE_BYTES}-byte scan limit; not scanned for secrets`,
+      });
     }
   }
 
@@ -311,9 +338,10 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
 
   // Per-indicator file locations for every indicator flipped to "hit", so
   // a SARIF result points at the file carrying the secret / bad posture.
-  // Content-regex hits record a byte offset rather than a line, so these
-  // are file-level locations (no startLine). The file-presence and
-  // posture indicators contribute the carrier file path directly.
+  // Content-regex hits carry a 1-based `line` (derived from the match offset),
+  // so these locations include a startLine region. The file-presence and
+  // posture indicators contribute the carrier file path directly (file-level,
+  // no line).
   const evidence_locations = {};
   for (const p of INDICATOR_PATTERNS) {
     if (signal_overrides[p.id] === "hit") {

package/lib/cve-cli.js

@@ -28,7 +28,11 @@ const { resolveCve } = require("./citation-resolve.js");
     process.exitCode = 1;
     return;
   }
-  const id = argv.find((a) => !a.startsWith("--"));
+  // Trim the positional so a whitespace-only argument (`cve "   "`) is
+  // treated identically to a missing one (`cve ""`) — a usage error, not a
+  // "fabricated" lookup of the literal spaces.
+  const rawId = argv.find((a) => !a.startsWith("--"));
+  const id = rawId == null ? rawId : rawId.trim();
   const pretty = flags.has("--pretty");
   const json = flags.has("--json") || pretty;
 
@@ -41,7 +45,12 @@ const { resolveCve } = require("./citation-resolve.js");
   }
 
   const r = await resolveCve(id, { airGap: flags.has("--air-gap"), noNetwork: flags.has("--no-network") });
-  const body = { ok: true, verb: "cve", ...r };
+  // A citation that won't stand up exits non-zero so a CI/script gate trips.
+  // Derive `ok` from the same set of statuses that drive the exit code — a
+  // non-zero exit must carry ok:false, never the inverted ok:true the
+  // envelope previously hardcoded.
+  const fails = r.status === "rejected" || r.status === "fabricated" || r.status === "nonexistent" || r.status === "withdrawn";
+  const body = { verb: "cve", ...r, ok: !fails };
 
   if (json) {
     process.stdout.write(JSON.stringify(body, null, pretty ? 2 : 0) + "\n");
@@ -57,8 +66,7 @@ const { resolveCve } = require("./citation-resolve.js");
     if (r.reason) line += `\n  ${r.reason}`;
     process.stdout.write(line + "\n");
   }
-  // A citation that won't stand up is a non-zero exit so a CI/script gate trips.
-  if (r.status === "rejected" || r.status === "fabricated" || r.status === "nonexistent" || r.status === "withdrawn") {
+  if (fails) {
     process.exitCode = 2;
   }
 })();

package/lib/framework-gap.js

@@ -141,7 +141,7 @@ function lagScore(frameworkId, controlGaps, globalFrameworks) {
  * @param {object} cveCatalog - Parsed cve-catalog.json (optional)
  * @returns {{ frameworks: object, universal_gaps: object[], theater_risks: object[] }}
  */
-function gapReport(frameworkIds, threatScenario, controlGaps, cveCatalog = {}) {
+function gapReport(frameworkIds, threatScenario, controlGaps, cveCatalog = {}, opts = {}) {
   const scenario = threatScenario.toLowerCase();
 
   const relevantGaps = Object.entries(controlGaps).filter(([, gap]) => {
@@ -207,6 +207,25 @@ function gapReport(frameworkIds, threatScenario, controlGaps, cveCatalog = {}) {
       theater_test_present: !!g.theater_test,
     }));
 
+  // Summary matching count. With `all` frameworks the summary counts every
+  // scenario-relevant gap across the whole catalog (relevantGaps). With an
+  // explicit framework filter the summary must agree with the per-framework
+  // body the operator actually sees — otherwise `framework-gap nist-800-53
+  // <cve>` shows e.g. "2 matching control gap(s)" per-framework but "Summary:
+  // 8 matching gaps" (every framework's hits, pre-filter). Sum the per-
+  // framework gap_count so body + summary agree. De-duplicate by gap key in
+  // case a single gap matches multiple requested frameworks.
+  let matchingGapCount;
+  if (opts.allFrameworks) {
+    matchingGapCount = relevantGaps.length;
+  } else {
+    const seen = new Set();
+    for (const id of frameworkIds) {
+      for (const g of frameworkResults[id]?.gaps ?? []) seen.add(g.id);
+    }
+    matchingGapCount = seen.size;
+  }
+
   return {
     threat_scenario: threatScenario,
     frameworks: frameworkResults,
@@ -217,7 +236,7 @@ function gapReport(frameworkIds, threatScenario, controlGaps, cveCatalog = {}) {
     })),
     theater_risks: theaterRisks,
     summary: {
-      total_gaps: relevantGaps.length,
+      total_gaps: matchingGapCount,
       universal_gaps: universalGaps.length,
       theater_risk_controls: theaterRisks.length
     }

package/lib/playbook-runner.js

@@ -2345,7 +2345,7 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
       }] : [];
       const base = {
         scores,
-        threats: c.active_exploitation === 'confirmed' ? [{ category: 'exploit_status', details: 'Active exploitation confirmed (CISA KEV).' }] : [],
+        threats: c.active_exploitation === 'confirmed' ? [{ category: 'exploit_status', details: `Active exploitation confirmed${c.cisa_kev ? ' (CISA KEV)' : ''}.` }] : [],
         remediations,
         product_status: isFixed ? { fixed: [productId] } : { known_affected: [productId] }
       };
@@ -2473,9 +2473,18 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
       ? { tlp: { label: CSAF_TLP_LABEL[runOpts.tlp] }, text: `TLP:${runOpts.tlp}` }
       : null;
 
+    // CSAF 2.0: an advisory with zero vulnerabilities is a csaf_informational_advisory
+    // (Profile 5, which does not require /vulnerabilities) rather than a
+    // csaf_security_advisory (Profile 4, where an empty vulnerabilities array is
+    // semantically wrong and warns under strict profile validators). A clean run
+    // becomes an informational attestation; any firing CVE/indicator keeps the
+    // security-advisory category.
+    const csafCategory = (cveVulns.length + indicatorVulns.length) > 0
+      ? 'csaf_security_advisory'
+      : 'csaf_informational_advisory';
     return {
       document: {
-        category: 'csaf_security_advisory',
+        category: csafCategory,
         csaf_version: '2.0',
         publisher: publisherBlock,
         title: `exceptd finding: ${playbook.domain.name} (${analyze.matched_cves.length} CVE(s), ${indicatorHits.length} indicator hit(s), ${(analyze.framework_gap_mapping || []).length} framework gap(s))`,
@@ -2562,20 +2571,29 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
     // every rule definition is unambiguously attributable to one playbook,
     // and cross-playbook merges retain all results.
     const rulePrefix = `${playbookSlug}/`;
-    const cveResults = analyze.matched_cves.map(c => ({
-      ruleId: `${rulePrefix}${c.cve_id}`,
-      level: c.rwep >= 90 ? 'error' : c.rwep >= 70 ? 'warning' : 'note',
-      message: { text: `${c.cve_id}: RWEP ${c.rwep}, blast_radius ${analyze.blast_radius_score}. ${validate.selected_remediation?.description || ''}` },
-      properties: stripNulls({
-        kind: 'cve_match',
-        rwep: c.rwep,
-        cisa_kev: c.cisa_kev,
-        cisa_kev_due_date: c.cisa_kev_due_date ?? null,
-        active_exploitation: c.active_exploitation ?? null,
-        ai_discovered: c.ai_discovered ?? null,
-        blast_radius_score: analyze.blast_radius_score,
-      }),
-    }));
+    // CVE-match results get the coarse playbook-source location fallback
+    // (passing a null indicator skips the per-indicator evidence-locations
+    // branch). Without any `locations`, GitHub Code Scanning silently DROPS
+    // these results — the highest-severity result class would never surface.
+    const cveFallbackLocs = sarifLocationsForIndicator(playbook, null);
+    const cveResults = analyze.matched_cves.map(c => {
+      const result = {
+        ruleId: `${rulePrefix}${c.cve_id}`,
+        level: c.rwep >= 90 ? 'error' : c.rwep >= 70 ? 'warning' : 'note',
+        message: { text: `${c.cve_id}: RWEP ${c.rwep}, blast_radius ${analyze.blast_radius_score == null ? 'not assessed' : analyze.blast_radius_score}. ${validate.selected_remediation?.description || ''}` },
+        properties: stripNulls({
+          kind: 'cve_match',
+          rwep: c.rwep,
+          cisa_kev: c.cisa_kev,
+          cisa_kev_due_date: c.cisa_kev_due_date ?? null,
+          active_exploitation: c.active_exploitation ?? null,
+          ai_discovered: c.ai_discovered ?? null,
+          blast_radius_score: analyze.blast_radius_score,
+        }),
+      };
+      if (cveFallbackLocs) result.locations = cveFallbackLocs;
+      return result;
+    });
     const indicatorHits = (analyze._detect_indicators || []).filter(i => i.verdict === 'hit');
     const indicatorResults = indicatorHits.map(i => {
       const locs = sarifLocationsForIndicator(playbook, i);
@@ -2696,7 +2714,7 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
         vulnerability: { '@id': vulnIdToUrn(c.cve_id), name: c.cve_id },
         products: [productEntry],
         timestamp: issued,
-        impact_statement: `RWEP ${c.rwep}. Blast radius ${analyze.blast_radius_score}/5.`,
+        impact_statement: `RWEP ${c.rwep}. ${analyze.blast_radius_score == null ? 'Blast radius not assessed.' : `Blast radius ${analyze.blast_radius_score}/5.`}`,
       };
       if (c.vex_status === 'fixed') {
         stmt.status = 'fixed';
@@ -2767,11 +2785,14 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
       vexAuthor = vexOperatorClean;
     } else {
       vexAuthor = 'urn:exceptd:operator:unknown';
+      // Same shape + singleton dedupe as the CSAF path so a multi-format emit
+      // produces one canonical bundle_publisher_unclaimed entry that machine
+      // consumers can read consistently (reason/remediation, not message).
       pushRunError(runOpts._runErrors, {
         kind: 'bundle_publisher_unclaimed',
-        format: 'openvex',
-        message: 'OpenVEX author falls back to urn:exceptd:operator:unknown — supply runOpts.operator or runOpts.publisherNamespace to claim disposition attribution.',
-      });
+        reason: 'OpenVEX author fell back to urn:exceptd:operator:unknown because no --publisher-namespace and no URL-shaped --operator were supplied. Disposition attribution is unclaimed on this VEX document.',
+        remediation: 'Re-run with --publisher-namespace <https-url> (or a URL-shaped --operator).'
+      }, { dedupeKey: () => 'singleton' });
     }
     return {
       '@context': 'https://openvex.dev/ns/v0.2.0',

package/lib/prefetch.js

@@ -112,7 +112,7 @@ function parseArgs(argv) {
   for (let i = 2; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--force") out.force = true;
-    else if (a === "--no-network" || a === "--dry-run") out.noNetwork = true;
+    else if (a === "--no-network" || a === "--dry-run" || a === "--air-gap") out.noNetwork = true;
     else if (a === "--quiet") out.quiet = true;
     else if (a === "--help" || a === "-h") out.help = true;
     else if (a === "--source") out.source = argv[++i];
@@ -121,7 +121,17 @@ function parseArgs(argv) {
     else if (a.startsWith("--max-age=")) out.maxAgeMs = parseDuration(a.slice("--max-age=".length));
     else if (a === "--cache-dir") out.cacheDir = path.resolve(argv[++i]);
     else if (a.startsWith("--cache-dir=")) out.cacheDir = path.resolve(a.slice("--cache-dir=".length));
+    // Any remaining --flag is an unrecognized typo. Record it; main() refuses
+    // before any network work rather than silently dropping it.
+    else if (typeof a === "string" && a.startsWith("--")) {
+      const base = a.indexOf("=") === -1 ? a : a.slice(0, a.indexOf("="));
+      (out._unknownFlags || (out._unknownFlags = [])).push(base);
+    }
   }
+  // The global air-gap switch implies a report-only / no-egress run: treat
+  // EXCEPTD_AIR_GAP=1 the same as --no-network so prefetch never plans live
+  // fetches under air-gap.
+  if (process.env.EXCEPTD_AIR_GAP === "1") out.noNetwork = true;
   return out;
 }
 
@@ -646,12 +656,36 @@ function readCached(cacheDir, source, id, opts = {}) {
   }
 }
 
+// Known --flag base names prefetch accepts. Drives the unknown-flag error
+// message's known list.
+const PREFETCH_KNOWN_FLAGS = Object.freeze([
+  "--force", "--no-network", "--dry-run", "--air-gap", "--quiet", "--help", "-h",
+  "--source", "--max-age", "--cache-dir",
+]);
+
 async function main() {
   const opts = parseArgs(process.argv);
   if (opts.help) {
     printHelp();
     return;
   }
+
+  // Reject unknown flags BEFORE any network work. A swallowed typo (e.g.
+  // `--max-aeg 12h`) previously fell through to a default full-cache fetch.
+  // Exit 2 matches prefetch's existing usage-error convention (invalid
+  // --source / --max-age also surface as exit 2 via main()'s catch).
+  if (Array.isArray(opts._unknownFlags) && opts._unknownFlags.length > 0) {
+    const uniq = [...new Set(opts._unknownFlags)];
+    process.stderr.write(JSON.stringify({
+      ok: false,
+      verb: "prefetch",
+      error: `prefetch: unknown flag(s): ${uniq.join(", ")}`,
+      unknown_flags: uniq,
+      known_flags: PREFETCH_KNOWN_FLAGS,
+    }) + "\n");
+    process.exitCode = 2;
+    return;
+  }
   // Why process.exitCode and not process.exit():
   // On Windows + Node 25 (libuv), calling process.exit() synchronously
   // while in-flight fetch / AbortController teardown is still mid-close

package/lib/refresh-external.js

@@ -109,6 +109,22 @@ function parseArgs(argv) {
     // older than 7d or one that was prefetched without a signing keypair.
     // EXCEPTD_FORCE_STALE=1 mirrors for non-interactive automation.
     else if (a === "--force-stale") out.forceStale = true;
+    // Aliases that bin/exceptd.js may pass through or translate; accept them
+    // here so the unknown-flag guard below doesn't false-reject a legitimate
+    // operator invocation. (--no-network / --indexes-only / --network /
+    // --curate / --prefetch are normally rewritten upstream, but tolerate
+    // them when refresh-external is invoked directly.)
+    else if (
+      a === "--no-network" || a === "--prefetch" || a === "--indexes-only" ||
+      a === "--network" || a === "--curate" || a === "--force-stale-acked"
+    ) { /* accepted, no-op at this layer */ }
+    // Any remaining --flag is an unrecognized typo. Record it; refuse after
+    // the loop rather than silently dropping it into a default full-refresh
+    // (which previously hit the live network on every source).
+    else if (typeof a === "string" && a.startsWith("--")) {
+      const base = a.indexOf("=") === -1 ? a : a.slice(0, a.indexOf("="));
+      (out._unknownFlags || (out._unknownFlags = [])).push(base);
+    }
   }
   if (process.env.EXCEPTD_FORCE_STALE === "1") out.forceStale = true;
   // Report-only is intrinsic to the advisory poll regardless of flag order —
@@ -202,10 +218,11 @@ Outputs:
 
 Exit codes (refresh's own scheme — distinct from the seven-phase verbs):
   0  applied (or a clean dry-run with no diffs to surface)
+  1  apply-mode downstream gate failed (build-indexes, or a per-source error)
   2  error (unknown --source, unreadable fixture, invalid --advisory id, air-gap refusal)
   3  draft produced, editorial review pending (a successful --advisory seed —
      NOT a failure; run --advisory <id> --apply to land it, or curate first)
-  4  network/source unreachable
+  4  network/source unreachable OR cache precondition refused (unsigned/stale/tampered/unindexed cache)
 Note: exit 3 here means "review needed", which differs from \`exceptd run\`'s
 exit 3 ("ran but no evidence"). Script \`refresh --advisory\` on the body's
 \`ok\` field, not on \`$? == 0\`.
@@ -1252,8 +1269,18 @@ async function withCatalogLock(catalogPath, mutator) {
 }
 
 function chosenSources(opts) {
-  if (!opts.source) return Object.values(ALL_SOURCES);
+  // Flag-absent (opts.source == null) means "all sources" — the default
+  // refresh behavior. Flag-present-but-empty (`--source ""`, or a value that
+  // trims to nothing like `--source ","`) is an operator error, not a
+  // silent run-everything: refuse and list the valid names so the typo is
+  // visible rather than masquerading as a full refresh.
+  if (opts.source == null) return Object.values(ALL_SOURCES);
   const names = opts.source.split(",").map((s) => s.trim()).filter(Boolean);
+  if (names.length === 0) {
+    const err = new Error(`refresh-external: --source requires at least one source name. Valid: ${Object.keys(ALL_SOURCES).join(", ")}`);
+    err._exceptd_unknown_source = true;
+    throw err;
+  }
   const out = [];
   for (const n of names) {
     if (!ALL_SOURCES[n]) {
@@ -1412,6 +1439,15 @@ async function seedSingleAdvisory(opts) {
   process.exitCode = 3;
 }
 
+// Known --flag base names refresh accepts (operator-facing surface + the
+// bin-translated aliases). Drives the unknown-flag error message's known list.
+const REFRESH_KNOWN_FLAGS = Object.freeze([
+  "--apply", "--quiet", "--swarm", "--json", "--help", "-h", "--advisory",
+  "--check-advisories", "--catalog", "--from-cache", "--source", "--from-fixture",
+  "--report-out", "--air-gap", "--force-stale", "--force-stale-acked",
+  "--no-network", "--prefetch", "--indexes-only", "--network", "--curate",
+]);
+
 async function main() {
   const opts = parseArgs(process.argv);
   if (opts.help) {
@@ -1421,6 +1457,22 @@ async function main() {
     return;
   }
 
+  // Reject unknown flags BEFORE any network / catalog work. A swallowed typo
+  // (e.g. `--aply`) previously fell through to a default all-sources live
+  // refresh. Exit 2 matches refresh's own scheme (2 = error / unknown source).
+  if (Array.isArray(opts._unknownFlags) && opts._unknownFlags.length > 0) {
+    const uniq = [...new Set(opts._unknownFlags)];
+    process.stderr.write(JSON.stringify({
+      ok: false,
+      verb: "refresh",
+      error: `refresh: unknown flag(s): ${uniq.join(", ")}`,
+      unknown_flags: uniq,
+      known_flags: REFRESH_KNOWN_FLAGS,
+    }) + "\n");
+    process.exitCode = 2;
+    return;
+  }
+
   // v0.12.0: `--advisory <id>` short-circuits the normal source loop and
   // seeds a single CVE catalog entry from GHSA. Exits non-zero ("draft
   // written, please review") so CI pipelines surface the needed editorial
@@ -1428,7 +1480,7 @@ async function main() {
   // the seed is printed to stdout for review.
   // An empty --advisory value (`--advisory ""` / `--advisory=`) must error
   // rather than silently falling through to a full-refresh dry-run.
-  if (opts.advisory === "") {
+  if (opts.advisory != null && opts.advisory.trim() === "") {
     process.stderr.write(JSON.stringify({
       ok: false,
       error: "refresh: --advisory requires a non-empty identifier (e.g. CVE-2026-1234, GHSA-xxxx-xxxx-xxxx, MAL-2026-1).",
@@ -1496,11 +1548,22 @@ async function main() {
     ? await Promise.all(sources.map(runOne))
     : await sequential(sources, runOne);
 
+  // Cache-integrity refusals (sha256 mismatch, missing/partial _index.json,
+  // unindexed payload) are thrown by readCachedJson with _exceptd_exit_code=4
+  // but caught inside runOne and returned as a per-source error — so the
+  // throw never reaches main().catch where the code is otherwise honored.
+  // Carry the marker through here so main() can prefer exit 4 (BLOCKED /
+  // precondition refusal) over the generic per-source-failure exit 1.
+  let cacheIntegrityFailure = false;
   for (const { src, diff, error } of outcomes) {
     if (error) {
       log(`\n  [${src.name}] ${src.description}`);
       log(`    error: ${error.message}`);
       report.sources[src.name] = { status: "error", error: error.message };
+      if (error._exceptd_cache_integrity || error._exceptd_exit_code === 4) {
+        report.sources[src.name].cache_integrity = true;
+        cacheIntegrityFailure = true;
+      }
       hadFailure = true;
       continue;
     }
@@ -1550,7 +1613,10 @@ async function main() {
   // truncate buffered stdout (refresh-report path log line, summary log
   // lines piped to a consumer). exitCode + return lets the event loop end
   // naturally and stdout drains in full.
-  process.exitCode = hadFailure ? 1 : 0;
+  // Prefer the documented BLOCKED (4) code when any source refused on a
+  // cache-integrity precondition; fall back to generic failure (1) for other
+  // per-source errors / downstream gate failures.
+  process.exitCode = cacheIntegrityFailure ? 4 : (hadFailure ? 1 : 0);
 }
 
 async function sequential(items, fn) {

package/lib/refresh-network.js

@@ -45,14 +45,16 @@ const PKG_NAME = "@blamejs/exceptd-skills";
 const REQUEST_TIMEOUT_MS = 15000;
 
 function parseArgs(argv) {
-  const out = { force: false, dryRun: false, timeoutMs: REQUEST_TIMEOUT_MS, json: false };
+  const out = { force: false, dryRun: false, timeoutMs: REQUEST_TIMEOUT_MS, json: false, airGap: false };
   for (let i = 2; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--force") out.force = true;
     else if (a === "--dry-run") out.dryRun = true;
     else if (a === "--json") out.json = true;
+    else if (a === "--air-gap") out.airGap = true;
     else if (a === "--timeout") out.timeoutMs = parseInt(argv[++i], 10) || REQUEST_TIMEOUT_MS;
   }
+  if (process.env.EXCEPTD_AIR_GAP === "1") out.airGap = true;
   return out;
 }
 
@@ -275,6 +277,19 @@ async function main() {
   const localPkg = JSON.parse(fs.readFileSync(path.join(ROOT, "package.json"), "utf8"));
   const localVersion = localPkg.version;
 
+  // Air-gap refusal. --network needs egress to registry.npmjs.org for the
+  // /latest metadata + tarball pull. Under air-gap there is no offline
+  // substitute (the test fixture path remains available for offline tests),
+  // so refuse before any network attempt and point at the offline workflow.
+  if (opts.airGap && !process.env.EXCEPTD_REGISTRY_FIXTURE) {
+    emit({
+      ok: false,
+      source: "air-gap",
+      error: "air-gap: refresh --network requires network egress; refused. Use --from-cache --apply for the offline path.",
+    }, opts.json);
+    process.exitCode = 4; return;
+  }
+
   progress(`local v${localVersion} — querying npm registry...`, opts.json);
 
   let meta;

package/lib/rfc-cli.js

@@ -57,7 +57,12 @@ const { resolveRfc } = require("./citation-resolve.js");
     const a = norm(claimedTitle), b = norm(r.title);
     titleMatch = a.length > 0 && (b.includes(a) || a.includes(b));
   }
-  const body = { ok: true, verb: "rfc", ...r, ...(claimedTitle ? { claimed_title: claimedTitle, title_match: titleMatch } : {}) };
+  // Derive `ok` from the resolved status + title-check the same way the exit
+  // code is derived below — a non-zero exit (status nonexistent OR an explicit
+  // title mismatch) must carry ok:false, not the inverted ok:true the envelope
+  // previously hardcoded.
+  const fails = r.status === "nonexistent" || titleMatch === false;
+  const body = { verb: "rfc", ...r, ...(claimedTitle ? { claimed_title: claimedTitle, title_match: titleMatch } : {}), ok: !fails };
 
   if (json) {
     process.stdout.write(JSON.stringify(body, null, pretty ? 2 : 0) + "\n");
@@ -77,5 +82,5 @@ const { resolveRfc } = require("./citation-resolve.js");
     process.stdout.write(line + "\n");
   }
   // A mismatched or nonexistent citation is a non-zero exit for gates.
-  if (r.status === "nonexistent" || titleMatch === false) process.exitCode = 2;
+  if (fails) process.exitCode = 2;
 })();