Shannon

Core Positioning#

Shannon, developed by Keygraph, is positioned as a Fully autonomous AI pentester. Unlike traditional DAST tools or code audit tools that only provide remediation suggestions, Shannon emphasizes a "No Exploit, No Report" strategy — vulnerabilities are only included in the report if they are successfully exploited, thereby eliminating false positives.

Core Capabilities#

Fully Autonomous Operation#

• Single command to start penetration testing, automatically handles advanced 2FA/TOTP login (including Google Sign In)
• Automatic browser navigation, command-line tool invocation
• Generates final Markdown format security assessment report

Hybrid Testing Mode#

• White-box Analysis: Source code static analysis
• Black-box Verification: Dynamic HTTP/browser interaction attack verification

Parallel Agent Architecture#

Launches 5 concurrent specialized agents during vulnerability analysis and exploitation phases:

• Injection Agent (SQLi, Command Injection, Code Injection, SSTI)
• XSS Agent (Reflected, Stored, DOM-based)
• Auth Agent (Broken Authentication, JWT attacks, OAuth weaknesses)
• AuthZ Agent (Authorization Bypass, IDOR)
• SSRF Agent (Server-Side Request Forgery)

Supported Vulnerability Types#

Benchmark & Real-World Results#

• XBOW Benchmark: 96.15% success rate
• OWASP Juice Shop: 20+ high-risk vulnerabilities identified, including complete Auth Bypass, database leakage, IDOR, SSRF
• c{api}tal API: ~15 critical/high vulnerabilities, root-level Injection, Auth Bypass, Mass Assignment privilege escalation
• OWASP crAPI: 15+ critical/high vulnerabilities, JWT attacks, PostgreSQL credential leakage, SSRF stealing internal tokens

Five-Phase Pipeline Architecture#

Phase 1: Pre-Recon (External scanning Nmap/Subfinder/WhatWeb + Source code analysis)
         ↓
Phase 2: Recon (Attack surface mapping)
         ↓
Phase 3: Vulnerability Analysis (5 parallel Agents)
         ↓
Phase 4: Exploitation (5 parallel Agents, conditional execution)
         ↓
Phase 5: Reporting (Final security report)

Core Modules#

Key Design Patterns#

• Configuration-Driven: YAML + JSON Schema validation
• SDK-First: Built on @anthropic-ai/claude-agent-sdk, maxTurns: 10_000, bypassPermissions mode
• Service Boundary Separation: Activities only as Temporal wrappers; business logic in src/services/
• DI Container: Per-workflow instantiation (src/services/container.ts)
• Modular Error Handling: ErrorCode enum + Result<T,E> explicit error propagation, automatic retry (3 times per Agent)

Quick Start#

Prerequisites#

• Docker (container runtime)
• AI Provider credentials: Anthropic API Key (recommended) or Claude Code OAuth Token

Startup Steps#

# 1. Clone repository
git clone https://github.com/KeygraphHQ/shannon.git
cd shannon

# 2. Configure credentials
export ANTHROPIC_API_KEY="your-api-key"
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000

# 3. Prepare target repository (place in ./repos/ directory)
git clone https://github.com/your-org/your-repo.git ./repos/your-repo

# 4. Start testing
./shannon start URL=https://your-app.com REPO=your-repo

CLI Commands#

# Basic run
./shannon start URL=https://example.com REPO=repo-name

# Specify config file
./shannon start URL=https://example.com REPO=repo-name CONFIG=./configs/my-config.yaml

# Custom output directory
./shannon start URL=https://example.com REPO=repo-name OUTPUT=./my-reports

# Named workspace
./shannon start URL=https://example.com REPO=repo-name WORKSPACE=my-audit

# View workspace list
./shannon workspaces

# Monitor logs
./shannon logs
./shannon query ID=shannon-1234567890

# Stop
./shannon stop
./shannon stop CLEAN=true  # Complete cleanup

Configuration File Example#

authentication:
  login_type: form
  login_url: "https://your-app.com/login"
  credentials:
    username: "test@example.com"
    password: "yourpassword"
    totp_secret: "LB2E2RX7XFHSTGCK"  # Optional, for 2FA
  login_flow:
    - "Type $username into the email field"
    - "Type $password into the password field"
    - "Click the 'Sign In' button"
  success_condition:
    type: url_contains
    value: "/dashboard"

rules:
  avoid:
    - description: "AI should avoid testing logout functionality"
      type: path
      url_path: "/logout"
  focus:
    - description: "AI should emphasize testing API endpoints"
      type: path
      url_path: "/api"

Output Structure#

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

Important Disclaimers#

1. Do not run in production environments — Only for sandbox/development/testing environments
2. Explicit authorization required — Unauthorized scanning of others' systems is illegal
3. Manual review required — LLMs may produce hallucinated content
4. Cost estimate — Complete test takes ~1-1.5 hours, using Claude 4.5 Sonnet costs ~$50 USD
5. White-box mode — Shannon Lite requires access to target source code

Version Notes#

• Shannon Lite: Open source version, AGPL-3.0 license, requires target source code access
• Shannon Pro: Commercial version, contact shannon@keygraph.io for details