Shannon Lite

Shannon Lite is an autonomous white-box AI pentester with 41k+ GitHub stars that uses the Claude API to analyze application source code, trace data flows from sources to sinks, and automatically generate proof-of-concept exploits for discovered vulnerabilities.

Installation

pip (Recommended)

pip install shannon-lite

# Verify installation
shannon-lite --version

From Source

git clone https://github.com/shannon-sec/shannon-lite
cd shannon-lite
pip install -r requirements.txt
pip install -e .

Docker

# Pull official image
docker pull shannonsec/shannon-lite:latest

# Run with source code mounted
docker run --rm \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  -v /path/to/target:/target \
  shannonsec/shannon-lite:latest \
  scan /target

pipx (Isolated Install)

pipx install shannon-lite

Configuration

API Key Setup

# Set Claude API key (required)
export ANTHROPIC_API_KEY="sk-ant-..."

# Persist in shell profile
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.bashrc

# Or use .env file in project root
echo "ANTHROPIC_API_KEY=sk-ant-..." > .env

Configuration File (`shannon.yaml`)

# ~/.config/shannon-lite/shannon.yaml
api:
  model: claude-opus-4-5          # Model for deep analysis
  fast_model: claude-haiku-4-5    # Model for quick triage
  max_tokens: 8192
  rate_limit: 50                  # Requests per minute

scan:
  max_file_size: 1048576          # 1MB per file
  excluded_dirs:
    - node_modules
    - .git
    - vendor
    - dist
  excluded_extensions:
    - .min.js
    - .map
    - .lock
  depth: 10                       # Max directory traversal depth

output:
  format: html                    # html | json | markdown | sarif
  severity_threshold: medium      # low | medium | high | critical
  include_poc: true
  poc_validate: true              # Auto-validate generated PoCs

Scan Profiles

# List available scan profiles
shannon-lite profiles list

# Create custom profile
shannon-lite profiles create \
  --name "api-focused" \
  --focus "authentication,injection,ssrf" \
  --depth 8

Core Commands

Command	Description
`shannon-lite scan <path>`	Scan a local codebase
`shannon-lite scan --url <repo>`	Clone and scan a remote repository
`shannon-lite scan --api <path>`	Focus scan on API endpoints only
`shannon-lite report <scan-id>`	Generate report from previous scan
`shannon-lite poc <vuln-id>`	Generate PoC for a specific vulnerability
`shannon-lite triage <path>`	Quick triage without deep analysis
`shannon-lite flows <path>`	Map source-to-sink data flows
`shannon-lite endpoints <path>`	Discover API endpoints
`shannon-lite auth <path>`	Analyze authentication mechanisms
`shannon-lite diff <before> <after>`	Security diff between two versions
`shannon-lite watch <path>`	Continuous monitoring mode
`shannon-lite validate <poc-file>`	Validate a generated PoC

Advanced Usage

Source-to-Sink Analysis

# Full data flow tracing
shannon-lite flows \
  --source "request.params,request.body,request.headers" \
  --sink "exec,eval,query,render" \
  --path /path/to/app \
  --output flows-report.html

# Trace specific sink type
shannon-lite flows \
  --sink sql \
  --path /path/to/app \
  --format json | jq '.flows[] | select(.severity == "critical")'

API Endpoint Discovery

# Discover all API endpoints with auth requirements
shannon-lite endpoints \
  --path /path/to/app \
  --format json \
  --include-auth-info \
  --include-params

# Export as OpenAPI spec for further analysis
shannon-lite endpoints \
  --path /path/to/app \
  --format openapi \
  --output api-spec.yaml

Authentication Bypass Detection

# Analyze auth implementation
shannon-lite auth \
  --path /path/to/app \
  --check jwt,session,oauth,apikey \
  --verbose

# Test specific auth endpoint patterns
shannon-lite auth \
  --path /path/to/app \
  --endpoint-pattern "/api/v*/admin/*" \
  --report auth-analysis.html

Automated PoC Generation

