@blamejs/exceptd-skills 0.9.1

package/scripts/audit-perf.js

@@ -0,0 +1,160 @@
+"use strict";
+/**
+ * scripts/audit-perf.js
+ *
+ * Micro-benchmarks the hot paths a skill / orchestrator / audit
+ * actually exercises. Times each operation so we can decide what's
+ * worth pre-computing into a seeded index.
+ *
+ * Usage: node scripts/audit-perf.js
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const ROOT = path.join(__dirname, "..");
+const ABS = (p) => path.join(ROOT, p);
+
+function bench(label, fn, iters = 1) {
+  const start = process.hrtime.bigint();
+  let result;
+  for (let i = 0; i < iters; i++) result = fn();
+  const ns = Number(process.hrtime.bigint() - start);
+  const ms = (ns / 1e6 / iters).toFixed(3);
+  console.log(`  ${ms.padStart(10)} ms  ${label}`);
+  return result;
+}
+
+console.log("\n=== exceptd hot-path performance ===\n");
+console.log("Operation                                            Time");
+console.log("-".repeat(70));
+
+// 1. Load manifest
+const manifest = bench("load manifest.json (parse)", () =>
+  JSON.parse(fs.readFileSync(ABS("manifest.json"), "utf8"))
+);
+const skills = manifest.skills;
+
+// 2. Load every data catalog
+const catalogs = [
+  "cve-catalog.json",
+  "atlas-ttps.json",
+  "framework-control-gaps.json",
+  "global-frameworks.json",
+  "cwe-catalog.json",
+  "d3fend-catalog.json",
+  "rfc-references.json",
+  "dlp-controls.json",
+  "zeroday-lessons.json",
+  "exploit-availability.json",
+];
+const catalogObjs = bench(`load all ${catalogs.length} data catalogs`, () => {
+  const out = {};
+  for (const c of catalogs) out[c] = JSON.parse(fs.readFileSync(ABS("data/" + c), "utf8"));
+  return out;
+});
+
+// 3. Read every skill body
+bench(`read all ${skills.length} skill.md bodies`, () => {
+  for (const s of skills) fs.readFileSync(ABS(s.path), "utf8");
+});
+
+// 4. Parse every skill frontmatter (the linter's expensive op)
+function parseFm(text) {
+  if (!text.startsWith("---")) return null;
+  const end = text.indexOf("\n---", 3);
+  if (end < 0) return null;
+  const fm = text.slice(3, end).replace(/^\r?\n/, "");
+  const r = {};
+  const lines = fm.split(/\r?\n/);
+  let i = 0;
+  while (i < lines.length) {
+    const L = lines[i];
+    if (!L.trim() || L.trimStart().startsWith("#")) { i++; continue; }
+    const m = L.match(/^([A-Za-z_]+):\s*(.*)$/);
+    if (!m) { i++; continue; }
+    const k = m[1], rest = m[2].trim();
+    if (rest === "" || rest === undefined) {
+      const items = []; i++;
+      while (i < lines.length && /^\s+-\s+/.test(lines[i])) {
+        items.push(lines[i].match(/^\s+-\s+(.*)$/)[1].trim()); i++;
+      }
+      r[k] = items; continue;
+    }
+    if (rest === "[]") { r[k] = []; i++; continue; }
+    r[k] = rest; i++;
+  }
+  return r;
+}
+bench(`parse all ${skills.length} skill frontmatters`, () => {
+  for (const s of skills) parseFm(fs.readFileSync(ABS(s.path), "utf8"));
+});
+
+// 5. Trigger lookup (what the dispatcher does)
+const flatTriggers = [];
+for (const s of skills) for (const t of s.triggers || []) flatTriggers.push([t.toLowerCase(), s.name]);
+bench("trigger string-match against all skills (single query)", () => {
+  const q = "ai red team";
+  return flatTriggers.filter(([t]) => t.includes(q) || q.includes(t));
+});
+
+// 6. Cross-reference lookup: which skills cite a given CWE?
+bench("xref: which skills cite CWE-79? (linear scan)", () => {
+  const refSet = "CWE-79";
+  return skills.filter((s) => (s.cwe_refs || []).includes(refSet)).map((s) => s.name);
+});
+
+// 7. Multi-hop chain: CVE → CWE → ATLAS → framework_gaps for one CVE
+const cve = catalogObjs["cve-catalog.json"]["CVE-2026-31431"];
+bench("multi-hop chain: CVE-2026-31431 → CWE → ATLAS → frameworks", () => {
+  // skills that mention CVE → their CWE refs → their ATLAS refs → their framework gaps
+  const skillsCiting = skills.filter((s) =>
+    (catalogObjs["cve-catalog.json"]["CVE-2026-31431"].evidence_cves || []).length > 0 // dummy filter
+  );
+  const cwes = new Set();
+  const atlases = new Set();
+  const fws = new Set();
+  for (const s of skills) {
+    if (!(s.atlas_refs || []).length) continue;
+    for (const c of s.cwe_refs || []) cwes.add(c);
+    for (const a of s.atlas_refs || []) atlases.add(a);
+    for (const f of s.framework_gaps || []) fws.add(f);
+  }
+  return { cwes: [...cwes], atlases: [...atlases], fws: [...fws] };
+});
+
+// 8. Forward_watch aggregator (read 38 skill files, parse frontmatter, union all forward_watch)
+bench(`watchlist aggregator (full scan, ${skills.length} skills)`, () => {
+  const watch = new Set();
+  for (const s of skills) {
+    const fm = parseFm(fs.readFileSync(ABS(s.path), "utf8"));
+    if (fm && Array.isArray(fm.forward_watch)) for (const w of fm.forward_watch) watch.add(w);
+  }
+  return watch.size;
+});
+
+// 9. Full cross-skill audit
+bench("full cross-skill audit script (subprocess overhead included)", () => {
+  // Simulate: load manifest + all catalogs + all skill files + compute every refset
+  for (const s of skills) {
+    fs.readFileSync(ABS(s.path), "utf8");
+    for (const f of s.cwe_refs || []) { /* lookup */ }
+    for (const f of s.d3fend_refs || []) { /* lookup */ }
+    for (const f of s.framework_gaps || []) { /* lookup */ }
+    for (const f of s.atlas_refs || []) { /* lookup */ }
+    for (const f of s.rfc_refs || []) { /* lookup */ }
+  }
+});
+
+console.log("");
+console.log("=== Sizes ===");
+const totalBytes = (paths) => paths.reduce((t, p) => t + fs.statSync(ABS(p)).size, 0);
+console.log(`  manifest.json:                    ${fs.statSync(ABS("manifest.json")).size.toLocaleString()} bytes`);
+console.log(`  manifest-snapshot.json:           ${fs.statSync(ABS("manifest-snapshot.json")).size.toLocaleString()} bytes`);
+console.log(`  data/*.json (${catalogs.length} files):              ${totalBytes(catalogs.map(c => "data/" + c)).toLocaleString()} bytes`);
+console.log(`  skills/*/skill.md (${skills.length} files):           ${totalBytes(skills.map(s => s.path)).toLocaleString()} bytes`);
+
+console.log("\n=== Recommendation surfaces (manual review) ===");
+console.log("  - Anything slower than 50 ms in the hot path = candidate for pre-computed index");
+console.log("  - Anything called >1×/operation = candidate for cached + invalidated index");
+console.log("  - JSON files >100 KB = candidate for streaming or partial load if hot-path indexed");

