cipher-security 2.0.8 → 2.1.0

package/bin/cipher.js

@@ -144,7 +144,7 @@ let queryNoStream = false;
 let autonomousMode = null;
 
 /** Set of valid autonomous mode names (lowercased). */
-const MODE_NAMES = new Set(['red', 'blue', 'incident', 'purple', 'recon', 'privacy', 'architect']);
+const MODE_NAMES = new Set(['red', 'blue', 'incident', 'purple', 'recon', 'privacy', 'architect', 'researcher']);
 
 /** Clean args with --backend, --no-stream, and --autonomous extracted */
 const cleanedArgs = [];

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

@@ -0,0 +1,199 @@
+// Copyright (c) 2026 defconxt. All rights reserved.
+// Licensed under AGPL-3.0 — see LICENSE file for details.
+
+import { BaseHandler } from './base.js';
+
+/**
+ * ARCHITECT mode handler — security architecture & design.
+ * Adds: threat-model, controls, design
+ */
+export class ArchitectHandler extends BaseHandler {
+  constructor() { super('architect'); }
+
+  domainActions() {
+    return ['threat-model', 'controls', 'design'];
+  }
+
+  describeDomain(action) {
+    return {
+      'threat-model': 'Build STRIDE/DREAD threat model from technique patterns',
+      'controls':     'Map security controls (CIS, NIST, ISO) to technique',
+      'design':       'Extract architecture design patterns and recommendations',
+    }[action];
+  }
+
+  async executeDomain(command, ctx) {
+    switch (command) {
+      case 'threat-model': return this.threatModel(ctx);
+      case 'controls':     return this.controls(ctx);
+      case 'design':       return this.design(ctx);
+      default: throw new Error(`Unknown ARCHITECT command: ${command}`);
+    }
+  }
+
+  /** Build threat model structure. */
+  threatModel(ctx) {
+    const { skill, technique } = ctx;
+    if (!skill) throw new Error('No SKILL.md found');
+
+    const scope = ctx.flags.scope || 'unspecified';
+
+    // Extract STRIDE elements from content
+    const stride = {
+      spoofing: [],
+      tampering: [],
+      repudiation: [],
+      informationDisclosure: [],
+      dos: [],
+      elevationOfPrivilege: [],
+    };
+
+    const stridePatterns = {
+      spoofing: /spoof|impersonat|forge|fake identity/i,
+      tampering: /tamper|modif|alter|inject|manipulat/i,
+      repudiation: /repudiat|non-repudiat|audit|log/i,
+      informationDisclosure: /disclos|leak|expos|exfiltrat|data breach/i,
+      dos: /denial.of.service|dos|ddos|availability|exhaust/i,
+      elevationOfPrivilege: /privilege.escalat|elevat|root|admin|bypass auth/i,
+    };
+
+    for (const section of skill.sections) {
+      for (const [category, pattern] of Object.entries(stridePatterns)) {
+        if (pattern.test(section.title) || pattern.test(section.content.slice(0, 200))) {
+          stride[category].push({
+            source: section.title,
+            summary: section.content.slice(0, 200),
+          });
+        }
+      }
+    }
+
+    // Extract trust boundaries from diagrams
+    const diagrams = skill.codeBlocks
+      .filter(b => b.lang === 'mermaid' || /diagram|flow|architect/i.test(b.context))
+      .map(b => ({ context: b.context, code: b.code }));
+
+    return {
+      action: 'threat-model',
+      technique,
+      mode: 'ARCHITECT',
+      scope,
+      attackIds: skill.attackIds,
+      stride,
+      diagrams: diagrams.slice(0, 5),
+      mitigations: this.extractRecommendations(skill),
+      status: 'threat_model_complete',
+    };
+  }
+
+  /** Map security controls. */
+  controls(ctx) {
+    const { skill, technique } = ctx;
+    if (!skill) throw new Error('No SKILL.md found');
+
+    // Extract control references
+    const controlRefs = new Set();
+    const patterns = [
+      /CIS\s*(?:Control\s*)?\d+(?:\.\d+)*/gi,
+      /NIST\s*(?:SP\s*)?(?:800-\d+(?:[A-Z])?\s*)?(?:[A-Z]{2}-\d+)?/gi,
+      /ISO\s*27\d{3}(?:[-:]\d+(?:\.\d+)*)?/gi,
+      /SOC\s*[12](?:\s*Type\s*[12I]+)?/gi,
+      /PCI[\s-]DSS\s*(?:v?\d+(?:\.\d+)?\s*)?(?:Req(?:uirement)?\s*\d+(?:\.\d+)*)?/gi,
+      /OWASP\s*(?:Top\s*10)?\s*(?:A\d{2}(?::\d{4})?)?/gi,
+      /MITRE\s*(?:ATT&CK|D3FEND)/gi,
+    ];
+
+    for (const re of patterns) {
+      let m;
+      while ((m = re.exec(skill.raw))) {
+        controlRefs.add(m[0].trim());
+      }
+    }
+
+    // Extract from tables with control columns
+    const controlTables = [];
+    for (const table of skill.tables) {
+      if (table.headers.some(h => /control|requirement|standard|framework|compliance/i.test(h))) {
+        controlTables.push({
+          headers: table.headers,
+          rows: table.rows.slice(0, 15),
+        });
+      }
+    }
+
+    const controlsList = [...controlRefs];
+
+    return {
+      action: 'controls',
+      technique,
+      mode: 'ARCHITECT',
+      attackIds: skill.attackIds,
+      controls: controlsList,
+      controlValidation: this.validateControlRefs(controlsList),
+      controlTables: controlTables.slice(0, 5),
+      status: 'controls_complete',
+    };
+  }
+
+  /** Validate control reference strings against known framework formats. */
+  validateControlRefs(controls) {
+    if (!Array.isArray(controls)) return { valid: [], invalid: [], total: 0 };
+    const patterns = [
+      /^CIS\s*(?:Control\s*)?\d+(?:\.\d+)*/i,
+      /^NIST\s*(?:SP\s*)?800-\d+/i,
+      /^(?:AC|AT|AU|CA|CM|CP|IA|IR|MA|MP|PE|PL|PM|PS|RA|SA|SC|SI|SR)-\d+/i,
+      /^ISO\s*27\d{3}/i,
+      /^OWASP/i,
+      /^PCI[\s-]DSS/i,
+      /^SOC\s*[12]/i,
+      /^MITRE\s*(?:ATT&CK|D3FEND)/i,
+    ];
+    const valid = [];
+    const invalid = [];
+    for (const ref of controls) {
+      const s = String(ref).trim();
+      if (patterns.some(p => p.test(s))) { valid.push(s); } else { invalid.push(s); }
+    }
+    return { valid, invalid, total: controls.length };
+  }
+
+  /** Extract architecture design patterns. */
+  design(ctx) {
+    const { skill, technique } = ctx;
+    if (!skill) throw new Error('No SKILL.md found');
+
+    // Extract design/architecture sections
+    const patterns = skill.sections
+      .filter(s => /design|architect|pattern|principle|best.practice|implement/i.test(s.title))
+      .map(s => ({
+        area: s.title,
+        content: s.content.slice(0, 400),
+      }));
+
+    // Extract configuration examples
+    const configs = skill.codeBlocks
+      .filter(b => ['yaml', 'json', 'toml', 'hcl', 'tf', 'xml'].includes(b.lang))
+      .map(b => ({
+        lang: b.lang,
+        context: b.context,
+        config: b.code.slice(0, 500),
+      }));
+
+    // Extract diagrams
+    const diagrams = skill.codeBlocks
+      .filter(b => b.lang === 'mermaid')
+      .map(b => ({ context: b.context, code: b.code }));
+
+    return {
+      action: 'design',
+      technique,
+      mode: 'ARCHITECT',
+      tools: skill.tools,
+      patterns: patterns.slice(0, 10),
+      configs: configs.slice(0, 10),
+      diagrams: diagrams.slice(0, 5),
+      recommendations: this.extractRecommendations(skill),
+      status: 'design_complete',
+    };
+  }
+}

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

