@blamejs/exceptd-skills 0.14.9 → 0.14.11

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;
 

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

@@ -1545,16 +1545,21 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
     const obligation = (g.jurisdiction_obligations || []).find(o =>
       `${o.jurisdiction}/${o.regulation} ${o.window_hours}h` === na.obligation_ref
     );
-    // Thread runOpts through so computeClockStart can check
-    // operator_consent.explicit before auto-stamping detect_confirmed.
-    const clockStart = obligation ? computeClockStart(obligation.clock_starts, agentSignals, runOpts) : null;
-    // When the clock event is detect_confirmed AND the classification
-    // matched AND the operator did NOT pass --ack, surface
-    // clock_pending_ack so the notification record is visibly waiting on
-    // acknowledgement.
+    // Thread runOpts + the engine-computed classification through so
+    // computeClockStart can check operator_consent.explicit before
+    // auto-stamping detect_confirmed, and so an engine-confirmed detection
+    // starts the clock even without a separately-submitted classification.
+    const engineClassification = analyzeResult?._detect_classification || null;
+    const clockStart = obligation
+      ? computeClockStart(obligation.clock_starts, agentSignals, runOpts, engineClassification)
+      : null;
+    // When the clock event is detect_confirmed AND detection was confirmed
+    // (by the agent OR the engine) AND the operator did NOT pass --ack,
+    // surface clock_pending_ack so the notification record is visibly waiting
+    // on acknowledgement.
     const clockPendingAck = !clockStart
       && obligation?.clock_starts === 'detect_confirmed'
-      && agentSignals?.detection_classification === 'detected'
+      && (agentSignals?.detection_classification === 'detected' || engineClassification === 'detected')
       && !(runOpts && runOpts.operator_consent && runOpts.operator_consent.explicit === true);
     const deadline = obligation && clockStart
       ? new Date(clockStart.getTime() + obligation.window_hours * 3600 * 1000).toISOString()
@@ -3571,13 +3576,21 @@ function stripOuterParens(expr) {
  *     waiting on acknowledgement.
  *   - All other events without an explicit timestamp: return null.
  */
-function computeClockStart(eventName, agentSignals, runOpts = {}) {
+function computeClockStart(eventName, agentSignals, runOpts = {}, engineClassification = null) {
   // The agent submits clock_started_at_<event> ISO strings as it progresses.
   const key = `clock_started_at_${eventName}`;
   if (agentSignals && agentSignals[key]) return new Date(agentSignals[key]);
   // For detect_confirmed: only auto-stamp when the operator has explicitly
   // acknowledged the result via --ack. Otherwise leave the clock pending.
-  if (eventName === 'detect_confirmed' && agentSignals?.detection_classification === 'detected'
+  // Detection is "confirmed" when EITHER the agent submitted
+  // detection_classification:'detected' OR the engine itself classified the
+  // detect phase as 'detected'. Pre-fix only the agent-submitted signal was
+  // honored, so an engine-confirmed detection (indicators fired from
+  // signal_overrides without a separate classification submission) never
+  // started the regulatory clock — notification deadlines silently stalled.
+  const detected = agentSignals?.detection_classification === 'detected'
+    || engineClassification === 'detected';
+  if (eventName === 'detect_confirmed' && detected
       && runOpts && runOpts.operator_consent && runOpts.operator_consent.explicit === true) {
     return new Date();
   }

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];
@@ -122,6 +122,10 @@ function parseArgs(argv) {
     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));
   }
+  // 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;
 }
 

package/lib/refresh-external.js

@@ -202,10 +202,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 +1253,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]) {
@@ -1428,7 +1439,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 +1507,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 +1572,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;