cipher-security 2.0.8 → 2.1.0

package/lib/agent-runtime/handlers/incident.js

@@ -0,0 +1,161 @@
+// Copyright (c) 2026 defconxt. All rights reserved.
+// Licensed under AGPL-3.0 — see LICENSE file for details.
+
+import { BaseHandler } from './base.js';
+
+/**
+ * INCIDENT mode handler — forensics & IR.
+ * Adds: forensic, timeline, evidence
+ */
+export class IncidentHandler extends BaseHandler {
+  constructor() { super('incident'); }
+
+  domainActions() {
+    return ['forensic', 'timeline', 'evidence'];
+  }
+
+  describeDomain(action) {
+    return {
+      'forensic': 'Extract forensic procedures and artifact collection steps',
+      'timeline': 'Build investigation timeline from technique indicators',
+      'evidence': 'List evidence sources, preservation steps, and chain-of-custody',
+    }[action];
+  }
+
+  async executeDomain(command, ctx) {
+    switch (command) {
+      case 'forensic': return this.forensic(ctx);
+      case 'timeline': return this.timeline(ctx);
+      case 'evidence': return this.evidence(ctx);
+      default: throw new Error(`Unknown INCIDENT command: ${command}`);
+    }
+  }
+
+  /** Extract forensic procedures. */
+  forensic(ctx) {
+    const { skill, technique } = ctx;
+    if (!skill) throw new Error('No SKILL.md found');
+
+    const procedures = [];
+    for (const section of skill.sections) {
+      if (/forensic|collect|acqui|preserv|analyz|examin|procedur/i.test(section.title)) {
+        procedures.push({
+          phase: section.title,
+          content: section.content.slice(0, 500),
+        });
+      }
+    }
+
+    // Extract forensic commands
+    const commands = skill.codeBlocks
+      .filter(b => ['bash', 'powershell', 'sh', 'python'].includes(b.lang))
+      .map(b => ({
+        lang: b.lang,
+        context: b.context,
+        commands: b.code.split('\n')
+          .filter(l => l.trim() && !l.trim().startsWith('#'))
+          .slice(0, 10),
+      }));
+
+    return {
+      action: 'forensic',
+      technique,
+      mode: 'INCIDENT',
+      attackIds: skill.attackIds,
+      tools: skill.tools,
+      procedures: procedures.slice(0, 10),
+      commands: commands.slice(0, 15),
+      status: 'forensic_complete',
+    };
+  }
+
+  /** Build investigation timeline framework. */
+  timeline(ctx) {
+    const { skill, technique } = ctx;
+    if (!skill) throw new Error('No SKILL.md found');
+
+    // Extract timeline-relevant data from tables
+    const artifacts = [];
+    for (const table of skill.tables) {
+      if (table.headers.some(h => /event|log|artifact|timestamp|evidence|indicator/i.test(h))) {
+        artifacts.push({
+          headers: table.headers,
+          entries: table.rows.slice(0, 15),
+        });
+      }
+    }
+
+    // Extract phases from workflow sections
+    const phases = skill.sections
+      .filter(s => /step|phase|stage|workflow|timeline|triage|contain|eradicat|recover/i.test(s.title))
+      .map(s => ({
+        phase: s.title,
+        summary: s.content.slice(0, 300),
+      }));
+
+    return {
+      action: 'timeline',
+      technique,
+      mode: 'INCIDENT',
+      attackIds: skill.attackIds,
+      artifacts: artifacts.slice(0, 5),
+      phases: phases.slice(0, 10),
+      status: 'timeline_complete',
+    };
+  }
+
+  /** Classify evidence sources as volatile or non-volatile. */
+  classifyEvidenceType(sources) {
+    if (!Array.isArray(sources)) return { volatile: [], nonVolatile: [], unclassified: [] };
+    const volatileRe = /memory|ram|process|network|connection|cache|register/i;
+    const nonVolatileRe = /disk|file|log|registry|image|backup|database/i;
+    const volatile = [];
+    const nonVolatile = [];
+    const unclassified = [];
+    sources.forEach((src, idx) => {
+      const text = typeof src === 'string' ? src : Object.values(src || {}).join(' ');
+      const isVolatile = volatileRe.test(text);
+      const isNonVolatile = nonVolatileRe.test(text);
+      if (isVolatile) { volatile.push(idx); }
+      else if (isNonVolatile) { nonVolatile.push(idx); }
+      else { unclassified.push(idx); }
+    });
+    return { volatile, nonVolatile, unclassified };
+  }
+
+  /** List evidence sources and preservation steps. */
+  evidence(ctx) {
+    const { skill, technique } = ctx;
+    if (!skill) throw new Error('No SKILL.md found');
+
+    const sources = [];
+    // Extract from tables
+    for (const table of skill.tables) {
+      if (table.headers.some(h => /source|evidence|artifact|log|location|path/i.test(h))) {
+        for (const row of table.rows) {
+          sources.push(row);
+        }
+      }
+    }
+
+    // Extract preservation notes
+    const preservation = skill.sections
+      .filter(s => /preserv|chain|custody|integrity|hash|imag/i.test(s.title))
+      .map(s => ({
+        topic: s.title,
+        content: s.content.slice(0, 300),
+      }));
+
+    return {
+      action: 'evidence',
+      technique,
+      mode: 'INCIDENT',
+      attackIds: skill.attackIds,
+      tools: skill.tools,
+      sources: sources.slice(0, 20),
+      evidenceClassification: this.classifyEvidenceType(sources.slice(0, 20)),
+      preservation: preservation.slice(0, 5),
+      status: 'evidence_complete',
+    };
+  }
+}

