Shannon: autonomous pentest with exploit proof

Everything worth knowing about KeygraphHQ/shannon: a command-line agent that checks web applications and their APIs for vulnerabilities, combining code analysis with real exploitation in authorized environments.

---

What Shannon is

Shannon Open Source is Keygraph’s autonomous pentester for web applications and their APIs. It runs locally, takes the target’s URL and repository, analyzes the source code to build attack paths, and tests those hypotheses against the running application. The final report only includes findings for which the agent obtained a working proof of concept; it does not claim to replace human review.

The repository mainly covers injection, XSS, SSRF, broken authentication, and broken authorization. Keygraph’s commercial edition uses Shannon as the testing engine inside a broader platform that adds static analysis, scoped SCA, findings management, remediation, and verification; those additional capabilities should not be attributed to the open-source CLI.

The origin: closing the gap between shipping and testing

GitHub dates the repository’s creation to September 27, 2025. Keygraph identifies itself in the README and on its site as the company behind Shannon; no official entry naming the individual creators was recovered, so no individual authorship is attributed.

The stated rationale is a cadence tension: teams can ship code continuously with the help of coding assistants, while a conventional pentest happens far less often. Shannon attempts to offer an on-demand check, potentially on every build or release, instead of waiting for an annual audit. The official page presents it as a white-box pentester: it needs the code and a running application.

The official @KeygraphHQ account posted on X on February 7, 2026 announcing early access to Shannon Pro, the platform version. On July 31 it announced Shannon 2.0 and stated the engine had been rebuilt to work with any major model using an open-source harness. These are vendor communications, not independent reviews.

Philosophy and principles

• Proof before hypothesis: the flow attempts to exploit a vulnerability before including it in the report.
• Code-guided white box: repository analysis is used to steer reconnaissance and dynamic attacks, not to produce a static list of alerts.
• Automation with operational limits: rules of engagement, paths to avoid, and priority areas are declared in configuration.
• Testing security, not passive security: the project itself warns that agents can create users, modify data, send outbound requests, and leave exploitation artifacts. It requires written authorization and recommends local, staging, or disposable environments — not production.
• Human judgment at the end: even though it is validated through exploitation, the README acknowledges that model-generated details can be weak or incorrect.

How it works

The multi-agent flow has five documented phases:

1. Pre-reconnaissance: examines the code to identify technologies, entry points, data flows, and attack surfaces.
2. Reconnaissance: explores the live application and correlates its behavior with the code’s context.
3. Specialized analysis: runs agents for injection, XSS, SSRF, authentication, and authorization.
4. Exploitation: attempts real proofs of concept and discards hypotheses it cannot demonstrate.
5. Reporting: gathers evidence and recommendations into a final Markdown document.

The repository is mounted read-only inside an ephemeral Docker container. In the recommended mode, the CLI downloads the worker image, boots the local infrastructure, and writes state to a workspace. It can resume an interrupted analysis because it keeps per-agent checkpoints.

Official and semi-official status

Shannon is not an accepted add-on in any model vendor’s marketplace, nor a formal standard. Its verifiable official status is different: Keygraph maintains the repository, the CLI, the documentation, Discord, and community office hours, and sells a platform that uses an enhanced version of Shannon as its pentest engine.

In practice, the repository is the open, self-hosted edition of Keygraph’s product, under AGPL-3.0. That relationship is official, but it is not equivalent to certification from Anthropic, OpenAI, xAI, AWS, or GitHub. The README states credential compatibility with Anthropic, OpenAI, xAI, and AWS Bedrock; it also warns that the project’s official support concentrates on Claude models and that alternatives may be incomplete or unstable.

The ecosystem

Vendor repositories

Querying the organization on GitHub retrieved the following related public repositories:

