@blamejs/exceptd-skills 0.10.2 → 0.11.0

package/data/_indexes/_meta.json

@@ -1,10 +1,10 @@
 {
   "schema_version": "1.1.0",
-  "generated_at": "2026-05-12T13:50:32.319Z",
+  "generated_at": "2026-05-12T14:47:57.871Z",
   "generator": "scripts/build-indexes.js",
   "source_count": 49,
   "source_hashes": {
-    "manifest.json": "3614ad87835688365283c95a8b7af1d66f14928c07efef750c206ba2f13aab33",
+    "manifest.json": "f4243591af627c02011ae29d97eb702764e495522188a4d8fcab7b58950d941c",
     "data/atlas-ttps.json": "1500b5830dab070c4252496964a8c0948e1052a656e2c7c6e1efaf0350645e13",
     "data/cve-catalog.json": "a81d3e4b491b27ccc084596b063a6108ff10c9eb01d7776922fc393980b534fe",
     "data/cwe-catalog.json": "c3367d469b4b3d31e4c56397dd7a8305a0be338ecd85afa27804c0c9ce12157b",

package/lib/playbook-runner.js

@@ -586,13 +586,23 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
     }
   }
 
-  // evidence_package
+  // evidence_package — playbook declares one primary bundle_format; the
+  // operator may request additional formats via agentSignals._bundle_formats
+  // (e.g. SARIF for GitHub Code Scanning + OpenVEX for supply-chain tooling
+  // alongside the CSAF default).
+  const primaryFormat = c.evidence_package?.bundle_format || 'csaf-2.0';
+  const extraFormats = Array.isArray(agentSignals._bundle_formats)
+    ? agentSignals._bundle_formats.filter(f => f !== primaryFormat)
+    : [];
   const evidencePackage = c.evidence_package ? {
-    bundle_format: c.evidence_package.bundle_format || 'csaf-2.0',
+    bundle_format: primaryFormat,
     contents: c.evidence_package.contents || [],
     destination: c.evidence_package.destination || 'local_only',
     signed: c.evidence_package.signed !== false,
-    bundle_body: buildEvidenceBundle(c.evidence_package.bundle_format || 'csaf-2.0', playbook, analyzeResult, validateResult, agentSignals)
+    bundle_body: buildEvidenceBundle(primaryFormat, playbook, analyzeResult, validateResult, agentSignals),
+    bundles_by_format: extraFormats.length ? Object.fromEntries(
+      [primaryFormat, ...extraFormats].map(f => [f, buildEvidenceBundle(f, playbook, analyzeResult, validateResult, agentSignals)])
+    ) : null,
   } : null;
 
   if (evidencePackage && evidencePackage.signed && runOpts.session_key) {
@@ -687,29 +697,219 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals)
       },
       vulnerabilities: analyze.matched_cves.map(c => ({
         cve: c.cve_id,
-        scores: [{ products: [], cvss_v3: { base_score: 0 } }],
+        scores: [{ products: [], cvss_v3: { base_score: c.cvss_score || 0 } }],
         threats: c.active_exploitation === 'confirmed' ? [{ category: 'exploit_status', details: 'Active exploitation confirmed (CISA KEV).' }] : [],
         remediations: [{ category: 'vendor_fix', details: validate.selected_remediation?.description || 'See selected remediation path.' }]
       })),
       exceptd_extension: {
         rwep: analyze.rwep,
         blast_radius_score: analyze.blast_radius_score,
-        compliance_theater: analyze.compliance_theater,
+        compliance_theater: analyze.compliance_theater_check,
         framework_gap_mapping: analyze.framework_gap_mapping,
         evidence_requirements: validate.evidence_requirements,
         residual_risk_statement: validate.residual_risk_statement
       }
     };
   }
