cipher-security 2.0.8 → 2.2.0

package/lib/execution/parallel.js

@@ -0,0 +1,292 @@
+// Copyright (c) 2026 defconxt. All rights reserved.
+// Licensed under AGPL-3.0 — see LICENSE file for details.
+// CIPHER is a trademark of defconxt.
+
+/**
+ * Parallel Assessment Engine — wave-based concurrent security assessment.
+ *
+ * Dispatches independent domain assessments in parallel (wave 1),
+ * then cross-references results in a synthesis phase (wave 2).
+ *
+ * Pattern: Superpowers subagent dispatch + SuperClaude parallel execution.
+ *
+ * @module execution/parallel
+ */
+
+// ---------------------------------------------------------------------------
+// Assessment result types
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {Object} DomainAssessment
+ * @property {string} domain — Assessment domain
+ * @property {string} status — 'completed' | 'failed' | 'skipped'
+ * @property {Object} findings — Domain-specific findings
+ * @property {number} durationMs — Execution time
+ * @property {string|null} error — Error message if failed
+ */
+
+/**
+ * @typedef {Object} BriefingResult
+ * @property {DomainAssessment[]} assessments — Individual domain results
+ * @property {Object} synthesis — Cross-domain synthesis
+ * @property {number} totalDurationMs — Total wall-clock time
+ * @property {{ completed: number, failed: number, skipped: number }} summary
+ */
+
+// ---------------------------------------------------------------------------
+// ParallelAssessor
+// ---------------------------------------------------------------------------
+
+export class ParallelAssessor {
+  /**
+   * @param {{ assessors?: Record<string, Function>, timeoutMs?: number }} opts
+   */
+  constructor(opts = {}) {
+    this._assessors = opts.assessors || {};
+    this._timeoutMs = opts.timeoutMs || 30000;
+  }
+
+  /**
+   * Register a domain assessor function.
+   * @param {string} domain — Domain name (e.g., 'attack_surface', 'threat_profile')
+   * @param {Function} fn — Async function(target, context) → findings object
+   */
+  register(domain, fn) {
+    this._assessors[domain] = fn;
+  }
+
+  /**
+   * Run all registered assessors in parallel (Wave 1), then synthesize (Wave 2).
+   * @param {string} target — Assessment target
+   * @param {Object} [context] — Additional context
+   * @returns {Promise<BriefingResult>}
+   */
+  async assess(target, context = {}) {
+    const startTime = Date.now();
+
+    // Wave 1: Parallel domain assessments
+    const domains = Object.keys(this._assessors);
+    const wave1 = await Promise.allSettled(
+      domains.map(async (domain) => {
+        const domainStart = Date.now();
+        try {
+          const timeoutPromise = new Promise((_, reject) =>
+            setTimeout(() => reject(new Error(`Timeout after ${this._timeoutMs}ms`)), this._timeoutMs)
+          );
+          const findings = await Promise.race([
+            this._assessors[domain](target, context),
+            timeoutPromise,
+          ]);
+          return {
+            domain,
+            status: 'completed',
+            findings: findings || {},
+            durationMs: Date.now() - domainStart,
+            error: null,
+          };
+        } catch (err) {
+          return {
+            domain,
+            status: 'failed',
+            findings: {},
+            durationMs: Date.now() - domainStart,
+            error: err.message,
+          };
+        }
+      })
+    );
+
+    const assessments = wave1.map(r =>
+      r.status === 'fulfilled' ? r.value : {
+        domain: 'unknown',
+        status: 'failed',
+        findings: {},
+        durationMs: 0,
+        error: r.reason?.message || 'Unknown error',
+      }
+    );
+
+    // Wave 2: Cross-domain synthesis
+    const synthesis = this._synthesize(assessments, target);
+
+    const totalDurationMs = Date.now() - startTime;
+    const completed = assessments.filter(a => a.status === 'completed').length;
+    const failed = assessments.filter(a => a.status === 'failed').length;
+    const skipped = assessments.filter(a => a.status === 'skipped').length;
+
+    return {
+      assessments,
+      synthesis,
+      totalDurationMs,
+      summary: { completed, failed, skipped },
+    };
+  }
+
+  /**
+   * Cross-reference domain assessments and produce synthesis.
+   * @private
+   */
+  _synthesize(assessments, target) {
+    const completed = assessments.filter(a => a.status === 'completed');
+    if (completed.length === 0) {
+      return { target, gaps: [], priorities: [], crossReferences: [], overallRisk: 'unknown' };
+    }
+
+    // Cross-reference: find gaps between attack surface and detection coverage
+    const attackFindings = completed.find(a => a.domain === 'attack_surface')?.findings || {};
+    const detectionFindings = completed.find(a => a.domain === 'detection_coverage')?.findings || {};
+
+    const gaps = [];
+    if (attackFindings.techniques && detectionFindings.coveredTechniques) {
+      const uncovered = (attackFindings.techniques || []).filter(
+        t => !(detectionFindings.coveredTechniques || []).includes(t)
+      );
+      for (const t of uncovered) {
+        gaps.push({ technique: t, type: 'detection_gap', severity: 'high' });
+      }
+    }
+
+    // Prioritize by cross-domain risk
+    const priorities = completed
+      .flatMap(a => Object.entries(a.findings).map(([k, v]) => ({ domain: a.domain, finding: k, value: v })))
+      .slice(0, 20);
+
+    return {
+      target,
+      gaps,
+      priorities,
+      crossReferences: completed.map(a => a.domain),
+      overallRisk: gaps.length > 5 ? 'critical' : gaps.length > 2 ? 'high' : gaps.length > 0 ? 'medium' : 'low',
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Engagement Constitution
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {Object} Constitution
+ * @property {string} engagementId
+ * @property {string} target
+ * @property {Object} scope — { inScope: string[], outOfScope: string[] }
+ * @property {Object} rulesOfEngagement — { passiveOnly: boolean, activeScanAllowed: boolean, exploitAllowed: boolean, socialEngAllowed: boolean }
+ * @property {string[]} complianceFrameworks — Applicable frameworks
+ * @property {Object} severityClassification — Custom severity criteria
+ * @property {string} reportingFormat — 'json' | 'markdown' | 'sarif'
+ * @property {string} createdAt
+ */
+
+export class EngagementConstitution {
+  /**
+   * @param {Partial<Constitution>} opts
+   */
+  constructor(opts = {}) {
+    this.engagementId = opts.engagementId || `ENG-${Date.now().toString(36)}`;
+    this.target = opts.target || '';
+    this.scope = opts.scope || { inScope: [], outOfScope: [] };
+    this.rulesOfEngagement = opts.rulesOfEngagement || {
+      passiveOnly: false,
+      activeScanAllowed: true,
+      exploitAllowed: false,
+      socialEngAllowed: false,
+    };
+    this.complianceFrameworks = opts.complianceFrameworks || [];
+    this.severityClassification = opts.severityClassification || {
+      critical: 'RCE, auth bypass, data exfiltration',
+      high: 'Privilege escalation, sensitive data exposure',
+      medium: 'Information disclosure, CSRF',
+      low: 'Verbose errors, missing headers',
+      info: 'Informational findings, best practice deviations',
+    };
+    this.reportingFormat = opts.reportingFormat || 'markdown';
+    this.createdAt = opts.createdAt || new Date().toISOString();
+  }
+
+  /**
+   * Validate an output against the constitution.
+   * @param {Object} output — Security assessment output to validate
+   * @returns {{ valid: boolean, violations: string[] }}
+   */
+  validate(output) {
+    const violations = [];
+
+    // Check scope compliance
+    if (output.target && this.scope.outOfScope.length > 0) {
+      for (const excluded of this.scope.outOfScope) {
+        if (output.target.includes(excluded)) {
+          violations.push(`Target "${output.target}" is out of scope (excluded: ${excluded})`);
+        }
+      }
+    }
+
+    // Check RoE compliance
+    if (output.technique) {
+      if (this.rulesOfEngagement.passiveOnly && output.technique.includes('exploit')) {
+        violations.push(`Exploitation techniques not allowed (passive-only engagement)`);
+      }
+      if (!this.rulesOfEngagement.exploitAllowed && output.technique.includes('exploit')) {
+        violations.push(`Exploitation not authorized in rules of engagement`);
+      }
+    }
+
+    return { valid: violations.length === 0, violations };
+  }
+
+  /**
+   * Serialize to markdown.
+   * @returns {string}
+   */
+  toMarkdown() {
+    const lines = [
+      `# Engagement Constitution: ${this.engagementId}`,
+      '',
+      `**Target:** ${this.target}`,
+      `**Created:** ${this.createdAt}`,
+      `**Reporting Format:** ${this.reportingFormat}`,
+      '',
+      '## Scope',
+      '',
+      '### In Scope',
+      ...this.scope.inScope.map(s => `- ${s}`),
+      '',
+      '### Out of Scope',
+      ...this.scope.outOfScope.map(s => `- ${s}`),
+      '',
+      '## Rules of Engagement',
+      '',
+      `- Passive only: ${this.rulesOfEngagement.passiveOnly ? 'Yes' : 'No'}`,
+      `- Active scanning: ${this.rulesOfEngagement.activeScanAllowed ? 'Allowed' : 'Not allowed'}`,
+      `- Exploitation: ${this.rulesOfEngagement.exploitAllowed ? 'Allowed' : 'Not allowed'}`,
+      `- Social engineering: ${this.rulesOfEngagement.socialEngAllowed ? 'Allowed' : 'Not allowed'}`,
+      '',
+      '## Compliance Frameworks',
+      '',
+      ...(this.complianceFrameworks.length > 0 ? this.complianceFrameworks.map(f => `- ${f}`) : ['- None specified']),
+      '',
+      '## Severity Classification',
+      '',
+      ...Object.entries(this.severityClassification).map(([level, desc]) => `- **${level}:** ${desc}`),
+      '',
+    ];
+    return lines.join('\n');
+  }
+
+  /**
+   * Serialize to JSON.
+   * @returns {Object}
+   */
+  toDict() {
+    return {
+      engagementId: this.engagementId,
+      target: this.target,
+      scope: this.scope,
+      rulesOfEngagement: this.rulesOfEngagement,
+      complianceFrameworks: this.complianceFrameworks,
+      severityClassification: this.severityClassification,
+      reportingFormat: this.reportingFormat,
+      createdAt: this.createdAt,
+    };
+  }
+}

package/lib/gates/circuit-breaker.js

@@ -0,0 +1,135 @@
+// Copyright (c) 2026 defconxt. All rights reserved.
+// Licensed under AGPL-3.0 — see LICENSE file for details.
+// CIPHER is a trademark of defconxt.
+
+/**
+ * Circuit Breaker — 3-strike architecture rule.
+ *
+ * Tracks consecutive failures per issue ID. After 3 failed attempts
+ * on the same issue, halts execution and surfaces an architecture
+ * review question instead of attempting Fix #4.
+ *
+ * Source: Superpowers systematic-debugging "Three-Fix Architecture Questioning Rule"
+ *
+ * @module gates/circuit-breaker
+ */
+
+// ---------------------------------------------------------------------------
+// ThreeStrikeBreaker
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {Object} IssueState
+ * @property {number} consecutiveFailures — Current streak of failures
+ * @property {string[]} failureDescriptions — Description of each failure
+ * @property {string} lastAttempt — ISO timestamp of last attempt
+ * @property {number} totalAttempts — Total attempts (including successes)
+ */
+
+export class ThreeStrikeBreaker {
+  /**
+   * @param {{ threshold?: number }} [opts]
+   */
+  constructor(opts = {}) {
+    /** @type {Map<string, IssueState>} */
+    this._issues = new Map();
+    this._threshold = opts.threshold ?? 3;
+  }
+
+  /**
+   * Record an attempt on an issue.
+   * @param {string} issueId — Unique identifier for the issue
+   * @param {boolean} success — Whether the attempt succeeded
+   * @param {string} [description] — Description of what was tried
+   */
+  recordAttempt(issueId, success, description = '') {
+    let state = this._issues.get(issueId);
+    if (!state) {
+      state = { consecutiveFailures: 0, failureDescriptions: [], lastAttempt: '', totalAttempts: 0 };
+      this._issues.set(issueId, state);
+    }
+
+    state.totalAttempts++;
+    state.lastAttempt = new Date().toISOString();
+
+    if (success) {
+      state.consecutiveFailures = 0;
+      state.failureDescriptions = [];
+    } else {
+      state.consecutiveFailures++;
+      if (description) {
+        state.failureDescriptions.push(description);
+      }
+    }
+  }
+
+  /**
+   * Check if the circuit breaker should halt for this issue.
+   * @param {string} issueId
+   * @returns {boolean}
+   */
+  shouldHalt(issueId) {
+    const state = this._issues.get(issueId);
+    if (!state) return false;
+    return state.consecutiveFailures >= this._threshold;
+  }
+
+  /**
+   * Get the architecture review question for a halted issue.
+   * @param {string} issueId
+   * @returns {{ halted: boolean, question: string, failures: string[], totalAttempts: number }}
+   */
+  getArchitectureQuestion(issueId) {
+    const state = this._issues.get(issueId);
+    if (!state || state.consecutiveFailures < this._threshold) {
+      return { halted: false, question: '', failures: [], totalAttempts: 0 };
+    }
+
+    const failureList = state.failureDescriptions
+      .map((d, i) => `  ${i + 1}. ${d}`)
+      .join('\n');
+
+    const question = [
+      `CIRCUIT BREAKER: ${this._threshold} consecutive failures on "${issueId}".`,
+      '',
+      'Failed attempts:',
+      failureList || '  (no descriptions recorded)',
+      '',
+      'Before attempting another fix, answer these questions:',
+      '  1. Is this pattern fundamentally sound?',
+      '  2. Are we sticking with it through sheer inertia?',
+      '  3. Should we refactor architecture vs. continue fixing symptoms?',
+      '',
+      'Discuss with human before attempting more fixes.',
+    ].join('\n');
+
+    return {
+      halted: true,
+      question,
+      failures: state.failureDescriptions,
+      totalAttempts: state.totalAttempts,
+    };
+  }
+
+  /**
+   * Reset tracking for an issue.
+   * @param {string} issueId
+   */
+  reset(issueId) {
+    this._issues.delete(issueId);
+  }
+
+  /**
+   * Get current state for an issue.
+   * @param {string} issueId
+   * @returns {IssueState|null}
+   */
+  getState(issueId) {
+    return this._issues.get(issueId) || null;
+  }
+
+  /** Number of tracked issues */
+  get size() {
+    return this._issues.size;
+  }
+}