@blamejs/exceptd-skills 0.18.8 → 0.18.11

package/orchestrator/pipeline.js

@@ -140,26 +140,52 @@ function _loadManifestCached() {
   return parsed;
 }
 
+/**
+ * Compute the currency row for a single skill against a reference `now`.
+ *
+ * Pulled out of currencyCheck so the parse-guard is unit-testable without a
+ * real manifest read. A malformed `last_threat_review` (e.g. "2026-13-99",
+ * which is structurally ISO-shaped but not a real calendar date) must map to
+ * maximally STALE — score 0, action_required true — not to the safe-LOOKING
+ * 100 a NaN delta would otherwise yield. The misformat is also surfaced via
+ * `unparseable_review_date` so a bad date is OBSERVABLE rather than silently
+ * defaulting (matching the project rule that a no-match/fall-through path must
+ * surface, not silently pass).
+ *
+ * @param {object} skill
+ * @param {Date} now
+ */
+function _skillCurrencyRow(skill, now) {
+  const rawDate = skill.last_threat_review || '2020-01-01';
+  // Use the timezone-stable date-only convention the sibling builders use
+  // (append T00:00:00Z for bare YYYY-MM-DD) so the day delta doesn't shift by
+  // the runner's local offset.
+  const t = Date.parse(/^\d{4}-\d{2}-\d{2}$/.test(rawDate) ? rawDate + 'T00:00:00Z' : rawDate);
+  const unparseable = !Number.isFinite(t);
+  const reviewDate = unparseable ? new Date('2020-01-01T00:00:00Z') : new Date(t);
+  const daysSinceReview = Math.floor((now - reviewDate) / (1000 * 60 * 60 * 24));
+
+  const currencyScore = _currencyScore(daysSinceReview, skill.forward_watch?.length || 0);
+
+  return {
+    skill: skill.name,
+    last_threat_review: skill.last_threat_review,
+    days_since_review: daysSinceReview,
+    currency_score: currencyScore,
+    currency_label: _currencyLabel(currencyScore),
+    forward_watch_count: skill.forward_watch?.length || 0,
+    unparseable_review_date: unparseable,
+    action_required: currencyScore < 70
+  };
+}
+
 function currencyCheck() {
   const manifest = _loadManifestCached();
   const now = new Date();
   const report = [];
 
   for (const skill of manifest.skills) {
-    const reviewDate = new Date(skill.last_threat_review || '2020-01-01');
-    const daysSinceReview = Math.floor((now - reviewDate) / (1000 * 60 * 60 * 24));
-
-    const currencyScore = _currencyScore(daysSinceReview, skill.forward_watch?.length || 0);
-
-    report.push({
-      skill: skill.name,
-      last_threat_review: skill.last_threat_review,
-      days_since_review: daysSinceReview,
-      currency_score: currencyScore,
-      currency_label: _currencyLabel(currencyScore),
-      forward_watch_count: skill.forward_watch?.length || 0,
-      action_required: currencyScore < 70
-    });
+    report.push(_skillCurrencyRow(skill, now));
   }
 
   report.sort((a, b) => a.currency_score - b.currency_score);
@@ -190,6 +216,18 @@ function getAgentDefinition(stageName) {
 // --- private helpers ---
 
 function validateHandoff(stageName, output) {
+  // Guard the `in` deref below: a null / non-object / array `output` would
+  // otherwise throw an opaque "Cannot use 'in' operator …" TypeError deep in
+  // the missing-fields filter. Reject up front with a named error in the same
+  // style as buildHandoff's stageIndex RangeError, so the caller sees which
+  // input was wrong. A handoff payload is a keyed object — an array is not a
+  // valid payload, so Array.isArray is rejected too (today it would yield the
+  // less-precise "missing fields" error).
+  if (output === null || typeof output !== 'object' || Array.isArray(output)) {
+    throw new TypeError(
+      `buildHandoff: stageOutput for ${stageName} must be a non-null object`
+    );
+  }
   const required = {
     'threat-researcher': ['cve_id_or_ttp', 'findings', 'primary_sources', 'confidence'],
     'source-validator': ['verdict', 'verified_claims', 'rejected_claims'],
@@ -240,6 +278,13 @@ function _currencyScore(daysSinceReview, _forwardWatchCount) {
   // and the workflow issue they gate — could never fire. The deeper penalties
   // only bite past 180/270/365 days, so a normally-maintained skill stays
   // 'acceptable' while a genuinely abandoned one reaches the gate.
+  //
+  // Belt-and-suspenders: a NaN delta (the day-count derived from an
+  // unparseable last_threat_review) must map to maximally STALE (0), never the
+  // safe-LOOKING 100 the additive schedule below would leave it at. This is an
+  // exported surface other callers/tests use, so guard here even though
+  // _skillCurrencyRow already substitutes a stale fallback date upstream.
+  if (!Number.isFinite(daysSinceReview)) return 0;
   let score = 100;
   if (daysSinceReview > 365) score -= 100;      // a year+ unreviewed → 0 (critical_stale)
   else if (daysSinceReview > 270) score -= 60;  // → 40 (critical_stale, < 50)
@@ -277,4 +322,7 @@ module.exports = {
   // Exported for the gate-reachability contract test: the schedule must be able
   // to reach the warn (< 70) and critical (< 50) tiers the workflow issues on.
   _currencyScore,
+  // Exported so the malformed-date staleness guard is unit-testable without a
+  // real manifest read.
+  _skillCurrencyRow,
 };

package/orchestrator/scanner.js

@@ -15,6 +15,30 @@ const { execFileSync, spawnSync } = require('child_process');
 
 const DATA_DIR = process.env.EXCEPTD_DATA_DIR || path.join(__dirname, '..', 'data');
 
+// CLI flags that request air-gap (no-egress) operation. `--air-gap` is the
+// documented form; `--offline` / `--no-network` are accepted aliases (the
+// orchestrator's flag allowlists accept all three). The flag MUST be honored
+// equivalently to EXCEPTD_AIR_GAP=1 on the egress path — historically the env
+// var suppressed the outbound TLS probe but the CLI flag did not, so an
+// operator passing `--air-gap` still fired a TLS s_client connect.
+const AIR_GAP_FLAGS = ['--air-gap', '--offline', '--no-network'];
+
+/**
+ * Resolve whether air-gap mode is active. True when EXCEPTD_AIR_GAP=1, when an
+ * explicit `opts.airGap` is passed, OR when any air-gap flag is present on the
+ * invoking process's argv. Checking argv makes the CLI flag effective even
+ * though the scanner is reached in-process from the orchestrator entry — the
+ * flag and the env var are now equivalent on the egress path.
+ *
+ * @param {{ airGap?: boolean }} [opts]
+ */
+function isAirGap(opts) {
+  if (opts && opts.airGap) return true;
+  if (process.env.EXCEPTD_AIR_GAP === '1') return true;
+  const argv = Array.isArray(process.argv) ? process.argv : [];
+  return argv.some(a => typeof a === 'string' && AIR_GAP_FLAGS.includes(a));
+}
+
 // --- public API ---
 
 /**
@@ -32,9 +56,13 @@ const DATA_DIR = process.env.EXCEPTD_DATA_DIR || path.join(__dirname, '..', 'dat
  * deadlines, auditor-ready exception language, regression schedules.
  * `exceptd scan` will be removed in v1.0.
  *
+ * @param {{ airGap?: boolean }} [opts] - When `opts.airGap` is set, the
+ *   outbound TLS probe is suppressed exactly as EXCEPTD_AIR_GAP=1 does. The
+ *   air-gap CLI flags (--air-gap / --offline / --no-network) are also honored
+ *   directly off process.argv, so the flag is equivalent to the env var.
  * @returns {{ timestamp: string, host: object, findings: object[], summary: object }}
  */
-async function scan() {
+async function scan(opts) {
   const timestamp = new Date().toISOString();
   const findings = [];
 
@@ -50,7 +78,7 @@ async function scan() {
   const host = hostInfo();
   findings.push(...kernelScan());
   findings.push(...mcpScan());
-  findings.push(...cryptoScan());
+  findings.push(...cryptoScan(opts));
   findings.push(...aiApiScan());
   findings.push(...frameworkScan());
 
@@ -65,11 +93,11 @@ async function scan() {
  * Run a targeted scan for a specific domain.
  * @param {'kernel'|'mcp'|'crypto'|'ai_api'|'framework'} domain
  */
-async function scanDomain(domain) {
+async function scanDomain(domain, opts) {
   const scanners = { kernel: kernelScan, mcp: mcpScan, crypto: cryptoScan, ai_api: aiApiScan, framework: frameworkScan };
   const fn = scanners[domain];
   if (!fn) throw new Error(`Unknown scan domain: ${domain}. Valid: ${Object.keys(scanners).join(', ')}`);
-  return fn();
+  return fn(opts);
 }
 
 // --- domain scanners ---
@@ -175,7 +203,7 @@ function mcpScan() {
   return findings;
 }
 
-function cryptoScan() {
+function cryptoScan(opts) {
   const findings = [];
 
   const opensslRaw = safeExecFile('openssl', ['version']);
@@ -218,15 +246,18 @@ function cryptoScan() {
 
   // Air-gap mode short-circuits the outbound TLS probe entirely; emit a
   // skipped annotation so operators can see the probe was intentionally
-  // suppressed rather than failing silently.
-  if (process.env.EXCEPTD_AIR_GAP === '1') {
+  // suppressed rather than failing silently. Honored equivalently for the
+  // EXCEPTD_AIR_GAP=1 env var AND the --air-gap / --offline / --no-network CLI
+  // flags (isAirGap inspects opts, env, and process.argv) — the flag is NOT a
+  // no-op on this egress path.
+  if (isAirGap(opts)) {
     findings.push({
       domain: 'crypto',
       signal: 'tls_probe',
       probe: 'skipped (air-gap)',
       severity: 'info',
       skill_hint: 'pqc-first',
-      action_required: 'Air-gap mode active — TLS probe suppressed. Run with EXCEPTD_AIR_GAP=0 to probe.'
+      action_required: 'Air-gap mode active — TLS probe suppressed. Run without --air-gap (and with EXCEPTD_AIR_GAP unset) to probe.'
     });
   } else {
     const target = process.env.EXCEPTD_TLS_PROBE_TARGET || 'registry.npmjs.org:443';
@@ -589,4 +620,4 @@ function loadJson(filename) {
   }
 }
 
-module.exports = { scan, scanDomain, sanitizeConfig };
+module.exports = { scan, scanDomain, sanitizeConfig, isAirGap };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/exceptd-skills",
-  "version": "0.18.8",
+  "version": "0.18.11",
   "description": "AI security skills grounded in mid-2026 threat reality, not stale framework documentation. 51 skills, 11 catalogs (459 CVEs / 181 CWEs / 805 ATT&CK + ICS / 170 ATLAS / 468 D3FEND / 8888 RFCs), 35 jurisdictions, 10-class catalog gap detector + budget gate, real XML parser + canonical-form diff + content-pattern regression detection, Ed25519-signed.",
   "keywords": [
     "ai-security",