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

> Discover Shannon's multi-agent architecture enabling parallel vulnerability analysis and exploitation. Learn how its temporal-driven pipeline accelerates security testing.

- Repository: [KeygraphHQ/shannon](https://github.com/keygraphhq/shannon)
- Tags: architecture
- Published: 2026-02-16

---

**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`](https://github.com/KeygraphHQ/shannon/blob/main/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`](https://github.com/KeygraphHQ/shannon/blob/main/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.

```typescript
// 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`](https://github.com/KeygraphHQ/shannon/blob/main/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.

```typescript
// 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`](https://github.com/KeygraphHQ/shannon/blob/main/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.

```typescript
// 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`](https://github.com/KeygraphHQ/shannon/blob/main/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.

```typescript
// 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`](https://github.com/KeygraphHQ/shannon/blob/main/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`.

```typescript
// 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`](https://github.com/KeygraphHQ/shannon/blob/main/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`](https://github.com/KeygraphHQ/shannon/blob/main/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`](https://github.com/KeygraphHQ/shannon/blob/main/src/temporal/workflows.ts).

```bash

# 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:

```typescript
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`:

```typescript
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`](https://github.com/KeygraphHQ/shannon/blob/main/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`](https://github.com/KeygraphHQ/shannon/blob/main/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`](https://github.com/KeygraphHQ/shannon/blob/main/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`](https://github.com/KeygraphHQ/shannon/blob/main/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`](https://github.com/KeygraphHQ/shannon/blob/main/src/session-manager.ts) and executed in [`src/temporal/workflows.ts`](https://github.com/KeygraphHQ/shannon/blob/main/src/temporal/workflows.ts), reduces total assessment time while maintaining isolation between different vulnerability classes.