KeygraphHQ/shannon

[!NOTE]

php2shell upgrade verification: confirm your PHP apps are patched against the php2shell RCE chain with the experimental --exp-php2shell probe. See the test results.

npx @keygraph/shannon@latest

[!TIP]

AI agents and LLMs: start with llms.txt for a concise map of this repository, or use llms-full.txt for the README and docs combined into one file.

Table of Contents

• Table of Contents
• What is Shannon?
• Why Shannon Exists
• Why "Shannon"?
• Not a replacement for human pentesters
• Shannon in Action
• Quick Start
• Prerequisites
• Run Shannon
• Key Capabilities
• CI/CD Integrations
• GitHub Actions
• Editions
• Architecture
• Documentation
• Safety, Scope, and Limitations
• License
• Acknowledgements
• About Keygraph
• Community and Support
• Common Questions
• Can I self-host Shannon?
• Does Shannon support bring your own key (BYOK)?
• Does Shannon output SARIF?
• Which AI providers does Shannon support?
• Can I run Shannon on a local or self-hosted model?
• Does Shannon actually exploit vulnerabilities, or just scan?

What is Shannon?

Shannon is an autonomous AI pentester developed by Keygraph. It performs 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 is the agent. This repository is Shannon, the open-source pentester you run yourself. The same Shannon also powers Keygraph's commercial editions, Pro and Enterprise. See Editions for how Shannon compares with Pro, Enterprise, and the Community Program.

Shannon in Action

These reports are from Shannon OSS scans of Photoview 2.4.0, one of the applications in Doyensec's comparison of Aikido and XBOW. We ran Shannon against the same application version and evaluated its results separately. Read the Doyensec study and our Shannon follow-up comparison for the methodology, limitations, costs, and results.

| Model | Report | SARIF | | ----------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------- | | DeepSeek v4 Flash | View report | SARIF | | Grok 4.6 | View report | SARIF | | Claude Opus 5 | View report | SARIF |

Quick Start

Prerequisites

• Docker: required for the worker container.
• Node.js 18+: required for the recommended npx workflow.
• AI provider credentials: Shannon runs on Anthropic, OpenAI, xAI, AWS Bedrock, and any other provider in the harness catalogue — each of which you can point at a proxy or LLM gateway through a custom base URL, and a model the catalogue does not carry can be described with a custom model configuration. You bring your own key, and Keygraph never proxies your model traffic. Shannon is provider-agnostic. See AI providers for suggested model IDs.
• Cyber safeguards cleared with your provider: Anthropic and OpenAI apply real-time safeguards to cyber-security workloads, which can interrupt a scan mid-run. Complete their guidance for legitimate security testers before your first run - see AI providers and the cyber verification announcement.

Run Shannon

[!WARNING]

Shannon actively executes exploits. Run it only against applications and environments you own or have explicit written authorization to test. Do not run Shannon against production systems.

# Configure credentials with the interactive wizard.
npx @keygraph/shannon@latest setup
Run a pentest against a source-available target.
npx @keygraph/shannon@latest start \
  -u https://your-app.com \
  -r /path/to/your/repo

Shannon pulls the worker image from Docker Hub, starts the required local infrastructure, mounts the target repository read-only inside an ephemeral worker container, and writes results to a local workspace.

For source builds, authenticated scans, provider-specific setup, and platform notes, see Documentation.

[!TIP]

Prefer to use a subscription instead of API credits?

> - OpenAI Codex: The latest version of Shannon supports ChatGPT Plus and Pro subscriptions. Follow the OpenAI Codex subscription setup guide to get started.

- xAI (Grok): The latest version of Shannon supports xAI subscriptions. Follow the xAI subscription setup guide to get started.

- Claude Code: The latest version of Shannon does not support Claude Code subscriptions. Follow the Claude Code subscription setup guide to use version 1.9.0, which is the final release built on the Claude Agent SDK.

Key Capabilities