@@ -0,0 +1,240 @@
+// Copyright (c) 2026 defconxt. All rights reserved.
+// Licensed under AGPL-3.0 — see LICENSE file for details.
+
+/**
+ * Base handler — shared actions every domain handler inherits.
+ *
+ * Subclasses override domainActions() and executeDomain() to add
+ * domain-specific commands on top of the common set.
+ */
+
+export class BaseHandler {
+  constructor(mode) {
+    this.mode = mode;
+  }
+
+  /** All available actions (common + domain-specific). */
+  actions() {
+    return [...this.commonActions(), ...this.domainActions()];
+  }
+
+  /** Actions shared across all modes. */
+  commonActions() {
+    return ['analyze', 'enumerate', 'assess', 'report'];
+  }
+
+  /** Override in subclass — domain-specific actions. */
+  domainActions() {
+    return [];
+  }
+
+  /** Description for help text. Override per-action in subclass. */
+  describe(action) {
+    const common = {
+      analyze:   'Extract knowledge, tables, ATT&CK mappings from SKILL.md',
+      enumerate: 'List commands and tools from api-reference.md',
+      assess:    'Evaluate against technique checklist',
+      report:    'Generate structured findings report',
+    };
+    return common[action] || this.describeDomain(action) || 'No description';
+  }
+
+  /** Override in subclass for domain-specific descriptions. */
+  describeDomain(action) { return null; }
+
+  /** Dispatch to the right action. */
+  async execute(command, ctx) {
+    switch (command) {
+      case 'analyze':   return this.analyze(ctx);
+      case 'enumerate': return this.enumerate(ctx);
+      case 'assess':    return this.assess(ctx);
+      case 'report':    return this.report(ctx);
+      default:          return this.executeDomain(command, ctx);
+    }
+  }
+
+  /** Override in subclass for domain-specific execution. */
+  async executeDomain(command, ctx) {
+    throw new Error(`Unknown command: ${command}`);
+  }
+
+  // ── Common actions ────────────────────────────────────────────────
+
+  /** Analyze SKILL.md — extract all structured data. */
+  analyze(ctx) {
+    const { skill, technique, domain, mode } = ctx;
+    if (!skill) throw new Error('No SKILL.md found');
+
+    return {
+      action: 'analyze',
+      technique,
+      domain,
+      mode: mode.toUpperCase(),
+      name: skill.frontmatter?.name || technique,
+      description: skill.frontmatter?.description || '',
+      tags: skill.frontmatter?.tags || [],
+      attackIds: skill.attackIds,
+      tools: skill.tools,
+      sections: skill.sections.map(s => ({
+        level: s.level,
+        title: s.title,
+        // Truncate content to avoid dumping entire SKILL.md
+        summary: s.content.slice(0, 200) + (s.content.length > 200 ? '...' : ''),
+      })),
+      tables: skill.tables.map(t => ({
+        headers: t.headers,
+        rowCount: t.rows.length,
+        sample: t.rows.slice(0, 3),
+      })),
+      codeBlockCount: skill.codeBlocks.length,
+      status: 'analyze_complete',
+    };
+  }
+
+  /** Enumerate commands/tools from api-reference.md. */
+  enumerate(ctx) {
+    const source = ctx.apiRef || ctx.skill;
+    if (!source) throw new Error('No api-reference.md or SKILL.md found');
+
+    const commands = [];
+
+    // Extract from code blocks
+    for (const block of source.codeBlocks) {
+      for (const line of block.code.split('\n')) {
+        const trimmed = line.trim();
+        // Skip comments and empty lines
+        if (!trimmed || trimmed.startsWith('#') || trimmed.startsWith('//') || trimmed.startsWith('*')) continue;
+        // Skip pure Python/JS function defs — only collect executable commands
+        if (trimmed.startsWith('def ') || trimmed.startsWith('function ') || trimmed.startsWith('import ')) continue;
+        if (trimmed.startsWith('class ') || trimmed.startsWith('from ')) continue;
+        commands.push({
+          command: trimmed,
+          lang: block.lang,
+          context: block.context,
+        });
+      }
+    }
+
+    // Extract from tables (command tables)
+    for (const table of source.tables) {
+      const cmdHeader = table.headers.find(h =>
+        /command|syntax|usage/i.test(h)
+      );
+      if (cmdHeader) {
+        for (const row of table.rows) {
+          commands.push({
+            command: row[cmdHeader],
+            description: row[table.headers.find(h => /description|purpose/i.test(h))] || '',
+            context: 'table',
+          });
+        }
+      }
+    }
+
+    return {
+      action: 'enumerate',
+      technique: ctx.technique,
+      domain: ctx.domain,
+      mode: ctx.mode.toUpperCase(),
+      tools: source.tools,
+      commandCount: commands.length,
+      commands: commands.slice(0, 50), // Cap output size
+      status: 'enumerate_complete',
+    };
+  }
+
+  /** Assess against technique checklist. */
+  assess(ctx) {
+    const { skill, technique, domain, mode, flags } = ctx;
+    if (!skill) throw new Error('No SKILL.md found');
+
+    const target = flags.target || flags.scope || 'unspecified';
+
+    // Build checklist from tables and sections
+    const checklist = [];
+
+    // Look for prerequisite tables
+    for (const table of skill.tables) {
+      if (table.headers.some(h => /requirement|prerequisite|control|check/i.test(h))) {
+        for (const row of table.rows) {
+          const item = row[table.headers[0]] || Object.values(row)[0];
+          checklist.push({
+            item,
+            category: table.headers[0],
+            status: 'needs_review',
+          });
+        }
+      }
+    }
+
+    // Look for checklist patterns in content ([ ] and [x])
+    const checklistRe = /^\s*[-*] \[([x ])\] (.+)$/gm;
+    let m;
+    while ((m = checklistRe.exec(skill.raw))) {
+      checklist.push({
+        item: m[2].trim(),
+        category: 'checklist',
+        status: m[1] === 'x' ? 'implemented' : 'needs_review',
+      });
+    }
+
+    return {
+      action: 'assess',
+      technique,
+      domain,
+      mode: mode.toUpperCase(),
+      target,
+      attackIds: skill.attackIds,
+      checklistItems: checklist.length,
+      checklist: checklist.slice(0, 50),
+      coverage: checklist.length > 0
+        ? `${checklist.filter(c => c.status === 'implemented').length}/${checklist.length}`
+        : 'no checklist found',
+      status: 'assess_complete',
+    };
+  }
+
+  /** Generate structured report. */
+  report(ctx) {
+    const { skill, technique, domain, mode, flags } = ctx;
+    if (!skill) throw new Error('No SKILL.md found');
+
+    const format = flags.format || 'json';
+    const title = skill.frontmatter?.name || technique;
+
+    return {
+      action: 'report',
+      technique,
+      domain,
+      mode: mode.toUpperCase(),
+      report: {
+        title,
+        description: skill.frontmatter?.description || '',
+        attackTechniques: skill.attackIds,
+        tools: skill.tools,
+        sections: skill.sections.map(s => s.title),
+        tableCount: skill.tables.length,
+        codeBlockCount: skill.codeBlocks.length,
+        recommendations: this.extractRecommendations(skill),
+      },
+      format,
+      status: 'report_complete',
+    };
+  }
+
+  /** Extract recommendations from sections named remediation, mitigation, etc. */
+  extractRecommendations(skill) {
+    const recs = [];
+    const recSections = skill.sections.filter(s =>
+      /remediat|mitigat|recommend|harden|defense|protect|prevent/i.test(s.title)
+    );
+    for (const s of recSections) {
+      // Extract list items
+      const items = s.content.match(/^[-*] .+$/gm);
+      if (items) {
+        recs.push(...items.map(i => i.replace(/^[-*] /, '').trim()));
+      }
+    }
+    return recs.slice(0, 20);
+  }
+}

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

