GitHub Trending Repositories

KeygraphHQ/shannon

Author: KeygraphHQ

Stars: 4,144 stars today

Description: Fully autonomous AI hacker to find actual exploits in your web apps. Shannon has achieved a 96.15% success rate on the hint-free, source-aware XBOW Benchmark.

README

[!NOTE] Shannon Lite achieves a 96.15% success rate on a hint-free, source-aware XBOW benchmark. →

KeygraphHQ%2Fshannon | Trendshift Shannon Screen # Shannon is your fully autonomous AI pentester. Shannon’s job is simple: break your web app before anyone else does.
The Red Team to your vibe-coding Blue team.
Every Claude (coder) deserves their Shannon. --- [Website](https://keygraph.io) • [Discord](https://discord.gg/KAqzSHHpRt) ---

🎯 What is Shannon?

Shannon is an AI pentester that delivers actual exploits, not just alerts.

Shannon's goal is to break your web app before someone else does. It autonomously hunts for attack vectors in your code, then uses its built-in browser to execute real exploits, such as injection attacks, and auth bypass, to prove the vulnerability is actually exploitable.

What Problem Does Shannon Solve?

Thanks to tools like Claude Code and Cursor, your team ships code non-stop. But your penetration test? That happens once a year. This creates a massive security gap. For the other 364 days, you could be unknowingly shipping vulnerabilities to production.

Shannon closes this gap by acting as your on-demand whitebox pentester. It doesn't just find potential issues. It executes real exploits, providing concrete proof of vulnerabilities. This lets you ship with confidence, knowing every build can be secured.

[!NOTE] From Autonomous Pentesting to Automated Compliance

Shannon is a core component of the Keygraph Security and Compliance Platform.

While Shannon automates the critical task of penetration testing for your application, our broader platform automates your entire compliance journey—from evidence collection to audit readiness. We're building the "Rippling for Cybersecurity," a single platform to manage your security posture and streamline compliance frameworks like SOC 2 and HIPAA.

➡️ Learn more about the Keygraph Platform

🎬 See Shannon in Action

Real Results: Shannon discovered 20+ critical vulnerabilities in OWASP Juice Shop, including complete auth bypass and database exfiltration. See full report →

Demo

✨ Features

📦 Product Line

Shannon is available in two editions:

| Edition | License | Best For | |---------|---------|----------| | Shannon Lite | AGPL-3.0 | Security teams, independent researchers, testing your own applications | | Shannon Pro | Commercial | Enterprises requiring advanced features, CI/CD integration, and dedicated support |

This repository contains Shannon Lite, which utilizes our core autonomous AI pentesting framework. Shannon Pro enhances this foundation with an advanced, LLM-powered data flow analysis engine (inspired by the LLMDFA paper) for enterprise-grade code analysis and deeper vulnerability detection.

[!IMPORTANT] White-box only. Shannon Lite is designed for white-box (source-available) application security testing.
It expects access to your application's source code and repository layout.

See feature comparison

📑 Table of Contents

🚀 Setup & Usage Instructions

Prerequisites

Quick Start

```bash

1. Clone Shannon

git clone https://github.com/KeygraphHQ/shannon.git cd shannon

2. Configure credentials (choose one method)

Option A: Export environment variables

export ANTHROPIC_API_KEY="your-api-key" # or CLAUDE_CODE_OAUTH_TOKEN export CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000 # recommended

Option B: Create a .env file

cat > .env << 'EOF' ANTHROPIC_API_KEY=your-api-key CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000 EOF

3. Run a pentest

./shannon start URL=https://your-app.com REPO=your-repo ```

Shannon will build the containers, start the workflow, and return a workflow ID. The pentest runs in the background.

Monitoring Progress

```bash

View real-time worker logs

./shannon logs

Query a specific workflow's progress

./shannon query ID=shannon-1234567890

Open the Temporal Web UI for detailed monitoring

open http://localhost:8233 ```

Stopping Shannon

```bash

Stop all containers (preserves workflow data)

./shannon stop

Full cleanup (removes all data)

./shannon stop CLEAN=true ```

Usage Examples

```bash

Basic pentest

./shannon start URL=https://example.com REPO=repo-name

With a configuration file

./shannon start URL=https://example.com REPO=repo-name CONFIG=./configs/my-config.yaml

Custom output directory

./shannon start URL=https://example.com REPO=repo-name OUTPUT=./my-reports ```

Prepare Your Repository

Shannon expects target repositories to be placed under the ./repos/ directory at the project root. The REPO flag refers to a folder name inside ./repos/. Copy the repository you want to scan into ./repos/, or clone it directly there:

bash git clone https://github.com/your-org/your-repo.git ./repos/your-repo

For monorepos:

bash git clone https://github.com/your-org/your-monorepo.git ./repos/your-monorepo

For multi-repository applications (e.g., separate frontend/backend):

bash mkdir ./repos/your-app cd ./repos/your-app git clone https://github.com/your-org/frontend.git git clone https://github.com/your-org/backend.git git clone https://github.com/your-org/api.git

Platform-Specific Instructions

For Linux (Native Docker):

You may need to run commands with sudo depending on your Docker setup. If you encounter permission issues with output files, ensure your user has access to the Docker socket.

For macOS:

Works out of the box with Docker Desktop installed.

Testing Local Applications:

Docker containers cannot reach localhost on your host machine. Use host.docker.internal in place of localhost:

bash ./shannon start URL=http://host.docker.internal:3000 REPO=repo-name

Configuration (Optional)

While you can run without a config file, creating one enables authenticated testing and customized analysis. Place your configuration files inside the ./configs/ directory — this folder is mounted into the Docker container automatically.

Create Configuration File

Copy and modify the example configuration:

bash cp configs/example-config.yaml configs/my-app-config.yaml

Basic Configuration Structure

```yaml authentication: login_type: form login_url: "https://your-app.com/login" credentials: username: "test@example.com" password: "yourpassword" totp_secret: "LB2E2RX7XFHSTGCK" # Optional for 2FA

login_flow: - "Type $username into the email field" - "Type $password into the password field" - "Click the 'Sign In' button"

success_condition: type: url_contains value: "/dashboard"

rules: avoid: - description: "AI should avoid testing logout functionality" type: path url_path: "/logout"

focus: - description: "AI should emphasize testing API endpoints" type: path url_path: "/api" ```

TOTP Setup for 2FA

If your application uses two-factor authentication, simply add the TOTP secret to your config file. The AI will automatically generate the required codes during testing.

[EXPERIMENTAL - UNSUPPORTED] Router Mode (Alternative Providers)

Shannon can experimentally route requests through alternative AI providers using claude-code-router. This mode is not officially supported and is intended primarily for:

Quick Setup

  1. Add your provider API key to .env:

```bash

Choose one provider:

OPENAI_API_KEY=sk-...

OR

OPENROUTER_API_KEY=sk-or-...

Set default model:

ROUTER_DEFAULT=openai,gpt-5.2 # provider,model format ```

  1. Run with ROUTER=true:

bash ./shannon start URL=https://example.com REPO=repo-name ROUTER=true

Experimental Models

| Provider | Models | |----------|--------| | OpenAI | gpt-5.2, gpt-5-mini | | OpenRouter | google/gemini-3-flash-preview |

Disclaimer

This feature is experimental and unsupported. Output quality depends heavily on the model. Shannon is built on top of the Anthropic Agent SDK and is optimized and primarily tested with Anthropic Claude models. Alternative providers may produce inconsistent results (including failing early phases like Recon) depending on the model and routing setup.

Output and Results

All results are saved to ./audit-logs/{hostname}_{sessionId}/ by default. Use --output <path> to specify a custom directory.

Output structure: audit-logs/{hostname}_{sessionId}/ ├── session.json # Metrics and session data ├── agents/ # Per-agent execution logs ├── prompts/ # Prompt snapshots for reproducibility └── deliverables/ └── comprehensive_security_assessment_report.md # Final comprehensive security report

📊 Sample Reports

Looking for quantitative benchmarks? See full benchmark methodology and results →

See Shannon's capabilities in action with penetration test results from industry-standard vulnerable applications:

🧃 OWASP Juice Shop • GitHub

A notoriously insecure web application maintained by OWASP, designed to test a tool's ability to uncover a wide range of modern vulnerabilities.

Performance: Identified over 20 high-impact vulnerabilities across targeted OWASP categories in a single automated run.

Key Accomplishments:

📄 View Complete Report →

🔗 c{api}tal API • GitHub

An intentionally vulnerable API from Checkmarx, designed to test a tool's ability to uncover the OWASP API Security Top 10.

Performance: Identified nearly 15 critical and high-severity vulnerabilities, leading to full application compromise.

Key Accomplishments:

📄 View Complete Report →

🚗 OWASP crAPI • GitHub

A modern, intentionally vulnerable API from OWASP, designed to benchmark a tool's effectiveness against the OWASP API Security Top 10.

Performance: Identified over 15 critical and high-severity vulnerabilities, achieving full application compromise.

Key Accomplishments:

📄 View Complete Report →

These results demonstrate Shannon's ability to move beyond simple scanning, performing deep contextual exploitation with minimal false positives and actionable proof-of-concepts.

🏗️ Architecture

Shannon emulates a human penetration tester's methodology using a sophisticated multi-agent architecture. It combines white-box source code analysis with black-box dynamic exploitation across four distinct phases:

┌──────────────────────┐ │ Reconnaissance │ └──────────┬───────────┘ │ ▼ ┌──────────┴───────────┐ │ │ │ ▼ ▼ ▼ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Vuln Analysis │ │ Vuln Analysis │ │ ... │ │ (Injection) │ │ (XSS) │ │ │ └─────────┬───────┘ └─────────┬───────┘ └─────────┬───────┘ │ │ │ ▼ ▼ ▼ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Exploitation │ │ Exploitation │ │ ... │ │ (Injection) │ │ (XSS) │ │ │ └─────────┬───────┘ └─────────┬───────┘ └─────────┬───────┘ │ │ │ └─────────┬─────────┴───────────────────┘ │ ▼ ┌──────────────────────┐ │ Reporting │ └──────────────────────┘

Architectural Overview

Shannon is engineered to emulate the methodology of a human penetration tester. It leverages Anthropic's Claude Agent SDK as its core reasoning engine, but its true strength lies in the sophisticated multi-agent architecture built around it. This architecture combines the deep context of white-box source code analysis with the real-world validation of black-box dynamic exploitation, managed by an orchestrator through four distinct phases to ensure a focus on minimal false positives and intelligent context management.

Phase 1: Reconnaissance

The first phase builds a comprehensive map of the application's attack surface. Shannon analyzes the source code and integrates with tools like Nmap and Subfinder to understand the tech stack and infrastructure. Simultaneously, it performs live application exploration via browser automation to correlate code-level insights with real-world behavior, producing a detailed map of all entry points, API endpoints, and authentication mechanisms for the next phase.

Phase 2: Vulnerability Analysis

To maximize efficiency, this phase operates in parallel. Using the reconnaissance data, specialized agents for each OWASP category hunt for potential flaws in parallel. For vulnerabilities like Injection and SSRF, agents perform a structured data flow analysis, tracing user input to dangerous sinks. This phase produces a key deliverable: a list of hypothesized exploitable paths that are passed on for validation.

Phase 3: Exploitation

Continuing the parallel workflow to maintain speed, this phase is dedicated entirely to turning hypotheses into proof. Dedicated exploit agents receive the hypothesized paths and attempt to execute real-world attacks using browser automation, command-line tools, and custom scripts. This phase enforces a strict "No Exploit, No Report" policy: if a hypothesis cannot be successfully exploited to demonstrate impact, it is discarded as a false positive.

Phase 4: Reporting

The final phase compiles all validated findings into a professional, actionable report. An agent consolidates the reconnaissance data and the successful exploit evidence, cleaning up any noise or hallucinated artifacts. Only verified vulnerabilities are included, complete with reproducible, copy-and-paste Proof-of-Concepts, delivering a final pentest-grade report focused exclusively on proven risks.

📋 Coverage and Roadmap

For detailed information about Shannon's security testing coverage and development roadmap, see our Coverage and Roadmap documentation.

⚠️ Disclaimers

Important Usage Guidelines & Disclaimers

Please review the following guidelines carefully before using Shannon (Lite). As a user, you are responsible for your actions and assume all liability.

1. Potential for Mutative Effects & Environment Selection

This is not a passive scanner. The exploitation agents are designed to actively execute attacks to confirm vulnerabilities. This process can have mutative effects on the target application and its data.

[!WARNING] ⚠️ DO NOT run Shannon on production environments.

2. Legal & Ethical Use

Shannon is designed for legitimate security auditing purposes only.

[!CAUTION] You must have explicit, written authorization from the owner of the target system before running Shannon.

Unauthorized scanning and exploitation of systems you do not own is illegal and can be prosecuted under laws such as the Computer Fraud and Abuse Act (CFAA). Keygraph is not responsible for any misuse of Shannon.

3. LLM & Automation Caveats

4. Scope of Analysis

5. Cost & Performance

6. Windows Antivirus False Positives

Windows Defender may flag files in xben-benchmark-results/ or deliverables/ as malware. These are false positives caused by exploit code in the reports. Add an exclusion for the Shannon directory in Windows Defender, or use Docker/WSL2.

📜 License

Shannon Lite is released under the GNU Affero General Public License v3.0 (AGPL-3.0).

Shannon is open source (AGPL v3). This license allows you to: - Use it freely for all internal security testing. - Modify the code privately for internal use without sharing your changes.

The AGPL's sharing requirements primarily apply to organizations offering Shannon as a public or managed service (such as a SaaS platform). In those specific cases, any modifications made to the core software must be open-sourced.

👥 Community & Support

Community Resources

Contributing: At this time, we’re not accepting external code contributions (PRs).
Issues are welcome for bug reports and feature requests.

Stay Connected

💬 Get in Touch

Interested in Shannon Pro?

Shannon Pro is designed for organizations serious about application security. It offers enterprise-grade features, dedicated support, and seamless CI/CD integration, all powered by our most advanced LLM-based analysis engine. Find and fix complex vulnerabilities deep in your codebase before they ever reach production.

For a detailed breakdown of features, technical differences, and enterprise use cases, see our complete comparison guide.

Express Interest

Or contact us directly:

📧 Email: shannon@keygraph.io

Built with ❤️ by the Keygraph team
Making application security accessible to everyone

File Structure

Unable to fetch file structure.

Back to Trending