• No exploit, no report: Reports only vulnerabilities confirmed with a reproducible proof of concept, reducing speculative scanner noise.
• Advanced code analysis: Maps architecture, trust boundaries, interfaces, data flows, and critical assets before sending credible attack paths to live pentesting agents.
• Autonomous execution: Runs reconnaissance, analysis, exploitation, and reporting from a single command.
• Live terminal experience: Simplifies scan setup and shows agent progress and results without exposing orchestration logs.
• Authenticated testing: Supports credentials, login flows, TOTP, email authentication, focus areas, and rules of engagement through configuration.
• OWASP-focused coverage: Tests for exploitable injection, XSS, SSRF, broken authentication, and broken authorization.
• Resumable workspaces: Resumes interrupted scans without repeating completed work.
• Native CI/CD integrations: Runs through the official GitHub Action or GitLab CI/CD component, preserves artifacts, publishes findings, and gates releases on proven vulnerabilities.
• Multi-format reports: Produces evidence-rich PDF and Markdown reports plus JSON and SARIF 2.1.0. SARIF is enabled by default for exploit-mode scans.
• Provider agnostic and BYOK: Supports Anthropic, OpenAI, xAI, AWS Bedrock, compatible APIs and LLM 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.

CI/CD Integrations

Shannon can run continuously against deployed staging and development environments through official integrations for GitHub Actions and GitLab CI/CD.

Both integrations:

• analyze the checked-out source repository while attacking a running target;
• preserve PDF, Markdown, and SARIF reports as pipeline artifacts;
• preserve scan and agent logs for debugging, including incomplete runs;
• support pull-request, release, and scheduled pentests;
• distinguish an incomplete assessment from a completed scan with no findings; and
• optionally fail the pipeline when Shannon exploits a vulnerability at or above a configured severity threshold.

GitHub Actions

name: Shannon Pentest
on:
  workflow_dispatch:
permissions:
  security-events: write
jobs:
  pentest:
    runs-on: ubuntu-latest
steps:
uses: actions/checkout@v4
name: Run Shannon
        uses: KeygraphHQ/shannon-action@v1
        with:
          url: https://staging.example.com
          api-key: ${{ secrets.SHANNON_AI_API_KEY }}
          fail-on-severity: high
          upload-sarif: true

The Action defaults repo to the checked-out GitHub workspace. It uploads one artifact containing the security assessment reports and SARIF, plus a separate run artifact containing scan and agent logs. Enabling upload-sarif publishes supported findings to GitHub code scanning.

Requirements:

• a private repository;
• a runner with Docker and Docker Compose v2;
• access to the running staging or development target; and
• a model-provider credential stored as a GitHub Actions secret.

Editions

| Edition | What it is | Price | | --- | --- | --- | | Shannon (open source) | This repository. A complete autonomous pentester you run yourself, locally or in CI/CD, against an application whose source code you have. Well suited to individual developers and small teams. | Open source under AGPL-3.0. You pay only your own model costs. | | Community Program | Keygraph Pro at no cost, for U.S.-based 501(c)(3) nonprofits and for seed or pre-Series-A startups with 20 or fewer active developers. | $0 in cloud service fees while you qualify. | | Pro | Keygraph's cloud-hosted edition, managed by Keygraph, with every module included. | $50 per active developer per month. | | Enterprise | Everything in Pro, self-hosted in your own environment or fully air-gapped. | Custom. |

See keygraph.io/pricing for current prices and the full feature table.

Pro, Enterprise, and the Community Program are powered by an enhanced, enterprise-grade version of the Shannon engine, and all three add:

• Black-box pentesting: tests the running application from the outside, with no source code needed.
• Dependency (SCA) and secret checks: SCA with reachability, and secrets scanning that includes repository history.
• Findings management: one record per vulnerability per repository across scans and scanners, with status history, owners, SLAs, and dashboards.
• Fix pull requests and retests: reviewable fix pull requests, with each fix verified by re-analysis and exploit replay, without a full rescan.
• Jira and access control: two-way Jira sync, SSO, RBAC, and audit logs.

Compare Shannon, Pro, and Enterprise in detail →

Architecture

Shannon combines multi-stage security code analysis with live reconnaissance and exploitation:

flowchart TD
    S["Source code"] --> EXISTING["Recon + vulnerability analysis"]
    S --> SAST["Agentic security code analysis"]