package/scripts/bootstrap.js

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * exceptd Security — bootstrap ceremony.
+ *
+ * Three audiences, three behaviors. The script auto-detects which mode is
+ * appropriate so a downstream consumer never accidentally invalidates the
+ * maintainer's signing key.
+ *
+ *   1. Downstream consumer (keys/public.pem exists, .keys/private.pem missing,
+ *      no --init flag) — VERIFY ONLY. The maintainer already shipped the public
+ *      key + signed manifest. Running `npm run bootstrap` here just confirms
+ *      the working tree is intact. No keypair is generated; no signatures are
+ *      rewritten. This is the safe default.
+ *
+ *   2. Maintainer re-sign (.keys/private.pem exists) — SIGN + VERIFY. Used
+ *      after editing skill content. Re-signs every skill with the existing
+ *      private key, then verifies.
+ *
+ *   3. First-maintainer init (no keys/public.pem, OR --init explicitly passed)
+ *      — GENERATE + SIGN + VERIFY. Used once when a maintainer sets up signing
+ *      for a brand-new clone. Generates an Ed25519 keypair, signs every skill,
+ *      and verifies. The new public key is committed; the private key stays in
+ *      .keys/ (gitignored).
+ *
+ * The private key never leaves the maintainer's machine. The public key in
+ * keys/public.pem is the one tracked artifact and is committed by the
+ * maintainer after first init.
+ *
+ * Subprocesses use execFileSync (no shell) with argument arrays — there is no
+ * user input on the path, and avoiding the shell removes the injection surface
+ * regardless.
+ *
+ * Usage:
+ *   node scripts/bootstrap.js              Auto-detect mode and run.
+ *   node scripts/bootstrap.js --init       Force first-maintainer init (generate
+ *                                          keypair + sign + verify).
+ *   node scripts/bootstrap.js --force      Re-run even if marker exists.
+ *   node scripts/bootstrap.js --help       Print this help text.
+ *
+ * Dependencies: Node 24 stdlib only. package.json has no runtime deps and
+ * this script keeps it that way.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const childProcess = require('node:child_process');
+
+const ROOT = path.join(__dirname, '..');
+const PRIVATE_KEY_PATH = path.join(ROOT, '.keys', 'private.pem');
+const PUBLIC_KEY_PATH = path.join(ROOT, 'keys', 'public.pem');
+const MARKER_PATH = path.join(ROOT, '.bootstrap-complete');
+const SIGN_SCRIPT = path.join(ROOT, 'lib', 'sign.js');
+const VERIFY_SCRIPT = path.join(ROOT, 'lib', 'verify.js');
+
+const HELP = `
+exceptd Security — bootstrap ceremony
+
+Mode is auto-detected from current state:
+
+  Downstream consumer (default):
+    Public key present, private key absent → VERIFY ONLY.
+    No keypair generated; no signatures rewritten.
+
+  Maintainer re-sign:
+    Private key present → SIGN + VERIFY.
+    Re-signs every skill in manifest.json with the existing private key.
+
+  First-maintainer init (--init or no keys at all):
+    GENERATE + SIGN + VERIFY.
+    Generates an Ed25519 keypair, signs every skill, runs the verifier.
+
+Usage:
+  node scripts/bootstrap.js              Auto-detect mode and run.
+  node scripts/bootstrap.js --init       Force first-maintainer init.
+  node scripts/bootstrap.js --force      Re-run even if marker exists.
+  node scripts/bootstrap.js --help       Show this message.
+
+Outputs (only in maintainer modes):
+  .keys/private.pem        Ed25519 private key (gitignored — never commit).
+  keys/public.pem          Ed25519 public key (commit this).
+  manifest.json            Updated with per-skill signatures.
+  .bootstrap-complete      Local timestamp marker (gitignored).
+`;
+
+function parseArgs(argv) {
+  const args = { force: false, init: false, help: false };
+  for (const a of argv.slice(2)) {
+    if (a === '--force') args.force = true;
+    else if (a === '--init') args.init = true;
+    else if (a === '--help' || a === '-h') args.help = true;
+    else {
+      console.error(`[bootstrap] Unknown argument: ${a}`);
+      console.error('[bootstrap] Run with --help for usage.');
+      process.exit(2);
+    }
+  }
+  return args;
+}
+
+function detectMode(args) {
+  const hasPublic = fs.existsSync(PUBLIC_KEY_PATH);
+  const hasPrivate = fs.existsSync(PRIVATE_KEY_PATH);
+
+  if (args.init) return 'init';
+  if (hasPrivate) return 'resign';
+  if (hasPublic) return 'verify-only';
+  return 'init';
+}
+
+function run(label, scriptPath, scriptArgs) {
+  const pretty = `node ${path.relative(ROOT, scriptPath)} ${scriptArgs.join(' ')}`.trim();
+  console.log(`[bootstrap] ${label}: ${pretty}`);
+  try {
+    // execFileSync: no shell, args passed as a vetted array. The script path
+    // and all args here are constants under this repo's control.
+    childProcess.execFileSync(process.execPath, [scriptPath, ...scriptArgs], {
+      cwd: ROOT,
+      stdio: 'inherit'
+    });
+  } catch (err) {
+    console.error(`[bootstrap] FAILED at step "${label}".`);
+    process.exit(err.status && Number.isInteger(err.status) ? err.status : 1);
+  }
+}
+
+function writeMarker() {
+  const payload = {
+    completed_at: new Date().toISOString(),
+    node_version: process.version,
+    platform: process.platform
+  };
+  fs.writeFileSync(MARKER_PATH, JSON.stringify(payload, null, 2) + '\n', 'utf8');
+  console.log(`[bootstrap] Wrote ${path.relative(ROOT, MARKER_PATH)}`);
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+
+  if (args.help) {
+    process.stdout.write(HELP);
+    return;
+  }
+
+  if (fs.existsSync(MARKER_PATH) && !args.force) {
+    console.log('[bootstrap] Already complete (.bootstrap-complete present).');
+    console.log('[bootstrap] Pass --force to re-run the ceremony.');
+    return;
+  }
+
+  const mode = detectMode(args);
+
+  if (mode === 'verify-only') {
+    // Downstream consumer path. The maintainer already shipped the public
+    // key and signed manifest. Running bootstrap here just confirms tree
+    // integrity — never generates or signs, which would invalidate the
+    // upstream maintainer's signing chain.
+    console.log('[bootstrap] Detected downstream-consumer state:');
+    console.log('  - keys/public.pem present (shipped by maintainer)');
+    console.log('  - .keys/private.pem absent');
+    console.log('[bootstrap] Running VERIFY ONLY. No keypair will be generated.');
+    console.log('[bootstrap] If you ARE the maintainer setting up a new clone, pass --init.');
+    console.log();
+    run('verify signatures', VERIFY_SCRIPT, []);
+    writeMarker();
+    console.log('\n[bootstrap] Verify-only ceremony complete. Tree integrity confirmed.');
+    return;
+  }
+
+  if (mode === 'resign') {
+    // Maintainer re-sign path. Private key already exists; re-sign every
+    // skill against the current content and verify.
+    console.log('[bootstrap] Detected maintainer re-sign state (private key present).');
+    console.log('[bootstrap] Re-signing every skill with the existing private key.');
+    console.log();
+    run('sign all skills', SIGN_SCRIPT, ['sign-all']);
+    run('verify signatures', VERIFY_SCRIPT, []);
+    writeMarker();
+    console.log('\n[bootstrap] Re-sign ceremony complete.');
+    console.log('[bootstrap] If skill content or manifest.json changed, commit the updates:');
+    console.log('  git add manifest.json');
+    console.log('  git commit -m "resign: skill content updated"');
+    return;
+  }
+
+  // mode === 'init' — first-maintainer setup.
+  console.log('[bootstrap] First-maintainer init mode:');
+  console.log('  - generating Ed25519 keypair (one-time)');
+  console.log('  - signing every skill listed in manifest.json');
+  console.log('  - verifying the signature chain end-to-end');
+  console.log();
+  run('generate Ed25519 keypair', SIGN_SCRIPT, ['generate-keypair']);
+  run('sign all skills', SIGN_SCRIPT, ['sign-all']);
+  run('verify signatures', VERIFY_SCRIPT, []);
+  writeMarker();
+
+  console.log('\n[bootstrap] First-maintainer init complete. Next steps:');
+  console.log('  git add keys/public.pem manifest.json');
+  console.log('  git commit -m "bootstrap: add signing public key and signed manifest"');
+}
+
+if (require.main === module) {
+  main();
+}