KeygraphHQ/shannon

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.

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. Point Shannon at a locally hosted endpoint and that traffic stays inside your environment too.

Can I run Shannon on a local or self-hosted model?

Shannon works with local models served through Ollama, vLLM, or LM Studio, which expose an OpenAI-compatible endpoint, as well as routers such as OpenRouter and LLM gateways such as LiteLLM. A model the harness catalogue does not carry, which most self-hosted models are, is described in a custom model configuration file passed with --models-config; routers and gateways can also be reached with a custom base URL. Capability varies, and a model that does not follow Shannon's instructions or tool-use constraints reliably will produce weaker pentests than a frontier model, so take this path only i

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 b
• 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 sec

Architecture

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

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.

• 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.
• 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 the
• Finding reconciliation merges both streams of candidates, deduplicates the overlap, and groups what remains into an exploitation queue.
• Exploitation agents attempt real proof-of-concept attacks against the running application.
• Validation throws out every candidate Shannon can't demonstrate.
• Reporting produces PDF and Markdown reports with the evidence attached, plus structured JSON and SARIF for downstream systems.

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.

Read the full Safety and limitations guide before running Shannon in a new environment.

• 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 manag
• 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 ga
• 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.

Shannon is an autonomous, AI pentester for web applications and APIs.

It analyzes your source code, identifies attack paths, and executes real exploits to prove vulnerabilities before they reach production. No exploit, no report.

This repository is Shannon: the full open-source agent, run locally from your command line.

The interactive launcher will guide you through setup and your first pentest.