Skip to main content
Get Shannon up and running with a single command. This guide will have you executing your first automated penetration test in under 5 minutes.

​
Prerequisites

Before you begin, ensure you have:
Shannon uses Claude models for autonomous security analysis. You’ll need an active Anthropic API key to run pentests.

​
Three Steps to Your First Pentest

1

Clone and Configure

Clone Shannon and set up your API credentials:
# Clone the repository
git clone https://github.com/KeygraphHQ/shannon.git
cd shannon

# Configure your API key (choose one method)

export ANTHROPIC_API_KEY="your-api-key"
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000
Setting CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000 enables larger tool outputs and improves analysis quality.
2

Prepare Your Repository

Shannon analyzes source code to guide its attacks. Place your target repository in the ./repos/ directory:
# Clone your target application
git clone https://github.com/your-org/your-app.git ./repos/your-app
The REPO parameter refers to a folder name inside ./repos/, not an absolute path.
3

Run Your First Pentest

Launch Shannon with a single command:
./shannon start URL=https://your-app.com REPO=your-app
Shannon will:
  • Build and start Docker containers
  • Initialize the Temporal workflow orchestrator
  • Begin autonomous penetration testing
  • Return a workflow ID for monitoring

Example Output

Starting Shannon containers...
Temporal is ready!

🚀 Pentest workflow started
Workflow ID: your-app.com_shannon-1234567890

Monitor progress:
  ./shannon logs ID=your-app.com_shannon-1234567890
  http://localhost:8233

​
Monitoring Your Pentest

Shannon runs in the background. Use these commands to monitor progress: 
# View worker logs as they happen
./shannon logs ID=your-app.com_shannon-1234567890
Shannon typically completes a full pentest in 1 to 1.5 hours, depending on application complexity. You can safely close your terminal — the workflow continues in Docker.

​
Getting Your Results

When the pentest completes, find your comprehensive security report: 
# Reports are saved to audit-logs by default
cat audit-logs/{hostname}_{sessionId}/deliverables/comprehensive_security_assessment_report.md
The report includes:
  • Verified vulnerabilities only — Shannon’s “No Exploit, No Report” policy eliminates false positives
  • Reproducible exploits — Copy-and-paste Proof-of-Concepts you can run immediately
  • Source code references — Exact file and line numbers for each vulnerability
  • Impact analysis — Real-world damage potential of each finding
DO NOT run Shannon on production environments. Shannon actively executes exploits that can modify or delete data. Always test on staging, sandboxed, or local development environments.

​
Advanced Options

Customize your pentest with additional parameters: 
# Use a memorable workspace name for easy resumption
./shannon start URL=https://example.com REPO=repo-name WORKSPACE=q1-audit

​
What Happens During a Pentest?

Shannon executes a multi-phase workflow:
  1. Pre-Reconnaissance — External scans with nmap, subfinder, whatweb + source code analysis
  2. Reconnaissance — Attack surface mapping and entry point discovery
  3. Vulnerability Analysis — 5 parallel agents hunt for injection, XSS, SSRF, auth flaws, authorization issues
  4. Exploitation — Real browser-based attacks to prove vulnerabilities are exploitable
  5. Reporting — Professional security report with only verified, reproducible findings
Phases 3 and 4 run in parallel for maximum speed. Shannon uses intelligent retry logic to handle API rate limits automatically.

​
Stopping Shannon

When you’re done, stop the containers: 
# Stop containers but keep workflow data for later analysis
./shannon stop

​
Next Steps

Installation Guide

Detailed installation for Windows, macOS, and Linux

Configuration

Set up authentication, 2FA, and testing rules

CLI Reference

Explore all available commands and options

Sample Reports

See real pentest results from Shannon
Need help? Join our Discord community or check troubleshooting for common issues.

Build docs developers (and LLMs) love

Get started for freeTalk to us