@blamejs/exceptd-skills 0.9.1

package/orchestrator/README.md

@@ -0,0 +1,124 @@
+# Orchestrator
+
+The scanning and orchestration layer that ties all exceptd skills together. It scans an environment, routes findings to relevant skills, coordinates the multi-agent pipeline, and generates structured reports.
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────┐
+│                    orchestrator/                      │
+│                                                       │
+│   scanner.js    →    dispatcher.js    →   pipeline.js │
+│     │                    │                    │       │
+│     ↓                    ↓                    ↓       │
+│  findings.json   matched skills       agent handoffs  │
+│                                                       │
+│   event-bus.js  ←  external events (KEV, ATLAS, etc) │
+│   scheduler.js  ←  weekly/annual currency checks     │
+└──────────────────────────────────────────────────────┘
+```
+
+## Components
+
+### scanner.js
+Discovers the security posture of the current environment:
+- Kernel version and patch status
+- MCP server configurations across AI coding assistants
+- Cryptographic posture (TLS versions, algorithm inventory)
+- Framework compliance claims
+- AI API dependencies in use
+
+Outputs: `findings.json` — a structured list of signals, each with a severity and a hint toward which skills apply.
+
+### dispatcher.js
+Routes scanner findings to relevant skills. Matches findings against skill `triggers` in `manifest.json`. Returns an ordered list of skills to invoke, sorted by RWEP urgency.
+
+### pipeline.js
+Coordinates the multi-agent research → validation → update → report pipeline:
+1. **threat-researcher** — investigates new CVEs and TTPs
+2. **source-validator** — gates data quality before it enters the catalog
+3. **skill-updater** — applies validated findings to skill files and data
+4. **report-generator** — produces structured output for the target audience
+
+### event-bus.js
+Event-driven trigger system. Fires when:
+- CISA KEV catalog adds a new entry
+- MITRE ATLAS publishes a new version
+- A kernel CVE with RWEP > 80 is added to the catalog
+- An AI/MCP platform CVE drops
+- A compliance framework publishes an amendment
+
+Each event triggers `skill-update-loop` and marks affected skills for review.
+
+### scheduler.js
+Scheduled tasks:
+- **Weekly**: currency check on all skills (any `last_threat_review` > 30 days gets flagged)
+- **Monthly**: full CVE catalog validation against NVD
+- **Annual**: full skill audit — all skills reviewed against current threat landscape
+
+## Usage
+
+```bash
+# Scan current environment and produce findings
+node orchestrator/index.js scan
+
+# Route findings to relevant skills
+node orchestrator/index.js dispatch
+
+# Run a specific skill programmatically
+node orchestrator/index.js skill kernel-lpe-triage
+
+# Run the full agent pipeline (threat-researcher → report)
+node orchestrator/index.js pipeline
+
+# Check skill currency scores
+node orchestrator/index.js currency
+
+# Generate an executive report from current findings
+node orchestrator/index.js report --format executive
+
+# Watch for events and trigger updates automatically
+node orchestrator/index.js watch
+```
+
+## Output Formats
+
+The orchestrator produces output in three formats:
+
+| Format | Audience | File |
+|--------|----------|------|
+| `executive` | CISO / Board | `reports/templates/executive-summary.md` |
+| `technical` | Security Engineers | `reports/templates/technical-assessment.md` |
+| `compliance` | Auditors / GRC | `reports/templates/compliance-gap-report.md` |
+| `zero-day` | Incident Response | `reports/templates/zero-day-response.md` |
+
+## Agent Handoff Protocol
+
+When `pipeline.js` hands off between agents, it passes a structured JSON package:
+
+```json
+{
+  "handoff_id": "uuid",
+  "from_agent": "threat-researcher",
+  "to_agent": "source-validator",
+  "timestamp": "2026-05-11T00:00:00Z",
+  "payload": {
+    "cve_id": "CVE-XXXX-XXXXX",
+    "findings": {},
+    "confidence": "high|medium|low",
+    "primary_sources": [],
+    "flags": []
+  }
+}
+```
+
+Source-validator either approves (passes to skill-updater), returns for revision, or rejects with reason.
+
+## Environment Variables
+
+```bash
+EXCEPTD_SCAN_TARGETS=./          # Directories to scan for MCP configs
+EXCEPTD_REPORT_FORMAT=technical  # Default report format
+EXCEPTD_KEV_CHECK_INTERVAL=3600  # KEV polling interval in seconds (default: 1h)
+EXCEPTD_DATA_DIR=./data          # Path to data directory
+```

package/orchestrator/dispatcher.js

@@ -0,0 +1,140 @@
+'use strict';
+
+/**
+ * Skill dispatcher. Routes scanner findings to relevant skills via manifest trigger matching.
+ * Returns an ordered dispatch plan sorted by RWEP urgency.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const MANIFEST_PATH = process.env.EXCEPTD_MANIFEST || path.join(__dirname, '..', 'manifest.json');
+const SKILLS_DIR = process.env.EXCEPTD_SKILLS_DIR || path.join(__dirname, '..', 'skills');
+
+// --- public API ---
+
+/**
+ * Route findings to skills and return a dispatch plan.
+ *
+ * @param {object[]} findings - From scanner.scan()
+ * @returns {{ plan: object[], unmatched: object[], summary: object }}
+ */
+function dispatch(findings) {
+  const manifest = loadManifest();
+  const plan = [];
+  const unmatched = [];
+  const seen = new Set();
+
+  for (const finding of findings) {
+    const matched = matchFinding(finding, manifest.skills);
+
+    if (matched.length === 0) {
+      unmatched.push(finding);
+      continue;
+    }
+
+    for (const skill of matched) {
+      if (seen.has(skill.name)) continue;
+      seen.add(skill.name);
+
+      plan.push({
+        skill_name: skill.name,
+        skill_path: path.join(SKILLS_DIR, skill.name, 'skill.md'),
+        triggered_by: finding.signal,
+        finding_domain: finding.domain,
+        finding_severity: finding.severity,
+        action_required: finding.action_required,
+        priority: severityToPriority(finding.severity),
+        last_threat_review: skill.last_threat_review || 'unknown'
+      });
+    }
+  }
+
+  plan.sort((a, b) => a.priority - b.priority);
+
+  return {
+    plan,
+    unmatched,
+    summary: {
+      total_findings: findings.length,
+      matched_findings: findings.length - unmatched.length,
+      skills_to_invoke: plan.length,
+      critical_priority: plan.filter(p => p.priority === 1).length,
+      high_priority: plan.filter(p => p.priority === 2).length
+    }
+  };
+}
+
+/**
+ * Route a single natural language query to matching skills.
+ *
+ * @param {string} query - Free text query
+ * @returns {object[]} Matched skills from manifest
+ */
+function routeQuery(query) {
+  const manifest = loadManifest();
+  const q = query.toLowerCase();
+
+  return manifest.skills.filter(skill => {
+    const triggers = skill.triggers || [];
+    return triggers.some(t => q.includes(t.toLowerCase()) || t.toLowerCase().includes(q));
+  });
+}
+
+/**
+ * Get the full dispatch context for a specific skill (data deps, frontmatter).
+ *
+ * @param {string} skillName
+ * @returns {{ skill: object, data_paths: object, skill_content: string|null }}
+ */
+function getSkillContext(skillName) {
+  const manifest = loadManifest();
+  const skill = manifest.skills.find(s => s.name === skillName);
+  if (!skill) return null;
+
+  const DATA_DIR = path.join(__dirname, '..', 'data');
+  const dataPaths = {};
+  for (const dep of skill.data_deps || []) {
+    const fullPath = path.join(DATA_DIR, dep);
+    dataPaths[dep] = { path: fullPath, exists: fs.existsSync(fullPath) };
+  }
+
+  const skillPath = path.join(SKILLS_DIR, skillName, 'skill.md');
+  let skillContent = null;
+  try {
+    skillContent = fs.readFileSync(skillPath, 'utf8');
+  } catch (_) {}
+
+  return { skill, data_paths: dataPaths, skill_content: skillContent };
+}
+
+// --- private helpers ---
+
+function matchFinding(finding, skills) {
+  if (finding.skill_hint) {
+    const direct = skills.find(s => s.name === finding.skill_hint);
+    if (direct) return [direct];
+  }
+
+  const domainToSkills = {
+    kernel: ['kernel-lpe-triage', 'exploit-scoring', 'compliance-theater'],
+    mcp: ['mcp-agent-trust', 'ai-attack-surface', 'security-maturity-tiers'],
+    crypto: ['pqc-first', 'framework-gap-analysis'],
+    ai_api: ['ai-c2-detection', 'ai-attack-surface', 'threat-model-currency'],
+    framework: ['framework-gap-analysis', 'compliance-theater', 'global-grc']
+  };
+
+  const candidateNames = domainToSkills[finding.domain] || [];
+  return skills.filter(s => candidateNames.includes(s.name));
+}
+
+function severityToPriority(severity) {
+  const map = { critical: 1, high: 2, medium: 3, low: 4, info: 5 };
+  return map[severity] || 5;
+}
+
+function loadManifest() {
+  return JSON.parse(fs.readFileSync(MANIFEST_PATH, 'utf8'));
+}
+
+module.exports = { dispatch, routeQuery, getSkillContext };

package/orchestrator/event-bus.js

@@ -0,0 +1,146 @@
+'use strict';
+
+/**
+ * Event bus for trigger-driven skill updates.
+ *
+ * Events are typed and carry structured payloads. Handlers are registered per event type.
+ * This is an in-process event bus — no external message queue required.
+ * For production deployments, swap the internal emitter for a durable queue (Redis, SQS, etc.)
+ * without changing the event schema.
+ */
+
+const { EventEmitter } = require('events');
+
+const EVENT_TYPES = {
+  CISA_KEV_ADDED: 'cisa.kev.added',
+  ATLAS_VERSION_RELEASED: 'atlas.version.released',
+  KERNEL_CVE_HIGH_RWEP: 'cve.kernel.high_rwep',
+  AI_PLATFORM_CVE: 'cve.ai_platform',
+  FRAMEWORK_AMENDMENT: 'framework.amendment',
+  PQC_STANDARD_UPDATE: 'pqc.standard.update',
+  EXPLOIT_STATUS_CHANGE: 'exploit.status.change',
+  NEW_ATTACK_CLASS: 'attack_class.new',
+  SKILL_CURRENCY_LOW: 'skill.currency.low'
+};
+
+// Maps event types to the skills they should trigger for review
+const EVENT_SKILL_MAP = {
+  [EVENT_TYPES.CISA_KEV_ADDED]: ['kernel-lpe-triage', 'exploit-scoring', 'compliance-theater', 'skill-update-loop'],
+  [EVENT_TYPES.ATLAS_VERSION_RELEASED]: ['ai-attack-surface', 'mcp-agent-trust', 'rag-pipeline-security', 'ai-c2-detection', 'skill-update-loop'],
+  [EVENT_TYPES.KERNEL_CVE_HIGH_RWEP]: ['kernel-lpe-triage', 'exploit-scoring', 'zeroday-gap-learn', 'framework-gap-analysis'],
+  [EVENT_TYPES.AI_PLATFORM_CVE]: ['mcp-agent-trust', 'ai-attack-surface', 'zeroday-gap-learn'],
+  [EVENT_TYPES.FRAMEWORK_AMENDMENT]: ['framework-gap-analysis', 'compliance-theater', 'global-grc', 'policy-exception-gen'],
+  [EVENT_TYPES.PQC_STANDARD_UPDATE]: ['pqc-first', 'framework-gap-analysis'],
+  [EVENT_TYPES.EXPLOIT_STATUS_CHANGE]: ['exploit-scoring', 'kernel-lpe-triage', 'compliance-theater'],
+  [EVENT_TYPES.NEW_ATTACK_CLASS]: ['threat-model-currency', 'ai-attack-surface', 'skill-update-loop'],
+  [EVENT_TYPES.SKILL_CURRENCY_LOW]: ['skill-update-loop']
+};
+
+class ExceptdEventBus extends EventEmitter {
+  constructor() {
+    super();
+    this.eventLog = [];
+  }
+
+  /**
+   * Emit a typed event with structured payload.
+   *
+   * @param {string} eventType - One of EVENT_TYPES
+   * @param {object} payload - Event-specific data
+   */
+  emit(eventType, payload) {
+    const event = {
+      event_id: `evt_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+      type: eventType,
+      timestamp: new Date().toISOString(),
+      payload,
+      affected_skills: EVENT_SKILL_MAP[eventType] || []
+    };
+
+    this.eventLog.push(event);
+    super.emit(eventType, event);
+    super.emit('*', event);
+    return event;
+  }
+
+  /**
+   * Register a handler for an event type.
+   *
+   * @param {string} eventType
+   * @param {function} handler - (event) => void
+   */
+  on(eventType, handler) {
+    super.on(eventType, handler);
+    return this;
+  }
+
+  /**
+   * Register a handler for all events.
+   *
+   * @param {function} handler - (event) => void
+   */
+  onAny(handler) {
+    return this.on('*', handler);
+  }
+
+  /**
+   * Get all events that affected a specific skill.
+   *
+   * @param {string} skillName
+   * @returns {object[]}
+   */
+  getSkillEvents(skillName) {
+    return this.eventLog.filter(e => e.affected_skills.includes(skillName));
+  }
+
+  /**
+   * Get the event log, optionally filtered by type.
+   *
+   * @param {string} [eventType]
+   * @returns {object[]}
+   */
+  getLog(eventType) {
+    if (eventType) return this.eventLog.filter(e => e.type === eventType);
+    return [...this.eventLog];
+  }
+
+  /**
+   * Fire a CISA KEV addition event.
+   *
+   * @param {{ cve_id: string, kev_date: string, rwep_score: number }} params
+   */
+  kevAdded({ cve_id, kev_date, rwep_score }) {
+    return this.emit(EVENT_TYPES.CISA_KEV_ADDED, { cve_id, kev_date, rwep_score });
+  }
+
+  /**
+   * Fire an ATLAS version release event.
+   *
+   * @param {{ old_version: string, new_version: string, release_date: string }} params
+   */
+  atlasReleased({ old_version, new_version, release_date }) {
+    return this.emit(EVENT_TYPES.ATLAS_VERSION_RELEASED, { old_version, new_version, release_date });
+  }
+
+  /**
+   * Fire an exploit status change event.
+   *
+   * @param {{ cve_id: string, old_status: string, new_status: string }} params
+   */
+  exploitStatusChanged({ cve_id, old_status, new_status }) {
+    return this.emit(EVENT_TYPES.EXPLOIT_STATUS_CHANGE, { cve_id, old_status, new_status });
+  }
+
+  /**
+   * Fire a skill currency low event (emitted by scheduler).
+   *
+   * @param {{ skill_name: string, currency_score: number, days_since_review: number }} params
+   */
+  skillCurrencyLow({ skill_name, currency_score, days_since_review }) {
+    return this.emit(EVENT_TYPES.SKILL_CURRENCY_LOW, { skill_name, currency_score, days_since_review });
+  }
+}
+
+const bus = new ExceptdEventBus();
+
+module.exports = { bus, EVENT_TYPES, EVENT_SKILL_MAP };