A practical setup guide for Shannon, the open-source white-hat AI pentester from Keygraph. Point it at your staging URL and your repo. It reads your code, runs real exploits, and writes the report. AGPL licensed, about $50 per run on Claude Sonnet, 90 minutes per full scan.
The problem nobody talks about
Most builders shipping with Claude Code never run security testing. The reasons are obvious. Annual pentests cost $5K to $50K, take 2 to 6 weeks, and don't fit a daily-ship cadence. By the time you book one, the codebase has changed three times.
So you ship without testing. Then you find the SQL injection in production from a customer report. Or the broken auth from a security researcher's email. Or the SSRF from a postmortem after an incident.
Shannon collapses the cycle. $50 per scan, 90 minutes per run, code-aware, runs on every push to staging if you want it. The annual pentest becomes a daily habit.
Why this changes everything
Real exploits, not theoretical scans.The "no exploit, no report" policy means every finding has a working proof of concept. Zero false positives. If it's in the report, it's exploitable.
Code-aware. Shannon reads your source code as part of the test. It uses the code to plan smarter attacks instead of just probing the surface like a black-box scanner.
Autonomous. Handles 2FA logins, navigation, exploitation, and reporting. No manual intervention. Once you start the scan, it runs to completion.
Built on the Claude Agent SDK. Powered by Anthropic Claude. Not a wrapper around an old vulnerability scanner. A true AI agent making decisions about where to attack and how.
Step 1: install prerequisites
Three things on your machine first:
- Docker (Shannon runs scanners in containers)
- Node.js 18+
- pnpm (only if you're building from source, npx-based install skips this)
Plus one of:
- Anthropic API key, or
- AWS Bedrock credentials, or
- Google Vertex AI credentials
You also need a staging or sandbox URL to test against. Never production. Never apps you don't own.
Step 2: run your first scan (npx, recommended)
The fastest path is via npx. Two commands.
Setup:
npx @keygraph/shannon setupThis pulls the Docker images, sets up the scanning environment, and validates your API credentials.
Run a scan:
npx @keygraph/shannon start -u https://your-app.com -r /path/to/repoReplace the URL with your staging app. Replace the path with your local clone of the repo. Shannon takes it from here.
Step 3: or build from source
If you'd rather clone and build locally:
git clone https://github.com/KeygraphHQ/shannon.git
cd shannon
pnpm install
pnpm build
./shannon start -u https://your-app.com -r /path/to/repoSame outcome. More control if you want to modify the source.
Step 4: how Shannon actually works
Shannon runs a 5-phase pipeline. Each phase feeds the next.
Phase 1: Pre-Reconnaissance.Infrastructure fingerprinting using nmap, subfinder, and whatweb. Maps subdomains, open ports, and tech stack so the next phases know what they're attacking.
Phase 2: Reconnaissance. Browser-driven attack surface mapping. Logs in (handles 2FA and TOTP), explores the app, catalogs every endpoint, form, and parameter.
Phase 3: Vulnerability Analysis.Parallel agents read your source code and the live app at the same time. They look for OWASP-class flaws: SQL injection, XSS, SSRF, broken authentication and authorization. Code-aware, so attacks are guided by what's actually in your codebase, not generic payloads.
Phase 4: Exploitation.This is where Shannon differs from a scanner. It tries to exploit each suspected vulnerability and only logs the ones it can actually exploit. No "this might be vulnerable" hand-waving.
Phase 5: Reporting. Final report with reproducible exploits. Each finding includes the exact request, response, and steps to reproduce.
Step 5: what Shannon tests
SQL Injection. Classic and blind variants, across all input vectors Shannon discovered in recon.
Cross-Site Scripting (XSS). Stored, reflected, and DOM-based. Tests both client-side and server-side rendering paths.
Server-Side Request Forgery (SSRF). Probes for internal network access, cloud metadata leaks, and protocol confusion.
Broken Authentication and Authorization. Tests for broken session handling, privilege escalation, IDOR, and missing access controls.
Step 6: reading the report
Each finding in the Shannon report includes:
- The vulnerability category and severity
- The exact endpoint and parameter
- The HTTP request that triggered it
- The HTTP response showing the impact
- A reproduction script you can run by hand
- A suggested fix
Because of the "no exploit, no report" policy, every finding is real. You can verify each one yourself before pushing the fix.