@blamejs/exceptd-skills 0.9.1

package/orchestrator/pipeline.js

@@ -0,0 +1,201 @@
+'use strict';
+
+/**
+ * Multi-agent pipeline coordinator.
+ * Orchestrates: threat-researcher → source-validator → skill-updater → report-generator
+ *
+ * This module coordinates agent handoffs using a structured JSON protocol.
+ * Each stage produces a handoff package that the next stage consumes.
+ * Agents themselves are defined in agents/ and executed by AI assistants — not by this code.
+ * This module tracks state, validates handoffs, and routes between stages.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const AGENTS_DIR = path.join(__dirname, '..', 'agents');
+const DATA_DIR = process.env.EXCEPTD_DATA_DIR || path.join(__dirname, '..', 'data');
+const REPORTS_DIR = path.join(__dirname, '..', 'reports');
+
+const PIPELINE_STAGES = ['threat-researcher', 'source-validator', 'skill-updater', 'report-generator'];
+
+// --- public API ---
+
+/**
+ * Initialize a new pipeline run for a given trigger.
+ *
+ * @param {'new_cve'|'atlas_update'|'framework_amendment'|'manual'} triggerType
+ * @param {object} triggerPayload - CVE ID, ATLAS version, etc.
+ * @returns {{ pipeline_id: string, trigger: object, stages: object[], status: string }}
+ */
+function initPipeline(triggerType, triggerPayload) {
+  const pipelineId = crypto.randomUUID();
+  const run = {
+    pipeline_id: pipelineId,
+    trigger: { type: triggerType, payload: triggerPayload, timestamp: new Date().toISOString() },
+    stages: PIPELINE_STAGES.map(name => ({
+      name,
+      status: 'pending',
+      agent_path: path.join(AGENTS_DIR, `${name}.md`),
+      started_at: null,
+      completed_at: null,
+      handoff: null,
+      errors: []
+    })),
+    status: 'initialized',
+    created_at: new Date().toISOString()
+  };
+
+  run.stages[0].status = 'ready';
+  return run;
+}
+
+/**
+ * Build the handoff package for a specific pipeline stage.
+ * This is what an AI assistant reads to understand what to do and what to pass forward.
+ *
+ * @param {object} run - Pipeline run object from initPipeline()
+ * @param {number} stageIndex - 0-based stage index
+ * @param {object} stageOutput - Output from the current stage
+ * @returns {object} Handoff package for the next stage
+ */
+function buildHandoff(run, stageIndex, stageOutput) {
+  const currentStage = run.stages[stageIndex];
+  const nextStage = run.stages[stageIndex + 1];
+
+  validateHandoff(currentStage.name, stageOutput);
+
+  const handoff = {
+    handoff_id: crypto.randomUUID(),
+    pipeline_id: run.pipeline_id,
+    from_stage: currentStage.name,
+    to_stage: nextStage?.name || 'complete',
+    timestamp: new Date().toISOString(),
+    trigger: run.trigger,
+    payload: stageOutput,
+    instructions: nextStage ? getStageInstructions(nextStage.name, stageOutput) : null
+  };
+
+  currentStage.handoff = handoff;
+  currentStage.status = 'completed';
+  currentStage.completed_at = new Date().toISOString();
+
+  if (nextStage) {
+    nextStage.status = 'ready';
+  } else {
+    run.status = 'completed';
+  }
+
+  return handoff;
+}
+
+/**
+ * Check the currency of all skills and return a report.
+ * Used by the scheduler for weekly currency checks.
+ *
+ * @returns {{ currency_report: object[], action_required: boolean }}
+ */
+function currencyCheck() {
+  const manifest = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'manifest.json'), 'utf8'));
+  const now = new Date();
+  const report = [];
+
+  for (const skill of manifest.skills) {
+    const reviewDate = new Date(skill.last_threat_review || '2020-01-01');
+    const daysSinceReview = Math.floor((now - reviewDate) / (1000 * 60 * 60 * 24));
+
+    const currencyScore = _currencyScore(daysSinceReview, skill.forward_watch?.length || 0);
+
+    report.push({
+      skill: skill.name,
+      last_threat_review: skill.last_threat_review,
+      days_since_review: daysSinceReview,
+      currency_score: currencyScore,
+      currency_label: _currencyLabel(currencyScore),
+      forward_watch_count: skill.forward_watch?.length || 0,
+      action_required: currencyScore < 70
+    });
+  }
+
+  report.sort((a, b) => a.currency_score - b.currency_score);
+
+  return {
+    currency_report: report,
+    action_required: report.some(r => r.action_required),
+    critical_count: report.filter(r => r.currency_score < 50).length,
+    check_timestamp: now.toISOString()
+  };
+}
+
+/**
+ * Get the agent definition for a stage.
+ *
+ * @param {string} stageName - Agent name
+ * @returns {string|null} Agent instruction content
+ */
+function getAgentDefinition(stageName) {
+  const agentPath = path.join(AGENTS_DIR, `${stageName}.md`);
+  try {
+    return fs.readFileSync(agentPath, 'utf8');
+  } catch (_) {
+    return null;
+  }
+}
+
+// --- private helpers ---
+
+function validateHandoff(stageName, output) {
+  const required = {
+    'threat-researcher': ['cve_id_or_ttp', 'findings', 'primary_sources', 'confidence'],
+    'source-validator': ['verdict', 'verified_claims', 'rejected_claims'],
+    'skill-updater': ['updated_skills', 'updated_data_files', 'change_summary'],
+    'report-generator': ['report_format', 'report_content', 'audience']
+  };
+
+  const req = required[stageName] || [];
+  const missing = req.filter(k => !(k in output));
+  if (missing.length > 0) {
+    throw new Error(`Handoff from ${stageName} missing required fields: ${missing.join(', ')}`);
+  }
+}
+
+function getStageInstructions(stageName, previousOutput) {
+  const instructions = {
+    'source-validator': `Validate the threat research findings. Check each claimed primary source.
+      Verify: CVE exists in NVD, CISA KEV status is accurate, RWEP factor breakdown is justified.
+      Return verdict: approved | approved_with_corrections | rejected.
+      Input: ${JSON.stringify(previousOutput, null, 2).substring(0, 500)}...`,
+
+    'skill-updater': `Apply validated research to skill files and data catalogs.
+      For each approved finding: update data/cve-catalog.json, data/zeroday-lessons.json,
+      data/framework-control-gaps.json as appropriate. Bump last_threat_review in affected skills.
+      Input: ${JSON.stringify(previousOutput, null, 2).substring(0, 500)}...`,
+
+    'report-generator': `Generate structured reports from the completed pipeline run.
+      Produce: executive-summary.md, compliance-gap-report.md as applicable.
+      Focus on RWEP scores >= 80 and compliance theater findings.
+      Input: ${JSON.stringify(previousOutput, null, 2).substring(0, 500)}...`
+  };
+
+  return instructions[stageName] || null;
+}
+
+function _currencyScore(daysSinceReview, forwardWatchCount) {
+  let score = 100;
+  if (daysSinceReview > 180) score -= 30;
+  else if (daysSinceReview > 90) score -= 20;
+  else if (daysSinceReview > 60) score -= 10;
+  else if (daysSinceReview > 30) score -= 5;
+  score -= forwardWatchCount * 5;
+  return Math.max(0, score);
+}
+
+function _currencyLabel(score) {
+  if (score >= 90) return 'current';
+  if (score >= 70) return 'acceptable';
+  if (score >= 50) return 'stale';
+  return 'critical_stale';
+}
+
+module.exports = { initPipeline, buildHandoff, currencyCheck, getAgentDefinition };

