KeygraphHQ/shannon: Trending on GitHub

KeygraphHQ/shannon: Trending on GitHub

Shannon: The AI-Powered Penetration Tester

In the world of cybersecurity, penetration testing is a crucial step in identifying vulnerabilities in applications and systems. However, traditional penetration testing methods can be time-consuming, expensive, and often rely on human intuition. Enter Shannon, an AI-powered penetration tester that's taking the industry by storm.

What is Shannon?

Shannon is a fully autonomous AI pentester that delivers actual exploits, not just alerts. Its goal is to break your web app before someone else does. With Shannon, you can run a penetration test with a single command, and the AI will handle everything from advanced 2FA/TOTP logins to browser navigation and final report generation with zero intervention.

What Problem Does Shannon Solve?

Traditional penetration testing methods often rely on human intuition and can be time-consuming and expensive. 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.

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.

Key Features

1. Fully Autonomous Operation: Launch the pentest with a single command. The AI handles everything from advanced 2FA/TOTP logins (including sign in with Google) and browser navigation to the final report with zero intervention.
2. Pentester-Grade Reports with Reproducible Exploits: Delivers a final report focused on proven, exploitable findings, complete with copy-and-paste Proof-of-Concepts to eliminate false positives and provide actionable results.
3. Critical OWASP Vulnerability Coverage: Currently identifies and validates the following critical vulnerabilities: Injection, XSS, SSRF, and Broken Authentication/Authorization, with more types in development.
4. Code-Aware Dynamic Testing: Analyzes your source code to intelligently guide its attack strategy, then performs live, browser and command line based exploits on the running application to confirm real-world risk.
5. Powered by Integrated Security Tools: Enhances its discovery phase by leveraging leading reconnaissance and testing tools—including Nmap, Subfinder, WhatWeb, and Schemathesis—for deep analysis of the target environment.
6. Parallel Processing for Faster Results: Get your report faster. The system parallelizes the most time-intensive phases, running analysis and exploitation for all vulnerability types concurrently.

Product Line

Shannon is available in two editions:

1. Shannon Lite: AGPL-3.0, Security teams, independent researchers, testing your own applications
2. Shannon Pro: Commercial, Enterprises requiring advanced features, CI/CD integration, and dedicated support

Setup & Usage Instructions

1. Prerequisites: Docker - Container runtime (Install Docker), AI Provider Credentials (choose one): Anthropic API key (recommended) - Get from Anthropic Console, Claude Code OAuth token, [EXPERIMENTAL - UNSUPPORTED] Alternative providers via Router Mode - OpenAI or Google Gemini via OpenRouter (see Router Mode)
2. Quick Start: # 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 # 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=/path/to/your/repo

Monitoring Progress

1. View real-time worker logs: ./shannon logs
2. Query a specific workflow's progress: ./shannon query ID=shannon-1234567890
3. Open the Temporal Web UI for detailed monitoring: open http://localhost:8233

Stopping Shannon

1. Stop all containers (preserves workflow data): ./shannon stop
2. Full cleanup (removes all data): ./shannon stop CLEAN=true

Usage Examples

1. Basic pentest: ./shannon start URL=https://example.com REPO=/path/to/repo
2. With a configuration file: ./shannon start URL=https://example.com REPO=/path/to/repo CONFIG=./configs/my-config.yaml
3. Custom output directory: ./shannon start URL=https://example.com REPO=/path/to/repo OUTPUT=./my-reports

Prepare Your Repository

Shannon is designed for web application security testing and expects all application code to be available in a single directory structure. This works well for:

1. Monorepos: Single repository containing all components
2. Consolidated setups: Multiple repositories organized in a shared folder

For monorepos:

1. git clone https://github.com/your-org/your-monorepo.git /path/to/your-app

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

1. mkdir /path/to/your-app
2. cd /path/to/your-app
3. git clone https://github.com/your-org/frontend.git
4. git clone https://github.com/your-org/backend.git
5. git clone https://github.com/your-org/api.git

Platform-Specific Instructions

1. 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.
2. For macOS: Works out of the box with Docker Desktop installed.
3. Testing Local Applications: Docker containers cannot reach localhost on your host machine. Use host.docker.internal in place of localhost: ./shannon start URL=http://host.docker.internal:3000 REPO=/path/to/repo

Configuration (Optional)

While you can run without a config file, creating one enables authenticated testing and customized analysis.

1. Create Configuration File: Copy and modify the example configuration: cp configs/example-config.yaml configs/my-app-config.yaml
2. Basic Configuration Structure: authentication: login_type: form login_url: "https://your-app.com/login" credentials: username: "[email protected]" 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"

[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:

1. Model experimentation: try Shannon with GPT-5.2 or Gemini 3–family models
2. Quick Setup: Add your provider API key to .env: # 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 Run with ROUTER=true: ./shannon start URL=https://example.com REPO=/path/to/repo ROUTER=true

Experimental Models

1. Provider: OpenAI
2. Models: gpt-5.2, gpt-5-mini
3. 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 to specify a custom directory.

Output structure

1. audit-logs/{hostname}_{sessionId}/
2. ├── session.json: Metrics and session data
3. ├── agents/: Per-agent execution logs
4. ├── prompts/: Prompt snapshots for reproducibility
5. └── deliverables/
6. ** └── 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:

1. OWASP Juice Shop: GitHub
2. A notoriously insecure web application maintained by OWASP, designed to test a tool's ability to uncover a wide range of modern vulnerabilities.
3. Performance: Identified over 20 high-impact vulnerabilities across targeted OWASP categories in a single automated run.**
4. Key Accomplishments: Achieved complete authentication bypass and exfiltrated the entire user database via Injection attack Executed a full privilege escalation by creating a new administrator account through a registration workflow bypass Identified and exploited systemic authorization flaws (IDOR) to access and modify any user's private data and shopping cart Discovered a Server-Side Request Forgery (SSRF) vulnerability, enabling internal network reconnaissance**

c{api}tal API: GitHub

1. An intentionally vulnerable API from Checkmarx, designed to test a tool's ability to uncover the OWASP API Security Top 10.
2. Performance: Identified nearly 15 critical and high-severity vulnerabilities, leading to full application compromise.**
3. Key Accomplishments: Executed a root-level Injection attack by bypassing a denylist via command chaining in a hidden debug endpoint Achieved complete authentication bypass by discovering and targeting a legacy, unpatched v1 API endpoint Escalated a regular user to full administrator privileges by exploiting a Mass Assignment vulnerability in the user profile update function Demonstrated high accuracy by correctly confirming the application's robust XSS defenses, reporting zero false positives**

OWASP crAPI: GitHub

1. A modern, intentionally vulnerable API from OWASP, designed to benchmark a tool's effectiveness against the OWASP API Security Top 10.
2. Performance: Identified over 15 critical and high-severity vulnerabilities, achieving full application compromise.**
3. Key Accomplishments: Bypassed authentication using multiple advanced JWT attacks, including Algorithm Confusion, alg:none, and weak key (kid) injection Achieved full database compromise via Injection attacks, exfiltrating user credentials from the PostgreSQL database Executed a critical Server-Side Request Forgery (SSRF) attack that successfully forwarded internal authentication tokens to an external service Demonstrated high accuracy by correctly identifying the application's robust XSS defenses, reporting zero false positives**

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:

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

Source: https://github.com/KeygraphHQ/shannon