@@ -0,0 +1,220 @@
+// Copyright (c) 2026 defconxt. All rights reserved.
+// Licensed under AGPL-3.0 — see LICENSE file for details.
+
+import { BaseHandler } from './base.js';
+
+/**
+ * BLUE mode handler — defensive security.
+ * Adds: detect (Sigma rules, log queries), hunt, harden
+ */
+export class BlueHandler extends BaseHandler {
+  constructor() { super('blue'); }
+
+  domainActions() {
+    return ['detect', 'hunt', 'harden'];
+  }
+
+  describeDomain(action) {
+    return {
+      'detect':  'Generate detection rules (Sigma, KQL, SPL) from technique patterns',
+      'hunt':    'Build threat hunting queries from technique indicators',
+      'harden':  'Extract hardening recommendations and CIS controls',
+    }[action];
+  }
+
+  async executeDomain(command, ctx) {
+    switch (command) {
+      case 'detect':  return this.detect(ctx);
+      case 'hunt':    return this.hunt(ctx);
+      case 'harden':  return this.harden(ctx);
+      default: throw new Error(`Unknown BLUE command: ${command}`);
+    }
+  }
+
+  /** Generate detection rules from SKILL.md patterns. */
+  detect(ctx) {
+    const { skill, technique } = ctx;
+    if (!skill) throw new Error('No SKILL.md found');
+
+    const format = ctx.flags.format || 'sigma';
+    const rules = [];
+
+    // Extract Sigma rules from code blocks
+    for (const block of skill.codeBlocks) {
+      if (block.lang === 'yaml' || block.lang === 'sigma') {
+        if (block.code.includes('logsource') || block.code.includes('detection')) {
+          rules.push({
+            type: 'sigma',
+            context: block.context,
+            rule: block.code,
+          });
+        }
+      }
+    }
+
+    // Extract KQL/SPL queries
+    for (const block of skill.codeBlocks) {
+      if (block.lang === 'kql' || block.lang === 'kusto') {
+        rules.push({ type: 'kql', context: block.context, query: block.code });
+      }
+      if (block.lang === 'spl' || block.lang === 'splunk') {
+        rules.push({ type: 'spl', context: block.context, query: block.code });
+      }
+    }
+
+    // Extract detection patterns from tables
+    const detectionTables = [];
+    for (const table of skill.tables) {
+      if (table.headers.some(h => /event.?id|log|detection|indicator|signature/i.test(h))) {
+        detectionTables.push({
+          headers: table.headers,
+          rows: table.rows.slice(0, 10),
+        });
+      }
+    }
+
+    // Build detection summary from content
+    const detectionSections = skill.sections
+      .filter(s => /detect|sigma|rule|alert|monitor|query/i.test(s.title))
+      .map(s => ({
+        title: s.title,
+        summary: s.content.slice(0, 300),
+      }));
+
+    const sigmaValidation = this.validateSigmaRules(rules);
+
+    return {
+      action: 'detect',
+      technique,
+      mode: 'BLUE',
+      attackIds: skill.attackIds,
+      requestedFormat: format,
+      rules,
+      detectionTables,
+      detectionSections,
+      sigmaValid: sigmaValidation.invalid.length === 0,
+      sigmaErrors: sigmaValidation.errors,
+      evasionConsiderations: this.extractEvasionNotes(skill),
+      status: 'detect_complete',
+    };
+  }
+
+  /** Build threat hunting queries. */
+  hunt(ctx) {
+    const { skill, technique } = ctx;
+    if (!skill) throw new Error('No SKILL.md found');
+
+    const queries = [];
+
+    // Extract hunting-relevant code blocks
+    const huntLangs = ['kql', 'kusto', 'spl', 'splunk', 'sql', 'powershell', 'bash'];
+    for (const block of skill.codeBlocks) {
+      if (huntLangs.includes(block.lang)) {
+        queries.push({
+          lang: block.lang,
+          context: block.context,
+          query: block.code,
+        });
+      }
+    }
+
+    // Extract indicators from tables
+    const indicators = [];
+    for (const table of skill.tables) {
+      if (table.headers.some(h => /indicator|ioc|artifact|evidence|event/i.test(h))) {
+        indicators.push(...table.rows.slice(0, 10));
+      }
+    }
+
+    // Hunt hypothesis from sections
+    const hypotheses = skill.sections
+      .filter(s => /hunt|hypothesis|scenario|use.case/i.test(s.title))
+      .map(s => ({
+        title: s.title,
+        content: s.content.slice(0, 300),
+      }));
+
+    return {
+      action: 'hunt',
+      technique,
+      mode: 'BLUE',
+      attackIds: skill.attackIds,
+      tools: skill.tools,
+      queries: queries.slice(0, 20),
+      indicators: indicators.slice(0, 20),
+      hypotheses: hypotheses.slice(0, 5),
+      status: 'hunt_complete',
+    };
+  }
+
+  /** Extract hardening recommendations. */
+  harden(ctx) {
+    const { skill, technique } = ctx;
+    if (!skill) throw new Error('No SKILL.md found');
+
+    const recommendations = this.extractRecommendations(skill);
+
+    // Extract CIS/NIST references
+    const controls = [];
+    const controlRe = /(?:CIS|NIST|ISO)\s*[\w.-]+/g;
+    let m;
+    while ((m = controlRe.exec(skill.raw))) {
+      controls.push(m[0]);
+    }
+
+    // Extract configuration code blocks
+    const configs = skill.codeBlocks
+      .filter(b => /config|harden|secure|policy|baseline/i.test(b.context))
+      .map(b => ({
+        lang: b.lang,
+        context: b.context,
+        config: b.code.slice(0, 500),
+      }));
+
+    return {
+      action: 'harden',
+      technique,
+      mode: 'BLUE',
+      attackIds: skill.attackIds,
+      recommendations,
+      controls: [...new Set(controls)],
+      configs: configs.slice(0, 10),
+      evasionConsiderations: this.extractEvasionNotes(skill),
+      status: 'harden_complete',
+    };
+  }
+
+  /** Validate Sigma rules for required structural fields. */
+  validateSigmaRules(rules) {
+    if (!Array.isArray(rules)) return { valid: [], invalid: [], errors: [] };
+    const requiredFields = ['title:', 'logsource:', 'detection:', 'condition:'];
+    const valid = [];
+    const invalid = [];
+    const errors = [];
+    rules.forEach((rule, idx) => {
+      const ruleText = typeof rule === 'string' ? rule : (rule && rule.rule) || '';
+      const missing = requiredFields.filter(f => !ruleText.includes(f));
+      if (missing.length === 0) {
+        valid.push(idx);
+      } else {
+        invalid.push(idx);
+        errors.push({ index: idx, missing: missing.map(f => f.replace(':', '')) });
+      }
+    });
+    return { valid, invalid, errors };
+  }
+
+  /** PURPLE layer — every BLUE output includes evasion considerations. */
+  extractEvasionNotes(skill) {
+    const notes = [];
+    for (const section of skill.sections) {
+      if (/evas|bypass|limitation|blind.spot|false.negative|gap/i.test(section.title)) {
+        notes.push({
+          area: section.title,
+          summary: section.content.slice(0, 200),
+        });
+      }
+    }
+    return notes.slice(0, 5);
+  }
+}