package/orchestrator/scanner.js

@@ -0,0 +1,327 @@
+'use strict';
+
+/**
+ * Environment scanner. Discovers security posture signals from the current host.
+ * Produces structured findings that dispatcher.js routes to relevant skills.
+ *
+ * Designed to be run by a human operator or an AI assistant — not a background daemon.
+ * All discovery is read-only. No writes, no network calls beyond local probes.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execFileSync, spawnSync } = require('child_process');
+
+const DATA_DIR = process.env.EXCEPTD_DATA_DIR || path.join(__dirname, '..', 'data');
+
+// --- public API ---
+
+/**
+ * Run all scanners and return consolidated findings.
+ * @returns {{ timestamp: string, host: object, findings: object[], summary: object }}
+ */
+async function scan() {
+  const timestamp = new Date().toISOString();
+  const findings = [];
+
+  const host = hostInfo();
+  findings.push(...kernelScan());
+  findings.push(...mcpScan());
+  findings.push(...cryptoScan());
+  findings.push(...aiApiScan());
+  findings.push(...frameworkScan());
+
+  const summary = summarize(findings);
+  return { timestamp, host, findings, summary };
+}
+
+/**
+ * Run a targeted scan for a specific domain.
+ * @param {'kernel'|'mcp'|'crypto'|'ai_api'|'framework'} domain
+ */
+async function scanDomain(domain) {
+  const scanners = { kernel: kernelScan, mcp: mcpScan, crypto: cryptoScan, ai_api: aiApiScan, framework: frameworkScan };
+  const fn = scanners[domain];
+  if (!fn) throw new Error(`Unknown scan domain: ${domain}. Valid: ${Object.keys(scanners).join(', ')}`);
+  return fn();
+}
+
+// --- domain scanners ---
+
+function kernelScan() {
+  const findings = [];
+  if (os.platform() !== 'linux') return findings;
+
+  const kernel = safeExecFile('uname', ['-r']) || 'unknown';
+  const catalog = loadJson('cve-catalog.json');
+
+  for (const [cveId, cve] of Object.entries(catalog)) {
+    if (cve.type !== 'LPE' && cve.type !== 'kernel') continue;
+    findings.push({
+      domain: 'kernel',
+      signal: 'kernel_version_detected',
+      value: kernel,
+      cve_id: cveId,
+      rwep_score: cve.rwep_score,
+      cisa_kev: cve.cisa_kev,
+      action_required: 'Cross-reference kernel version against patched version for this CVE',
+      skill_hint: 'kernel-lpe-triage',
+      severity: cve.rwep_score >= 90 ? 'critical' : cve.rwep_score >= 70 ? 'high' : 'medium'
+    });
+  }
+
+  return findings;
+}
+
+function mcpScan() {
+  const findings = [];
+  const homeDir = os.homedir();
+  const platform = os.platform();
+
+  const mcpLocations = [
+    { tool: 'claude-code', paths: [path.join(homeDir, '.claude', 'settings.json')] },
+    { tool: 'cursor', paths: [path.join(homeDir, '.cursor', 'mcp.json')] },
+    { tool: 'vscode', paths: [
+      path.join(homeDir, '.vscode', 'settings.json'),
+      ...(platform === 'darwin' ? [path.join(homeDir, 'Library', 'Application Support', 'Code', 'User', 'settings.json')] : []),
+      ...(platform === 'win32' ? [path.join(homeDir, 'AppData', 'Roaming', 'Code', 'User', 'settings.json')] : []),
+      ...(platform === 'linux' ? [path.join(homeDir, '.config', 'Code', 'User', 'settings.json')] : [])
+    ]},
+    { tool: 'windsurf', paths: [path.join(homeDir, '.windsurf', 'mcp.json')] },
+    { tool: 'gemini-cli', paths: [path.join(homeDir, '.gemini', 'settings.json')] }
+  ];
+
+  for (const { tool, paths } of mcpLocations) {
+    for (const p of paths) {
+      if (!fs.existsSync(p)) continue;
+      try {
+        const raw = fs.readFileSync(p, 'utf8');
+        const config = JSON.parse(raw);
+        const mcpServers = config.mcpServers || config.mcp?.servers || {};
+        const serverList = Object.keys(mcpServers);
+        if (serverList.length === 0) continue;
+
+        for (const serverName of serverList) {
+          const server = mcpServers[serverName];
+          const isSigned = server.signature !== undefined;
+          const serverJson = JSON.stringify(server);
+          const hasPinnedVersion = /[@#]\d+\.\d+\.\d+/.test(serverJson);
+
+          findings.push({
+            domain: 'mcp',
+            signal: 'mcp_server_detected',
+            tool,
+            config_path: p,
+            server_name: serverName,
+            server_config: sanitizeConfig(server),
+            signed: isSigned,
+            version_pinned: hasPinnedVersion,
+            severity: !isSigned ? 'high' : !hasPinnedVersion ? 'medium' : 'low',
+            skill_hint: 'mcp-agent-trust',
+            action_required: !isSigned
+              ? 'Unsigned MCP server — verify provenance immediately'
+              : !hasPinnedVersion
+              ? 'MCP server version not pinned — pin to a specific version'
+              : 'MCP server detected — include in security review'
+          });
+        }
+      } catch (_) {
+        findings.push({
+          domain: 'mcp',
+          signal: 'mcp_config_parse_error',
+          tool,
+          config_path: p,
+          severity: 'low',
+          action_required: 'MCP config file exists but could not be parsed'
+        });
+      }
+    }
+  }
+
+  return findings;
+}
+
+function cryptoScan() {
+  const findings = [];
+
+  const opensslRaw = safeExecFile('openssl', ['version']);
+  if (opensslRaw) {
+    const match = opensslRaw.match(/OpenSSL (\d+\.\d+\.\d+)/);
+    const version = match ? match[1] : 'unknown';
+    const [major, minor] = version.split('.').map(Number);
+    const isPqcReady = major > 3 || (major === 3 && minor >= 5);
+
+    findings.push({
+      domain: 'crypto',
+      signal: 'openssl_version',
+      value: version,
+      pqc_ready: isPqcReady,
+      severity: isPqcReady ? 'info' : 'high',
+      skill_hint: 'pqc-first',
+      action_required: isPqcReady
+        ? `OpenSSL ${version} — PQC-capable. Verify ML-KEM/ML-DSA algorithm availability.`
+        : `OpenSSL ${version} — below 3.5. Upgrade required for PQC support (ML-KEM, ML-DSA, SLH-DSA).`
+    });
+  }
+
+  const tlsProbe = probeTls();
+  if (tlsProbe) {
+    findings.push({
+      domain: 'crypto',
+      signal: 'tls_probe',
+      value: tlsProbe,
+      severity: tlsProbe.includes('TLSv1.3') ? 'info' : 'high',
+      skill_hint: 'pqc-first',
+      action_required: tlsProbe.includes('TLSv1.3')
+        ? 'TLS 1.3 detected — verify X25519+ML-KEM-768 hybrid for HNDL-exposed connections'
+        : 'TLS below 1.3 — upgrade to TLS 1.3 minimum'
+    });
+  }
+
+  return findings;
+}
+
+function aiApiScan() {
+  const findings = [];
+
+  const aiApiIndicators = [
+    { name: 'openai', envVars: ['OPENAI_API_KEY'] },
+    { name: 'anthropic', envVars: ['ANTHROPIC_API_KEY'] },
+    { name: 'google-ai', envVars: ['GOOGLE_AI_API_KEY', 'GEMINI_API_KEY'] },
+    { name: 'azure-openai', envVars: ['AZURE_OPENAI_API_KEY'] },
+    { name: 'cohere', envVars: ['COHERE_API_KEY'] },
+    { name: 'mistral', envVars: ['MISTRAL_API_KEY'] },
+    { name: 'groq', envVars: ['GROQ_API_KEY'] },
+    { name: 'together-ai', envVars: ['TOGETHER_API_KEY'] }
+  ];
+
+  for (const api of aiApiIndicators) {
+    const detected = api.envVars.some(v => process.env[v]);
+    if (!detected) continue;
+
+    findings.push({
+      domain: 'ai_api',
+      signal: 'ai_api_dependency_detected',
+      api_name: api.name,
+      severity: 'info',
+      skill_hint: 'ai-c2-detection',
+      action_required: `${api.name} AI API detected — verify process-level monitoring and query anomaly alerting`
+    });
+  }
+
+  const apiCount = findings.filter(f => f.signal === 'ai_api_dependency_detected').length;
+  if (apiCount > 0) {
+    findings.push({
+      domain: 'ai_api',
+      signal: 'ai_api_c2_risk_summary',
+      count: apiCount,
+      severity: 'medium',
+      skill_hint: 'ai-c2-detection',
+      action_required: `${apiCount} AI API(s) detected. Run ai-c2-detection skill to assess SesameOp/PROMPTFLUX exposure.`
+    });
+  }
+
+  return findings;
+}
+
+function frameworkScan() {
+  const findings = [];
+  const gaps = loadJson('framework-control-gaps.json');
+  const openGaps = Object.entries(gaps).filter(([, g]) => g.status === 'open');
+
+  if (openGaps.length > 0) {
+    findings.push({
+      domain: 'framework',
+      signal: 'open_framework_gaps',
+      count: openGaps.length,
+      universal_gaps: openGaps.filter(([, g]) => g.framework === 'ALL').length,
+      severity: 'high',
+      skill_hint: 'framework-gap-analysis',
+      action_required: `${openGaps.length} open control gaps — run framework-gap-analysis for your compliance scope`
+    });
+  }
+
+  const kev = loadJson('cve-catalog.json');
+  const kevHigh = Object.entries(kev).filter(([, c]) => c.cisa_kev && c.rwep_score >= 90);
+  if (kevHigh.length > 0) {
+    findings.push({
+      domain: 'framework',
+      signal: 'cisa_kev_high_rwep',
+      items: kevHigh.map(([id, c]) => ({ id, rwep: c.rwep_score, name: c.name })),
+      severity: 'critical',
+      skill_hint: 'compliance-theater',
+      action_required: `${kevHigh.length} CISA KEV CVEs with RWEP >= 90. Standard 30-day patch SLAs are theater for these.`
+    });
+  }
+
+  return findings;
+}
+
+// --- helpers ---
+
+function hostInfo() {
+  return {
+    platform: os.platform(),
+    arch: os.arch(),
+    release: os.release(),
+    hostname: os.hostname(),
+    scan_user: os.userInfo().username
+  };
+}
+
+function summarize(findings) {
+  const byDomain = {};
+  const bySeverity = { critical: 0, high: 0, medium: 0, low: 0, info: 0 };
+  for (const f of findings) {
+    byDomain[f.domain] = (byDomain[f.domain] || 0) + 1;
+    if (bySeverity[f.severity] !== undefined) bySeverity[f.severity]++;
+  }
+  const skills = [...new Set(findings.map(f => f.skill_hint).filter(Boolean))];
+  return {
+    total_findings: findings.length,
+    by_domain: byDomain,
+    by_severity: bySeverity,
+    recommended_skills: skills,
+    action_required: bySeverity.critical > 0 || bySeverity.high > 0
+  };
+}
+
+function safeExecFile(cmd, args) {
+  try {
+    return execFileSync(cmd, args, { timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'] })
+      .toString().trim();
+  } catch (_) {
+    return null;
+  }
+}
+
+function probeTls() {
+  const result = spawnSync('openssl', ['s_client', '-connect', 'google.com:443', '-brief'], {
+    input: '',
+    timeout: 5000,
+    stdio: ['pipe', 'pipe', 'pipe']
+  });
+  if (result.error || result.status !== 0) return null;
+  const output = (result.stdout || '').toString() + (result.stderr || '').toString();
+  const match = output.match(/Protocol\s*:\s*(TLSv\d+\.\d+)/);
+  return match ? match[1] : null;
+}
+
+function sanitizeConfig(obj) {
+  const safe = { ...obj };
+  for (const key of Object.keys(safe)) {
+    if (/token|key|secret|password|credential/i.test(key)) safe[key] = '[REDACTED]';
+  }
+  return safe;
+}
+
+function loadJson(filename) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(DATA_DIR, filename), 'utf8'));
+  } catch (_) {
+    return {};
+  }
+}
+
+module.exports = { scan, scanDomain };

