Shannon Multi-Agent Architecture: How It Enables Parallel Vulnerability Analysis and Exploitation

Shannon uses a Temporal-driven pipeline that runs five independent vulnerability-exploitation pipelines in parallel, allowing each exploit agent to start immediately after its corresponding vulnerability agent finishes while remaining resilient to individual failures.

Shannon is an open-source penetration testing framework developed by KeygraphHQ that orchestrates specialized AI agents through a multi-agent architecture designed for parallel vulnerability analysis and exploitation. Unlike sequential scanning tools that process one vulnerability class at a time, Shannon's architecture in src/temporal/workflows.ts executes five distinct vulnerability-exploitation pipelines concurrently, significantly reducing total assessment time while maintaining granular control over each agent's lifecycle.

Understanding Shannon's Agent Orchestration Model

Agent Declaration and Prerequisites in session-manager.ts

All agents are declared in src/session-manager.ts with explicit metadata defining their execution constraints. Each agent object contains a name, human-readable displayName, and a prerequisites array that enforces sequential dependencies. The AGENT_ORDER array establishes the global execution sequence, ensuring that reconnaissance completes before any vulnerability analysis begins.

// src/session-manager.ts
export const AGENTS = {
  'pre-recon': { displayName: 'Pre-Reconnaissance', prerequisites: [] },
  'recon': { displayName: 'Reconnaissance', prerequisites: ['pre-recon'] },
  'injection-vuln': { displayName: 'Injection Vulnerability Analysis', prerequisites: ['recon'] },
  'injection-exploit': { displayName: 'Injection Exploitation', prerequisites: ['injection-vuln'] },
  // Additional agents follow the same pattern...
} as const;

Parallel Group Configuration for Vulnerability and Exploit Phases

The getParallelGroups() function in src/session-manager.ts explicitly partitions the vulnerability and exploitation agents into two parallel arrays. This configuration enables the Temporal workflow to launch all five vulnerability agents simultaneously, then immediately begin each corresponding exploit agent as soon as its prerequisite vulnerability analysis completes.

// src/session-manager.ts
export const getParallelGroups = () => ({
  vuln: ['injection-vuln', 'xss-vuln', 'auth-vuln', 'ssrf-vuln', 'authz-vuln'],
  exploit: ['injection-exploit', 'xss-exploit', 'auth-exploit', 'ssrf-exploit', 'authz-exploit']
});

Temporal Workflow Architecture for Parallel Execution

Sequential Pre-Reconnaissance and Reconnaissance Phases

The pentestPipelineWorkflow in src/temporal/workflows.ts begins execution by running the first two phases sequentially. The pre-recon and recon agents must complete before any vulnerability analysis begins, ensuring that the subsequent parallel pipelines have adequate target intelligence.

// src/temporal/workflows.ts (simplified)
await runAgent('pre-recon');
await runAgent('recon');
state.currentPhase = 'vulnerability-exploitation';

The Five Parallel Vulnerability-Exploitation Pipelines

Starting at line 59 of src/temporal/workflows.ts, the workflow transitions to the parallel vulnerability-exploitation stage. The runVulnExploitPipeline helper function encapsulates a single pipeline consisting of three steps: vulnerability analysis, exploitation queue check, and conditional exploitation.

// src/temporal/workflows.ts
async function runVulnExploitPipeline(
  vulnType: VulnType,
  runVulnAgent: () => Promise<AgentMetrics>,
  runExploitAgent: () => Promise<AgentMetrics>
): Promise<VulnExploitPipelineResult> {
  const vulnMetrics = await runVulnAgent();
  const decision = await a.checkExploitationQueue(activityInput, vulnType);
  
  let exploitMetrics: AgentMetrics | null = null;
  if (decision.shouldExploit) {
    exploitMetrics = await runExploitAgent();
  }
  
  return { vulnType, vulnMetrics, exploitMetrics, exploitDecision: decision, error: null };
}

Graceful Failure Handling with Promise.allSettled

The workflow launches all five pipelines concurrently using Promise.allSettled (lines 99-126 in src/temporal/workflows.ts). This approach ensures that the failure of one vulnerability-exploitation pipeline does not terminate the others. Each result is inspected individually, with failures logged to state.pipelineErrors while successful completions update state.agentMetrics.

// src/temporal/workflows.ts
const pipelineResults = await Promise.allSettled([
  runVulnExploitPipeline('injection', 
    () => a.runInjectionVulnAgent(activityInput), 
    () => a.runInjectionExploitAgent(activityInput)),
  runVulnExploitPipeline('xss', 
    () => a.runXssVulnAgent(activityInput), 
    () => a.runXssExploitAgent(activityInput)),
  // ... auth, ssrf, authz pipelines follow same pattern
]);

Inside the Vulnerability-Exploitation Pipeline

Step-by-Step Pipeline Execution Flow

Each parallel pipeline follows a strict three-phase execution model defined in the runVulnExploitPipeline function:

