shannon-ai-pentester — Автоматизированный поиск и эксплуатация уязвимостей

--- name: shannon-ai-pentester description: Autonomous white-box AI pentester for web applications and APIs using source code analysis and live exploit execution triggers: - run a pentest on my web app - scan my application for security vulnerabilities - set up Shannon AI pentester - automate security testing with Shannon - find vulnerabilities in my API - run Shannon against my repo - configure Shannon pentesting tool - generate a security audit report for my app --- # 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