Shannon Ai Pentester

# Shannon AI Pentester

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

Shannon is an autonomous, white-box AI pentester for web applications and APIs. It reads your source code to identify attack vectors, then executes real exploits (SQLi, XSS, SSRF, auth bypass, authorization flaws) against a live running application — only reporting vulnerabilities with a working proof-of-concept.

## How It Works

1. **Reconnaissance** — Nmap, Subfinder, WhatWeb, and Schemathesis scan the target
2. **Code Analysis** — Shannon reads your repository to map attack surfaces
3. **Parallel Exploitation** — Concurrent agents attempt live exploits across all vulnerability categories
4. **Report Generation** — Only confirmed, reproducible findings with copy-paste PoCs are included

## Installation & Prerequisites

- Docker (required — Shannon runs entirely in containers)
- An Anthropic API key, Claude Code OAuth token, AWS Bedrock credentials, or Google Vertex AI credentials

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

## Quick Start

```bash
# Option A: Export credentials
export ANTHROPIC_API_KEY="sk-ant-..."
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000

# Option B: .env file
cat > .env << 'EOF'
ANTHROPIC_API_KEY=sk-ant-...
CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000
EOF

# Run a pentest
./shannon start URL=https://your-app.example.com REPO=/path/to/your/repo
```

Shannon builds containers, starts the workflow in the background, and returns a workflow ID.

## Key CLI Commands

```bash
# Start a pentest
./shannon start URL=https://target.example.com REPO=/path/to/repo

# Start with explicit workspace name (for resuming)
./shannon start URL=https://target.example.com REPO=/path/to/repo WORKSPACE=my-audit-2024

# Monitor live progress (tail logs)
./shannon logs <workflow-id>

# Check status of a running pentest
./shannon status <workflow-id>

# Resume an interrupted pentest
./shannon resume WORKSPACE=my-audit-2024

# Stop a running pentest
./shannon stop <workflow-id>

# View the final report
./shannon report <workflow-id>
```

## Configuration

### Environment Variables

```bash
# Required (choose one auth method)
ANTHROPIC_API_KEY=sk-ant-...           # Anthropic direct
CLAUDE_CODE_OAUTH_TOKEN=...            # Claude Code OAuth

# Recommended
CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000   # Increase output window for large reports

# AWS Bedrock (alternative to Anthropic direct)
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_DEFAULT_REGION=us-east-1
SHANNON_AI_PROVIDER=bedrock
SHANNON_BEDROCK_MODEL=anthropic.claude-3-7-sonnet-20250219-v1:0

# Google Vertex AI (alternative to Anthropic direct)
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
SHANNON_AI_PROVIDER=vertex
SHANNON_VERTEX_PROJECT=your-gcp-project
SHANNON_VERTEX_REGION=us-east5
```

### .env File Example

```bash
# .env (place in the shannon project root)
ANTHROPIC_API_KEY=sk-ant-...
CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000

# Optional: target credentials for authenticated testing
TARGET_USERNAME=admin@example.com
TARGET_PASSWORD=supersecret
TARGET_TOTP_SECRET=BASE32TOTPSECRET   # Shannon handles 2FA automatically
```

## Usage Examples

### Basic Web App Pentest

```bash
# Point Shannon at a running local app with its source code
./shannon start \
  URL=http://localhost:3000 \
  REPO=$(pwd)/../my-express-app
```

### Testing Against OWASP Juice Shop (Demo)

```bash
# Pull and run Juice Shop
docker run -d -p 3000:3000 bkimminich/juice-shop

# Run Shannon against i