1. Vulnerability Analysis: The vulnerability agent (e.g., runInjectionVulnAgent from src/temporal/activities.ts) analyzes the target for specific vulnerability classes.
2. Exploitation Decision: The checkExploitationQueue activity evaluates whether discovered vulnerabilities warrant immediate exploitation based on configured policies.
3. Conditional Exploitation: If decision.shouldExploit returns true, the corresponding exploit agent (e.g., runInjectionExploitAgent) executes immediately without waiting for other vulnerability analyses to complete.

Real-Time Metrics and Progress Tracking

The workflow maintains a PipelineState object (defined in src/temporal/shared.ts) that tracks execution metrics for every agent. After each agent completes, its AgentMetrics (duration, cost, turn count) are appended to state.agentMetrics. The workflow exposes a getProgress query handler that allows external monitoring tools to poll the current phase, active agent, and accumulated metrics in real time.

Code Examples: Running and Monitoring Shannon

Starting a Shannon Scan from the CLI

The command-line interface parses arguments, constructs a PipelineInput object, and triggers the Temporal workflow defined in src/temporal/workflows.ts.

# Assuming a target URL and a cloned repo under ./repos/my-app

./shannon start URL=https://example.com REPO=my-app

Programmatic Invocation (Node.js)

For integration into larger security automation platforms, import the Temporal client directly:

import { startWorkflow } from './src/temporal/client.js';

async function launch() {
  const input = {
    webUrl: 'https://example.com',
    repoPath: '/tmp/instagit__wjeh2mp/repos/my-app',
    pipelineTestingMode: false,   // use production retry settings
  };
  const result = await startWorkflow(input);
  console.log('Workflow completed:', result.summary);
}

launch().catch(console.error);

Querying Live Progress

External monitoring systems can poll the workflow state using the getProgress query handler registered in pentestPipelineWorkflow:

import { queryWorkflow } from './src/temporal/client.js';

async function watch(workflowId: string) {
  const interval = setInterval(async () => {
    const progress = await queryWorkflow(workflowId, 'getProgress');
    console.log(`Phase: ${progress.currentPhase} – Agent: ${progress.currentAgent}`);
    if (progress.status !== 'running') clearInterval(interval);
  }, 5000);
}

Summary

Shannon's multi-agent architecture delivers high-performance vulnerability assessment through several key design patterns:

• Pipeline-style orchestration separates reconnaissance, vulnerability analysis, and exploitation into distinct phases managed by Temporal workflows in src/temporal/workflows.ts.
• Parallel execution of five independent vulnerability-exploitation pipelines (injection, XSS, authentication, SSRF, and authorization) eliminates sequential bottlenecks.
• Immediate exploitation allows each exploit agent to run as soon as its corresponding vulnerability analysis completes, rather than waiting for a global barrier.
• Resilient failure handling via Promise.allSettled ensures that pipeline failures are isolated and logged without terminating the overall assessment.
• Real-time observability through queryable workflow state and accumulated AgentMetrics enables external monitoring of phase transitions and resource consumption.

Frequently Asked Questions

How does Shannon decide when to run an exploit agent?

Shannon uses a conditional execution model defined in the runVulnExploitPipeline function within src/temporal/workflows.ts. After a vulnerability agent completes its analysis, the workflow invokes the checkExploitationQueue activity to evaluate whether discovered vulnerabilities meet the threshold for exploitation. Only when decision.shouldExploit returns true does the workflow execute the corresponding exploit agent (e.g., runInjectionExploitAgent).

What happens if one vulnerability-exploitation pipeline fails in Shannon?

The workflow uses Promise.allSettled to launch all five pipelines concurrently, as implemented in lines 99-126 of src/temporal/workflows.ts. This approach ensures that the failure of a single pipeline (such as the XSS or SSRF pipeline) does not cause the entire workflow to terminate. Failed pipelines are logged to state.pipelineErrors while successful completions continue to update state.agentMetrics, allowing the assessment to proceed with available results.

Can Shannon's parallel pipelines be monitored in real time?

Yes, the pentestPipelineWorkflow exposes a getProgress query handler that returns the current phase, active agent, and accumulated metrics from the PipelineState object defined in src/temporal/shared.ts. External tools can poll this query through the Temporal client to track which of the five parallel pipelines is currently active, monitor phase transitions from vulnerability analysis to exploitation, and retrieve real-time AgentMetrics including duration, cost, and turn count.

How does Shannon's architecture differ from traditional sequential vulnerability scanners?

Traditional scanners typically execute vulnerability checks in a linear sequence, waiting for all checks to complete before attempting any exploitation. Shannon's multi-agent architecture inverts this model by running five independent pipelines (injection, XSS, authentication, SSRF, authorization) in parallel through Temporal workflows. Each pipeline couples vulnerability analysis directly with conditional exploitation, allowing exploit agents to begin immediately when their specific vulnerability agent finishes rather than waiting for a global synchronization point. This pipeline-style orchestration, defined in src/session-manager.ts and executed in src/temporal/workflows.ts, reduces total assessment time while maintaining isolation between different vulnerability classes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}