• KeygraphHQ/xbow-validation-benchmarks: 37 stars and 8 forks. By its name and organizational membership, it appears to be validation material associated with the XBOW benchmark; no further integration is inferred without recovered documentation.
• KeygraphHQ/validation-benchmarks: 2 stars and 1 fork; it had no description in the queried API.
• KeygraphHQ/juice-shop: 12 stars and 4 forks, a fork of OWASP Juice Shop that the README uses as the target for sample reports.
• KeygraphHQ/hipaa-baa-tax: 6 stars and 2 forks; its description is “HIPAA (BAA) Tax,” with no explicit technical link to Shannon recovered.

The Keygraph platform is the main commercial companion, not another repository: it adds continuous pentesting, code analysis, management, and a remediation cycle around the open engine.

Forks and community extensions

The forks API shows heavy reuse, but most retain the original description and do not demonstrate being a port. The derivatives with their own positioning that were recovered were:

• Steake/shannon-uncontained: 58 stars and 8 forks. Described as a Docker-free fork, black-box first, with agentic reconnaissance, analysis, and synthesis; it is an explicit variant, not a mirror.
• baianquanzu/shannon: 19 stars and 3 forks. Presented as “Shannon Lite”; the API did not provide independent documentation to pin down its differences.
• ClaraOswald076/shannon-with-deepseek: 3 stars and 1 fork. Declares compatibility with the DeepSeek API.
• DoroninDobroCorp/shannon_copilot: 2 stars. Declares usage with Copilot without an API key; this is recorded as the fork’s own claim, not as compatibility endorsed by Keygraph.

No non-English translation with verifiable documentation, nor a community port with official support, was recovered. The figures above are those returned by GitHub on August 6, 2026; they do not certify quality, security, or maintenance.

Repo numbers

Measured: August 6, 2026, GitHub API.

Metric	Value
Stars	46,469
Forks	5,364
Real subscribers	223
Commits	272
Open issues reported by the API	33
Main language	TypeScript
License	AGPL-3.0
Created	September 27, 2025
Latest release	v2.2.0, August 4, 2026

The total of 272 commits comes from the last page indicated by the API’s pagination header. The top returned contributors were ajmallesh (123 contributions), ezl-keygraph (75), keygraphVarun (35), and george-keygraph (26).

GitHub also returns a watchers_count equal to the star count; that is why subscribers_count is reported separately as the real subscriber figure. The open_issues_count field can include open pull requests, so it does not necessarily equal exclusive issue count. The API reported updated_at as August 6, 2026, consistent with the measurement date; the latest code update available in that response was August 4.

Release v2.2.0 fixes severity logging in analysis mode and instruction substitutions. v2.1.0 added multi-provider support, SARIF output, and exploitation-mode fixes. v2.0.0 migrated the agent harness from Claude Agent SDK to pi and dropped Vertex AI as a provider; per the release notes, Vertex users should migrate to Anthropic, AWS Bedrock, or an Anthropic-compatible endpoint.

How to contribute

The README explicitly states that Keygraph is not accepting external code contributions at this time. It does invite opening issues for bugs and discussions for feature requests. As a result, there is no documented fork-branch-pull-request flow to present as an official contribution path.

For local development, the guide does document git clone, pnpm install, and pnpm build, plus rebuilding the image with ./shannon build --no-cache. This enables local testing and modification, but does not guarantee the vendor will incorporate it.

Quick usage guide

Installation and first run

Use Docker, Node.js 18 or higher, and credentials for an AI provider. Before the first scan, the README requires resolving with the provider which safeguards apply to legitimate cybersecurity work. Only test systems you own or have written authorization for, and do not use production.

npx @keygraph/shannon setup
npx @keygraph/shannon start -u https://your-app.com -r /path/to/your-repo

The setup wizard saves the npx configuration, and the first scan downloads the Docker worker, mounts the repository read-only, and creates a local workspace. A full scan typically takes roughly one to one and a half hours, with API cost depending on the model, the application, and concurrency.

To build from source:

