@blamejs/exceptd-skills 0.19.32 → 0.19.34

package/scripts/check-epss-consistency.js

@@ -2,40 +2,10 @@
 "use strict";
 
 /**
- * EPSS score/percentile consistency gate.
+ * EPSS score/percentile consistency gate. Exit 0 consistent, 1 inconsistent.
  *
- * EPSS publishes a score and a percentile for every CVE, refreshed daily. The
- * percentile is the score's RANK within that day's publication: if A scores
- * higher than B on a given day, A's percentile is at least B's. That makes the
- * pair self-checking with no network access — sort a day's entries by score and
- * the percentiles must come out sorted too.
- *
- * The failure this catches is updating one field without the other. A refresh
- * that writes a new score but keeps yesterday's percentile leaves a plausible
- * entry: both numbers are in range, both look like EPSS values, and nothing
- * downstream can tell they describe different days. The result is a CVE ranked
- * as top-decile urgency on a score that no longer supports it, which is exactly
- * the input the prioritisation model trusts most.
- *
- * What the ordering check does and does not establish. Monotonicity is a
- * necessary condition, not a sufficient one: it catches a stale percentile that
- * contradicts the new score's rank, which is what a partial refresh usually
- * produces, but a stale value that happens to preserve the ordering passes.
- * Proving two fields share a publication would require the fetched row, and
- * that is not recoverable from the catalog offline. So this is a corruption
- * detector, not a provenance proof — the provenance guarantee has to come from
- * the write side, by fetching and writing score, percentile and date together.
- *
- * Three checks run:
- *   - within each epss_date, sorting by score must sort by percentile;
- *   - an entry carries both numeric fields or neither;
- *   - epss_note, which is derived text, must restate the current fields.
- *
- * Entries are grouped by epss_date so each publication is checked against
- * itself; comparing across days is meaningless because the whole distribution
- * shifts.
- *
- * Exit codes: 0 consistent, 1 inconsistent.
+ * The percentile is the score's rank within one publication, so a cohort must
+ * sort the same way by both. Monotonicity is necessary, not sufficient.
  */
 
 const fs = require("node:fs");
@@ -44,13 +14,8 @@ const path = require("node:path");
 const ROOT = path.resolve(__dirname, "..");
 
 /**
- * Percentiles are published rounded to five decimals, so two scores that are
- * adjacent in the ranking can round to percentiles that invert by a hair. That
- * is arithmetic, not drift. Real mismatches are pairs pulled from different
- * days, which land orders of magnitude above this: the widest rounding artifact
- * observed in the catalog is 8e-5, while a stale-field mismatch runs 0.05-0.9.
- * The threshold sits between the two, far enough from each that neither
- * classification is a close call.
+ * Percentiles publish rounded to five decimals, so adjacent scores can invert by
+ * a hair. Rounding artifacts reach 8e-5; a stale-field mismatch runs 0.05-0.9.
  */
 const ROUNDING_TOLERANCE = 1e-3;
 
@@ -58,24 +23,10 @@ function loadCatalog(file) {
   return JSON.parse(fs.readFileSync(file, "utf8"));
 }
 
-/**
- * The operator-readable restatement of an entry's EPSS fields. Entries carry it
- * as `epss_note`, and it is derived, not authored — so it must be rebuilt
- * whenever the numbers move.
- *
- * The renderer lives in lib/cve-enrich.js because the refresh writer rebuilds
- * the note from the same definition. A second copy here would let the gate and
- * the writer disagree about the exact wording, which shows up as this gate
- * failing on data that was refreshed correctly.
- */
+/** Shared with the refresh writer so gate and writer cannot disagree on wording. */
 const { renderEpssNote: renderNote } = require("../lib/cve-enrich.js");
 
