Architecture

Architectural Overview

Shannon is engineered to emulate the methodology of a human penetration tester through a sophisticated multi-agent architecture. Its strength lies in combining white-box source code analysis with black-box dynamic exploitation, orchestrated through durable workflows.

System Architecture Diagram

Hybrid Testing Approach

Shannon’s power comes from combining two complementary testing methodologies:

White-Box Analysis
Black-Box Exploitation

Source Code Analysis

Shannon analyzes your application’s source code to understand:

Data Flow Paths: How user input flows through the application
Dangerous Sinks: Where untrusted data reaches sensitive operations
Security Controls: Authentication, authorization, and input validation mechanisms
Technology Stack: Frameworks, libraries, and their known vulnerability patterns
API Endpoints: All exposed routes and their parameters

Key File: src/session-manager.ts:14-108 - Agent definitions and prerequisites

export const AGENTS: Readonly<Record<AgentName, AgentDefinition>> = {
  'pre-recon': {
    name: 'pre-recon',
    displayName: 'Pre-recon agent',
    prerequisites: [],
    promptTemplate: 'pre-recon-code',
    deliverableFilename: 'code_analysis_deliverable.md',
    modelTier: 'large',
  },
  // ... more agents
};

Live Application Testing

Shannon validates findings against the running application:

Browser Automation: Playwright-based headless browser for realistic user interactions
Authentication Handling: Supports form login, SSO, 2FA/TOTP, and API authentication
Real Exploits: Executes actual injection attacks, XSS payloads, and auth bypass attempts
Evidence Collection: Screenshots, network logs, and response data
Impact Validation: Confirms that vulnerabilities can achieve real-world impact

Key File: src/session-manager.ts:152-181 - MCP agent mapping for parallel execution

export const MCP_AGENT_MAPPING: Record<string, PlaywrightAgent> = {
  // Phase 3: Vulnerability Analysis (5 parallel agents)
  'vuln-injection': 'playwright-agent1',
  'vuln-xss': 'playwright-agent2',
  'vuln-auth': 'playwright-agent3',
  'vuln-ssrf': 'playwright-agent4',
  'vuln-authz': 'playwright-agent5',
  // Phase 4: Exploitation (5 parallel agents)
  'exploit-injection': 'playwright-agent1',
  'exploit-xss': 'playwright-agent2',
  // ...
};

Core Modules

Shannon’s codebase is organized into focused, testable modules:

Agent Management

// Agent definitions registry
export const AGENTS: Readonly<Record<AgentName, AgentDefinition>> = {
  // 13 total agents across 5 phases
};

// Phase mapping for metrics aggregation
export const AGENT_PHASE_MAP: Readonly<Record<AgentName, PhaseName>> = {
  'pre-recon': 'pre-recon',
  'recon': 'recon',
  'injection-vuln': 'vulnerability-analysis',
  'injection-exploit': 'exploitation',
  // ...
};

Temporal Orchestration

Workflow Orchestration

File: src/temporal/workflows.tsThe main workflow orchestrates all five phases:

Sequential execution for pre-recon and recon
Parallel execution for 5 vuln/exploit pipelines
Configurable concurrency limits (1-5 concurrent pipelines)
Graceful error handling - other pipelines continue if one fails
Queryable progress via getProgress query

export async function pentestPipelineWorkflow(
  input: PipelineInput
): Promise<PipelineState> {
  // Phase 1: Pre-Reconnaissance
  await runSequentialPhase('pre-recon', 'pre-recon', a.runPreReconAgent);
  
  // Phase 2: Reconnaissance
  await runSequentialPhase('recon', 'recon', a.runReconAgent);
  
  // Phases 3-4: Vulnerability + Exploitation (Pipelined)
  const pipelineResults = await runWithConcurrencyLimit(
    pipelineThunks,
    maxConcurrent
  );
  
  // Phase 5: Reporting
  await runSequentialPhase('reporting', 'report', a.runReportAgent);
}

Activity Layer

File: src/temporal/activities.tsActivities are thin wrappers that:

Provide heartbeat for long-running operations
Classify errors as retryable vs. non-retryable
Manage container lifecycle
Delegate business logic to services

export async function runReconAgent(
  input: ActivityInput
): Promise<AgentMetrics> {
  return await executeAgent({
    agentName: 'recon',
    activityInput: input,
  });
}

Service Layer

Directory: src/services/Business logic layer is Temporal-agnostic:

agent-execution.ts - Agent lifecycle management
error-handling.ts - Error classification and retry logic
container.ts - Dependency injection container
prompt-manager.ts - Prompt template loading and variable substitution
queue-validation.ts - Exploitation queue validation

All services accept ActivityLogger interface and return Result<T, E> for explicit error handling.

AI Execution Engine

File: src/ai/claude-executor.ts The execution engine handles:

MCP Server Configuration

Configures Playwright and Shannon Helper MCP servers for each agent

SDK Invocation

Calls Claude Agent SDK with 10,000 max turns and bypass permissions mode

