Shannon: Autonomous Pentesting for Your Own Apps

What This Does

Shannon is an autonomous white-box AI pentester by Keygraph. It reads your repository, maps attack paths against the running application, executes real exploits, and writes a Markdown report containing only findings it could prove with a working proof of concept.

This playbook is not a self-contained prompt skill. Most playbooks on this site are pure CLAUDE.md rule sets that work the moment you download them. This one is an operating guide for an external CLI. Shannon is a separate application you install and run yourself, and none of this does anything until you do. The template teaches Claude Code four things: how to get Shannon installed and credentialed, how to write a scoping config for your specific app, which CLI commands and flags to use, and how to read and triage the report that comes out.

The triage half is where most of the value sits. A Shannon run against a real application produces dozens of findings across five vulnerability classes, split between proven exploits and unproven observations, often with the same root cause appearing under three different IDs. The template gives Claude a procedure for collapsing that into a ranked fix list.

---

Before You Run This

Shannon executes real attacks. Two rules, stated plainly:

1. Run it only against applications and repositories you own, or that you hold explicit written authorization to test. Unauthorized scanning is illegal.
2. Do not run it against production. Exploitation agents can create users, modify or delete data, compromise test accounts, and generate unexpected outbound traffic. Use a sandbox, staging, or local environment with disposable data.

The template opens with an authorization gate that makes Claude confirm both before running any command. Keygraph also warns against pointing Shannon at untrusted or adversarial codebases, since a tool that reads source can be influenced by malicious content inside it.

This playbook covers operating the tool and acting on its report. It contains no exploit payloads or attack techniques.

---

Prerequisites

• Docker — Shannon runs its worker in a container pulled from Docker Hub.
• Node.js 18+ — for the npx workflow.
• AI provider credentials — Anthropic recommended. AWS Bedrock and Anthropic-compatible proxy endpoints are supported. Only Claude models are officially supported.

Platform notes from the docs:

• Windows: WSL2 only. Native Windows and Git Bash are not supported. Install Docker Desktop with the WSL2 backend and run Shannon inside WSL.
• macOS: Docker Desktop.
• Linux: native Docker, possibly with sudo.

---

Quick Start

Step 1: Install Shannon

npx @keygraph/shannon setup

The wizard collects your provider credentials and writes ~/.shannon/config.toml. Environment variables override it, so export ANTHROPIC_API_KEY=... wins for a single session.

Step 2: Create a Project Folder

mkdir -p ~/Projects/ShannonRuns

Step 3: Download the Template

Click Download above, then:

mv ~/Downloads/CLAUDE.md ~/Projects/ShannonRuns/

Step 4: Start Working

cd ~/Projects/ShannonRuns
claude

Ask Claude to help you scope a config for your app, then kick off the run:

npx @keygraph/shannon start -u https://staging.your-app.com -r /path/to/your-repo -c ./my-app-config.yaml -w q1-audit

Testing a local app? The container cannot reach your host's localhost. Use http://host.docker.internal:3000.

---

The CLI

Flag	Purpose
-u	Target URL of the running application
-r	Repository path, mounted read-only in the worker
-c	YAML configuration file
-o	Copy deliverables to a custom output directory
-w	Workspace name, and how you resume a run

npx @keygraph/shannon status              # is Shannon running
npx @keygraph/shannon logs <workspace>    # follow a run
npx @keygraph/shannon workspaces          # list all workspaces
npx @keygraph/shannon stop
npx @keygraph/shannon stop --clean        # confirms first; -y skips

The Temporal Web UI at http://localhost:8233 gives per-agent detail during a run. If a run dies, pass the same -w name to resume; completed agents are skipped. The URL must match the one the workspace was created with.

---

Scoping the Run

Shannon runs without a config, but the config is what makes the run useful. The template walks Claude through building one:

