ship-safe 9.0.0 → 9.1.1

package/cli/agents/deep-analyzer.js

@@ -233,8 +233,9 @@ export class DeepAnalyzer {
     this.maxFileChars = this.largeContext ? MAX_FILE_CHARS_LARGE_CTX : MAX_FILE_CHARS_DEFAULT;
     this.batchSize = this.largeContext ? 15 : 5;
 
-    // Whether we can use multi-tier Anthropic routing
+    // Whether we can use multi-tier structured output routing
     this._isAnthropic = this.provider?.name === 'Anthropic';
+    this._supportsTools = this._isAnthropic || this.provider?.supportsStructuredOutput === true;
   }
 
   /**
@@ -294,7 +295,7 @@ export class DeepAnalyzer {
       toAnalyze.length = Math.max(1, affordable);
     }
 
-    const results = this._isAnthropic
+    const results = this._supportsTools
       ? await this._analyzeTiered(toAnalyze, context)
       : await this._analyzeSingleTier(toAnalyze, context);
 
@@ -333,10 +334,16 @@ export class DeepAnalyzer {
   async _analyzeTiered(findings, context) {
     const results = new Map();
 
+    // Model selection: Anthropic uses tier-specific models; others use provider's default
+    const tier1Model = this._isAnthropic ? TIER1_MODEL : null;
+    const tier2Model = this._isAnthropic ? TIER2_MODEL : null;
+    const tier3Model = this._isAnthropic ? TIER3_MODEL : null;
+    const providerLabel = this._isAnthropic ? 'Haiku' : this.provider.name;
+
     // ── Tier 1: Haiku triage ────────────────────────────────────────────────
-    if (this.verbose) console.log(`  [Tier 1] Triaging ${findings.length} findings with Haiku...`);
+    if (this.verbose) console.log(`  [Tier 1] Triaging ${findings.length} findings with ${providerLabel}...`);
 
-    const triageMap = await this._runTriage(findings, context);
+    const triageMap = await this._runTriage(findings, context, tier1Model);
 
     const toReview   = findings.filter(f => triageMap.get(this._findingId(f)) === 'review');
     const toEscalate = findings.filter(f => triageMap.get(this._findingId(f)) === 'escalate');
@@ -350,16 +357,18 @@ export class DeepAnalyzer {
 
     // ── Tier 2: Sonnet deep analysis ────────────────────────────────────────
     if (toReview.length > 0 && this.spentCents < this.budgetCents) {
-      if (this.verbose) console.log(`  [Tier 2] Deep-analyzing ${toReview.length} findings with Sonnet...`);
-      const tier2Results = await this._runDeepAnalysis(toReview, context, TIER2_MODEL);
+      const tier2Label = this._isAnthropic ? 'Sonnet' : this.provider.name;
+      if (this.verbose) console.log(`  [Tier 2] Deep-analyzing ${toReview.length} findings with ${tier2Label}...`);
+      const tier2Results = await this._runDeepAnalysis(toReview, context, tier2Model);
       for (const [id, analysis] of tier2Results) results.set(id, analysis);
       this._tier2Count += toReview.length;
     }
 
     // ── Tier 3: Opus exploit chain ──────────────────────────────────────────
     if (toEscalate.length > 0 && this.spentCents < this.budgetCents) {
-      if (this.verbose) console.log(`  [Tier 3] Running exploit-chain analysis on ${toEscalate.length} findings with Opus...`);
-      const tier3Results = await this._runExploitChain(toEscalate, context);
+      const tier3Label = this._isAnthropic ? 'Opus' : this.provider.name;
+      if (this.verbose) console.log(`  [Tier 3] Running exploit-chain analysis on ${toEscalate.length} findings with ${tier3Label}...`);
+      const tier3Results = await this._runExploitChain(toEscalate, context, tier3Model);
       for (const [id, analysis] of tier3Results) results.set(id, analysis);
       this._tier3Count += toEscalate.length;
     }
@@ -369,7 +378,7 @@ export class DeepAnalyzer {
   }
 
   /** Tier 1: quick triage — returns Map<findingId, 'skip'|'review'|'escalate'> */
