Skip to main content

​
Prerequisites

Before you begin, ensure you have:

Docker

Container runtime for running Shannon’s components

AI Provider

Anthropic API key, Claude Code OAuth token, AWS Bedrock, or Google Vertex AI
Don’t have Docker? Install Docker for your platform.

​
Run your first pentest

Follow these steps to run Shannon against a target application:
1

Clone Shannon

Clone the Shannon repository and navigate to the directory:
git clone https://github.com/KeygraphHQ/shannon.git
cd shannon
2

Configure credentials

Choose one of the following methods to configure your AI provider credentials:
export ANTHROPIC_API_KEY="your-api-key"
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000
Get your Anthropic API key from the Anthropic Console.
3

Prepare your repository

Shannon expects target repositories in the ./repos/ directory. Clone or copy your target application:
git clone https://github.com/your-org/your-repo.git ./repos/your-repo
The REPO parameter refers to a folder name inside ./repos/, not an absolute path.
4

Start the pentest

Launch Shannon with a single command:
./shannon start URL=https://your-app.com REPO=your-repo
Shannon will:
  • Build the necessary Docker containers
  • Start the workflow engine
  • Return a workflow ID
  • Run the pentest in the background
The pentest runs asynchronously. You can monitor progress using the commands in the next step.
5

Monitor progress

Track your pentest in real-time:
./shannon logs ID=shannon-1234567890
The Temporal Web UI at http://localhost:8233 provides detailed workflow visualization and progress tracking.
6

Review results

Once complete, find your security assessment report in:
audit-logs/{hostname}_{sessionId}/deliverables/comprehensive_security_assessment_report.md
The report includes:
  • Executive summary of all findings
  • Detailed vulnerability descriptions
  • Step-by-step exploitation proof-of-concepts
  • Severity ratings and impact analysis

​
Testing local applications

Docker containers cannot reach localhost on your host machine. Use host.docker.internal instead: 
./shannon start URL=http://host.docker.internal:3000 REPO=repo-name
This works on macOS and Windows with Docker Desktop. On Linux, you may need to configure the Docker network differently.

​
Example: Testing with configuration

For applications requiring authentication, create a configuration file:
1

Create config file

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

Edit configuration

configs/my-app-config.yaml
authentication:
  login_type: form
  login_url: "https://your-app.com/login"
  credentials:
    username: "[email protected]"
    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"
3

Run with config

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

​
Workspace management

Shannon supports workspaces for resuming interrupted runs: 
# Start with custom name
./shannon start URL=https://example.com REPO=repo-name WORKSPACE=q1-audit

# Resume same workspace (skips completed agents)
./shannon start URL=https://example.com REPO=repo-name WORKSPACE=q1-audit
Shannon detects which agents completed successfully and picks up where it left off. Each agent’s progress is checkpointed via git commits.

​
Common commands

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

​
Expected runtime and costs

Runtime

A full test run typically takes 1 to 1.5 hours to complete

Cost

Approximately $50 USD using Anthropic’s Claude 4.5 Sonnet model
Costs vary based on model pricing and application complexity. The system uses three model tiers: Haiku for summarization, Sonnet for analysis, and Opus for deep reasoning.

​
Important disclaimers

DO NOT run Shannon on production environments. This is not a passive scanner. The exploitation agents actively execute attacks that can have mutative effects on the target application and its data.
Legal requirement: You must have explicit, written authorization from the owner of the target system before running Shannon. Unauthorized scanning and exploitation is illegal.

​
Next steps

Installation Guide

Platform-specific installation instructions and troubleshooting

Configuration

Configure authentication, 2FA, rate limits, and testing rules

Architecture

Understanding Shannon’s multi-agent architecture

Sample Reports

See Shannon’s capabilities with real penetration test results

Build docs developers (and LLMs) love

Get started for freeTalk to us