package/orchestrator/scheduler.js

@@ -0,0 +1,137 @@
+'use strict';
+
+/**
+ * Scheduled task coordinator for skill currency maintenance.
+ *
+ * Schedules: weekly currency check, monthly CVE validation, annual full audit.
+ * Emits events via event-bus.js when currency thresholds are breached.
+ *
+ * This is a simple interval-based scheduler. For production use, swap for a
+ * proper cron daemon or cloud scheduler without changing the task definitions.
+ */
+
+const { bus, EVENT_TYPES } = require('./event-bus');
+const { currencyCheck } = require('./pipeline');
+
+const INTERVALS = {
+  WEEKLY_CURRENCY: 7 * 24 * 60 * 60 * 1000,
+  MONTHLY_CVE_VALIDATION: 30 * 24 * 60 * 60 * 1000,
+  ANNUAL_AUDIT: 365 * 24 * 60 * 60 * 1000
+};
+
+const CURRENCY_THRESHOLDS = {
+  critical: 50,
+  warning: 70
+};
+
+let timers = [];
+let running = false;
+
+// --- public API ---
+
+/**
+ * Start the scheduler. Runs all tasks immediately on start, then on schedule.
+ */
+function start() {
+  if (running) return;
+  running = true;
+
+  runWeeklyCurrencyCheck();
+  timers.push(setInterval(runWeeklyCurrencyCheck, INTERVALS.WEEKLY_CURRENCY));
+  timers.push(setInterval(runMonthlyCveValidation, INTERVALS.MONTHLY_CVE_VALIDATION));
+  timers.push(setInterval(runAnnualAudit, INTERVALS.ANNUAL_AUDIT));
+
+  console.log('[scheduler] Started. Weekly currency check, monthly CVE validation, annual audit scheduled.');
+}
+
+/**
+ * Stop the scheduler and clear all timers.
+ */
+function stop() {
+  for (const t of timers) clearInterval(t);
+  timers = [];
+  running = false;
+  console.log('[scheduler] Stopped.');
+}
+
+/**
+ * Run just the currency check immediately (for CLI use).
+ * @returns {object} Currency report
+ */
+function runCurrencyNow() {
+  return runWeeklyCurrencyCheck();
+}
+
+// --- task implementations ---
+
+function runWeeklyCurrencyCheck() {
+  const timestamp = new Date().toISOString();
+  console.log(`[scheduler] Running weekly currency check — ${timestamp}`);
+
+  const { currency_report, action_required, critical_count } = currencyCheck();
+
+  for (const skill of currency_report) {
+    if (skill.currency_score < CURRENCY_THRESHOLDS.critical) {
+      bus.skillCurrencyLow({
+        skill_name: skill.skill,
+        currency_score: skill.currency_score,
+        days_since_review: skill.days_since_review
+      });
+    }
+  }
+
+  const result = {
+    task: 'weekly_currency_check',
+    timestamp,
+    skills_checked: currency_report.length,
+    action_required,
+    critical_count,
+    critical_skills: currency_report.filter(s => s.currency_score < CURRENCY_THRESHOLDS.critical).map(s => s.skill),
+    warning_skills: currency_report.filter(s =>
+      s.currency_score >= CURRENCY_THRESHOLDS.critical && s.currency_score < CURRENCY_THRESHOLDS.warning
+    ).map(s => s.skill)
+  };
+
+  if (action_required) {
+    console.log(`[scheduler] Currency action required — ${critical_count} critical skills`);
+    console.log('[scheduler] Critical skills:', result.critical_skills.join(', ') || 'none');
+  }
+
+  return result;
+}
+
+function runMonthlyCveValidation() {
+  const timestamp = new Date().toISOString();
+  console.log(`[scheduler] Monthly CVE validation reminder — ${timestamp}`);
+  console.log('[scheduler] Action: Verify all data/cve-catalog.json entries against NVD and CISA KEV.');
+  console.log('[scheduler] Action: Update last_verified dates in data/exploit-availability.json.');
+  console.log('[scheduler] Run: node orchestrator/index.js validate-cves');
+
+  return {
+    task: 'monthly_cve_validation',
+    timestamp,
+    action: 'Run node orchestrator/index.js validate-cves to check all CVE entries'
+  };
+}
+
+function runAnnualAudit() {
+  const timestamp = new Date().toISOString();
+  console.log(`[scheduler] Annual full skill audit — ${timestamp}`);
+  console.log('[scheduler] All skills require full threat review against current landscape.');
+  console.log('[scheduler] See skill-update-loop for the full annual audit procedure.');
+
+  bus.emit(EVENT_TYPES.SKILL_CURRENCY_LOW, {
+    skill_name: 'ALL',
+    currency_score: 0,
+    days_since_review: 365,
+    note: 'Annual audit — all skills require review'
+  });
+
+  return {
+    task: 'annual_full_audit',
+    timestamp,
+    action: 'Invoke skill-update-loop for all skills — annual currency review required'
+  };
+}
+
+module.exports = { start, stop, runCurrencyNow };