git clone https://github.com/KeygraphHQ/shannon.git
cd shannon
cp .env.example .env
pnpm install
pnpm build
./shannon start -u https://your-app.com -r /path/to/your-repo

Common workflows

• Basic authorized scan: npx @keygraph/shannon start -u https://example.com -r /path/to/repo creates a workspace and leaves Security-Assessment-Report.md at its root.
• Application with login or explicit limits: copy configs/example-config.yaml to ./my-app-config.yaml, describe authentication and rules, and run npx @keygraph/shannon start -u https://example.com -r /path/to/repo -c ./my-app-config.yaml.
• Keeping an identifiable run and resuming it: use -w q1-audit; to resume, repeat the URL, repository, and the same name: npx @keygraph/shannon start -u https://example.com -r /path/to/repo -w q1-audit.
• Monitoring and exporting: npx @keygraph/shannon logs <workspace>, npx @keygraph/shannon status, and npx @keygraph/shannon start -u https://example.com -r /path/to/repo -o ./my-reports. The Temporal UI is available at http://localhost:8233 per the guide.

Essential configuration

• ~/.shannon/config.toml: credentials and options created by npx @keygraph/shannon setup; environment variables take priority.
• .env: a credential alternative for a build from source; at minimum it can contain ANTHROPIC_API_KEY.
• my-app-config.yaml: a per-target file for authentication, login_flow steps, rules, vulnerability classes, and report filters.
• report.sarif: optional output enabled with exploit: "true" and report: { sarif: "true" }; it appears alongside the Markdown report and serves SARIF consumers, including GitHub code scanning.
• ~/.shannon/workspaces/ in npx mode or ./workspaces/ when building from source: directories with state, reports, logs, rendered instructions, and session.json.

Common pitfalls and fixes

• Unexpected cost: discussion #72 records that olsenbudanur spent 30 dollars on pre-reconnaissance alone, though they noted they found bugs they wanted to fix. Discussion #74 shows that carterjohndixon used up 20 dollars in about two hours. These are individual experiences, not a guaranteed rate; the documented remedy is budgeting for a staging environment and deliberately choosing the provider and model.
• Interrupted run: do not change the URL when resuming; Shannon rejects a different URL to avoid mixing targets. Use the same -w <name> and check npx @keygraph/shannon workspaces.
• Report apparently missing: the final report sits at the workspace root as Security-Assessment-Report.md; logs, intermediate deliverables, and session.json live inside .shannon/.
• The model refuses during an exploit: pull request #387 documents that a content-policy refusal could abort a full run and skip the report. That pull request was closed and describes a fix to preserve analysis and continue with other pipelines, but it is worth checking the version and logs before re-running the scan.
• Claude Code OAuth after version 2: the README identifies shannon-v1 and npx @keygraph/shannon@1.9.0 setup as the historical path for an OAuth token; v2 changed harnesses. Do not use Vertex AI variables that were removed by v2.0.0.

Integrations and migration

SARIF output allows loading results into GitHub Code Scanning or another SARIF consumer. For networking and local applications, the platform documentation covers Docker, Windows/WSL2, Linux, macOS, and custom hostnames; the repository does not present an editor integration as a requirement.

The explicitly documented migration is from v2 for those who used Google Vertex AI: move to Anthropic, AWS Bedrock, or an Anthropic-compatible endpoint. To run against a Claude Code subscription instead of API credits, the README points to the shannon-v1 branch, a token created with claude setup-token, and version 1.9.0; it is a legacy path, not a v2 compatibility promise.

How the community received it

The external reception recovered on Hacker News was brief and low-engagement, so it does not establish a consensus:

• Thread 46915303, submitted by charlieirish on February 6, 2026: 4 points and 0 comments. It links directly to the repository; it demonstrates reach, not an external opinion.
• Thread 46926419, submitted by hendler on February 7: 3 points and 2 comments. Its title compared the idea to Claude Code applied to pentesting; the search did not recover comment text specific enough to attribute praise or criticism.
• Thread 46936352, submitted by koqoo: 3 points and 0 comments. It is a direct link, not a review.
• Thread 46944416, submitted by wslh: 1 point and 0 comments. It also demonstrates discovery, not qualitative reception.