-  // Other formats deferred.
-  return { format, note: 'Non-CSAF formats deferred to GRC integration layer.', analyze, validate };
+
+  // SARIF 2.1.0 — GitHub Code Scanning / VS Code SARIF Viewer / Azure DevOps
+  // and most static analysis tooling. One run per playbook directive, one
+  // result per matched CVE. Each result references a rule (cve_id) and ties
+  // back to the directive as the "tool" producer.
+  if (format === 'sarif' || format === 'sarif-2.1.0') {
+    return {
+      $schema: 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json',
+      version: '2.1.0',
+      runs: [{
+        tool: {
+          driver: {
+            name: 'exceptd',
+            version: playbook._meta.version,
+            informationUri: 'https://exceptd.com',
+            rules: analyze.matched_cves.map(c => ({
+              id: c.cve_id,
+              shortDescription: { text: c.cve_id },
+              fullDescription: { text: `RWEP ${c.rwep} · KEV=${c.cisa_kev} · active_exploitation=${c.active_exploitation} · PoC=${c.poc_available}` },
+              defaultConfiguration: { level: c.rwep >= 90 ? 'error' : c.rwep >= 70 ? 'warning' : 'note' },
+              helpUri: `https://nvd.nist.gov/vuln/detail/${c.cve_id}`,
+            }))
+          }
+        },
+        results: analyze.matched_cves.map(c => ({
+          ruleId: c.cve_id,
+          level: c.rwep >= 90 ? 'error' : c.rwep >= 70 ? 'warning' : 'note',
+          message: { text: `${c.cve_id}: RWEP ${c.rwep}, blast_radius ${analyze.blast_radius_score}. ${validate.selected_remediation?.description || ''}` },
+          properties: {
+            rwep: c.rwep,
+            cisa_kev: c.cisa_kev,
+            cisa_kev_due_date: c.cisa_kev_due_date,
+            active_exploitation: c.active_exploitation,
+            ai_discovered: c.ai_discovered,
+            blast_radius_score: analyze.blast_radius_score,
+            framework_gaps: analyze.framework_gap_mapping?.length || 0,
+          }
+        }))
+      }]
+    };
+  }
+
+  // OpenVEX 0.2.0 — supply-chain VEX statements. Each matched CVE becomes a
+  // statement with status derived from confidence + RWEP. Downstream tools
+  // (sigstore, in-toto, GUAC) consume this directly.
+  if (format === 'openvex' || format === 'openvex-0.2.0') {
+    const issued = new Date().toISOString();
+    return {
+      '@context': 'https://openvex.dev/ns/v0.2.0',
+      '@id': `https://exceptd.com/vex/${playbook._meta.id}/${Date.now()}`,
+      author: 'exceptd',
+      timestamp: issued,
+      version: 1,
+      statements: analyze.matched_cves.map(c => ({
+        vulnerability: { '@id': c.cve_id, name: c.cve_id },
+        status: c.active_exploitation === 'confirmed' ? 'under_investigation' : (c.live_patch_available ? 'fixed' : 'affected'),
+        timestamp: issued,
+        action_statement: validate.selected_remediation?.description || null,
+        impact_statement: `RWEP ${c.rwep}. Blast radius ${analyze.blast_radius_score}/5.`
+      }))
+    };
+  }
+
+  // v0.11.0 redesign #39: --format summary emits a 5-line digest for CI gates
+  // and human triage. Drops everything except verdict + RWEP + blast +
+  // feeds_into + jurisdiction clock count.
+  if (format === 'summary') {
+    return {
+      format: 'summary',
+      summary: {
+        playbook: playbook._meta.id,
+        verdict: analyze.compliance_theater_check?.verdict || 'pending',
+        matched_cves: analyze.matched_cves.length,
+        rwep_adjusted: analyze.rwep?.adjusted || 0,
+        rwep_threshold_escalate: analyze.rwep?.threshold?.escalate || null,
+        blast_radius_score: analyze.blast_radius_score || 0,
+        feeds_into: null,  // populated by close()
+        jurisdiction_clocks_active: null,  // populated by close()
+        remediation_recommended: validate.selected_remediation?.id || null,
+      }
+    };
+  }
+
+  if (format === 'markdown') {
+    const lines = [
+      `# exceptd finding: ${playbook.domain.name}`,
+      `**Playbook:** ${playbook._meta.id} v${playbook._meta.version}`,
+      `**Matched CVEs:** ${analyze.matched_cves.length}`,
+      `**Top RWEP:** ${analyze.rwep?.adjusted || 0}`,
+      `**Blast radius:** ${analyze.blast_radius_score || 'unknown'}/5`,
+      `**Theater verdict:** ${analyze.compliance_theater_check?.verdict || 'n/a'}`,
+      `\n## Matched CVEs`,
+      ...analyze.matched_cves.map(c => `- **${c.cve_id}** RWEP ${c.rwep} · KEV=${c.cisa_kev} · ${c.active_exploitation}`),
+      `\n## Selected remediation`,
+      validate.selected_remediation ? `${validate.selected_remediation.id} (priority ${validate.selected_remediation.priority}): ${validate.selected_remediation.description}` : 'No remediation path selected.',
+      `\n## Residual risk`,
+      validate.residual_risk_statement ? `${validate.residual_risk_statement.risk}\n\n_Acceptance level: ${validate.residual_risk_statement.acceptance_level}_` : 'None recorded.',
+    ];
+    return { format: 'markdown', body: lines.join('\n') };
+  }
+
+  return { format, note: 'Unknown format — supported: csaf-2.0, sarif, openvex, markdown.', analyze, validate };
 }
 
 // --- orchestrate: full run in one call ---
 
