@blamejs/exceptd-skills 0.12.22 → 0.12.24

package/lib/schemas/playbook.schema.json

@@ -6,6 +6,57 @@
   "type": "object",
   "required": ["_meta", "domain", "phases", "directives"],
   "additionalProperties": false,
+  "allOf": [
+    {
+      "if": {
+        "type": "object",
+        "properties": {
+          "_meta": {
+            "type": "object",
+            "properties": { "air_gap_mode": { "const": true } },
+            "required": ["air_gap_mode"]
+          }
+        },
+        "required": ["_meta"]
+      },
+      "then": {
+        "description": "When _meta.air_gap_mode is true, every artifact whose source contains a network-call substring (https://, http://, gh api, gh release, curl, wget, fetch) MUST carry an air_gap_alternative. The runner refuses to use the network when --air-gap is set, so an artifact with no offline fallback cannot be collected and the run is incomplete.",
+        "type": "object",
+        "properties": {
+          "phases": {
+            "type": "object",
+            "properties": {
+              "look": {
+                "type": "object",
+                "properties": {
+                  "artifacts": {
+                    "type": "array",
+                    "items": {
+                      "anyOf": [
+                        {
+                          "not": {
+                            "type": "object",
+                            "properties": {
+                              "source": {
+                                "type": "string",
+                                "pattern": "(https://|http://|gh api|gh release|curl |wget |fetch )"
+                              }
+                            },
+                            "required": ["source"]
+                          }
+                        },
+                        { "required": ["air_gap_alternative"] }
+                      ]
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  ],
   "properties": {
 
     "_meta": {

package/lib/scoring.js

@@ -92,7 +92,7 @@ function score(cveId, catalog) {
 }
 
 /**
- * E10: Validate an RWEP factor bag. Returns an array of warning strings
+ * Validate an RWEP factor bag. Returns an array of warning strings
  * for missing-but-defaultable fields and out-of-range values. Does NOT
  * throw — operators wanting hard enforcement should treat a non-empty
  * return as a failure themselves.
@@ -342,13 +342,14 @@ function validate(catalog) {
   const errors = [];
   for (const [cveId, entry] of Object.entries(catalog)) {
     if (cveId.startsWith('_')) continue;
-    // FF P1-1: skip auto-imported drafts. KEV/GHSA/OSV-discovered drafts
-    // store a conservative-default rwep_score (poc=true, reboot=true, etc.)
+    // Skip auto-imported drafts. KEV/GHSA/OSV-discovered drafts store a
+    // conservative-default rwep_score (poc=true, reboot=true, etc.)
     // alongside `poc_available: null` and other null-until-curated factor
-    // fields, so the recomputed-vs-stored divergence check ALWAYS fires
-    // against them — flooding the predeploy gate. Drafts are reviewed
-    // separately via the `_auto_imported_meta.curation_needed` list and the
-    // strict catalog validator's draft-warning tier. Once curation promotes
+    // fields, so the recomputed-vs-stored divergence check would always
+    // fire against them and flood the predeploy gate. Drafts are reviewed
+    // separately via the `_auto_imported_meta.curation_needed` list and
+    // the strict catalog validator's draft-warning tier. Once curation
+    // promotes
     // an entry, `_auto_imported` is cleared and full validation resumes.
     if (entry && entry._auto_imported === true) continue;
     for (const field of CVE_SCHEMA_REQUIRED) {
@@ -380,6 +381,46 @@ function validate(catalog) {
   return errors;
 }
 
+/**
+ * Strict CVSS 3.1 vector parse. Returns `{ ok, version, reason? }`.
+ *
+ * The CSAF 2.0 cvss_v3 score block requires a canonical CVSS 3.1 vector
+ * string. Strict validators (BSI CSAF Validator, ENISA dashboard) reject
+ * documents that emit a cvss_v3 block keyed off a malformed vector — the
+ * pre-fix permissive `^CVSS:(\d+\.\d+)/` regex let through 3.0 vectors,
+ * truncated metric sets, and unknown environmental-metric values, which
+ * downstream tooling then rejected wholesale.
+ *
+ * Required metric set (in order): AV / AC / PR / UI / S / C / I / A.
+ * Optional temporal metrics: E / RL / RC.
+ * Optional environmental metrics: CR / IR / AR / MAV / MAC / MPR / MUI /
+ *                                 MS / MC / MI / MA.
+ */
+// CVSS 3.0 and 3.1 share an identical vector grammar (metric set, value enums,
+// and metric order are the same; only the `CVSS:X.Y/` prefix differs). CSAF
+// 2.0 §3.2.4.3 accepts both versions in the cvss_v3 block. The strict regex
+// matches either prefix; the parser records which version the vector declared
+// so the emitter can stamp the right `version` field.
+const CVSS_3X_RE = /^CVSS:3\.[01]\/AV:[NALP]\/AC:[LH]\/PR:[NLH]\/UI:[NR]\/S:[UC]\/C:[NLH]\/I:[NLH]\/A:[NLH](\/E:[XUPFH])?(\/RL:[XOTWU])?(\/RC:[XURC])?(\/CR:[XLMH])?(\/IR:[XLMH])?(\/AR:[XLMH])?(\/MAV:[XNALP])?(\/MAC:[XLH])?(\/MPR:[XNLH])?(\/MUI:[XNR])?(\/MS:[XUC])?(\/MC:[XNLH])?(\/MI:[XNLH])?(\/MA:[XNLH])?$/;
+
+function parseCvss31Vector(v) {
+  if (typeof v !== 'string' || v.length === 0) {
+    return { ok: false, version: null, reason: 'cvss_vector is not a non-empty string' };
+  }
+  const versionMatch = v.match(/^CVSS:(\d+\.\d+)\//);
+  if (!versionMatch) {
+    return { ok: false, version: null, reason: 'cvss_vector does not start with a CVSS:X.Y/ version prefix' };
+  }
+  const version = versionMatch[1];
+  if (version !== '3.0' && version !== '3.1') {
+    return { ok: false, version, reason: `cvss_vector declares version ${version}; CSAF 2.0 cvss_v3 accepts 3.0 and 3.1 only. Backfill a CVSS 3.x vector against this CVE in the catalog, or wait for CSAF 2.1 (cvss_v4 support).` };
+  }
+  if (!CVSS_3X_RE.test(v)) {
+    return { ok: false, version, reason: 'cvss_vector does not match the strict CVSS 3.x grammar (missing/invalid mandatory metric, unknown metric value, or out-of-order metric)' };
+  }
+  return { ok: true, version };
+}
+
 module.exports = {
   score,
   scoreCustom,
@@ -388,6 +429,7 @@ module.exports = {
   validate,
   validateFactors,
   deriveRwepFromFactors,
+  parseCvss31Vector,
   RWEP_WEIGHTS,
   ACTIVE_EXPLOITATION_LADDER,
   RECOGNISED_FACTOR_KEYS,

package/lib/sign.js

@@ -178,9 +178,9 @@ function signAll() {
 
   fs.writeFileSync(MANIFEST_PATH, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
 
-  // S5: verdict line FIRST, fingerprint banner after. An operator
-  // scrolling output should not be able to see "fingerprint: SHA256..."
-  // and assume success when errors > 0.
+  // Verdict line FIRST, fingerprint banner after. An operator scrolling
+  // output should not be able to see "fingerprint: SHA256..." and assume
+  // success when errors > 0.
   if (errors > 0) {
     console.error(`\n[sign] FAILED — ${signed} signed, ${errors} errors.`);
   } else {
@@ -343,14 +343,13 @@ function canonicalManifestBytes(manifest) {
  * Returns the manifest_signature object literal to splice into the
  * manifest top level.
  *
- * A: the previous shape included a `signed_at` ISO timestamp.
- * That field was stripped from the canonical bytes before signing (via
- * `delete clone.manifest_signature`), so it was NOT covered by the
- * signature — an attacker who replayed a known-valid signature could
- * rewrite `signed_at` to any value, lending false freshness authority to
- * a stale signature. The field is now omitted entirely. Freshness signal
- * lives outside the signed bytes (git-log mtime of manifest.json, npm
- * publish timestamp).
+ * The manifest_signature shape carries `algorithm` + `signature_base64`
+ * only — no `signed_at` ISO timestamp. A `signed_at` field stripped from
+ * the canonical bytes before signing would be unsigned metadata; an
+ * attacker who replayed a known-valid signature could rewrite it to any
+ * value, lending false freshness authority to a stale signature.
+ * Freshness signal lives outside the signed bytes (git-log mtime of
+ * manifest.json, npm publish timestamp).
  *
  * @param {object} manifest
  * @param {string} privateKey PEM-encoded Ed25519 private key

package/lib/source-osv.js

@@ -175,7 +175,7 @@ function osvRequestOnce({ method, reqPath, body, timeoutMs }) {
   return new Promise((resolve, reject) => {
     const t = osvTransport();
     if (t.error) {
-      // F13: surface the validation error structurally; no retry.
+      // Surface the validation error structurally; no retry.
       return resolve({ ok: false, error: t.error, source: "offline" });
     }
     const { mod, host, port } = t;
@@ -539,7 +539,7 @@ function extractCvss(rec) {
     const prev = vectorsByVersion.get(ver);
     if (!prev) vectorsByVersion.set(ver, v);
   }
-  // F10: try versions in descending order. CVSS 4.0 derivation is not yet
+  // Try versions in descending order. CVSS 4.0 derivation is not yet
   // implemented here — if v4 was the highest but can't be computed, walk
   // down to v3.x. Only return null when ALL versions fail.
   const versions = Array.from(vectorsByVersion.keys()).sort((a, b) => b - a);
@@ -737,7 +737,7 @@ function normalizeAdvisory(rec) {
   // OSV.dev canonical advisory URL — used as the primary vendor advisory.
   const osvUrl = `https://osv.dev/vulnerability/${encodeURIComponent(rec.id)}`;
 
-  // F6: dedupe verification_sources. OSV records frequently carry the
+  // Dedupe verification_sources. OSV records frequently carry the
   // canonical osv.dev URL in references[] as well, which would otherwise
   // produce a duplicate alongside the prepended `osvUrl`.
   const verification_sources = Array.from(new Set([
@@ -746,9 +746,9 @@ function normalizeAdvisory(rec) {
     ...refUrls.slice(0, 10),
   ]));
 
-  // F5: EPSS coverage does not extend to non-CVE identifiers. Surface this
+  // EPSS coverage does not extend to non-CVE identifiers. Surface this
   // explicitly so curators know to re-query if MITRE later assigns a CVE
-  // id to the entry. Wording mirrors the MAL-2026-3083 catalog entry.
+  // id to the entry.
   const isCveKey = /^CVE-/i.test(catalogKey);
   const epss_note = isCveKey
     ? null
@@ -840,13 +840,13 @@ async function buildDiff(ctx) {
   const cveCatalog = ctx.cveCatalog || {};
   const existingKeys = new Set(Object.keys(cveCatalog));
   const diffs = [];
-  // F7: distinguish unreachable (fetch failed, network or 5xx) from
+  // Distinguish unreachable (fetch failed, network or 5xx) from
   // normalize-rejected (record fetched but normalization produced null).
   // Operators triaging a refresh-report want to know whether to chase a
   // network outage or a malformed upstream record.
   let unreachable = 0;
   let normalizeErrors = 0;
-  // Finding 18: ids that ARE in the catalog but skipped because of overlap
+  // Ids that ARE in the catalog but skipped because of overlap
   // are not "errors"; surface them so the summary doesn't read as silently
   // dropping work. Particularly useful when a curator dispatches the same
   // batch twice and wonders why nothing happened.

package/lib/upstream-check-cli.js

@@ -28,12 +28,13 @@ const ROOT = path.resolve(__dirname, "..");
 const { fetchLatestPublished, buildFreshnessReport } = require("./upstream-check.js");
 
 function parseArgs(argv) {
-  const out = { timeoutMs: 5000, raw: false };
+  const out = { timeoutMs: 5000, raw: false, airGap: false };
   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;
   }
   return out;
 }
@@ -52,6 +53,20 @@ function readManifest() {
 
 (async () => {
   const opts = parseArgs(process.argv);
+  // Air-gap short-circuit — the registry probe is a network operation. When
+  // the operator has declared air-gapped mode (env var OR --air-gap), emit a
+  // structured `skipped` envelope and exit 0. Exit 0 because, like the
+  // existing "offline" path, missing freshness data is a graceful degradation
+  // — it is NOT an error condition for downstream callers.
+  if (process.env.EXCEPTD_AIR_GAP === "1" || opts.airGap) {
+    process.stdout.write(JSON.stringify({
+      ok: null,
+      skipped: "air-gap",
+      reason: "registry probe disabled in air-gap mode",
+      source: "upstream-check",
+    }) + "\n");
+    process.exit(0);
+  }
   const registry = await fetchLatestPublished({ timeoutMs: opts.timeoutMs });
   if (opts.raw) {
     process.stdout.write(JSON.stringify(registry) + "\n");

package/lib/upstream-check.js

@@ -33,6 +33,15 @@ const REQUEST_TIMEOUT_MS = 5000;
  * a path to a JSON file with { version, time: { <ver>: ISO } } shape.
  */
 async function fetchLatestPublished({ timeoutMs = REQUEST_TIMEOUT_MS, pkgName = PKG_NAME } = {}) {
+  // Air-gap refusal — registry probes are a network operation and must never
+  // be issued when the operator has declared an air-gapped environment.
+  // Returning a structured refusal (instead of throwing) lets callers degrade
+  // gracefully the same way they handle `offline` — the freshness signal is
+  // intentionally absent, not in error.
+  if (process.env.EXCEPTD_AIR_GAP === "1") {
+    return { ok: false, error: "air-gap-blocked", source: "fetchLatestPublished" };
+  }
+
   if (process.env.EXCEPTD_REGISTRY_FIXTURE) {
     try {
       const fs = require("fs");

package/lib/validate-catalog-meta.js

@@ -242,7 +242,7 @@ function main() {
   console.log(
     `\n${passed}/${total} catalogs validated${warnSuffix}${failSuffix}.`,
   );
-  // F18: process.exitCode + return so buffered writes drain.
+  // process.exitCode + return so buffered writes drain.
   process.exitCode = failed === 0 ? 0 : 1;
 }
 

package/lib/validate-cve-catalog.js

@@ -418,7 +418,7 @@ function main() {
     (warned ? `, ${warned} with warnings` : '') +
     (failed ? `, ${failed} failed` : '') + '.';
   console.log(summary);
-  // F18: process.exitCode + return so buffered output drains.
+  // process.exitCode + return so buffered output drains.
   process.exitCode = failed === 0 ? 0 : 1;
 }
 

package/lib/verify.js

@@ -164,14 +164,14 @@ function signAll() {
   const manifestSig = crypto.sign(null, canonical, {
     key: privateKey, dsaEncoding: 'ieee-p1363',
   });
-  // A: `signed_at` is intentionally OMITTED. The previous shape
-  // emitted a `signed_at` timestamp alongside the Ed25519 signature, but
-  // `signed_at` was stripped from the canonical bytes before signing — so
-  // an attacker could replay a known-valid signature against the same
-  // canonical content while rewriting `signed_at` to any value, lending
-  // false freshness authority to a stale signature. Operators who need
-  // freshness signal should consult the git-log mtime of manifest.json
-  // (or the npm publish timestamp), which are external to the signed bytes.
+  // `signed_at` is intentionally OMITTED. A `signed_at` timestamp
+  // alongside the Ed25519 signature would be unsigned metadata (stripped
+  // from the canonical bytes before signing), so an attacker could replay
+  // a known-valid signature against the same canonical content while
+  // rewriting `signed_at` to any value — lending false freshness
+  // authority to a stale signature. Operators who need a freshness
+  // signal should consult the git-log mtime of manifest.json (or the
+  // npm publish timestamp), which are external to the signed bytes.
   manifest.manifest_signature = {
     algorithm: 'Ed25519',
     signature_base64: manifestSig.toString('base64'),
@@ -347,11 +347,12 @@ function verifyManifestSignature(manifest) {
   if (typeof sig.signature_base64 !== 'string') {
     return { status: 'invalid', reason: 'manifest_signature.signature_base64 missing or not a string' };
   }
-  // E: require the algorithm field to be present and exactly
-  // 'Ed25519'. The previous form accepted a missing algorithm field
-  // (`if (sig.algorithm && sig.algorithm !== 'Ed25519')`) which let a
-  // future downgrade attacker drop the field to bait a weaker default.
-  // lib/sign.js always writes the field, so no legitimate consumer breaks.
+  // Require the algorithm field to be present and exactly 'Ed25519'.
+  // Accepting a missing algorithm field
+  // (`if (sig.algorithm && sig.algorithm !== 'Ed25519')`) would let a
+  // downgrade attacker drop the field to bait a weaker default.
+  // lib/sign.js always writes the field, so no legitimate consumer
+  // breaks.
   if (sig.algorithm !== 'Ed25519') {
     return {
       status: 'invalid',
@@ -441,10 +442,10 @@ function loadManifestValidated() {
     throw new Error(`[verify] manifest_signature verification FAILED — ${sigResult.reason}. The manifest has been modified (or signed with a different key) since last sign-all. Refusing to verify any skill against this manifest.`);
   }
   if (sigResult.status === 'missing') {
-    // D: dedupe the legacy-tarball warning. Many CLI verbs
-    // call loadManifestValidated() more than once per invocation; the
-    // previous console.warn spammed stderr per call. Node's emitWarning()
-    // with a stable `code` collapses repeated emissions automatically.
+    // Dedupe the legacy-tarball warning. Many CLI verbs call
+    // loadManifestValidated() more than once per invocation, so a plain
+    // console.warn would spam stderr per call. Node's emitWarning() with
+    // a stable `code` collapses repeated emissions automatically.
     process.emitWarning(
       'manifest.json has no top-level manifest_signature field. This tarball predates v0.12.17 manifest signing; skills will still be verified but a coordinated rewrite of manifest.json could go undetected. Re-run `node lib/sign.js sign-all` to add the signature.',
       { code: 'EXCEPTD_MANIFEST_UNSIGNED' }
@@ -594,12 +595,12 @@ function validateAgainstSchema(value, schema, here, root) {
  * @param {string} [pinPath]             optional override (testability)
  */
 /**
- * KK P1-5: shared loader for keys/EXPECTED_FINGERPRINT. Reads the pin file,
- * strips a leading UTF-8 BOM (Notepad with files.encoding=utf8bom would
- * otherwise prepend U+FEFF and silently break every verify path on the host),
- * tolerates CRLF line endings, ignores comment lines (`#`) and blanks, and
- * returns the first non-comment / non-empty line. Returns null if the file
- * is unreadable / empty.
+ * Shared loader for keys/EXPECTED_FINGERPRINT. Reads the pin file, strips
+ * a leading UTF-8 BOM (Notepad with files.encoding=utf8bom would otherwise
+ * prepend U+FEFF and silently break every verify path on the host),
+ * tolerates CRLF line endings, ignores comment lines (`#`) and blanks,
+ * and returns the first non-comment / non-empty line. Returns null if
+ * the file is unreadable / empty.
  *
  * Shared across four sites so every loader normalises identically:
  *   - lib/verify.js              (manifest signature gate)
@@ -610,9 +611,26 @@ function validateAgainstSchema(value, schema, here, root) {
  * four sites under a BOM + CRLF fuzz corpus.
  */
 function loadExpectedFingerprintFirstLine(pinPath) {
-  let raw;
-  try { raw = fs.readFileSync(pinPath, 'utf8'); }
+  let buf;
+  try { buf = fs.readFileSync(pinPath); }
   catch { return null; }
+  if (buf.length >= 2) {
+    const b0 = buf[0];
+    const b1 = buf[1];
+    // UTF-16LE (FF FE) and UTF-16BE (FE FF) pin files would silently decode
+    // as UTF-8 mojibake — the first line never matches a live fingerprint
+    // and the operator sees no signal. Refuse them; re-save as UTF-8.
+    if ((b0 === 0xFF && b1 === 0xFE) || (b0 === 0xFE && b1 === 0xFF)) return null;
+    // UTF-16BE-without-BOM defense: a pin file saved as UTF-16BE on a host
+    // whose editor stripped the BOM (or never wrote one) decodes as
+    // 0x00 <printable ASCII> 0x00 <printable ASCII>... The leading NUL byte
+    // would survive into the utf8 string and the first-line compare would
+    // never match a SHA256:... fingerprint. Detect "00 XX" where XX is
+    // printable ASCII (0x20-0x7E) and refuse — same remediation: re-save
+    // the file as UTF-8.
+    if (b0 === 0x00 && b1 >= 0x20 && b1 <= 0x7E) return null;
+  }
+  let raw = buf.toString('utf8');
   if (raw.length > 0 && raw.charCodeAt(0) === 0xFEFF) raw = raw.slice(1);
   const lines = raw
     .split(/\r?\n/)
@@ -627,7 +645,7 @@ function checkExpectedFingerprint(liveFp, pinPath) {
   if (!liveFp || typeof liveFp.sha256 !== 'string') {
     return { status: 'mismatch', expected: 'unknown', actual: '(invalid)', rotationOverride: false };
   }
-  // KK P1-5: route through the shared loader so a BOM-prefixed pin file
+  // Route through the shared loader so a BOM-prefixed pin file
   // (Notepad with files.encoding=utf8bom) is tolerated identically across
   // every verify site. Pre-fix the verbatim split-trim-find produced a
   // first-line of "SHA256:..." (with leading BOM) that would never equal
@@ -737,10 +755,18 @@ if (require.main === module) {
     );
   } else if (pinResult.status === 'mismatch') {
     if (pinResult.rotationOverride) {
-      console.warn(
-        `[verify] WARN: live key fingerprint ${pinResult.actual} differs from pin ` +
-        `${pinResult.expected}. KEYS_ROTATED=1 set — accepting rotation. ` +
-        `Update keys/EXPECTED_FINGERPRINT to lock the new pin.`
+      process.emitWarning(
+        `live key fingerprint ${pinResult.actual} differs from pin ${pinResult.expected}; ` +
+        `KEYS_ROTATED=1 accepted. Update keys/EXPECTED_FINGERPRINT to lock the new pin.`,
+        { code: 'EXCEPTD_KEYS_ROTATED_OVERRIDE' }
+      );
+      // Mirror to stderr unconditionally: NODE_NO_WARNINGS=1 silences
+      // process.emitWarning, but a key-rotation override is a
+      // security-relevant event that must surface in the operator's
+      // terminal even when warnings are muted.
+      console.error(
+        `[verify] KEYS_ROTATED=1 override accepted; live fingerprint ${pinResult.actual} ` +
+        `differs from pin ${pinResult.expected}. Update keys/EXPECTED_FINGERPRINT to lock the new pin.`
       );
     } else {
       console.error(