-/**
- * Group entries by publication date. Entries missing either field are reported
- * separately rather than skipped — a half-populated pair is its own defect, and
- * silently ignoring it would let the gate pass on the very shape it exists to
- * catch.
- */
+/** Group entries by publication date; a half-populated pair is reported, not skipped. */
 function cohorts(catalog) {
   const groups = new Map();
   const incomplete = [];
@@ -101,10 +52,7 @@ function cohorts(catalog) {
   return { groups, incomplete };
 }
 
-/**
- * Sort a cohort by score and report every place the percentile goes backwards
- * by more than rounding can explain.
- */
+/** Sort by score; report every percentile step backwards that rounding cannot explain. */
 function inversions(rows) {
   const sorted = [...rows].sort((a, b) => a.score - b.score);
   const found = [];
@@ -141,10 +89,7 @@ function check(catalogFile) {
     failures.push(`${row.id}: has one EPSS field but not ${row.missing} — write both together or neither`);
   }
 
-  // The prose restatement drifts the same way the percentile does: a refresh
-  // moves the numbers and leaves the sentence describing the previous
-  // publication, so the entry states two different scores as of two different
-  // dates. It is derived text, so it can be checked exactly.
+  // epss_note is derived text, so it can be checked exactly against the fields.
   for (const [id, entry] of Object.entries(catalog)) {
     if (typeof entry.epss_note !== "string") continue;
     if (typeof entry.epss_score !== "number" || typeof entry.epss_percentile !== "number") continue;

package/scripts/check-framework-gap-coverage.js

@@ -1,31 +1,16 @@
 #!/usr/bin/env node
 /*
- * scripts/check-framework-gap-coverage.js
+ * Enforces global-first coverage (AGENTS.md Hard Rule #5): every curated CVE in
+ * data/cve-catalog.json must declare a framework_control_gaps statement for all
+ * five jurisdiction buckets, so a multi-jurisdiction operator reading the
+ * offline catalog gets more than a US-centric subset.
  *
- * AGENTS.md Hard Rule #5 (global-first) enforcement gate. Every curated CVE
- * in data/cve-catalog.json must declare a framework_control_gaps statement
- * for all five jurisdiction buckets:
+ * Draft entries (_auto_imported) are exempt — they carry raw NVD data, and the
+ * curation bar requires promotion before shipping, at which point this applies.
  *
- *   NIST  — NIST-800-53-* / NIST-800-63*
- *   EU    — NIS2-* / DORA-* / EU-AI-* / GDPR-*
- *   UK    — UK-CAF-*
- *   AU    — AU-Essential-8-* / AU-ISM-*
- *   ISO   — ISO-27001-2022-*
- *
- * A multi-jurisdiction operator reading the offline catalog's framework-gap
- * output must get coverage for every required jurisdiction on every CVE, not
- * a US-centric subset. Before this gate, two-thirds of the corpus mapped only
- * a subset; a codex review surfaced it, the corpus was completed, and this
- * gate keeps it from regressing when new CVEs are curated.
- *
- * Draft entries (_auto_imported === true) are exempt — they carry raw NVD
- * data that has not been through curation yet. The curation bar (elsewhere)
- * requires drafts to be promoted before shipping, at which point this gate
- * applies.
- *
- * Exit code: 0 when every curated entry is complete, 1 when any entry omits a
- * required bucket (the list is printed). Uses process.exitCode (not
- * process.exit) so buffered stdout drains before the process ends.
+ * Exits 0 when every curated entry is complete, 1 when any omits a bucket.
+ * `process.exitCode`, never `process.exit()`: the failure list is a buffered
+ * stdout write that the exit can truncate.
  */
 
 'use strict';
@@ -34,19 +19,16 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 const ROOT = path.resolve(__dirname, '..');
-// Catalog path is overridable (argv[2]) so the gate's own test can point it at
-// a fixture; defaults to the shipped catalog for the real predeploy run.
+// argv[2] overrides the catalog so the gate's own test can point at a fixture.
 const CATALOG = process.argv[2] || path.join(ROOT, 'data', 'cve-catalog.json');
 
 const REQUIRED = ['NIST', 'EU', 'UK', 'AU', 'ISO'];
 
 function bucketOf(key) {
   if (/^NIST/i.test(key)) return 'NIST';
-  // EU bucket is the security-regulation family AGENTS.md Hard Rule #5 names:
-  // NIS2, DORA, the EU AI Act, and the EU Cyber Resilience Act. GDPR / EU-GDPR
-  // (data-protection) is NOT sufficient on its own — an entry mapped only to
-  // GDPR still owes NIS2/DORA/EU-AI coverage, so GDPR does not satisfy this
-  // bucket. Note EU-AI / EU-CRA match here; EU-GDPR deliberately does not.
+  // The EU bucket is the security-regulation family Hard Rule #5 names. GDPR is
+  // data protection and does NOT satisfy it: an entry mapped only to GDPR still
+  // owes NIS2/DORA/EU-AI coverage, so EU-GDPR must not match here.
   if (/^(NIS2|DORA|EU-AI|EU-CRA)/i.test(key)) return 'EU';
   if (/^UK-CAF/i.test(key)) return 'UK';
   if (/^(AU-Essential-?8|AU-ISM|Essential-?8)/i.test(key)) return 'AU';

package/scripts/check-manifest-snapshot.js

@@ -1,33 +1,9 @@
 "use strict";
 /**
- * scripts/check-manifest-snapshot.js
- *
- * CI gate. Captures the current public skill surface (skill name +
- * version + triggers + data_deps + atlas_refs + attack_refs +
- * framework_gaps) from manifest.json and compares it to the committed
- * manifest-snapshot.json baseline.
- *
- * The skill surface is the public contract this repo offers downstream
- * AI assistants: skill names that downstream prompts may reference,
- * trigger keywords that downstream skill-matchers index on, and the
- * data files that skills rely on. Removing a skill or trigger keyword
- * silently breaks every consumer that pinned that surface.
- *
- * Exit codes:
- *   0  — no breaking changes (additive changes printed but not failing)
- *   1  — breaking changes detected
- *   2  — script-level error (missing baseline, IO failure, etc.)
- *
- * Operators see this gate in SECURITY.md / CONTRIBUTING.md as a CI
- * promise: "removed skills, removed triggers, or removed data deps fail
- * the build before they reach main."
- *
- * Usage:
- *   node scripts/check-manifest-snapshot.js
- *
- * Regenerate the baseline after an intentional removal:
- *   node scripts/refresh-manifest-snapshot.js
- *   git add manifest-snapshot.json && git commit
+ * CI gate: diffs the public skill surface in manifest.json — name, version,
+ * triggers, data_deps, ref arrays — against the committed manifest-snapshot.json.
+ * Exit 0 when nothing broke (additive changes print and still pass), 1 on a
+ * breaking change, 2 on a script-level error such as a missing baseline.
  */
 
 const fs = require("fs");
@@ -39,9 +15,7 @@ const MANIFEST_PATH = path.join(ROOT, "manifest.json");
 const SNAPSHOT_PATH = path.join(ROOT, "manifest-snapshot.json");
 
 function captureSurface(manifest) {
-  // Public surface = the set of facts downstream consumers may have
-  // pinned against. NOT included: sha256 / signature / signed_at —
-  // those change every commit and are not a public contract.
+  // Only what a consumer pins against: sha256, signature and signed_at change every commit.
   const skills = (manifest.skills || []).map(s => ({
     name: s.name,
     version: s.version || null,
@@ -70,30 +44,24 @@ function diff(baseline, current) {
   const bSkills = new Map(baseline.skills.map(s => [s.name, s]));
   const cSkills = new Map(current.skills.map(s => [s.name, s]));
 
-  // Removed skills are breaking.
   for (const name of bSkills.keys()) {
     if (!cSkills.has(name)) {
       breaking.push(`removed skill: ${name}`);
     }
   }
 
-  // Added skills are additive.
   for (const name of cSkills.keys()) {
     if (!bSkills.has(name)) {
       additive.push(`added skill: ${name}`);
     }
   }
 
-  // For each skill present in both, diff the pinned facts.
   for (const [name, b] of bSkills) {
     const c = cSkills.get(name);
     if (!c) continue;
 
-    // version downgrades are breaking; bumps are additive.
     if (b.version && c.version && b.version !== c.version) {
-      // Use a simple lexicographic compare — semver isn't enforced
-      // upstream and the manifest version field is informational. The
-      // operator should bump, not unbump.
+      // Lexicographic, not semver: nothing upstream enforces a semver shape.
       if (c.version < b.version) {
         breaking.push(`${name}: version downgraded ${b.version} -> ${c.version}`);
       } else {
@@ -111,7 +79,7 @@ function diff(baseline, current) {
       additive.push(`${name}: added trigger keywords: ${addedTriggers.join(", ")}`);
     }
 
-    // Removed data deps break the skill at load time. Additions are fine.
+    // Removed data deps break the skill at load time.
     const removedDeps = b.data_deps.filter(d => !c.data_deps.includes(d));
     if (removedDeps.length > 0) {
       breaking.push(`${name}: removed data deps: ${removedDeps.join(", ")}`);
@@ -121,11 +89,7 @@ function diff(baseline, current) {
       additive.push(`${name}: added data deps: ${addedDeps.join(", ")}`);
     }
 
-    // Removed ATLAS/ATT&CK/framework refs are surface narrowing.
-    // Per AGENTS.md rule #4 (no orphaned controls) and #12 (external
-    // data version pinning), narrowing the cited surface is a
-    // deliberate decision worth surfacing in CI. Treat as breaking;
-    // the operator can refresh the baseline alongside the intent.
+    // Narrowing the cited surface is deliberate (AGENTS.md #4, #12), so removal is breaking.
     for (const field of ["atlas_refs", "attack_refs", "framework_gaps", "rfc_refs", "cwe_refs", "d3fend_refs", "dlp_refs"]) {
       const removed = b[field].filter(r => !c[field].includes(r));
       if (removed.length > 0) {
@@ -138,9 +102,6 @@ function diff(baseline, current) {
     }
   }
 
-  // ATLAS pinned-version change is breaking per AGENTS.md rule #12
-  // (never silently inherit version changes). The operator must update
-  // the baseline alongside the audit of TTP ID changes.
   if (baseline.atlas_version && current.atlas_version &&
       baseline.atlas_version !== current.atlas_version) {
     breaking.push(
@@ -171,33 +132,16 @@ function formatDiff(result) {
 }
 
 /**
- * Verify the on-disk snapshot still hashes to the value recorded in its
- * .sha256 sidecar. The sidecar is the only thing that catches a hand-edit
- * of manifest-snapshot.json that bypassed refresh-manifest-snapshot.js
- * (the surface diff alone is defeated by editing manifest.json AND the
- * baseline in lockstep — e.g. to hide a removed skill/trigger). The
- * sidecar pins the baseline's exact bytes so that lockstep edit no longer
- * produces a matching pair.
- *
- * Pairing invariant: refresh-manifest-snapshot.js always writes BOTH the
- * snapshot and its sidecar, and package.json `files` ships them together.
- * So a snapshot present WITHOUT its sidecar is not a benign legacy state
- * for any tree the current gate runs against (CI/predeploy run on the
- * committed tree, where both are present; the shipped tarball ships both).
- * An absent sidecar next to a present snapshot is the integrity-evasion
- * shape — treat it as a failure, symmetric with the present-but-mismatch
- * failure. Returns { ok, error } so callers can surface a hard exit.
- *
- * @param {string} root  repo root containing the snapshot + sidecar
- * @returns {{ok: boolean, error: (string|null)}}
+ * Verify the snapshot still hashes to its .sha256 sidecar. The surface diff
+ * alone is defeated by editing manifest.json and the baseline in lockstep; the
+ * sidecar pins the baseline's exact bytes so that pair no longer matches.
  */
 function checkSnapshotIntegrity(root) {
   const snapshotPath = path.join(root, "manifest-snapshot.json");
   const shaPath = path.join(root, "manifest-snapshot.sha256");
 
   if (!fs.existsSync(snapshotPath)) {
-    // No snapshot at all — the caller's baseline-read handles this as a
-    // distinct error. Nothing for the integrity check to anchor against.
+    // Nothing to anchor against; the caller's baseline read reports this.
     return { ok: true, error: null };
   }
 
@@ -253,11 +197,7 @@ if (require.main === module) {
       process.exit(2);
     }
 
-    // Integrity gate: the snapshot must hash to its recorded sidecar value,
-    // and the sidecar must be present whenever the snapshot is. A missing
-    // sidecar next to a present snapshot is itself a failure — it is the
-    // only thing that would have caught a lockstep hand-edit of manifest.json
-    // + the baseline, so allowing it to be deleted re-opens that bypass.
+    // Before the diff: a tampered baseline must not be diffed as though trustworthy.
     const integrity = checkSnapshotIntegrity(ROOT);
     if (!integrity.ok) {
       console.error("[check-manifest-snapshot] " + integrity.error);