Message Streaming

Processes SDK message stream with progress updates and audit logging

Output Validation

Validates agent deliverables using agent-specific validators

Error Handling

Classifies errors and determines retry strategy

export async function runClaudePrompt(
  prompt: string,
  sourceDir: string,
  context: string = '',
  description: string = 'Claude analysis',
  agentName: string | null = null,
  auditSession: AuditSession | null = null,
  logger: ActivityLogger,
  modelTier: ModelTier = 'medium'
): Promise<ClaudePromptResult> {
  const mcpServers = buildMcpServers(sourceDir, agentName, logger);
  
  for await (const message of query({ prompt: fullPrompt, options })) {
    // Process message stream
  }
  
  return { success: true, duration, turns, cost, model };
}

Key Design Patterns

Configuration-Driven

YAML configs with JSON Schema validation for authentication, retry strategies, and testing parameters

Progressive Analysis

Each phase builds on previous results - recon uses pre-recon data, exploits use vuln analysis

SDK-First

Claude Agent SDK handles autonomous analysis - Shannon provides orchestration and validation

Modular Error Handling

Result<T,E> pattern for explicit error propagation, automatic retry with exponential backoff

Services Boundary

Activities are thin Temporal wrappers - services own business logic with no Temporal imports

DI Container

Per-workflow dependency injection for testability and isolation

Data Flow

Here’s how data flows through Shannon during a pentest:

Input

User provides URL, repository path, and optional config via CLI

Pre-Recon

External tools (nmap, subfinder, whatweb) + source code analysis → code_analysis_deliverable.md

Recon

Attack surface mapping using pre-recon data → recon_deliverable.md

Vuln Analysis

5 parallel agents analyze for specific vuln types → {vulntype}_analysis_deliverable.md + exploitation queue

Exploitation

5 parallel agents exploit queued vulnerabilities → {vulntype}_exploitation_evidence.md

Reporting

Consolidate all evidence → comprehensive_security_assessment_report.md

Supporting Systems

Audit System

Directory: src/audit/ Crash-safe append-only logging:

audit-session.ts - Session-level metrics and agent logs
workflow-logger.ts - Human-readable workflow logs
log-stream.ts - Shared stream primitive

Output structure:

audit-logs/{hostname}_{sessionId}/
├── session.json          # Metrics and session data
├── workflow.log          # Human-readable log
├── agents/               # Per-agent execution logs
├── prompts/              # Prompt snapshots
└── deliverables/
    └── comprehensive_security_assessment_report.md

Prompt Management

Directory: prompts/ Prompt templates with variable substitution:

Phase-specific prompts: pre-recon-code.txt, vuln-injection.txt, exploit-auth.txt
Shared partials in prompts/shared/: _target.txt, _rules.txt, login-instructions.txt
Variable substitution: {{TARGET_URL}}, {{CONFIG_CONTEXT}}, {{LOGIN_INSTRUCTIONS}}

Deliverable Management

Tool: save_deliverable MCP tool Agents save structured deliverables:

Markdown format with consistent structure
Git checkpointed after each agent completes
Validated by agent-specific validators before marking complete
Used as input for subsequent phases

Next Steps

Workflow Phases

Deep dive into the five phases of execution

Agent System

Learn about agent definitions and parallel execution

Temporal Orchestration

Understand durable workflows and crash recovery

Core Modules

Explore the codebase structure in detail

Get Started

Core Concepts

CLI Reference

Configuration

Advanced Usage

Guides

Architectural Overview

System Architecture Diagram

Hybrid Testing Approach

Source Code Analysis

Live Application Testing

Core Modules

Agent Management

Temporal Orchestration

AI Execution Engine

Key Design Patterns

Configuration-Driven

Progressive Analysis

SDK-First

Modular Error Handling

Services Boundary

DI Container

Data Flow

Supporting Systems

Audit System

Prompt Management

Deliverable Management

Next Steps

Workflow Phases

Agent System

Temporal Orchestration

Core Modules

Build docs developers (and LLMs) love

Get Started

Core Concepts

CLI Reference

Configuration

Advanced Usage

Guides

​Architectural Overview

​System Architecture Diagram

​Hybrid Testing Approach

​Source Code Analysis

​Live Application Testing

​Core Modules

​Agent Management

​Temporal Orchestration

​AI Execution Engine

​Key Design Patterns

Configuration-Driven

Progressive Analysis

SDK-First

Modular Error Handling

Services Boundary

DI Container

​Data Flow

​Supporting Systems

​Audit System

​Prompt Management

​Deliverable Management

​Next Steps

Workflow Phases

Agent System

Temporal Orchestration

Core Modules

Build docs developers (and LLMs) love

Architectural Overview

System Architecture Diagram

Hybrid Testing Approach

Source Code Analysis

Live Application Testing

Core Modules

Agent Management

Temporal Orchestration

AI Execution Engine

Key Design Patterns

Data Flow

Supporting Systems

Audit System

Prompt Management

Deliverable Management

Next Steps