From 1aafc0c3d01fe2c9f565fd8df1fd1d42df5c70e2 Mon Sep 17 00:00:00 2001 From: keygraphVarun Date: Wed, 4 Mar 2026 13:08:18 -0800 Subject: [PATCH] Update README.md update readme --- README.md | 182 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 110 insertions(+), 72 deletions(-) diff --git a/README.md b/README.md index 21b2a0a..d784c23 100644 --- a/README.md +++ b/README.md @@ -1,82 +1,112 @@ -> [!NOTE] -> **[Shannon Lite achieves a 96.15% success rate on a hint-free, source-aware XBOW benchmark. →](https://github.com/KeygraphHQ/shannon/tree/main/xben-benchmark-results/README.md)** - -
+Shannon — AI Pentester for Web Applications and APIs + +# Shannon — AI Pentester by Keygraph + KeygraphHQ%2Fshannon | Trendshift -Shannon — AI Penetration Testing Framework - -# 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. +Shannon is an autonomous, white-box AI pentester for web applications and APIs.
+It analyzes your source code, identifies attack vectors, and executes real exploits to prove vulnerabilities before they reach production. --- -[Website](https://keygraph.io) • [Discord](https://discord.gg/KAqzSHHpRt) +[Keygraph Website](https://keygraph.io) • [Documentation](https://docs.keygraph.io) • [Discord](https://discord.gg/KAqzSHHpRt) ---
## 🎯 What is Shannon? -Shannon is an AI pentester that delivers actual exploits, not just alerts. +Shannon is an AI pentester developed by [Keygraph](https://keygraph.io). It performs white-box security testing of web applications and their underlying APIs by combining source code analysis with live exploitation. -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. +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 (injection attacks, authentication bypass, SSRF, XSS) against the running application and its APIs. Only vulnerabilities with a working proof-of-concept are included in the final report. -**What Problem Does Shannon Solve?** +**Why Shannon Exists** -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. +Most teams run penetration tests annually, but ship code continuously. Shannon closes that gap by providing on-demand, automated penetration testing that can run against every build or release. > [!NOTE] -> **From Autonomous Pentesting to Automated Compliance** +> **Shannon is part of the Keygraph Security and Compliance Platform** > -> Shannon is a core component of the **Keygraph Security and Compliance Platform**. +> Keygraph is an integrated security and compliance platform covering IAM, MDM, compliance automation (SOC 2, HIPAA), and application security. Shannon handles the AppSec layer. The broader platform automates evidence collection, audit readiness, and continuous compliance across multiple frameworks. > -> 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](https://keygraph.io)** +> **[Learn more at keygraph.io](https://keygraph.io)** -## 🎬 See Shannon in Action +## 🎬 Shannon in Action -**Real Results**: Shannon discovered 20+ critical vulnerabilities in OWASP Juice Shop, including complete auth bypass and database exfiltration. [See full report →](sample-reports/shannon-report-juice-shop.md) +Shannon identified 20+ vulnerabilities in OWASP Juice Shop, including authentication bypass and database exfiltration. [Full report →](sample-reports/shannon-report-juice-shop.md) ![Demo](assets/shannon-action.gif) ## ✨ Features -- **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. -- **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. -- **Critical OWASP Vulnerability Coverage**: Currently identifies and validates the following critical vulnerabilities: Injection, XSS, SSRF, and Broken Authentication/Authorization, with more types in development. -- **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. -- **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. -- **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. +- **Fully Autonomous Operation**: A single command launches the full pentest. Shannon handles 2FA/TOTP logins (including SSO), browser navigation, exploitation, and report generation without manual intervention. +- **Reproducible Proof-of-Concept Exploits**: The final report contains only proven, exploitable findings with copy-and-paste PoCs. Vulnerabilities that cannot be exploited are not reported. +- **OWASP Vulnerability Coverage**: Identifies and validates Injection, XSS, SSRF, and Broken Authentication/Authorization, with additional categories in development. +- **Code-Aware Dynamic Testing**: Analyzes source code to guide attack strategy, then validates findings with live browser and CLI-based exploits against the running application. +- **Integrated Security Tooling**: Leverages Nmap, Subfinder, WhatWeb, and Schemathesis during reconnaissance and discovery phases. +- **Parallel Processing**: Vulnerability analysis and exploitation phases run concurrently across all attack categories. ## 📦 Product Line -Shannon is available in two editions: +Shannon is developed by [Keygraph](https://keygraph.io) and 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 | +| **Shannon Lite** | AGPL-3.0 | Security teams, independent researchers, testing your own applications. | +| **Shannon Pro** | Commercial | Organizations needing a single AppSec platform (SAST, SCA, secrets, business logic testing, autonomous pentesting) with CI/CD integration and self-hosted deployment. | -> **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](https://arxiv.org/abs/2402.10754)) for enterprise-grade code analysis and deeper vulnerability detection. +> **This repository contains Shannon Lite,** the core autonomous AI pentesting framework. **Shannon Pro** is Keygraph's all-in-one AppSec platform, combining SAST, SCA, secrets scanning, business logic security testing, and autonomous AI pentesting in a single correlated workflow. Every finding is validated with a working proof-of-concept exploit. > [!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](./SHANNON-PRO.md) +### Shannon Pro: Architecture Overview + +Shannon Pro is an all-in-one application security platform that replaces the need to stitch together separate SAST, SCA, secrets scanning, and pentesting tools. It operates as a two-stage pipeline: agentic static analysis of the codebase, followed by autonomous AI penetration testing. Findings from both stages are cross-referenced and correlated, so every reported vulnerability has a working proof-of-concept exploit and a precise source code location. + +**Stage 1: Agentic Static Analysis** + +Shannon Pro transforms the codebase into a Code Property Graph (CPG) combining the AST, control flow graph, and program dependence graph. It then runs five analysis capabilities: + +- **Data Flow Analysis (SAST)**: Identifies sources (user input, API requests) and sinks (SQL queries, command execution), then traces paths between them. At each node, an LLM evaluates whether the specific sanitization applied is sufficient for the specific vulnerability in context, rather than relying on a hard-coded allowlist of safe functions. +- **Point Issue Detection (SAST)**: LLM-based detection of single-location vulnerabilities: weak cryptography, hardcoded credentials, insecure configuration, missing security headers, weak RNG, disabled certificate validation, and overly permissive CORS. +- **Business Logic Security Testing (SAST)**: LLM agents analyze the codebase to discover application-specific invariants (e.g., "document access must verify organizational ownership"), generate targeted fuzzers to violate those invariants, and synthesize full PoC exploits. This catches authorization failures and domain-specific logic errors that pattern-based scanners cannot detect. +- **SCA with Reachability Analysis**: Goes beyond flagging CVEs by tracing whether the vulnerable function is actually reachable from application entry points via the CPG. Unreachable vulnerabilities are deprioritized. +- **Secrets Detection**: Combines regex pattern matching with LLM-based detection (for dynamically constructed credentials, custom formats, obfuscated tokens) and performs liveness validation against the corresponding service using read-only API calls. + +**Stage 2: Autonomous Dynamic Penetration Testing** + +The same multi-agent pentest pipeline as Shannon Lite (reconnaissance, parallel vulnerability analysis, parallel exploitation, reporting), enhanced with static findings injected into the exploitation queue. Static findings are mapped to Shannon's five attack domains (Injection, XSS, SSRF, Auth, Authz), and exploit agents attempt real proof-of-concept attacks against the running application for each finding. + +**Static-Dynamic Correlation** + +This is the core differentiator. A data flow vulnerability identified in static analysis (e.g., unsanitized input reaching a SQL query) is not reported as a theoretical risk. It is fed to the corresponding exploit agent, which attempts to exploit it against the live application. A business logic invariant violation (e.g., missing cross-tenant authorization) is routed to the Authz agent for runtime confirmation. Confirmed exploits are traced back to the exact source code location, giving developers both proof of exploitability and the line of code to fix. + +**Deployment Model** + +Shannon Pro supports a self-hosted runner model (similar to GitHub Actions self-hosted runners). The data plane, which handles code access and all LLM API calls, runs entirely within the customer's infrastructure using the customer's own API keys. Source code never leaves the customer's network. The Keygraph control plane handles job orchestration, scan scheduling, and the reporting UI, receiving only aggregate findings. + +| Capability | Shannon Lite | Shannon Pro (All-in-One AppSec) | +| --- | --- | --- | +| **Licensing** | AGPL-3.0 | Commercial | +| **Static Analysis** | None | Full agentic SAST, SCA, secrets, business logic testing | +| **Dynamic Testing** | Autonomous AI pentesting | Autonomous AI pentesting with static-dynamic correlation | +| **Analysis Engine** | Code review prompting | CPG-based data flow with LLM reasoning at every node | +| **Business Logic** | None | Automated invariant discovery, fuzzer generation, exploit synthesis | +| **Correlation** | None | Cross-references static and dynamic findings | +| **CI/CD Integration** | Manual / CLI | Native CI/CD, GitHub PR scanning | +| **Deployment** | CLI | Managed cloud or self-hosted runner | +| **Boundary Analysis** | None | Automatic service boundary detection with team routing | + +[Full technical details →](./SHANNON-PRO.md) + ## 📑 Table of Contents - [What is Shannon?](#-what-is-shannon) -- [See Shannon in Action](#-see-shannon-in-action) +- [Shannon in Action](#-shannon-in-action) - [Features](#-features) - [Product Line](#-product-line) - [Setup & Usage Instructions](#-setup--usage-instructions) @@ -92,6 +122,7 @@ Shannon is available in two editions: - [[EXPERIMENTAL - UNSUPPORTED] Router Mode (Alternative Providers)](#experimental---unsupported-router-mode-alternative-providers) - [Output and Results](#output-and-results) - [Sample Reports](#-sample-reports) +- [Benchmark](#-benchmark) - [Architecture](#️-architecture) - [Coverage and Roadmap](#-coverage-and-roadmap) - [Disclaimers](#️-disclaimers) @@ -471,22 +502,20 @@ audit-logs/{hostname}_{sessionId}/ ## 📊 Sample Reports -> **Looking for quantitative benchmarks?** [See full benchmark methodology and results →](./xben-benchmark-results/README.md) - -See Shannon's capabilities in action with penetration test results from industry-standard vulnerable applications: +Sample penetration test reports from industry-standard vulnerable applications: #### 🧃 **OWASP Juice Shop** • [GitHub](https://github.com/juice-shop/juice-shop) *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. +**Results**: Identified over 20 vulnerabilities across targeted OWASP categories in a single automated run. -**Key Accomplishments**: +**Notable findings**: -- **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 +- Authentication bypass and full user database exfiltration via SQL injection +- Privilege escalation to administrator through registration workflow bypass +- IDOR vulnerabilities enabling access to other users' data and shopping carts +- SSRF enabling internal network reconnaissance 📄 **[View Complete Report →](sample-reports/shannon-report-juice-shop.md)** @@ -496,14 +525,14 @@ See Shannon's capabilities in action with penetration test results from industry *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. +**Results**: Identified approximately 15 critical and high-severity vulnerabilities. -**Key Accomplishments**: +**Notable findings**: -- **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 +- Root-level command injection via denylist bypass in a hidden debug endpoint +- Authentication bypass through a legacy, unpatched v1 API endpoint +- Privilege escalation via Mass Assignment in the user profile update function +- Zero false positives for XSS (correctly confirmed robust XSS defenses) 📄 **[View Complete Report →](sample-reports/shannon-report-capital-api.md)** @@ -513,26 +542,34 @@ See Shannon's capabilities in action with penetration test results from industry *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. +**Results**: Identified over 15 critical and high-severity vulnerabilities. -**Key Accomplishments**: +**Notable findings**: -- **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 +- Authentication bypass via multiple JWT attacks (Algorithm Confusion, alg:none, weak key injection) +- Full PostgreSQL database compromise via injection, exfiltrating user credentials +- SSRF attack forwarding internal authentication tokens to an external service +- Zero false positives for XSS (correctly identified robust XSS defenses) 📄 **[View Complete Report →](sample-reports/shannon-report-crapi.md)** --- -*These results demonstrate Shannon's ability to move beyond simple scanning, performing deep contextual exploitation with minimal false positives and actionable proof-of-concepts.* +*All reports contain reproducible proof-of-concept exploits for every finding.* + +--- + +## 📈 Benchmark + +Shannon Lite scored **96.15% (100/104 exploits)** on a hint-free, source-aware variant of the XBOW security benchmark. + +**[Full results with detailed agent logs and per-challenge pentest reports →](./xben-benchmark-results/README.md)** --- ## 🏗️ 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: +Shannon uses a multi-agent architecture that combines white-box source code analysis with dynamic exploitation across four phases: ``` ┌──────────────────────┐ @@ -564,7 +601,7 @@ Shannon emulates a human penetration tester's methodology using a sophisticated ### 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. +Shannon uses Anthropic's Claude Agent SDK as its reasoning engine within a multi-agent architecture. The system combines white-box source code analysis with black-box dynamic exploitation, managed by an orchestrator across four phases. The architecture is designed for minimal false positives through a "no exploit, no report" policy. --- @@ -653,12 +690,18 @@ The AGPL's sharing requirements primarily apply to organizations offering Shanno ### Community Resources -**Contributing:** At this time, we’re not accepting external code contributions (PRs). +📅 **1:1 Office Hours** — Thursdays, two time zones +Book a free 15-min session for hands-on help with bugs, deployments, or config questions. +→ US/EU: 10:00 AM PT | Asia: 2:00 PM IST +→ [Book a slot](https://cal.com/george-flores-keygraph/shannon-community-office-hours) + +💬 [Join our Discord](https://discord.gg/cmctpMBXwE) to ask questions, share feedback, and connect with other Shannon users. + +**Contributing:** At this time, we're not accepting external code contributions (PRs). Issues are welcome for bug reports and feature requests. - 🐛 **Report bugs** via [GitHub Issues](https://github.com/KeygraphHQ/shannon/issues) - 💡 **Suggest features** in [Discussions](https://github.com/KeygraphHQ/shannon/discussions) -- 💬 **Join our [Discord](https://discord.gg/KAqzSHHpRt)** for real-time community support ### Stay Connected @@ -670,25 +713,20 @@ Issues are welcome for bug reports and feature requests. ## 💬 Get in Touch -### Interested in Shannon Pro? +### 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](./SHANNON-PRO.md). +Shannon Pro is Keygraph's all-in-one AppSec platform. For organizations that need unified SAST, SCA, and autonomous pentesting with static-dynamic correlation, CI/CD integration, or self-hosted deployment, see the [Shannon Pro technical overview](./SHANNON-PRO.md).

- Express Interest + Shannon Pro Inquiry

-**Or contact us directly:** - 📧 **Email**: [shannon@keygraph.io](mailto:shannon@keygraph.io) ---

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