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 it
./shannon start \
  URL=http://localhost:3000 \
  REPO=/path/to/juice-shop
```

### Authenticated Testing with 2FA

```bash
export TARGET_USERNAME="admin@yourapp.com"
export TARGET_PASSWORD="$ADMIN_PASSWORD"
export TARGET_TOTP_SECRET="$TOTP_BASE32_SECRET"

./shannon start URL=https://staging.yourapp.com REPO=/path/to/repo
```

### AWS Bedrock Provider

```bash
export AWS_ACCESS_KEY_ID="$AWS_ACCESS_KEY_ID"
export AWS_SECRET_ACCESS_KEY="$AWS_SECRET_ACCESS_KEY"
export AWS_DEFAULT_REGION=us-east-1
export SHANNON_AI_PROVIDER=bedrock
export SHANNON_BEDROCK_MODEL=anthropic.claude-3-7-sonnet-20250219-v1:0

./shannon start URL=https://target.example.com REPO=/path/to/repo
```

### Google Vertex AI Provider

```bash
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
export SHANNON_AI_PROVIDER=vertex
export SHANNON_VERTEX_PROJECT=my-gcp-project
export SHANNON_VERTEX_REGION=us-east5

./shannon start URL=https://target.example.com REPO=/path/to/repo
```

## Workspace and Resume Pattern

Workspaces allow you to pause and resume long-running pentests:

```bash
# Start with a named workspace
./shannon start \
  URL=https://target.example.com \
  REPO=/path/to/repo \
  WORKSPACE=sprint-42-audit

# Later, resume from where it stopped
./shannon resume WORKSPACE=sprint-42-audit

# Workspaces persist results so you can re-run reports
./shannon report WORKSPACE=sprint-42-audit
```

## Output and Reports

Reports are written to the workspace directory (default: `./workspaces/<workflow-id>/`):

```
workspaces/
└── my-audit-2024/
    ├── report.md          # Final pentest report with PoC exploits
    ├── findings.json      # Machine-readable findings
    └── logs/              # Per-agent execution logs
```

The report includes:
- Vulnerability title and CVSS-style severity
- Affected endpoint and parameter
- Root cause with source code reference
- Step-by-step reproduction instructions
- Copy-paste curl/HTTP PoC

## Vulnerability Coverage

Shannon currently tests for:

| Category | Examples |
|---|---|
| **Injection** | SQL injection, command injection, LDAP injection |
| **XSS** | Reflected, stored, DOM-based |
| **SSRF** | Internal network access, cloud metadata endpoints |
| **Broken Authentication** | Weak tokens, session fixation, auth bypass |
| **Broken Authorization** | IDOR, privilege escalation, missing access controls |

## CI/CD Integration Pattern

```yaml
# .github/workflows/pentest.yml
name: Shannon Pentest
on:
  push:
    branches: [staging]

jobs:
  pentest:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          path: app

      - name: Clone Shannon
        run: git clone https://github.com/KeygraphHQ/shannon.git

      - name: Start Application
        run: |
          cd app
          docker compose up -d
          # Wait for app to be healthy
          sleep 30

      - name: Run Shannon
        working-directory: shannon
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          CLAUDE_CODE_MAX_OUTPUT_TOKENS: 64000
        run: |
          ./shannon start \
            URL=http://localhost:3000 \
            REPO=${{ github.workspace }}/app \
            WORKSPACE=ci-${{ github.sha }}
          # Wait for completion and get report
          ./shannon wait ci-${{ github.sha }}
          ./shannon report ci-${{ github.sha }} > pentest-report.md

      - name: Upload Report
        uses: actions/upload-artifact@v4
        with:
          name: pentest-report
          path: shannon/pentest-report.md
```

## Troubleshooting

### Docker not found or permission denied
```bash
# Ensure Docker daemon is running
docker info

# Add your user to the docker group (Linux)
sudo usermod -aG docker $USER
newgrp docker
```

### Shannon containers fail to build
```bash
# Force a clean rebuild
docker compose -f shannon/docker-compose.yml build --no-cache
```

### Pentest stalls / no progress
```bash
# Check live logs for the blocking agent
./shannon logs <workflow-id>

# Common causes:
# - Target app is not reachable from inside the Shannon container
# - ANTHROPIC_API_KEY is missing or rate-limited
# - CLAUDE_CODE_MAX_OUTPUT_TOKENS not set (model hits default limit)
```

### Target app not reachable from Shannon containers
```bash
# Use host.docker.internal instead of localhost
./shannon start \
  URL=http://host.docker.internal:3000 \
  REPO=/path/to/repo

# Or put both on the same Docker network
docker network create pentest-net
docker run --network pentest-net ...   # your app
# Then set SHANNON_DOCKER_NETWORK=pentest-net in .env
```

### Rate limit errors from Anthropic
```bash
# Use AWS Bedrock or Vertex AI to avoid shared rate limits
export SHANNON_AI_PROVIDER=bedrock
export AWS_DEFAULT_REGION=us-east-1
```

### Resume after crash
```bash
# Always use WORKSPACE= when starting to enable resumability
./shannon start URL=... REPO=... WORKSPACE=named-session

# Resume
./shannon resume WORKSPACE=named-session
```

## Important Disclaimers

- **Only test applications you own or have explicit written permission to test.**
- Shannon Lite is AGPL-3.0 licensed — any modifications must be open-sourced under the same license.
- Shannon is a **white-box tool**: it expects access to your application's source code.
- It is not a black-box scanner. Running it against third-party targets without authorization is illegal.

## Key Links

- **GitHub**: https://github.com/KeygraphHQ/shannon
- **Keygraph Platform (Pro)**: https://keygraph.io
- **Sample Report (Juice Shop)**: `sample-reports/shannon-report-juice-shop.md` in the repo
- **Shannon Pro Architecture**: `SHANNON-PRO.md` in the repo
- **Announcements**: https://github.com/KeygraphHQ/shannon/discussions/categories/announcements
- **Discord**: https://discord.gg/9ZqQPuhJB7