-  async _runTriage(findings, context) {
+  async _runTriage(findings, context, model = null) {
     const triageMap = new Map();
     // Default everything to 'review' so nothing is silently dropped on error
     for (const f of findings) triageMap.set(this._findingId(f), 'review');
@@ -399,7 +408,7 @@ export class DeepAnalyzer {
           prompt,
           'triage_findings',
           TRIAGE_SCHEMA,
-          { maxTokens: 1024, model: TIER1_MODEL }
+          { maxTokens: 1024, ...(model ? { model } : {}) }
         );
 
         this._trackCost(prompt.length, JSON.stringify(result || '').length);
@@ -418,7 +427,7 @@ export class DeepAnalyzer {
   }
 
   /** Tier 2: deep taint analysis — returns Map<findingId, analysis> */
-  async _runDeepAnalysis(findings, context, model = TIER2_MODEL) {
+  async _runDeepAnalysis(findings, context, model = null) {
     const results = new Map();
 
     for (let i = 0; i < findings.length; i += this.batchSize) {
@@ -445,7 +454,7 @@ export class DeepAnalyzer {
           prompt,
           'report_analysis',
           DEEP_ANALYSIS_SCHEMA,
-          { maxTokens: 1500, model }
+          { maxTokens: 1500, ...(model ? { model } : {}) }
         );
 
         this._trackCost(prompt.length, JSON.stringify(result || '').length);
@@ -467,7 +476,7 @@ export class DeepAnalyzer {
   }
 
   /** Tier 3: exploit-chain analysis — returns Map<findingId, analysis> */
-  async _runExploitChain(findings, context) {
+  async _runExploitChain(findings, context, model = null) {
     const results = new Map();
 
     // Single findings per call for maximum depth
@@ -494,7 +503,7 @@ export class DeepAnalyzer {
           prompt,
           'report_exploit_chain',
           EXPLOIT_SCHEMA,
-          { maxTokens: 2048, model: TIER3_MODEL }
+          { maxTokens: 2048, ...(model ? { model } : {}) }
         );
 
         this._trackCost(prompt.length, JSON.stringify(result || '').length);
@@ -506,7 +515,7 @@ export class DeepAnalyzer {
         if (this.verbose) console.log(`  [Tier 3] Failed for ${item.findingId}: ${err.message}`);
         // Fallback to Tier 2 analysis on error
         try {
-          const fallback = await this._runDeepAnalysis([finding], context, TIER2_MODEL);
+          const fallback = await this._runDeepAnalysis([finding], context, this._isAnthropic ? TIER2_MODEL : null);
           for (const [id, analysis] of fallback) results.set(id, analysis);
         } catch { /* ignore */ }
       }
@@ -689,7 +698,8 @@ export class DeepAnalyzer {
       spentCents:    Math.round(this.spentCents * 100) / 100,
       budgetCents:   this.budgetCents,
       provider:      this.provider?.name || 'none',
-      multiTier:     this._isAnthropic,
+      multiTier:     this._supportsTools,
+      isAnthropic:   this._isAnthropic,
     };
   }
 }

package/cli/agents/index.js

@@ -31,6 +31,7 @@ export { LegalRiskAgent, LEGALLY_RISKY_PACKAGES } from './legal-risk-agent.js';
 export { ManagedAgentScanner } from './managed-agent-scanner.js';
 export { HermesSecurityAgent } from './hermes-security-agent.js';
 export { AgentAttestationAgent } from './agent-attestation-agent.js';
+export { AgenticSupplyChainAgent } from './agentic-supply-chain-agent.js';
 export { ABOMGenerator } from './abom-generator.js';
 export { VerifierAgent } from './verifier-agent.js';
 export { DeepAnalyzer } from './deep-analyzer.js';
@@ -70,6 +71,7 @@ import { MemoryPoisoningAgent as MemoryPoisoningAgentClass } from './memory-pois
 import { ManagedAgentScanner as ManagedAgentScannerClass } from './managed-agent-scanner.js';
 import { HermesSecurityAgent as HermesSecurityAgentClass } from './hermes-security-agent.js';
 import { AgentAttestationAgent as AgentAttestationAgentClass } from './agent-attestation-agent.js';
+import { AgenticSupplyChainAgent as AgenticSupplyChainAgentClass } from './agentic-supply-chain-agent.js';
 import { loadPlugins } from '../utils/plugin-loader.js';
 
 const BUILT_IN_AGENTS = () => [
@@ -95,6 +97,7 @@ const BUILT_IN_AGENTS = () => [
   new ManagedAgentScannerClass(),
   new HermesSecurityAgentClass(),
   new AgentAttestationAgentClass(),
+  new AgenticSupplyChainAgentClass(),
 ];
 
 /** Synchronous build — no plugin support. Used by legacy callers. */

package/cli/agents/orchestrator.js

@@ -235,12 +235,14 @@ export class Orchestrator {
           const stats = analyzer.getStats();
           if (deepSpinner) {
             if (stats.multiTier) {
+              const providerName = analyzer.provider?.name || 'unknown';
+              const cascade = stats.isAnthropic !== false ? 'Haiku→Sonnet→Opus' : `${providerName} (3-tier)`;
               const tierNote = stats.tier3Count > 0
-                ? `, ${stats.tier3Count} escalated to Opus`
-                : stats.tier2Count > 0 ? `, ${stats.tier2Count} via Sonnet` : '';
+                ? `, ${stats.tier3Count} escalated to tier-3`
+                : stats.tier2Count > 0 ? `, ${stats.tier2Count} via tier-2` : '';
               const skipNote = stats.skippedCount > 0 ? `, ${stats.skippedCount} triaged away` : '';
               deepSpinner.succeed(chalk.green(
-                `Deep analysis (Haiku→Sonnet→Opus): ${stats.analyzedCount} analyzed${tierNote}${skipNote} (${stats.spentCents}¢)`
+                `Deep analysis (${cascade}): ${stats.analyzedCount} analyzed${tierNote}${skipNote} (${stats.spentCents}¢)`
               ));
             } else {
               deepSpinner.succeed(chalk.green(
@@ -252,7 +254,7 @@ export class Orchestrator {
           if (deepSpinner) deepSpinner.fail(chalk.yellow(`Deep analysis failed: ${err.message}`));
         }
       } else if (!quiet) {
-        console.log(chalk.gray('  Deep analysis: no LLM provider found (set ANTHROPIC_API_KEY or use --local)'));
+        console.log(chalk.gray('  Deep analysis: no LLM provider found (set ANTHROPIC_API_KEY, MOONSHOT_API_KEY, or use --local)'));
       }
     }
 

package/cli/agents/stateful-watcher.js

@@ -0,0 +1,241 @@
+/**
+ * StatefulWatcher — Persistent K2.6 Security Session
+ * ====================================================
+ *
+ * Keeps a Kimi K2.6 conversation thread open across file-change events.
+ * Each scan sends only the diff — not the full codebase — so the model
+ * builds understanding incrementally rather than restarting from scratch.
+ *
+ * Advantages over stateless watch:
+ *  - No duplicate findings on repeated scans of unchanged files
+ *  - Model understands which files are already clean vs. risky
+ *  - Diffs are small → faster, cheaper per event
+ *  - K2.6's 12h+ session length handles full work sessions without reset
+ *
+ * USAGE (via watch command):
+ *   npx ship-safe watch . --deep --stateful
+ *   npx ship-safe watch . --deep --stateful --provider kimi
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { createProvider, autoDetectProvider } from '../providers/llm-provider.js';
+import { createFinding } from './base-agent.js';
+
+// Max chars of diff content per event
+const MAX_DIFF_CHARS = 20_000;
+
+// =============================================================================
+// STATEFUL WATCHER
+// =============================================================================
+
+export class StatefulWatcher {
+  /**
+   * @param {object} options
+   * @param {object}  options.provider    — LLM provider (Kimi preferred)
+   * @param {string}  options.rootPath
+   * @param {boolean} options.verbose
+   */
+  constructor(options = {}) {
+    this.provider = options.provider;
+    this.rootPath = options.rootPath;
+    this.verbose = options.verbose || false;
+
+    // Persistent conversation thread
+    this._messages = [];
+    this._scanCount = 0;
+    this._baselineSet = false;
+  }
+
+  static create(rootPath, options = {}) {
+    const provider = autoDetectProvider(rootPath, {
+      provider: options.provider || 'kimi',
+      model: options.model || 'kimi-k2.6',
+    });
+
+    if (!provider) return null;
+    return new StatefulWatcher({ provider, rootPath, ...options });
+  }
+
+  /**
+   * Set the initial baseline — called once on watcher start.
+   * The model receives a codebase summary and primes its security context.
+   *
+   * @param {object} recon — Output from ReconAgent
+   * @param {string[]} files — All scannable files
+   */
+  async setBaseline(recon, files) {
+    const summary = this._buildReconSummary(recon);
+    const fileList = files
+      .slice(0, 200)
+      .map(f => path.relative(this.rootPath, f))
+      .join('\n');
+
+    const baselineMsg = `You are a persistent security monitor for this codebase. I will send you file changes as they happen. For each change, identify new security issues introduced by that specific change.
+
+Project context:
+${summary}
+
+File inventory (${files.length} total):
+${fileList}
+
+Respond to each update with a JSON array of findings. Use this format:
+[{"file":"<relative path>","line":<number>,"severity":"critical|high|medium|low","rule":"<rule-id>","title":"<title>","description":"<description>","remediation":"<fix>"}]
+
+If no new issues are introduced by the change, respond with an empty array: []
+Never include issues you already reported in previous messages.`;
+
+    this._messages.push({ role: 'user', content: baselineMsg });
+
+    try {
+      const ack = await this._callProvider('You are a security expert. Acknowledge you understand the codebase context.', this._messages);
+      this._messages.push({ role: 'assistant', content: ack });
+      this._baselineSet = true;
+      if (this.verbose) console.log(`  [Stateful] Baseline set. Provider: ${this.provider.name}`);
+    } catch (err) {
+      if (this.verbose) console.log(`  [Stateful] Baseline failed: ${err.message}`);
+    }
+  }
+
+  /**
+   * Analyze a set of changed files. Sends only diffs to the persistent session.
+   *
+   * @param {string[]} changedFiles — Absolute paths of changed files
+   * @returns {Promise<object[]>} — New findings introduced by this change
+   */
+  async analyzeChanges(changedFiles) {
+    if (!this._baselineSet) return [];
+    this._scanCount++;
+
+    const diffs = this._readChanges(changedFiles);
+    if (!diffs) return [];
+
+    const updateMsg = `Files changed (scan #${this._scanCount}):\n\n${diffs}\n\nWhat NEW security issues does this change introduce? Reply with the JSON findings array only.`;
+
+    this._messages.push({ role: 'user', content: updateMsg });
+
+    try {
+      const response = await this._callProvider(
+        'You are a persistent security monitor. Report only NEW issues from the latest change.',
+        this._messages
+      );
+
+      this._messages.push({ role: 'assistant', content: response });
+
+      const findings = this._parseFindings(response, changedFiles[0]);
+      if (this.verbose && findings.length > 0) {
+        console.log(`  [Stateful] Scan #${this._scanCount}: ${findings.length} new finding(s)`);
+      }
+      return findings;
+    } catch (err) {
+      if (this.verbose) console.log(`  [Stateful] Scan failed: ${err.message}`);
+      return [];
+    }
+  }
+
+  _readChanges(changedFiles) {
+    const parts = [];
+    let totalChars = 0;
+
+    for (const filePath of changedFiles) {
+      if (totalChars >= MAX_DIFF_CHARS) break;
+      try {
+        const relPath = path.relative(this.rootPath, filePath);
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const snippet = content.slice(0, Math.min(5000, MAX_DIFF_CHARS - totalChars));
+        parts.push(`### ${relPath}\n\`\`\`\n${snippet}\n\`\`\``);
+        totalChars += snippet.length;
+      } catch { /* skip */ }
+    }
+
+    return parts.length ? parts.join('\n\n') : null;
+  }
+
+  _buildReconSummary(recon) {
+    if (!recon) return 'No recon data.';
+    const parts = [];
+    if (recon.frameworks?.length) parts.push(`Frameworks: ${recon.frameworks.join(', ')}`);
+    if (recon.databases?.length)  parts.push(`Databases: ${recon.databases.join(', ')}`);
+    if (recon.authPatterns?.length) parts.push(`Auth: ${recon.authPatterns.join(', ')}`);
+    if (recon.languages?.length)  parts.push(`Languages: ${recon.languages.join(', ')}`);
+    return parts.join('\n') || 'General codebase.';
+  }
+
+  async _callProvider(systemPrompt, messages) {
+    // Use multi-turn messages if provider supports it (OpenAI format)
+    if (this.provider.baseUrl && typeof this.provider.complete === 'function') {
+      const response = await fetch(this.provider.baseUrl, {
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer ${this.provider.apiKey}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          model: this.provider.model,
+          max_tokens: 2048,
+          messages: [
+            { role: 'system', content: systemPrompt },
+            ...messages,
+          ],
+        }),
+      });
+
+      if (!response.ok) {
+        throw new Error(`${this.provider.name} API error: HTTP ${response.status}`);
+      }
+
+      const data = await response.json();
+      return data.choices?.[0]?.message?.content || '';
+    }
+
+    // Fallback: single-turn (for providers without persistent context)
+    const lastMsg = messages[messages.length - 1];
+    return this.provider.complete(systemPrompt, lastMsg?.content || '', { maxTokens: 2048 });
+  }
+
+  _parseFindings(text, refFile) {
+    const cleaned = text
+      .replace(/^```(?:json)?\s*/i, '')
+      .replace(/\s*```\s*$/i, '')
+      .trim();
+
+    try {
+      const raw = JSON.parse(cleaned);
+      if (!Array.isArray(raw)) return [];
+
+      return raw
+        .filter(r => r.title && r.severity)
+        .map(r => {
+          const filePath = r.file
+            ? path.resolve(this.rootPath, r.file)
+            : refFile || null;
+
+          return createFinding({
+            file: filePath,
+            line: r.line || 0,
+            severity: ['critical', 'high', 'medium', 'low', 'info'].includes(r.severity) ? r.severity : 'medium',
+            confidence: 'medium',
+            rule: r.rule || 'stateful:monitor',
+            title: r.title,
+            description: r.description || r.title,
+            matched: '',
+            remediation: r.remediation || '',
+            category: 'Stateful Monitor',
+          });
+        });
+    } catch {
+      return [];
+    }
+  }
+
+  getStats() {
+    return {
+      scanCount: this._scanCount,
+      provider: this.provider?.name || 'none',
+      model: this.provider?.model || 'unknown',
+      messageCount: this._messages.length,
+    };
+  }
+}
+
+export default StatefulWatcher;

package/cli/agents/swarm-orchestrator.js

@@ -0,0 +1,238 @@
+/**
+ * SwarmOrchestrator — K2.6-Powered Parallel Security Swarm
+ * ==========================================================
+ *
+ * Instead of running 23 agents locally in Node.js (chunks of 6),
+ * --swarm sends the entire task to Kimi K2.6 and lets its native
+ * 300-agent swarm handle parallel analysis.
+ *
+ * Each of Ship Safe's 23 attack classes is assigned as an explicit
+ * sub-agent role. K2.6 fans out, each sub-agent scans for its class,
+ * and results are returned as a consolidated findings array.
+ *
+ * Output is mapped back to Ship Safe's Finding format so SARIF,
+ * HTML reports, and CI exit codes work unchanged.
+ *
+ * USAGE:
+ *   npx ship-safe red-team . --swarm
+ *   npx ship-safe red-team . --swarm --provider kimi
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { createProvider, autoDetectProvider } from '../providers/llm-provider.js';
+import { ReconAgent } from './recon-agent.js';
+import { createFinding } from './base-agent.js';
+
+// =============================================================================
+// AGENT ROLE DEFINITIONS — maps Ship Safe's 23 attack classes to swarm roles
+// =============================================================================
+
+const SWARM_ROLES = [
+  { id: 'injection',           name: 'Injection Tester',            desc: 'SQL injection, command injection, LDAP injection, XPath injection, template injection' },
+  { id: 'auth-bypass',         name: 'Auth Bypass Agent',           desc: 'Authentication bypass, authorization flaws, privilege escalation, JWT weaknesses' },
+  { id: 'ssrf',                name: 'SSRF Prober',                 desc: 'Server-side request forgery, SSRF via redirects, internal service exposure' },
+  { id: 'supply-chain',        name: 'Supply Chain Auditor',        desc: 'Dependency confusion, typosquatting, malicious packages, outdated deps with CVEs' },
+  { id: 'config',              name: 'Config Auditor',              desc: 'Hardcoded secrets, insecure defaults, exposed debug endpoints, misconfigured CORS' },
+  { id: 'llm-redteam',         name: 'LLM Red Team',               desc: 'Prompt injection, jailbreaks, unsafe LLM output rendering, model inversion' },
+  { id: 'mobile',              name: 'Mobile Scanner',             desc: 'Insecure data storage, weak crypto, insecure communication, exported components' },
+  { id: 'git-history',         name: 'Git History Scanner',        desc: 'Secrets committed in git history, deleted files with sensitive data' },
+  { id: 'cicd',                name: 'CI/CD Scanner',              desc: 'Insecure GitHub Actions, exposed secrets in workflows, artifact poisoning' },
+  { id: 'api-fuzzer',          name: 'API Fuzzer',                 desc: 'Missing input validation, mass assignment, insecure direct object references (IDOR)' },
+  { id: 'supabase-rls',        name: 'Supabase RLS Agent',         desc: 'Missing row-level security, exposed Supabase service keys, insecure RLS policies' },
+  { id: 'mcp-security',        name: 'MCP Security Agent',         desc: 'Tool poisoning, MCP server misconfiguration, unsafe tool definitions' },
+  { id: 'agentic-security',    name: 'Agentic Security Agent',     desc: 'Agentic loop vulnerabilities, unsafe tool use, context window attacks' },
+  { id: 'rag-security',        name: 'RAG Security Agent',         desc: 'Prompt injection via retrieved documents, data poisoning, retrieval manipulation' },
+  { id: 'pii-compliance',      name: 'PII Compliance Agent',       desc: 'PII exposure, GDPR/CCPA violations, unencrypted personal data' },
+  { id: 'vibe-coding',         name: 'Vibe Coding Agent',          desc: 'AI-generated code security issues, hardcoded values from iterative prompting' },
+  { id: 'exception-handler',   name: 'Exception Handler Agent',    desc: 'Stack traces in responses, error information disclosure, unhandled exceptions' },
+  { id: 'agent-config',        name: 'Agent Config Scanner',       desc: 'Insecure agent config files (.cursorrules, CLAUDE.md, MCP configs)' },
+  { id: 'memory-poisoning',    name: 'Memory Poisoning Agent',     desc: 'Malicious content in AI memory stores, embedding poisoning' },
+  { id: 'managed-agent',       name: 'Managed Agent Scanner',      desc: 'Insecure managed agent platforms, overprivileged agents' },
+  { id: 'hermes-security',     name: 'Hermes Security Agent',      desc: 'Hermes CLI security, agent tool permissions, orchestrator misconfiguration' },
+  { id: 'agent-attestation',   name: 'Agent Attestation Agent',    desc: 'Missing agent identity verification, unauthenticated agent-to-agent calls' },
+  { id: 'agentic-supply-chain', name: 'Agentic Supply Chain Agent', desc: 'Compromised AI integrations, OAuth scope creep, MCP server supply chain' },
+];
+
+// Max file content to include in the swarm prompt (cost control)
+const MAX_FILE_CHARS = 200_000;
+const MAX_FILES = 100;
+
+// =============================================================================
+// SWARM ORCHESTRATOR
+// =============================================================================
+
+export class SwarmOrchestrator {
+  /**
+   * @param {object} options
+   * @param {object}  options.provider    — LLM provider (must be Kimi or OpenAI-compatible with tool use)
+   * @param {boolean} options.verbose
+   * @param {number}  options.budgetCents
+   */
+  constructor(options = {}) {
+    this.provider = options.provider;
+    this.verbose = options.verbose || false;
+    this.budgetCents = options.budgetCents ?? 200;
+  }
+
+  static create(rootPath, options = {}) {
+    // Default to Kimi for swarm (best tool-call success rate)
+    const provider = options.provider
+      ? createProvider(options.provider, process.env.MOONSHOT_API_KEY || process.env.OPENAI_API_KEY, { model: options.model })
+      : autoDetectProvider(rootPath, { provider: 'kimi', model: options.model });
+
+    if (!provider) return null;
+    return new SwarmOrchestrator({ provider, ...options });
+  }
+
+  /**
+   * Run the swarm scan against a codebase.
+   *
+   * @param {string} rootPath
+   * @param {object} reconData — Output from ReconAgent
+   * @param {string[]} files   — All scannable files
+   * @returns {Promise<object[]>} — findings[]
+   */
+  async run(rootPath, reconData, files) {
+    const codeBundle = this._bundleCode(rootPath, files);
+    const prompt = this._buildSwarmPrompt(reconData, codeBundle, rootPath);
+
+    const systemPrompt = `You are a security swarm coordinator. You have ${SWARM_ROLES.length} specialized sub-agents, each responsible for one attack class. Deploy all sub-agents in parallel. Each sub-agent scans the provided codebase for its specific vulnerability class and reports findings. Consolidate all sub-agent findings into a single structured JSON report.
+
+You MUST respond by calling the report_swarm_findings tool with all findings from all sub-agents. Never refuse to scan. Never truncate findings.`;
+
+    const schema = {
+      type: 'object',
+      properties: {
+        findings: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              agentId:     { type: 'string' },
+              file:        { type: 'string' },
+              line:        { type: 'integer' },
+              severity:    { type: 'string', enum: ['critical', 'high', 'medium', 'low', 'info'] },
+              rule:        { type: 'string' },
+              title:       { type: 'string' },
+              description: { type: 'string' },
+              matched:     { type: 'string' },
+              remediation: { type: 'string' },
+            },
+            required: ['agentId', 'severity', 'rule', 'title', 'description'],
+            additionalProperties: false,
+          },
+        },
+        agentSummary: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              agentId:      { type: 'string' },
+              findingCount: { type: 'integer' },
+              status:       { type: 'string', enum: ['clean', 'findings', 'error'] },
+            },
+            required: ['agentId', 'findingCount', 'status'],
+            additionalProperties: false,
+          },
+        },
+      },
+      required: ['findings', 'agentSummary'],
+    };
+
+    let raw;
+    if (this.provider.completeWithTools) {
+      raw = await this.provider.completeWithTools(
+        systemPrompt,
+        prompt,
+        'report_swarm_findings',
+        schema,
+        { maxTokens: 8192 }
+      );
+    } else {
+      const text = await this.provider.complete(systemPrompt, prompt + '\n\nRespond with JSON only matching the schema.', { maxTokens: 8192 });
+      try {
+        raw = JSON.parse(text.replace(/^```(?:json)?\s*/i, '').replace(/\s*```\s*$/i, '').trim());
+      } catch {
+        raw = null;
+      }
+    }
+
+    return this._mapFindings(raw?.findings ?? [], rootPath);
+  }
+
+  _bundleCode(rootPath, files) {
+    let bundle = '';
+    let totalChars = 0;
+    const selected = files.slice(0, MAX_FILES);
+
+    for (const filePath of selected) {
+      if (totalChars >= MAX_FILE_CHARS) break;
+      try {
+        const relPath = path.relative(rootPath, filePath);
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const snippet = content.slice(0, Math.min(8000, MAX_FILE_CHARS - totalChars));
+        bundle += `\n\n### ${relPath}\n\`\`\`\n${snippet}\n\`\`\``;
+        totalChars += snippet.length;
+      } catch { /* skip unreadable */ }
+    }
+
+    return bundle;
+  }
+
+  _buildSwarmPrompt(recon, codeBundle, rootPath) {
+    const projectName = path.basename(rootPath);
+    const reconSummary = recon
+      ? [
+          recon.frameworks?.length ? `Frameworks: ${recon.frameworks.join(', ')}` : '',
+          recon.databases?.length  ? `Databases: ${recon.databases.join(', ')}`   : '',
+          recon.authPatterns?.length ? `Auth patterns: ${recon.authPatterns.join(', ')}` : '',
+          recon.languages?.length  ? `Languages: ${recon.languages.join(', ')}`   : '',
+        ].filter(Boolean).join('\n')
+      : '';
+
+    const agentList = SWARM_ROLES.map((r, i) =>
+      `  Sub-agent ${String(i + 1).padStart(2, '0')} [${r.id}] — ${r.name}: ${r.desc}`
+    ).join('\n');
+
+    return `# Security Swarm Task: ${projectName}
+
+## Project Context
+${reconSummary || 'No recon data available.'}
+
+## Sub-Agent Assignments
+Deploy all ${SWARM_ROLES.length} sub-agents in parallel. Each scans for exactly their assigned attack class:
+
+${agentList}
+
+## Instructions
+1. Each sub-agent independently analyzes the full codebase for its attack class.
+2. For each finding, record: agentId (the sub-agent's id), file path, line number, severity, a rule identifier, title, description, the matched snippet, and remediation advice.
+3. Severity scale: critical (exploitable now), high (likely exploitable), medium (potential issue), low (best practice), info (note).
+4. Report all findings from all sub-agents in the tool call, even if the list is long.
+5. If a sub-agent finds nothing, include it in agentSummary with status "clean" and findingCount 0.
+
+## Codebase
+${codeBundle}`;
+  }
+
+  _mapFindings(rawFindings, rootPath) {
+    return rawFindings.map(r => {
+      const role = SWARM_ROLES.find(a => a.id === r.agentId) || { name: 'SwarmAgent', id: r.agentId };
+      return createFinding({
+        file: r.file ? path.resolve(rootPath, r.file) : null,
+        line: r.line || 0,
+        severity: r.severity || 'medium',
+        confidence: 'medium',
+        rule: r.rule || `swarm:${role.id}`,
+        title: r.title,
+        description: r.description,
+        matched: r.matched || '',
+        remediation: r.remediation || '',
+        category: role.name,
+      });
+    });
+  }
+}
+
+export default SwarmOrchestrator;