EXISTING -- "Pentest candidates" --> REC["Finding reconciliation
(merge + deduplicate)"]
    SAST -- "SAST candidates" --> REC
REC -- "Reconciled exploitation queue" --> EXP["Exploitation agents"]
    APP["Running application"] --> EXP
EXP -- "Exploit demonstrated" --> REPORT["Reporting
PDF · Markdown · SARIF"]
    EXP -- "No exploit demonstrated" --> DROP["Discard"]
REPORT --> CICD["CI/CD gate"]

Stage by stage:

1. Recon and vulnerability analysis explores the running application, ties runtime behavior back to the source, and runs specialized agents across Injection, XSS, SSRF, Authentication, and Authorization. 2. Agentic security code analysis maps the application's architecture, trust boundaries, exposed interfaces, dependencies, data flows, and high-risk assets, then opens targeted investigations against them. 3. Finding reconciliation merges both streams of candidates, deduplicates the overlap, and groups what remains into an exploitation queue. 4. Exploitation agents attempt real proof-of-concept attacks against the running application. 5. Validation throws out every candidate Shannon can't demonstrate. 6. Reporting produces PDF and Markdown reports with the evidence attached, plus structured JSON and SARIF for downstream systems.

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

Each scan runs in an ephemeral Docker container with an isolated workspace and per-invocation orchestration.

Documentation

Use these guides for operational detail:

| Guide | Use it for | | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Source build and CLI commands | Cloning, building, common commands, output paths, and local development. | | Configuration | Authenticated testing, login flows, rules of engagement, and report filters. | | AI providers | Selecting the model, the supported providers (Anthropic, OpenAI, xAI, AWS Bedrock, and any other Pi-supported provider), and custom LLM gateways. | | Platforms and networking | Windows/WSL2, Linux, macOS, Docker networking, local apps, and custom hostnames. | | Workspaces and resuming | Naming workspaces, resuming interrupted scans, and workspace storage. | | Safety and limitations | Authorized-use requirements, non-production guidance, mutative effects, cost, and model caveats. | | Coverage and roadmap | Current vulnerability coverage and planned work. | | Pro and Enterprise | Shannon compared with Pro, Enterprise, and the Community Program: black-box pentesting, SCA and secrets, findings management, fix pull requests, retests, Jira, and deployment. |

Safety, Scope, and Limitations

Shannon is not a passive scanner. Its exploitation agents can create users, submit forms, mutate application state, trigger outbound requests, and otherwise affect the target system. Use sandboxed, staging, or local development environments with disposable data.

You are responsible for using Shannon legally and ethically. Do not point Shannon at systems, repositories, or applications you do not own or do not have explicit authorization to test.

Important limitations:

• Shannon is tuned for fast, code-informed pentesting in everyday development and CI/CD. Exhaustive agentic SAST, broader scanner coverage, centralized governance, and full-lifecycle vulnerability management are delivered through Pro, Enterprise, and the Community Program.
• Findings still require human review. LLM-generated reports can contain weakly supported or incorrect details.
• Anthropic, OpenAI, xAI, and AWS Bedrock are built-in providers, and any other provider in the harness catalogue works too — each reachable through a custom base URL that points it at a proxy or LLM gateway. Model capability varies, and a model that does not follow Shannon's instructions or tool-use constraints reliably will produce weaker results.
• A full run can take roughly 1 to 1.5 hours and may incur LLM API costs depending on model pricing and application complexity.
• Do not scan untrusted or adversarial codebases. AI-powered tools that read source code can be exposed to prompt injection.

License

Shannon is licensed under the GNU Affero General Public License v3.0.

Commercial and enterprise licensing is available for organizations that need different license terms, commercial support, private redistribution, managed-service use, or broader deployment options, including Keygraph Pro and Enterprise.

For commercial licensing, contact [email protected].

Acknowledgements

Thanks to Pi, Playwright CLI, and Mantis.

See THIRD_PARTY_NOTICES.md for licensing and attribution details.

About Keygraph

Keygraph is the company behind Shannon. It also builds Keygraph Pro and Keygraph Enterprise, the commercial editions that close the full AppSec lifecycle and run an enhanced build of Shannon as their pentesting engine.

Community and Support

Community office hours are available for hands-on help with bugs, deployments, and configuration questions.

• US/EU: Thursday, 10:00 AM PT
• Asia: Thursday, 2:00 PM IST
• Book a slot

At this time, Keygraph is not accepting external code contributions. Issues are welcome for bug reports and feature requests:

• Report bugs
• Suggest features

• Keygraph website
• Twitter/X: @KeygraphHQ
• LinkedIn: Keygraph

Common Questions

Can I self-host Shannon?

Yes. Shannon runs inside your infrastructure in an ephemeral worker container. It mounts the repository read-only and writes results to a local workspace.

Keygraph never receives your source code and never proxies your model traffic. Your model requests go straight to the provider or endpoint you configure, and they carry source and application context with them. Poin