• description — stack, environment, and whether repo credentials are local-only. This feeds attack planning.
• vuln_classes — restrict to any of injection, xss, auth, authz, ssrf. Narrowing cuts time and cost.
• exploit: "false" — skip the exploitation phase entirely for a non-mutating first pass.
• rules_of_engagement — free text. Rate caps, no brute force, placeholders instead of real data in deliverables.
• authentication and login_flow — ordered steps quoting exact field labels and button text, with $username, $password, $totp, $email_address, $email_password, and $email_totp substituted at runtime. Magic-link and email-OTP flows are supported via optional mailbox credentials.
• rules.avoid / rules.focus — carve-outs and emphasis by url_path, subdomain, domain, method, header, parameter, or code_path. Avoid logout and destructive admin routes; focus on your API surface.
• report — min_severity, min_confidence, and free-form guidance for what to drop.
• pipeline — max_concurrent_pipelines takes 1-5 and defaults to 5. On a subscription plan, set retry_preset: subscription and drop concurrency to 2.

---

How to Read the Output

Workspaces land in ~/.shannon/workspaces/ (npx mode) or ./workspaces/ (source build).

workspaces/{hostname}_{sessionId}/
|-- Security-Assessment-Report.md   # the deliverable
`-- .shannon/                       # internals: agents, prompts, deliverables, logs

The report opens with an executive summary and a summary by vulnerability type, then splits into per-class evidence sections. Findings carry class-prefixed IDs (INJ-VULN-nn, XSS-VULN-nn, AUTH-VULN-nn, AUTHZ-VULN-nn, SSRF-VULN-nn) and a fixed shape: vulnerable location, overview, impact, severity, prerequisites, exploitation steps, proof of impact, notes.

The distinction that matters most is the split inside each class section:

Section	What it means
Successfully Exploited Vulnerabilities	An agent ran a proof of concept and the report shows the result. Real. Schedule the fix.
Confirmed Vulnerabilities Without Successful Exploits	The weakness was observed but no working exploit was produced. Worth fixing, but not a proven breach.

The template tells Claude never to flatten those two lists into one when summarizing. Severity labels in Keygraph's published sample reports run Critical, High, and Medium.

---

Triage

The template's triage procedure, in short:

1. Read the whole report before ranking anything.
2. Group by root cause, not by finding ID. Six IDOR findings across profiles, baskets, and feedback are usually one missing ownership check.
3. Verify each proven finding against the source file and line the report names. Flag anything you cannot corroborate as unverified.
4. Rank by exploited-plus-impact, not the severity label alone. A proven Medium reachable without auth often outranks a Critical needing an admin session.
5. Write fix tasks, not a summary: file, function, approach, and the finding IDs each task closes.
6. Mark what Shannon proved versus what it inferred.
7. Keep exploitation steps in the report file, out of tickets and commit messages.

Verification after a fix means re-running the whole scan. Shannon Open Source has no targeted re-test.

---

Tips

• Start with exploit: "false" on an environment you are not ready to have mutated. You get the attack surface analysis without the state changes.
• Narrow vuln_classes to the area you just shipped. A single-class run finishes far faster than all five.
• Name every workspace with -w. Auto-named workspaces look like example-com_shannon-1771007534808, which is unhelpful three runs later.
• Prefer a Claude Code subscription over API credits? The shannon-v1 branch is the last release built on the Claude Agent SDK and accepts an OAuth token from claude setup-token. Run npx @keygraph/shannon@1.9.0 setup and pick OAuth Token.
• Windows Defender may flag exploit code inside reports as a false positive. Exclude the Shannon directory.
• For maximum isolation, Keygraph suggests running Shannon inside a disposable virtual machine.

---

Limitations

Straight from Keygraph's own safety and coverage docs:

• Five classes only. Broken Authentication, Broken Authorization, Injection, XSS, and SSRF. Vulnerable dependencies, insecure configurations, secrets, IaC, and containers are out of scope for the open-source CLI.
• An empty report is not a clean bill of health. Proof-by-exploitation means Shannon stays silent about anything it cannot actively exploit.
• Human review is required. LLM-generated reports can contain weakly supported or incorrect details.
• Claude models only. Smaller, alternative, or proxied non-Claude models may be incomplete or unstable.
• Time and cost. A full run takes roughly 1 to 1.5 hours and incurs LLM API costs that scale with model pricing, application complexity, and concurrency.
• Prompt injection risk. Do not scan untrusted or adversarial codebases.
• No targeted re-test. Verifying a fix means running the full pipeline again.
• Not production, ever. Exploitation agents mutate application state by design.

Shannon Open Source is AGPL-3.0. Broader static analysis, finding management, and verified remediation live in Keygraph's commercial platform.