GitHub provides more concrete and mixed signals. In discussion #72, olsenbudanur valued that the scan caught some pending bugs, but objected to the cost. In #74, carterjohndixon asked for a clearer warning about spend and resuming after using up credit. In discussion #78, PopoviciGabriel praised the clear purpose, the separation between configuration, instructions, and logic, and the documentation, while proposing better architectural boundaries and error tests. These are opinions from identified GitHub users, not controlled evaluations.

Searches were attempted on Reddit, Product Hunt, and YouTube. Reddit returned no search results attributable to the project within the available access; Product Hunt returned an access block; and the YouTube query produced no verifiable metadata for tutorials or demos. As a result, no threads, votes, or view counts are invented.

Shannon versus other proposals

Proposal	Verifiable overlap	Verifiable difference
OWASP Juice Shop	A web application used to check security findings.	It is a deliberately vulnerable target, not a pentester or a competitor.
Keygraph platform	Uses an enhanced version of Shannon for penetration testing.	Adds continuous execution, static analysis, SCA, management, remediation, and enterprise deployment; Shannon Open Source is a local white-box CLI.
Steake/shannon-uncontained	A fork that preserves the AI-pentest purpose.	Declares Docker-free execution and black-box priority; it is not the official distribution.

No additional products are presented as direct competitors without a recovered source establishing a technical comparison. The practical alternative within the documentation itself is to use the Keygraph platform when continuous management, enterprise integration, and a remediation cycle are needed, versus running the CLI for an on-demand local pentest.

Use cases and who this repository can help

• Development teams with a staging application and code access can commission a white-box pentest before a release: Shannon combines repository, URL, and exploitation to produce reproducible proofs of injection, XSS, SSRF, authentication, or authorization issues.

• Security leads who need to bound an automated audit can use rules_of_engagement, paths to avoid, focus areas, test credentials, and severity or confidence filters in the YAML, instead of launching a scan without a declared scope.
• Teams integrating security results into code review can enable SARIF on scans with exploitation and consume report.sarif in GitHub Code Scanning or another compatible tool; the Markdown report remains as the readable deliverable.
• Operators running costly or long scans can name workspaces, follow logs, and resume without repeating already-completed agents, always for the same URL. They must budget for model cost, isolate data, and review every finding before acting on it.

Resources

• Repository: https://github.com/KeygraphHQ/shannon
• Documentation and installation: https://github.com/KeygraphHQ/shannon#quick-start
• Configuration: https://github.com/KeygraphHQ/shannon/blob/main/docs/configuration.md
• Safety and limits: https://github.com/KeygraphHQ/shannon/blob/main/docs/safety.md
• Workspaces and resuming: https://github.com/KeygraphHQ/shannon/blob/main/docs/workspaces.md
• Platform and official presentation: https://keygraph.io/open-source.html
• Discord and community office hours: https://discord.gg/cmctpMBXwE, https://cal.com/george-flores-keygraph/shannon-community-office-hours
• Official announcements on X: https://x.com/KeygraphHQ
• Hacker News threads: https://news.ycombinator.com/item?id=46915303, https://news.ycombinator.com/item?id=46926419, https://news.ycombinator.com/item?id=46936352, https://news.ycombinator.com/item?id=46944416
• GitHub conversations: https://github.com/KeygraphHQ/shannon/discussions/72, https://github.com/KeygraphHQ/shannon/discussions/74, https://github.com/KeygraphHQ/shannon/discussions/78
• npm registry: https://www.npmjs.com/package/@keygraph/shannon

---

Note: this article combines Shannon’s README, documentation, posts, discussions, and GitHub API, along with accessible Hacker News and X queries, carried out on August 6, 2026. Figures change over time.