shannon - Shannon is an AI pentester for web applications an

项目说明

> [!NOTE]
> Shannon 3.0 is live: deeper security 代码 analysis, more thoroughly findings, a rebuilt CLI, native CI/CD, professional PDF reports, and SARIF.

<di="center">

<picture>
<源码 media="(prefers-color-scheme: dark)" srcset="./assets/github-banner-dark.png">
<源码 media="(prefers-color-scheme: light)" srcset="./assets/github-banner-light.png">
<img src="./assets/github-banner-light.png" alt="Shannon, AI Pentester for Web Apps and APIs, by Keygraph" width="100%">
</picture>

<a href=" target="_blank"><img src=" alt="KeygraphHQ%2Fshannon | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>

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

It analyzes your 源码 代码, identifies attack paths, and executes real exploits to pro before they reach production. No exploit, no report.

This repository is Shannon Open 源码: the full agent, run locally from your command line.

<p><strong>Launch Shannon</strong></p>

_{The interacti will guide you through setup and your first pentest.}

---

<a href=" media="(prefers-color-scheme: dark)" srcset="./assets/discord_button_dark.png"><源码 media="(prefers-color-scheme: light)" srcset="./assets/discord_button_light.png"><img src="./assets/discord_button_light.png" height="40" alt="Join Discord"></picture></a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href=" media="(prefers-color-scheme: dark)" srcset="./assets/keygraph_button_dark.png"><源码 media="(prefers-color-scheme: light)" srcset="./assets/keygraph_button_light.png"><img src="./assets/keygraph_button_light.png" height="40" alt="Visit Keygraph.io"></picture></a>

---

</div>

