Installation

This guide covers everything you need to install and configure Shannon for autonomous penetration testing.

System Requirements

Docker

Container runtime for Shannon’s isolated environment

AI Provider Credentials

Anthropic API key, AWS Bedrock, or Google Vertex AI

Disk Space

Minimum 5GB for containers and audit logs

Network Access

Internet connection for AI API calls and security tools

Prerequisites

Docker Installation

Shannon requires Docker to run its containers. Install Docker for your platform:

macOS
Linux
Windows

Download and install Docker Desktop for Mac.

# Verify installation
docker --version
docker compose version

Shannon works out of the box on macOS with Docker Desktop installed. No additional configuration needed.

Install Docker Engine using your distribution’s package manager:

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install docker.io docker-compose-plugin

# Fedora/RHEL
sudo dnf install docker docker-compose-plugin

# Verify installation
docker --version
docker compose version

You may need to run Shannon commands with sudo depending on your Docker setup. To avoid this, add your user to the docker group:

sudo usermod -aG docker $USER
newgrp docker

Option 1: WSL2 (Recommended)

Install WSL2:

# Run in PowerShell as Administrator
wsl --install
wsl --set-default-version 2

# Install Ubuntu 24.04 (recommended)
wsl --list --online
wsl --install Ubuntu-24.04

Install Docker Desktop for Windows with WSL2 backend:
- Download Docker Desktop
- Enable Use the WSL 2 based engine under Settings > General
Open WSL terminal:

wsl -d Ubuntu-24.04

To access the Temporal Web UI from Windows, find your WSL IP address with ip addr inside WSL, then navigate to http://<wsl-ip>:8233 in your browser.

Option 2: Git Bash (Native Windows)

Install Git for Windows
Install Docker Desktop
Run Shannon from Git Bash terminal

Windows Defender may flag exploit code in reports as false positives. Add an exclusion for the Shannon directory in Windows Security settings.

AI Provider Credentials

Shannon requires access to Claude models. Choose one of the following options:

Anthropic (Default)
AWS Bedrock
Google Vertex AI
Router Mode (Experimental)

Get your API key from the Anthropic Console:

Create an Anthropic account
Navigate to API Keys section
Generate a new API key
Copy the key (starts with sk-ant-api03-...)

Anthropic offers pay-as-you-go pricing. A typical Shannon pentest costs approximately $50 USD using Claude 4.5 Sonnet.

Route through Amazon Bedrock for enterprise billing and compliance:

Enable Claude models in AWS Bedrock console
Create a Bedrock API key (AWS Guide)
Configure environment variables (see Configuration section below)

Required: AWS_REGION, AWS_BEARER_TOKEN_BEDROCK, and Bedrock-specific model IDs.

Route through Google Cloud Vertex AI:

Create a GCP service account with roles/aiplatform.user
Download JSON key file from GCP Console
Place key file in ./credentials/ directory
Configure environment variables (see Configuration section below)

Required: CLOUD_ML_REGION, ANTHROPIC_VERTEX_PROJECT_ID, GOOGLE_APPLICATION_CREDENTIALS.

Use alternative providers like OpenAI or Google Gemini via OpenRouter:

# OpenAI
export OPENAI_API_KEY=sk-...
export ROUTER_DEFAULT=openai,gpt-5.2

# OpenRouter (for Gemini)
export OPENROUTER_API_KEY=sk-or-...
export ROUTER_DEFAULT=openrouter,google/gemini-3-flash-preview

Router mode is experimental and unsupported. Shannon is optimized for Anthropic Claude models. Alternative providers may produce inconsistent results.

Installation Steps

Clone Shannon

Clone the Shannon repository from GitHub:

git clone https://github.com/KeygraphHQ/shannon.git
cd shannon

Configure Credentials

Create a .env file with your API credentials:

Anthropic API
AWS Bedrock
Google Vertex AI

cp .env.example .env

Edit .env and add your credentials:

.env

# Anthropic API Key (recommended)
ANTHROPIC_API_KEY=your-api-key-here

# Recommended for larger tool outputs
CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000

.env

# Enable Bedrock mode
CLAUDE_CODE_USE_BEDROCK=1
AWS_REGION=us-east-1
AWS_BEARER_TOKEN_BEDROCK=your-bearer-token