+/**
+ * v0.11.0 flat submission shape → v0.10.x nested shape. The flat shape is:
+ *
+ *   {
+ *     observations: {
+ *       <artifact-id>: { captured, value, indicator?, result? } | "<precondition-value>",
+ *     },
+ *     verdict: { theater, classification, blast_radius }
+ *   }
+ *
+ * Already-nested submissions pass through unchanged.
+ */
+function normalizeSubmission(submission, playbook) {
+  if (!submission || typeof submission !== "object") return submission || {};
+  if (submission.artifacts || submission.signal_overrides || submission.signals) return submission;
+  if (!submission.observations && !submission.verdict) return submission;
+
+  const out = { artifacts: {}, signal_overrides: {}, signals: {}, precondition_checks: {} };
+  const knownPreconditions = new Set((playbook?._meta?.preconditions || []).map(p => p.id));
+  const knownArtifacts = new Set((playbook?.phases?.look?.artifacts || []).map(a => a.id));
+
+  for (const [key, val] of Object.entries(submission.observations || {})) {
+    if (knownPreconditions.has(key)) {
+      out.precondition_checks[key] = val === "ok" || val === true || val === "true";
+      continue;
+    }
+    if (typeof val === "object" && val !== null) {
+      const aid = knownArtifacts.has(key) ? key : (val.artifact || key);
+      out.artifacts[aid] = { value: val.value, captured: val.captured !== false };
+      if (val.indicator && val.result) out.signal_overrides[val.indicator] = val.result;
+    }
+  }
+
+  const v = submission.verdict || {};
+  if (v.theater) out.signals.theater_verdict = v.theater === "actual_security" ? "clear" : v.theater;
+  if (v.classification) out.signals.detection_classification = v.classification;
+  if (v.blast_radius !== undefined) out.signals.blast_radius_score = v.blast_radius;
+
+  // Carry over precondition_checks if the operator supplied them at the top
+  // level even in the flat shape.
+  if (submission.precondition_checks) Object.assign(out.precondition_checks, submission.precondition_checks);
+
+  return out;
+}
+
+/**
+ * Smart precondition auto-detect (redesign #9). Some preconditions are
+ * mechanically answerable by the runner itself — host platform, cwd
+ * readability, command-on-PATH. The AI shouldn't have to declare these;
+ * we resolve them ourselves and only escalate to AI declaration when the
+ * check requires intent (e.g. "operator authorized this scan").
+ */
+function autoDetectPreconditions(submission, playbook) {
+  const fs = require('fs');
+  const out = { ...(submission || {}) };
+  out.precondition_checks = { ...(submission?.precondition_checks || {}) };
+  for (const pc of (playbook?._meta?.preconditions || [])) {
+    if (out.precondition_checks[pc.id] !== undefined) continue; // operator already supplied
+    const check = (pc.check || '').toLowerCase();
+    if (check.includes("host.platform == 'linux'") || check.includes("host.platform == \"linux\"")) {
+      out.precondition_checks[pc.id] = process.platform === 'linux';
+    } else if (check.includes("host.platform == 'darwin'") || check.includes("host.platform == \"darwin\"")) {
+      out.precondition_checks[pc.id] = process.platform === 'darwin';
+    } else if (check.includes("cwd_readable")) {
+      try { fs.readdirSync(process.cwd()); out.precondition_checks[pc.id] = true; }
+      catch { out.precondition_checks[pc.id] = false; }
+    } else if (check.includes("agent_has_filesystem_read")) {
+      out.precondition_checks[pc.id] = true; // Node has fs by definition
+    } else if (check.match(/agent_has_command\(['"]([^'"]+)['"]\)/)) {
+      const cmdName = check.match(/agent_has_command\(['"]([^'"]+)['"]\)/)[1];
+      const { spawnSync } = require('child_process');
+      const probe = spawnSync(process.platform === 'win32' ? 'where' : 'which', [cmdName], { stdio: 'ignore' });
+      out.precondition_checks[pc.id] = probe.status === 0;
+    }
+    // Intent-requiring checks (e.g. "operator_authorized == true") are NOT
+    // auto-resolved — the AI / operator still declares them. We leave them
+    // undefined and the preflight gate handles missing values per on_fail.
+  }
+  return out;
+}
+
 function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
   const playbook = loadPlaybook(playbookId);