package/lib/agent-runtime/handlers/privacy.js

@@ -0,0 +1,190 @@
+// Copyright (c) 2026 defconxt. All rights reserved.
+// Licensed under AGPL-3.0 — see LICENSE file for details.
+
+import { BaseHandler } from './base.js';
+
+/**
+ * PRIVACY mode handler — privacy engineering & compliance.
+ * Adds: dpia, data-flow, regulations
+ */
+export class PrivacyHandler extends BaseHandler {
+  constructor() { super('privacy'); }
+
+  domainActions() {
+    return ['dpia', 'data-flow', 'regulations'];
+  }
+
+  describeDomain(action) {
+    return {
+      'dpia':        'Generate Data Protection Impact Assessment structure',
+      'data-flow':   'Extract data flow mappings and processing activities',
+      'regulations': 'Map applicable regulations and compliance requirements',
+    }[action];
+  }
+
+  async executeDomain(command, ctx) {
+    switch (command) {
+      case 'dpia':        return this.dpia(ctx);
+      case 'data-flow':   return this.dataFlow(ctx);
+      case 'regulations': return this.regulations(ctx);
+      default: throw new Error(`Unknown PRIVACY command: ${command}`);
+    }
+  }
+
+  /** Generate DPIA structure. */
+  dpia(ctx) {
+    const { skill, technique } = ctx;
+    if (!skill) throw new Error('No SKILL.md found');
+
+    const scope = ctx.flags.scope || 'unspecified';
+
+    // Extract risk items from tables
+    const risks = [];
+    for (const table of skill.tables) {
+      if (table.headers.some(h => /risk|threat|impact|severity|likelihood/i.test(h))) {
+        for (const row of table.rows) {
+          risks.push(row);
+        }
+      }
+    }
+
+    // Extract checklist items
+    const checks = [];
+    const checkRe = /^\s*[-*] \[([x ])\] (.+)$/gm;
+    let m;
+    while ((m = checkRe.exec(skill.raw))) {
+      checks.push({ item: m[2].trim(), checked: m[1] === 'x' });
+    }
+
+    // Extract mitigation sections
+    const mitigations = skill.sections
+      .filter(s => /mitigat|control|safeguard|measure|protect/i.test(s.title))
+      .map(s => ({
+        area: s.title,
+        content: s.content.slice(0, 400),
+      }));
+
+    const regs = this.extractRegulations(skill);
+
+    return {
+      action: 'dpia',
+      technique,
+      mode: 'PRIVACY',
+      scope,
+      risks: risks.slice(0, 20),
+      checks: checks.slice(0, 30),
+      mitigations: mitigations.slice(0, 10),
+      regulations: regs,
+      regulationValidation: this.validateRegulations(regs),
+      status: 'dpia_complete',
+    };
+  }
+
+  /** Extract data flow mappings. */
+  dataFlow(ctx) {
+    const { skill, technique } = ctx;
+    if (!skill) throw new Error('No SKILL.md found');
+
+    // Extract data flow sections
+    const flows = skill.sections
+      .filter(s => /data.flow|process|transfer|collect|stor|shar/i.test(s.title))
+      .map(s => ({
+        phase: s.title,
+        content: s.content.slice(0, 400),
+      }));
+
+    // Extract from tables with data categories
+    const dataCategories = [];
+    for (const table of skill.tables) {
+      if (table.headers.some(h => /data|category|type|field|pii|personal/i.test(h))) {
+        for (const row of table.rows) {
+          dataCategories.push(row);
+        }
+      }
+    }
+
+    // Extract diagrams (mermaid blocks)
+    const diagrams = skill.codeBlocks
+      .filter(b => b.lang === 'mermaid' || b.context.toLowerCase().includes('flow'))
+      .map(b => ({ context: b.context, code: b.code }));
+
+    return {
+      action: 'data-flow',
+      technique,
+      mode: 'PRIVACY',
+      flows: flows.slice(0, 10),
+      dataCategories: dataCategories.slice(0, 20),
+      diagrams: diagrams.slice(0, 5),
+      status: 'data_flow_complete',
+    };
+  }
+
+  /** Map applicable regulations. */
+  regulations(ctx) {
+    const { skill, technique } = ctx;
+    if (!skill) throw new Error('No SKILL.md found');
+
+    const regs = this.extractRegulations(skill);
+    return {
+      action: 'regulations',
+      technique,
+      mode: 'PRIVACY',
+      regulations: regs,
+      regulationValidation: this.validateRegulations(regs),
+      status: 'regulations_complete',
+    };
+  }
+
+  /** Validate regulatory references for correct format and article/section ranges. */
+  validateRegulations(refs) {
+    if (!Array.isArray(refs)) return { valid: [], invalid: [], unknown: [] };
+    const valid = [];
+    const invalid = [];
+    const unknown = [];
+    const knownFrameworks = /^(HIPAA|CCPA|PCI[\s-]DSS|SOX|SOC\s*[12]|FERPA|COPPA|LGPD|PIPEDA|NIST|ISO|OWASP|MITRE)/i;
+
+    for (const ref of refs) {
+      const s = String(ref).trim();
+      // GDPR: validate article number 1-99
+      const gdprMatch = s.match(/GDPR\s*Art(?:icle)?\.?\s*(\d+)/i);
+      if (gdprMatch) {
+        const num = parseInt(gdprMatch[1], 10);
+        if (num >= 1 && num <= 99) { valid.push(s); } else { invalid.push(s); }
+        continue;
+      }
+      if (/^GDPR$/i.test(s)) { valid.push(s); continue; }
+      // Known frameworks accepted as valid
+      if (knownFrameworks.test(s)) { valid.push(s); continue; }
+      unknown.push(s);
+    }
+    return { valid, invalid, unknown };
+  }
+
+  /** Extract regulatory references from content. */
+  extractRegulations(skill) {
+    const regs = new Set();
+    const patterns = [
+      /GDPR\s*(?:Art(?:icle)?\.?\s*\d+(?:\(\d+\))?)/gi,
+      /CCPA\s*(?:§?\s*\d+(?:\.\d+)?)?/gi,
+      /HIPAA\s*(?:§?\s*\d+(?:\.\d+)?)?/gi,
+      /PCI[\s-]DSS\s*(?:\d+(?:\.\d+)*)?/gi,
+      /SOX\s*(?:§?\s*\d+)?/gi,
+      /NIST\s*(?:SP\s*)?(?:800-\d+(?:[A-Z])?)?/gi,
+      /ISO\s*(?:27\d{3}(?:[-:]\d+)?)/gi,
+      /SOC\s*[12]/gi,
+      /FERPA/gi,
+      /COPPA/gi,
+      /LGPD/gi,
+      /PIPEDA/gi,
+    ];
+
+    for (const re of patterns) {
+      let m;
+      while ((m = re.exec(skill.raw))) {
+        regs.add(m[0].trim());
+      }
+    }
+
+    return [...regs];
+  }
+}

