Introduction to Shannon

Note

Shannon 3.0 is live: deeper security code analysis, a rebuilt CLI, native CI/CD, PDF reports, and SARIF. These docs cover Shannon 3.x.

Shannon is an autonomous AI pentester developed by Keygraph. It performs white-box security testing of web applications and their underlying APIs by combining source-code analysis with live exploitation.

Shannon analyzes your web application’s source code to identify potential attack vectors, then uses browser automation and command-line tools to execute real exploits against the running application and its APIs. Only vulnerabilities with a working proof-of-concept are included in the final report.

Shannon, documented here, is the open-source pentester you run yourself. Keygraph’s commercial editions, Keygraph Pro and Keygraph Enterprise, are powered by an enhanced, enterprise-grade version of the Shannon engine. See Editions for how they compare.

Why Shannon exists

Thanks to tools like Claude Code and Cursor, your team ships code non-stop. Most teams still pentest once a year. Between tests, vulnerabilities can ship to production and sit there unnoticed.

Shannon closes that gap by providing on-demand, automated penetration testing that can run against every build or release.

Not a replacement for human pentesters

Shannon is built to work alongside expert pentesters and red teamers, not replace them. Great pentesters understand the business, chain attacks in ways nobody anticipated, and bring judgment that current models can’t match.

Shannon solves a different problem: there is far more software to test than security teams have time to cover. It shifts pentesting left into the software development lifecycle, so you can run exploitation-backed tests against staging environments and releases at the cadence they ship, and save expert human time for the risks that need someone who knows the organization.

Why “Shannon”?

It’s named after Claude Shannon, the father of information theory. Pentesting is an information problem: every probe reduces uncertainty about a system’s state, and the best tools maximize the signal gained from every request.

How Shannon works

Shannon combines multi-stage security code analysis with live reconnaissance and exploitation. Each scan flows through six stages:

1. Recon and vulnerability analysis explore the running application, tie runtime behavior back to the source, and run specialized agents for Injection, XSS, SSRF, Authentication, and Authorization.
2. Security code analysis (optional, agentic_sast) runs alongside them, mapping architecture, trust boundaries, data flows, and high-risk assets.
3. Finding reconciliation merges both streams, removes duplicates, and builds one exploitation queue.
4. Exploitation agents, including a sixth agent for findings outside the five classes, attempt real proof-of-concept attacks.
5. Validation discards every candidate Shannon cannot demonstrate.
6. Reporting produces PDF and Markdown reports with the evidence attached, plus JSON and SARIF.

flowchart TD
S["Source code"] --> A["1 · Recon + vulnerability analysis<br/><small>Injection · XSS · SSRF · Auth · Authz</small>"]
S --> B["2 · Security code analysis<br/><small>optional</small>"]

A -- "pentest candidates" --> C["3 · Finding reconciliation<br/><small>merge + deduplicate</small>"]
B -- "code-analysis candidates" --> C

C --> P4
APP["Running application"] --> P4

subgraph P4 ["4 · Exploitation"]
  X1["Exploit · Injection"]
  X2["Exploit · XSS"]
  X3["Exploit · SSRF"]
  X4["Exploit · Auth"]
  X5["Exploit · Authz"]
  X6["Exploit · Misc"]
end

P4 --> V{"5 · Validation"}
V -- "exploit demonstrated" --> R["6 · Reporting<br/><small>PDF · Markdown · JSON · SARIF</small>"]
V -- "not demonstrated" --> D["Discarded"]

Shannon's scan workflow

Only live-validated vulnerabilities become Shannon pentest findings or count toward CI/CD severity gates.

Each scan runs in an ephemeral Docker container with its own isolated workspace, so runs never share state.

What you see while it runs

shannon status shows each scan’s progress as a phase list: Authentication (login validation, shown as skipped when no login is configured), Pre-Recon, Recon, Vulnerability Analysis, Exploitation, and Reporting. Security code analysis and finding reconciliation appear as detail rows under the phase they feed.

Key capabilities

• Proof-by-exploitation reports: validated findings with reproducible proof-of-concept steps instead of speculative warnings.
• White-box attack planning: source-code analysis guides dynamic testing toward realistic attack paths.
• Autonomous execution: reconnaissance, vulnerability analysis, exploitation, and report generation launch from a single command.
• Authenticated testing: configuration files can describe login flows (including TOTP and email-based login), test credentials, focus areas, and rules of engagement.
• OWASP-focused coverage: targets exploitable Injection, XSS, SSRF, Broken Authentication, and Broken Authorization issues.
• Resumable workspaces: resume interrupted runs without re-running completed agents.
• Live terminal experience: simplifies scan setup and shows agent progress and results without exposing orchestration logs.
• Native CI/CD integrations: the official GitHub Action (KeygraphHQ/shannon-action@v1) and GitLab CI/CD component run pull-request, release, and scheduled pentests, and can fail a pipeline only on exploited findings at or above a severity you set.
• Multi-format reports: PDF and Markdown reports plus JSON and SARIF 2.1.0 (SARIF on by default for exploit runs).
• Provider-agnostic and BYOK: Anthropic, OpenAI, xAI, AWS Bedrock, compatible gateways, and local models served through Ollama, vLLM, or LM Studio.
• Private by design: runs in your infrastructure, stores results locally, and sends model requests directly to your chosen endpoint. A local endpoint keeps data inside your environment.
• Security code analysis: optional multi-stage code analysis that feeds exploitation candidates into the pentest.

Shannon in action

These reports are from Shannon Open Source 3.0 scans of Photoview 2.4.0, an open-source, self-hosted photo management application. Keygraph ran Shannon against it with three models and published the reports and SARIF logs.

Model	Token cost	Verified findings	Report
DeepSeek v4 Flash	$6.10	18	PDF · SARIF
Grok 4.6	$35.07	10	PDF · SARIF
Claude Opus 5	$115	23 (plus 1 false positive)	PDF · SARIF

All three runs found the critical pre-auth SQL injection (CVSS 9.8) that Photoview later patched, and the Opus 5 run caught 6 of the 7 vulnerabilities Photoview patched after 2.4.0. Every model caught the most urgent issue, while stronger models caught more of the subtler, higher-severity ones, which supports running a lower-cost model for frequent scans and a frontier model for periodic deeper assessments. Token cost is what a run consumed on a model key, not a product price. The reports and SARIF logs are in the benchmark folder on GitHub.

Older sample reports, produced by the pre-3.0 engine against intentionally vulnerable applications:

Target	Summary
OWASP Juice Shop	20+ vulnerabilities, including authentication bypass, SQL injection, IDOR, and SSRF.
c{api}tal API	~15 critical and high-severity API findings, including command injection, auth bypass, and mass assignment.
OWASP crAPI	15+ critical and high-severity findings across JWT, injection, SSRF, and API authorization paths.

Before you begin

Shannon actively executes exploits. Run it only against applications and environments you own or have explicit written authorization to test, and never against production systems. Read Safety & Limitations before your first run.

Next steps

Continue to the Quick Start to run your first pentest.