shannon-ai-pentester

$27

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

cd shannon

Quick Start

# 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

# 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

# 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

# .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

# 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)

# 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

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

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

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:

# 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

# .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

# 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

# Force a clean rebuild

docker compose -f shannon/docker-compose.yml build --no-cache

Pentest stalls / no progress

# 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

# 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

# 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

# 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