Shannon AI Pentester

Skill by 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

Reconnaissance — Nmap, Subfinder, WhatWeb, and Schemathesis scan the target
Code Analysis — Shannon reads your repository to map attack surfaces
Parallel Exploitation — Concurrent agents attempt live exploits across all vulnerability categories
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

shannon-ai-pentester

NPX Install

Tags

SKILL.md Content

Shannon AI Pentester

How It Works

Installation & Prerequisites

Quick Start

Key CLI Commands

Configuration

Environment Variables

.env File Example

Usage Examples

Basic Web App Pentest

Testing Against OWASP Juice Shop (Demo)

Authenticated Testing with 2FA

AWS Bedrock Provider

Google Vertex AI Provider

Workspace and Resume Pattern

Output and Reports

Vulnerability Coverage

CI/CD Integration Pattern

Troubleshooting

Docker not found or permission denied

Shannon containers fail to build

Pentest stalls / no progress

Target app not reachable from Shannon containers

Rate limit errors from Anthropic

Resume after crash

Important Disclaimers

Key Links