# Bedrock-specific model IDs for your region
ANTHROPIC_SMALL_MODEL=us.anthropic.claude-haiku-4-5-20251001-v1:0
ANTHROPIC_MEDIUM_MODEL=us.anthropic.claude-sonnet-4-6
ANTHROPIC_LARGE_MODEL=us.anthropic.claude-opus-4-6

CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000

.env

# Enable Vertex AI mode
CLAUDE_CODE_USE_VERTEX=1
CLOUD_ML_REGION=us-east5
ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id
GOOGLE_APPLICATION_CREDENTIALS=./credentials/gcp-sa-key.json

# Vertex AI model IDs
ANTHROPIC_SMALL_MODEL=claude-haiku-4-5@20251001
ANTHROPIC_MEDIUM_MODEL=claude-sonnet-4-6
ANTHROPIC_LARGE_MODEL=claude-opus-4-6

CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000

Place your GCP service account key:

mkdir -p ./credentials
cp /path/to/your-sa-key.json ./credentials/gcp-sa-key.json

Shannon uses three model tiers:

Small (Haiku) — Summarization and lightweight tasks
Medium (Sonnet) — Security analysis and vulnerability detection
Large (Opus) — Deep reasoning and complex exploit chains

Prepare Target Repository

Shannon expects repositories under the ./repos/ directory:

# Clone your target application
git clone https://github.com/your-org/your-app.git ./repos/your-app

Single Repository
Monorepo
Multi-Repository
Symlink

# Standard single-repo application
git clone https://github.com/your-org/app.git ./repos/app

# Application with multiple services in one repo
git clone https://github.com/your-org/monorepo.git ./repos/monorepo

# Separate frontend, backend, and API repos
mkdir ./repos/your-app
cd ./repos/your-app
git clone https://github.com/your-org/frontend.git
git clone https://github.com/your-org/backend.git
git clone https://github.com/your-org/api.git

# Link to an existing local repository
ln -s /path/to/existing/repo ./repos/my-app

White-box testing only. Shannon requires access to your application’s source code. It analyzes code to intelligently guide attack strategies.

Verify Installation

Test that Shannon is properly configured:

# Start Shannon and check for errors
./shannon start URL=https://example.com REPO=your-app

You should see:

Starting Shannon containers...
Waiting for Temporal to be ready...
Temporal is ready!

🚀 Pentest workflow started
Workflow ID: example.com_shannon-1234567890

The first run downloads Docker images (approximately 2GB). Subsequent runs start almost instantly.

Stop the test workflow:

./shannon stop

Configuration Files

Environment Variables Reference

Shannon supports multiple configuration options via .env:

.env

# === Core Configuration ===
ANTHROPIC_API_KEY=your-api-key-here
CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000

# === Model Tier Overrides ===
# ANTHROPIC_SMALL_MODEL=claude-haiku-4-5-20251001
# ANTHROPIC_MEDIUM_MODEL=claude-sonnet-4-6
# ANTHROPIC_LARGE_MODEL=claude-opus-4-6

# === AWS Bedrock ===
# CLAUDE_CODE_USE_BEDROCK=1
# AWS_REGION=us-east-1
# AWS_BEARER_TOKEN_BEDROCK=your-bearer-token

# === Google Vertex AI ===
# CLAUDE_CODE_USE_VERTEX=1
# CLOUD_ML_REGION=us-east5
# ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id
# GOOGLE_APPLICATION_CREDENTIALS=./credentials/gcp-sa-key.json

# === Router Mode (Experimental) ===
# OPENAI_API_KEY=sk-...
# ROUTER_DEFAULT=openai,gpt-5.2

Testing Configuration (Optional)

Create a YAML configuration file for advanced testing scenarios:

cp configs/example-config.yaml configs/my-app.yaml

Example configuration with authentication:

configs/my-app.yaml

authentication:
  login_type: form
  login_url: "https://your-app.com/login"
  credentials:
    username: "[email protected]"
    password: "yourpassword"
    totp_secret: "LB2E2RX7XFHSTGCK"  # Optional 2FA

  login_flow:
    - "Type $username into the email field"
    - "Type $password into the password field"
    - "Click the 'Sign In' button"
    - "Enter $totp in the verification code field"
    - "Click 'Verify'"

  success_condition:
    type: url_contains
    value: "/dashboard"