Option	Description
`--poc-format curl`	Generate curl-based PoC
`--poc-format python`	Generate Python requests PoC
`--poc-format burp`	Generate Burp Suite XML request
`--poc-validate`	Auto-test PoC against live target
`--poc-target <url>`	Target URL for PoC validation
`--poc-safe-mode`	Non-destructive PoC testing only

# Generate and validate PoC for all high/critical findings
shannon-lite poc \
  --scan-id abc123 \
  --severity "high,critical" \
  --format python \
  --validate \
  --target https://staging.example.com \
  --safe-mode \
  --output pocs/

Business Logic Analysis

# Detect business logic flaws
shannon-lite scan \
  --path /path/to/app \
  --focus business-logic \
  --checks "race-condition,idor,price-manipulation,workflow-bypass"

# IDOR-specific deep scan
shannon-lite scan \
  --path /path/to/app \
  --focus idor \
  --trace-object-references \
  --output idor-report.html

Common Workflows

Full White-Box Pentest

# Step 1: Initial triage to scope the scan
shannon-lite triage /path/to/app --output triage-summary.json

# Step 2: Full scan with all checks enabled
shannon-lite scan \
  --path /path/to/app \
  --profile full \
  --output-dir ./shannon-results/ \
  --format html

# Step 3: Map all data flows
shannon-lite flows \
  --path /path/to/app \
  --output ./shannon-results/flows.html

# Step 4: Generate PoCs for critical findings
SCAN_ID=$(cat ./shannon-results/scan-id.txt)
shannon-lite poc \
  --scan-id $SCAN_ID \
  --severity critical \
  --format python \
  --output ./shannon-results/pocs/

# Step 5: Compile final report
shannon-lite report \
  --scan-id $SCAN_ID \
  --format html \
  --include-poc \
  --output ./shannon-results/final-report.html

CI/CD Pipeline Integration

# Run in CI — exit code 1 if high/critical found
shannon-lite scan \
  --path . \
  --severity-threshold high \
  --format sarif \
  --output results.sarif \
  --ci-mode

# GitHub Actions example (in workflow YAML)
# - name: Shannon Lite Security Scan
#   run: |
#     pip install shannon-lite
#     shannon-lite scan --path . --ci-mode --severity-threshold high
#   env:
#     ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

Remote Repository Scan

# Scan a GitHub repo directly
shannon-lite scan \
  --url https://github.com/target-org/target-app \
  --branch main \
  --depth 5 \
  --output remote-scan.html

# Scan with GitHub token for private repos
GITHUB_TOKEN=ghp_... shannon-lite scan \
  --url https://github.com/target-org/private-app \
  --format json | jq '.vulnerabilities[] | select(.severity == "critical")'

Diff Scan for Code Reviews

# Compare two Git commits for new vulnerabilities
shannon-lite diff \
  --before $(git rev-parse HEAD~1) \
  --after $(git rev-parse HEAD) \
  --path . \
  --only-new \
  --output pr-security-review.html

Tips and Best Practices

Scope your scans — Use --focus to target specific vulnerability classes per engagement scope rather than running exhaustive full scans on every iteration.

Use fast model for triage — Set fast_model: claude-haiku-4-5 in your config for initial triage passes, then run the full model only on files flagged as interesting.

Exclude build artifacts — Always add node_modules, dist, vendor, and lock files to excluded_dirs; they inflate scan time without security value.

Validate PoCs on staging — Use --poc-validate --poc-safe-mode against a staging environment before including PoC outputs in client deliverables.

SARIF output for IDE integration — Use --format sarif to get findings directly in VS Code, JetBrains, and GitHub code scanning dashboards.

Combine with DAST — Shannon Lite excels at white-box source analysis; pair it with a DAST tool (Nuclei, ZAP) against a running instance to maximize coverage.

Rate limit awareness — The rate_limit config option controls API calls per minute; lower it if you hit Claude API throttling on large codebases.

Watch mode for continuous testing — Use shannon-lite watch during active development to get near-real-time vulnerability feedback on changed files.