-  const pre = preflight(playbook, runOpts);
+
+  // v0.11.0: accept flat submission shape (observations + verdict). Normalize
+  // to the engine's internal nested shape before preflight/detect. Smart
+  // precondition auto-detect (redesign #9) fires here when the cwd is readable
+  // / the host platform matches — the runner can answer those itself rather
+  // than blocking on AI declaration.
+  agentSubmission = normalizeSubmission(agentSubmission, playbook);
+  agentSubmission = autoDetectPreconditions(agentSubmission, playbook);
+
+  const pre = preflight(playbook, { ...runOpts, precondition_checks: { ...(agentSubmission.precondition_checks || {}), ...(runOpts.precondition_checks || {}) } });
   if (!pre.ok) {
     return { ok: false, phase: 'preflight', blocked_by: pre.blocked_by, reason: pre.reason, issues: pre.issues };
   }
@@ -906,13 +1106,24 @@ function plan(opts = {}) {
     session_id: opts.session_id || crypto.randomBytes(8).toString('hex'),
     playbooks: ids.map(id => {
       const pb = loadPlaybook(id);
+      const baseDirect = pb.phases?.direct || {};
       return {
         id,
         domain: pb.domain,
         scope: pb._meta.scope || null,
         threat_currency_score: pb._meta.threat_currency_score,
         air_gap_mode: !!pb._meta.air_gap_mode,
-        directives: pb.directives.map(d => ({ id: d.id, title: d.title, applies_to: d.applies_to }))
+        directives: pb.directives.map(d => {
+          const overrideDirect = d.phase_overrides?.direct || {};
+          const threatContext = overrideDirect.threat_context || baseDirect.threat_context || null;
+          // Bug #46: include description by default (not just under --directives).
+          // Operators picking a directive need operator-facing prose.
+          const desc = d.description
+            || (threatContext ? (threatContext.split(/(?<=[.!?])\s+/)[0] || "").slice(0, 240) : null)
+            || pb.domain?.name
+            || null;
+          return { id: d.id, title: d.title, description: desc, applies_to: d.applies_to };
+        })
       };
     })
   };
@@ -932,6 +1143,8 @@ module.exports = {
   close,
   run,
   vexFilterFromDoc,
+  normalizeSubmission,
+  autoDetectPreconditions,
   // internal helpers exposed for tests
   _resolvedPhase: resolvedPhase,
   _deepMerge: deepMerge,

package/lib/prefetch.js

@@ -260,6 +260,10 @@ async function prefetch(options = {}) {
         result.by_source[item.source].skipped_fresh++;
       }
     }
+    // Unconditional one-line summary (--quiet preserved on per-entry chatter
+    // but operator still needs confirmation the dry-run completed).
+    const stale = plan.length - result.skipped_fresh;
+    console.log(`prefetch summary: 0 fetched, ${result.skipped_fresh} fresh, ${stale} would-fetch (dry-run)`);
     return result;
   }
 
@@ -306,7 +310,11 @@ async function prefetch(options = {}) {
   idx.generated_at = new Date().toISOString();
   saveIndex(opts.cacheDir, idx);
 
-  log(`\nprefetch summary: ${result.fetched} fetched, ${result.skipped_fresh} fresh, ${result.errors} error(s)`);
+  // Final summary is unconditional — --quiet suppresses per-entry chatter
+  // (the noisy part) but the operator still needs one line confirming success.
+  // Without this, --quiet + --no-network was zero output even on dry-run
+  // success, leaving operators unsure if the command had run at all.
+  console.log(`prefetch summary: ${result.fetched} fetched, ${result.skipped_fresh} fresh, ${result.errors} error(s)${opts.noNetwork ? " (dry-run)" : ""}`);
   return result;
 }
 

package/manifest-snapshot.json

@@ -1,6 +1,6 @@
 {
   "_comment": "Auto-generated by scripts/refresh-manifest-snapshot.js — do not hand-edit. Public skill surface used by check-manifest-snapshot.js to detect breaking removals.",
-  "_generated_at": "2026-05-12T13:48:57.281Z",
+  "_generated_at": "2026-05-12T14:46:11.640Z",
   "atlas_version": "5.1.0",
   "skill_count": 38,
   "skills": [