rules:
  avoid:
    - description: "Skip logout functionality"
      type: path
      url_path: "/logout"

  focus:
    - description: "Prioritize API endpoints"
      type: path
      url_path: "/api"

Use the config when starting Shannon:

./shannon start URL=https://your-app.com REPO=your-app CONFIG=./configs/my-app.yaml

Shannon supports TOTP 2FA authentication automatically. Just add your totp_secret to the config — Shannon will generate codes during testing.

Platform-Specific Notes

macOS

Works out of the box with Docker Desktop
Access Temporal UI at http://localhost:8233
No additional configuration needed

Linux

May require sudo for Docker commands (or add user to docker group)
Ensure Docker daemon is running: sudo systemctl start docker
If output files have permission issues, verify Docker user has write access

Windows (WSL2)

Must use WSL2 — native Windows is experimental
Clone Shannon inside WSL filesystem (not /mnt/c/...)
Access Temporal UI at http://<wsl-ip>:8233 (find IP with ip addr)
Windows Defender may flag exploit reports — add exclusion

Testing Local Applications

Docker containers can’t reach localhost on your host. Use host.docker.internal:

# WRONG: Shannon can't reach localhost:3000 from inside Docker
./shannon start URL=http://localhost:3000 REPO=app

# CORRECT: Use special DNS name for host machine
./shannon start URL=http://host.docker.internal:3000 REPO=app

Troubleshooting Installation

Repository not found error

Problem: ERROR: Repository not found at ./repos/my-repoSolution: REPO must be a folder name inside ./repos/, not an absolute path:

# Clone your repo into ./repos/
git clone https://github.com/org/repo.git ./repos/my-repo

# Then use just the folder name
./shannon start URL=https://example.com REPO=my-repo

Temporal not ready

Problem: Timeout waiting for TemporalSolution:

# Check container status
docker compose ps

# View Temporal logs
docker compose logs temporal

# Reset and retry
./shannon stop CLEAN=true
./shannon start URL=https://example.com REPO=repo-name

Worker not processing

Problem: Workflow starts but no progress is madeSolution:

# Check worker logs
docker compose logs worker

# Restart worker container
docker compose restart worker

Permission denied errors

Problem: permission denied when creating output filesSolution:

# Ensure audit-logs is writable
chmod 777 ./audit-logs

# Linux: Add user to docker group
sudo usermod -aG docker $USER
newgrp docker

Missing API key

Problem: ERROR: Set ANTHROPIC_API_KEY in .envSolution: Create .env file with your credentials:

echo "ANTHROPIC_API_KEY=your-key-here" > .env

Next Steps

Quick Start Guide

Run your first pentest in 5 minutes

Configuration Guide

Set up authentication and testing rules

CLI Reference

Learn all available commands and options

Troubleshooting

Solve common issues and errors

Security Reminder: Shannon actively executes exploits. Always test on sandboxed, staging, or local development environments — never on production systems.

Get Started

Core Concepts

CLI Reference

Configuration

Advanced Usage

Guides

System Requirements

Docker

AI Provider Credentials

Disk Space

Network Access

Prerequisites

Docker Installation

AI Provider Credentials

Installation Steps

Configuration Files

Environment Variables Reference

Testing Configuration (Optional)

Platform-Specific Notes

macOS

Linux

Windows (WSL2)

Testing Local Applications

Troubleshooting Installation

Next Steps

Quick Start Guide

Configuration Guide

CLI Reference

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Core Concepts

CLI Reference

Configuration

Advanced Usage

Guides

​System Requirements

Docker

AI Provider Credentials

Disk Space

Network Access

​Prerequisites

​Docker Installation

​AI Provider Credentials

​Installation Steps

​Configuration Files

​Environment Variables Reference

​Testing Configuration (Optional)

​Platform-Specific Notes

​macOS

​Linux

​Windows (WSL2)

​Testing Local Applications

​Troubleshooting Installation

​Next Steps

Quick Start Guide

Configuration Guide

CLI Reference

Troubleshooting

Build docs developers (and LLMs) love

System Requirements

Prerequisites

Docker Installation

AI Provider Credentials

Installation Steps

Configuration Files

Environment Variables Reference

Testing Configuration (Optional)

Platform-Specific Notes

macOS

Linux

Windows (WSL2)

Testing Local Applications

Troubleshooting Installation

Next Steps