package/lib/agent-runtime/handlers/purple.js

@@ -0,0 +1,209 @@
+// Copyright (c) 2026 defconxt. All rights reserved.
+// Licensed under AGPL-3.0 — see LICENSE file for details.
+
+import { BaseHandler } from './base.js';
+
+/**
+ * PURPLE mode handler — detection engineering.
+ * Adds: emulate, coverage, gaps
+ */
+export class PurpleHandler extends BaseHandler {
+  constructor() { super('purple'); }
+
+  domainActions() {
+    return ['emulate', 'coverage', 'gaps'];
+  }
+
+  describeDomain(action) {
+    return {
+      'emulate':  'Build emulation plan pairing attack steps with detection validation',
+      'coverage': 'Map ATT&CK technique coverage from detection rules',
+      'gaps':     'Identify detection gaps with remediation recommendations',
+    }[action];
+  }
+
+  async executeDomain(command, ctx) {
+    switch (command) {
+      case 'emulate':  return this.emulate(ctx);
+      case 'coverage': return this.coverage(ctx);
+      case 'gaps':     return this.gaps(ctx);
+      default: throw new Error(`Unknown PURPLE command: ${command}`);
+    }
+  }
+
+  /** Build emulation plan — attack + detection pairs. */
+  emulate(ctx) {
+    const { skill, technique } = ctx;
+    if (!skill) throw new Error('No SKILL.md found');
+
+    // Extract attack steps from workflow/procedure sections
+    const attackSteps = [];
+    const detectionSteps = [];
+
+    for (const section of skill.sections) {
+      if (/step|workflow|procedure|emulat|attack|execution/i.test(section.title)) {
+        attackSteps.push({
+          phase: section.title,
+          content: section.content.slice(0, 400),
+        });
+      }
+      if (/detect|valid|verify|confirm|monitor|alert/i.test(section.title)) {
+        detectionSteps.push({
+          phase: section.title,
+          content: section.content.slice(0, 400),
+        });
+      }
+    }
+
+    // Pair attack commands with detection queries
+    const pairs = [];
+    const attackBlocks = skill.codeBlocks.filter(b =>
+      ['bash', 'powershell', 'sh', 'cmd', 'python'].includes(b.lang)
+    );
+    const detectBlocks = skill.codeBlocks.filter(b =>
+      ['yaml', 'sigma', 'kql', 'spl', 'kusto', 'splunk'].includes(b.lang)
+    );
+
+    const maxPairs = Math.min(attackBlocks.length, 10);
+    for (let i = 0; i < maxPairs; i++) {
+      pairs.push({
+        attack: {
+          lang: attackBlocks[i].lang,
+          context: attackBlocks[i].context,
+          command: attackBlocks[i].code.split('\n').slice(0, 5).join('\n'),
+        },
+        detection: detectBlocks[i] ? {
+          lang: detectBlocks[i].lang,
+          context: detectBlocks[i].context,
+          rule: detectBlocks[i].code.split('\n').slice(0, 10).join('\n'),
+        } : { note: 'No matching detection rule found — GAP' },
+      });
+    }
+
+    return {
+      action: 'emulate',
+      technique,
+      mode: 'PURPLE',
+      attackIds: skill.attackIds,
+      tools: skill.tools,
+      attackSteps: attackSteps.slice(0, 10),
+      detectionSteps: detectionSteps.slice(0, 10),
+      emulationPairs: pairs,
+      status: 'emulate_complete',
+    };
+  }
+
+  /** Map detection coverage. */
+  coverage(ctx) {
+    const { skill, technique } = ctx;
+    if (!skill) throw new Error('No SKILL.md found');
+
+    const covered = [];
+    const uncovered = [];
+
+    for (const id of skill.attackIds) {
+      // Check if any detection content references this ID
+      const hasDetection = skill.codeBlocks.some(b =>
+        (b.lang === 'yaml' || b.lang === 'sigma' || b.lang === 'kql' || b.lang === 'spl') &&
+        b.code.includes(id)
+      );
+      if (hasDetection) {
+        covered.push(id);
+      } else {
+        uncovered.push(id);
+      }
+    }
+
+    // Count detection artifacts
+    const sigmaCount = skill.codeBlocks.filter(b =>
+      (b.lang === 'yaml' || b.lang === 'sigma') &&
+      (b.code.includes('logsource') || b.code.includes('detection'))
+    ).length;
+
+    return {
+      action: 'coverage',
+      technique,
+      mode: 'PURPLE',
+      attackIds: skill.attackIds,
+      covered,
+      uncovered,
+      coveragePercent: skill.attackIds.length > 0
+        ? Math.round((covered.length / skill.attackIds.length) * 100)
+        : 0,
+      coverageGrade: this.validateCoverage(covered, uncovered),
+      sigmaRuleCount: sigmaCount,
+      status: 'coverage_complete',
+    };
+  }
+
+  /** Assign a coverage grade based on covered vs uncovered technique counts. */
+  validateCoverage(covered, uncovered) {
+    if (!Array.isArray(covered) || !Array.isArray(uncovered)) return 'N/A';
+    const total = covered.length + uncovered.length;
+    if (total === 0) return 'N/A';
+    const pct = (covered.length / total) * 100;
+    if (pct >= 90) return 'A';
+    if (pct >= 75) return 'B';
+    if (pct >= 50) return 'C';
+    if (pct >= 25) return 'D';
+    return 'F';
+  }
+
+  /** Identify detection gaps. */
+  gaps(ctx) {
+    const { skill, technique } = ctx;
+    if (!skill) throw new Error('No SKILL.md found');
+
+    const gaps = [];
+
+    // Attack techniques without detection rules
+    for (const id of skill.attackIds) {
+      const hasRule = skill.codeBlocks.some(b =>
+        ['yaml', 'sigma', 'kql', 'spl'].includes(b.lang)
+      );
+      if (!hasRule) {
+        gaps.push({
+          type: 'missing_detection',
+          attackId: id,
+          recommendation: `Create detection rule for ${id}`,
+        });
+      }
+    }
+
+    // Attack code blocks without corresponding detection
+    const attackBlockCount = skill.codeBlocks.filter(b =>
+      ['bash', 'powershell', 'sh', 'cmd'].includes(b.lang)
+    ).length;
+    const detectBlockCount = skill.codeBlocks.filter(b =>
+      ['yaml', 'sigma', 'kql', 'spl'].includes(b.lang)
+    ).length;
+
+    if (attackBlockCount > detectBlockCount) {
+      gaps.push({
+        type: 'coverage_imbalance',
+        attackCommands: attackBlockCount,
+        detectionRules: detectBlockCount,
+        recommendation: `${attackBlockCount - detectBlockCount} attack patterns lack detection rules`,
+      });
+    }
+
+    // Check for log source gaps
+    const logSources = new Set();
+    for (const block of skill.codeBlocks) {
+      if (block.code.includes('logsource')) {
+        const catMatch = block.code.match(/category:\s*(\S+)/);
+        if (catMatch) logSources.add(catMatch[1]);
+      }
+    }
+
+    return {
+      action: 'gaps',
+      technique,
+      mode: 'PURPLE',
+      attackIds: skill.attackIds,
+      gaps,
+      logSourcesCovered: [...logSources],
+      status: 'gaps_complete',
+    };
+  }
+}