> [!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 pro does Shannon support?
- Can I run Shannon on a local or self-hosted model?
- Does Shannon actually exploit , or just scan?

What is Shannon?

Shannon is an autonomous AI pentester de by Keygraph. It performs security testing of web applications and their underlying APIs by combining 源码-代码 analysis with li.

Shannon analyzes your web application's 源码 代码 to identify potential attack , then uses browser automation and command-line tools to execute real exploits against the running application and its APIs. Only with a working proof-of-concept are included in the final report.

Shannon is the agent. This repository is Shannon Open 源码, the standalone pentester you run yourself. The same Shannon also powers the Keygraph platform, Keygraph's commercial pentesting product. See Editions for how the two compare.

<a id="why-shannon-exists"></a>
<details>
<summary><strong>Why Shannon Exists</strong></summary>

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

Shannon closes that gap by pro on-demand, automated penetration testing that can run against every build or release.

</details>

<a id="why-shannon"></a>
<details>
<summary><strong>Why "Shannon"?</strong></summary>

It's named after Claude Shannon, the father of information theory. At its core, pentesting is an information problem: every probe reduces uncertainty about a system's state. The best tools maximize the signal gained from every request, turning those bits of knowledge into an exploit path.

Also, we wanted you to be able to say, "Hey Claude, run Shannon" to find all the security flaws in your app.

</details>

<a id="not-a-replacement-for-human-pentesters"></a>
<details>
<summary><strong>Not a replacement for human pentesters</strong></summary>

Shannon is built to work alongside expert pentesters and red teamers, not replace them. Great pentesters understand the business, chain attacks in ways nobody anticipated, and bring years of judgment that current models can't match.

Shannon solves a different problem: there is far more software to test than security teams have time to cover. Critical systems get periodic expert assessments, while the long tail of internal apps, APIs, and fast-moving services rarely gets tested at all.

Shannon shifts pentesting left into the software de lifecycle (SDLC). Use it to run exploitation-backed tests against staging en and releases at the cadence they actually ship, and sa human time for the risks that need someone who knows the organization.

</details>

Shannon in Action

!Shannon running an autonomous pentest

These reports are from Shannon Open 源码 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 and e 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 ne your model traffic. Shannon is pro. See AI pro 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 pro.

Run Shannon

> [!WARNING]
> Shannon actively executes exploits. Run it only against applications and en you own or ha written authorization to test. Do not run Shannon against production systems.

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 源码 builds, authenticated scans, pro setup, and platform notes, see Documentation.

> [!TIP]
> Prefer to use a subscription instead of API credits?
>
> - OpenAI Codex: The latest of Shannon supports ChatGPT Plus and Pro subscriptions. Follow the OpenAI Codex subscription setup guide to get started.
> - xAI (Grok): The latest of Shannon supports xAI subscriptions. Follow the xAI subscription setup guide to get started.
> - Claude Code: The latest of Shannon does not support Claude 代码 subscriptions. Follow the Claude 代码 subscription setup guide to use 1.9.0, which is the final release built on the Claude Agent SDK.

Key Capabilities

No exploit, no report: Reports only confirmed with a reproducible proof of concept, reducing speculati noise.

Ad code analysis: Maps architecture, trust boundaries, interfaces, data flows, and critical assets before sending credible attack paths to li agents.

Autonomous execution: Runs reconnaissance, analysis, exploitation, and reporting from a single command.

Li 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 co: 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, preser, publishes findings, and gates releases on pro.

Multi-format reports: Produces e 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 ser 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 en.

CI/CD Integrations

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

Both integrations:

analyze the checked-out 源码 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 at or above a configured se threshold.

A 代码-analysis hypothesis does not fail the pipeline. Se gates count only findings with status: exploited.

GitHub Actions

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 代码 scanning.

Requirements:

a private repository;

a runner with Docker and Docker Compose v2;

access to the running staging or de target; and

a model-provider credential stored as a GitHub Actions secret.

See the Shannon GitHub Action documentation and GitHub Marketplace listing.

Editions

Shannon Open Source is a complete autonomous pentester, especially well suited to indi de and small teams running focused security tests locally or in CI/CD.

Keygraph Enterprise Platform is for organizations that need a shared platform for continuous agentic pentesting/AppSec across many teams, repositories, and en. It centralizes deeper analysis, management, remediation, , go, and reporting so teams do not have to assemble and maintain those workflows themselves.

Learn about the Keygraph Enterprise Platform and compare editions →

Architecture

Shannon combines multi-stage security 代码 analysis with li and exploitation:

Stage by stage:

1. Recon and analysis explores the running application, ties runtime behavior back to the 源码, 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 in against them.
3. Finding reconciliation merges both streams of candidates, deduplicates the o, and groups what remains into an exploitation queue.
4. Exploitation agents attempt real proof-of-concept attacks against the running application.
5. throws out every candidate Shannon can't demonstrate.
6. Reporting produces PDF and Markdown reports with the e attached, plus structured JSON and SARIF for downstream systems.

Only li become Shannon pentest findings or count toward CI/CD se gates.

Each scan runs in an ephemeral Docker container with an isolated workspace and per-in 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 de. |
| Configuration | Authenticated testing, login flows, rules of engagement, and report filters. |
| AI pro | Selecting the model, the supported pro (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, mutati, cost, and model caveats. |
| Co and roadmap | Current co and planned work. |
| Keygraph Enterprise Platform | Exhausti SAST, continuous pentesting, full-lifecycle finding management, remediation, targeted , enterprise go, and on-premises deployment. |

Safety, Scope, and Limitations

Shannon is not a passi. 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 de en 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 ha authorization to test.

Important limitations:

Shannon Open 源码 is tuned for fast, 代码-informed pentesting in e de and CI/CD. Exhausti SAST, broader scanner co, centralized go, and full-lifecycle management are delivered through the Keygraph Enterprise Platform.

Findings still require human review. LLM-generated reports can contain weakly supported or incorrect details.

Anthropic, OpenAI, xAI, and AWS Bedrock are built-in pro, 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 , and a model that does not follow Shannon's instructions or 工具-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 ad codebases. AI-powered tools that read 源码 代码 can be exposed to prompt injection.

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

License

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

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

For commercial licensing, contact .

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 the Keygraph platform, the commercial agentic pentesting product that closes the full AppSec lifecycle and runs an enhanced build of Shannon as its pentesting 引擎.

Community and Support

Community office hours are a 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

Join Discord to ask questions, share feedback, and connect with other Shannon users.

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

Report bugs

Suggest features

Stay connected:

Keygraph website

Twitter/X:

LinkedIn: Keygraph

Common Questions

Can I self-host Shannon?

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

Keygraph ne your 源码 代码 and ne your model traffic. Your model requests go straight to the provider or endpoint you configure, and they carry 源码 and application context with them. Point Shannon at a locally hosted endpoint and that traffic stays inside your en too.

Does Shannon support bring your own key (BYOK)?

Yes, always. You provide the LLM credentials Shannon uses to run a pentest, in every deployment, open 源码 and commercial. Keygraph ne your model traffic.

Does Shannon output SARIF?

Yes. Shannon emits SARIF 2.1.0, the OASIS standard format for static analysis results, alongside structured JSON. Any SARIF consumer reads it: 代码 scanning services, management platforms, security dashboards, and CI/CD pipelines. It is written by default on exploit-mode scans; set report.sarif to "false" in your configuration file to opt out.

Which AI pro does Shannon support?

Anthropic, OpenAI, xAI, and AWS Bedrock are built in and configured directly by provider ID. Beyond those, Shannon runs on any provider in the Pi harness catalogue, named the same <provider>:<model-id> way. Any provider can be pointed at a proxy or LLM gateway through a custom base URL, which o only the endpoint and keeps that provider's API dialect. A model the catalogue does not carry, such as one a router or gateway ser its own ID, or a self-hosted model, is described in a custom model configuration file and passed with --models-config. Shannon uses a single unified model setting throughout a pentest.

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

Shannon works with local models ser 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 , and a model that does not follow Shannon's instructions or 工具-use constraints reliably will produce weaker pentests than a frontier model, so take this path only if you know how your chosen model behaves. See Local and self-hosted models.

Does Shannon actually exploit , or just scan?

Shannon executes real exploits. It reports a finding only when it has produced a working proof-of-concept, and discards hypotheses it cannot prove. It is a pentester, not a passi.

Built by Keygraph

项目信息

开发语言：TypeScript

Star 数：48582

技术要点

该项目属于黑客技术方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Shannon is an AI pentester for web applications and APIs. It analyzes your 源码 代码, identifies attack , and executes real exploits to pro before they reach production.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。