CalvinBackup/shannon
1
0
Fork 0
mirror of https://github.com/KeygraphHQ/shannon.git synced 2026-08-24 20:22:44 +02:00
Code Issues Packages Projects Releases Wiki Activity

README update

Browse Source 
Documentation pass over the README and supporting docs, incorporating the
Aug 19 review with Parathan.

README:
- Dark/light banner and Discord/Keygraph buttons via <picture>
- Add a Common Questions section at the bottom of the page
- State one consistent position on model support and provider breadth
- Name the OpenAI Responses API alongside Chat Completions
- Frame local and self-hosted models as technically supported but not
  recommended, since capability varies once the harness opens every
  provider and model
- Describe SARIF as machine-readable output rather than a CI feature

Docs:
- ai-providers: drop the Claude-preference claim; explain that capability
  varies and the model should be evaluated against your own targets
- configuration: correct rating semantics stale since v2.2.0, since
  severity is now recorded in both exploitative and analysis-only runs
- safety: reframe the model-support caveat in the same terms
- worker: correct the stale rationale on the SARIF analysis-mode gate

CI/CD documentation is intentionally omitted until the GitHub Marketplace
action lands, so the README does not ship a hand-rolled npx wrapper that
is about to be replaced.

llms.txt and llms-full.txt regenerated from source, with one deliberate
exception: the "Is Shannon free?" and "Is Shannon free for startups and
nonprofits?" questions are kept in the llms-full.txt copy of the README
but not in the README itself. That section exists for agents, so a naive
regeneration of llms-full.txt would drop them; re-add them if you rebuild
the file from source.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
George Flores
2026-08-19 18:26:34 -07:00
co-authored by Claude Opus 5
parent 12d1c48a78
commit af1ed2a563
16 changed files with 157 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+39 -7
View File
@@ -3,23 +3,26 @@
<div align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="./assets/github-banner-dark.png">
<source media="(prefers-color-scheme: light)" srcset="./assets/github-banner-light.png">
<img src="./assets/github-banner.png" alt="Shannon - AI Pentester by Keygraph" width="100%">
# Shannon - AI Pentester by Keygraph
</picture>
<a href="https://trendshift.io/repositories/15604" target="_blank"><img src="https://trendshift.io/api/badge/repositories/15604" 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. <br />
### 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.
**This repository is Shannon Open Source: the full agent, run locally from your command line.**
---
<a href="https://discord.gg/9ZqQPuhJB7"><img src="./assets/discord.png" height="40" alt="Join Discord"></a>
<a href="https://keygraph.io/"><img src="./assets/Keygraph_Button.png" height="40" alt="Visit Keygraph.io"></a>
<a href="https://discord.gg/9ZqQPuhJB7"><picture><source media="(prefers-color-scheme: dark)" srcset="./assets/discord_button_dark.png"><source 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="https://keygraph.io/"><picture><source media="(prefers-color-scheme: dark)" srcset="./assets/keygraph_button_dark.png"><source 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]
@@ -38,6 +41,7 @@ It analyzes your source code, identifies attack paths, and executes real exploit
- [License](#license)
- [About Keygraph](#about-keygraph)
- [Community and Support](#community-and-support)
- [Common Questions](#common-questions)
## What is Shannon?
@@ -73,7 +77,7 @@ Sample penetration test reports from intentionally vulnerable applications, prod
- **Docker**: required for the worker container.
- **Node.js 18+**: required for the recommended `npx` workflow.
- **AI provider credentials**: Anthropic, OpenAI, xAI, or AWS Bedrock - or [any other provider](docs/ai-providers.md#any-other-provider). Claude models are recommended. For suggested model IDs per provider, plus gateways and custom base URLs, see [AI providers](docs/ai-providers.md#suggested-models).
- **AI provider credentials**: Shannon runs on Anthropic, OpenAI, xAI, AWS Bedrock, [any other provider](docs/ai-providers.md#any-other-provider) in the harness catalogue, and any endpoint that speaks the Anthropic Messages API or the OpenAI Chat Completions or Responses API through a [custom base URL](docs/ai-providers.md#custom-base-url). You bring your own key, and Keygraph never proxies your model traffic. Shannon is provider-agnostic. See [AI providers](docs/ai-providers.md#suggested-models) 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 providers](docs/ai-providers.md#cyber-safeguards-do-this-before-your-first-scan).
### Run Shannon
@@ -107,6 +111,8 @@ For source builds, authenticated scans, provider-specific setup, and platform no
- **Authenticated testing**: configuration files can describe login flows, test credentials, TOTP, email-based login flows, focus areas, and rules of engagement.
- **OWASP-focused coverage**: Shannon targets exploitable Injection, XSS, SSRF, Broken Authentication, and Broken Authorization issues.
- **Resumable workspaces**: Shannon can resume interrupted runs without re-running completed agents.
- **Machine-readable output**: Shannon emits findings as structured JSON, and as SARIF 2.1.0 when you enable it in configuration. SARIF is the OASIS standard for static analysis results, so findings flow into any code scanning service, vulnerability management platform, security dashboard, or CI/CD pipeline that reads it.
- **Bring your own key, provider-agnostic**: Shannon runs on Anthropic, OpenAI, xAI, AWS Bedrock, and any endpoint speaking the Anthropic Messages API or the OpenAI Chat Completions or Responses API, including self-hosted models served through Ollama, vLLM, or LM Studio and gateways such as OpenRouter and LiteLLM. You supply the credentials, so source code and model traffic stay inside your infrastructure. Local and self-hosted models are technically supported but not recommended: they may not follow Shannon's instructions or tool-use constraints as reliably as frontier models, so take that path only if you know how your chosen model behaves.
## Editions
@@ -210,7 +216,7 @@ Important limitations:
- Shannon Open Source focuses on actively exploitable issues such as Injection, XSS, SSRF, Broken Authentication, and Broken Authorization. Broader static-analysis coverage, including vulnerable dependencies and insecure configurations, is delivered through the Keygraph platform.
- Findings still require human review. LLM-generated reports can contain weakly supported or incorrect details.
- Shannon is officially supported with Claude models. Smaller, alternative, or proxied non-Claude models may be incomplete or unstable.
- Anthropic, OpenAI, xAI, and AWS Bedrock are built-in providers, and any Anthropic Messages API or OpenAI Chat Completions or Responses API endpoint works through a custom base URL. Model capability varies, and a model that does not follow Shannon's instructions or tool-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 adversarial codebases. AI-powered tools that read source code can be exposed to prompt injection.
@@ -249,6 +255,32 @@ Stay connected:
- [Twitter/X: @KeygraphHQ](https://twitter.com/KeygraphHQ)
- [LinkedIn: Keygraph](https://linkedin.com/company/keygraph)
## Common Questions
### Can I self-host Shannon?
Yes. Shannon Open Source runs entirely on your own infrastructure in an ephemeral Docker container. Your source code is mounted read-only and never leaves your environment.
### 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 source and commercial. Keygraph never proxies 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: code scanning services, vulnerability management platforms, security dashboards, and CI/CD pipelines. Set `report.sarif` to `"true"` in your configuration file to enable the SARIF log.
### Which AI providers does Shannon support?
Anthropic, OpenAI, xAI, and AWS Bedrock are built in and configured directly by provider ID. Beyond those, Shannon runs on any endpoint that implements the Anthropic Messages API or the OpenAI Chat Completions or Responses API, reached through a custom base URL. The rule is the API format, not the vendor. Shannon uses a single unified model setting throughout a pentest.
### Can I run Shannon on a local or self-hosted model?
Technically yes, but it is not recommended. 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 gateways such as LiteLLM. Point Shannon at the endpoint 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 if you know how your chosen model behaves. See [AI providers](docs/ai-providers.md#custom-base-url).
### Does Shannon actually exploit vulnerabilities, 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 scanner.
<p align="center">
<b>Built by <a href="https://keygraph.io">Keygraph</a></b>
</p>