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

docs: align README and docs with Shannon / Keygraph naming

Browse Source 
Replace the README with the marketing-reviewed version and bring the
project onto one consistent naming scheme:

- "Shannon Lite" -> "Shannon" (the open-source CLI is just Shannon)
- "Shannon Pro" -> "Keygraph" (the commercial platform)
- Rename docs/shannon-pro.md -> docs/keygraph-platform.md and fix the
  internal link, matching the README's link target.
- Regenerate llms.txt and llms-full.txt from the updated README and docs.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
george-keygraph
2026-06-19 13:58:36 -07:00
co-authored by Claude Opus 4.8
parent 82b5278541
commit 10b26355be
11 changed files with 220 additions and 226 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ai-providers.md
+4 -4
View File
@@ -1,6 +1,6 @@
# AI Providers
Shannon Lite works best with Claude models. Anthropic API keys are recommended for most users, and Shannon Lite also supports AWS Bedrock, Google Vertex AI, and custom Anthropic-compatible endpoints.
Shannon works best with Claude models. Anthropic API keys are recommended for most users, and Shannon also supports AWS Bedrock, Google Vertex AI, and custom Anthropic-compatible endpoints.
## Anthropic
@@ -51,7 +51,7 @@ ANTHROPIC_MEDIUM_MODEL=us.anthropic.claude-sonnet-4-6
ANTHROPIC_LARGE_MODEL=us.anthropic.claude-opus-4-8
```
Shannon Lite uses three model tiers:
Shannon uses three model tiers:
- **small** for summarization
- **medium** for security analysis
@@ -93,10 +93,10 @@ Set `CLOUD_ML_REGION=global` for global endpoints, or use a specific region like
## Custom Base URL
Shannon Lite supports pointing the SDK at an Anthropic-compatible endpoint with `ANTHROPIC_BASE_URL`. For proxy-based routing, use an LLM proxy such as LiteLLM configured to expose an Anthropic-compatible endpoint.
Shannon supports pointing the SDK at an Anthropic-compatible endpoint with `ANTHROPIC_BASE_URL`. For proxy-based routing, use an LLM proxy such as LiteLLM configured to expose an Anthropic-compatible endpoint.
> [!IMPORTANT]
> Only Claude models are officially supported. Shannon Lite's evaluations, internal testing, and agent harness are optimized for Claude. Smaller or alternative models, including non-Claude models routed through a proxy, may not reliably follow Shannon Lite's instructions or tool-use constraints. Use them at your own risk.
> Only Claude models are officially supported. Shannon's evaluations, internal testing, and agent harness are optimized for Claude. Smaller or alternative models, including non-Claude models routed through a proxy, may not reliably follow Shannon's instructions or tool-use constraints. Use them at your own risk.
The experimental `claude-code-router` integration is being removed. If you rely on it, migrate to an Anthropic-compatible proxy such as LiteLLM before upgrading.
docs/configuration.md
+2 -2
View File
@@ -1,6 +1,6 @@
# Configuration
Shannon Lite can run without a configuration file, but configuration enables authenticated testing, scope guidance, rules of engagement, report filtering, and rate-limit tuning.
Shannon can run without a configuration file, but configuration enables authenticated testing, scope guidance, rules of engagement, report filtering, and rate-limit tuning.
## Credential Precedence
@@ -119,7 +119,7 @@ Supported placeholders:
- `$email_password`
- `$email_totp`
At runtime, Shannon Lite replaces these placeholders with the credentials passed in the config.
At runtime, Shannon replaces these placeholders with the credentials passed in the config.
```yaml
login_flow:
docs/coverage-roadmap.md
+5 -5
View File
@@ -1,8 +1,8 @@
# Coverage and Roadmap
Shannon Lite focuses on exploitable findings that can be validated against a running application.
Shannon focuses on exploitable findings that can be validated against a running application.
## Current Shannon Lite Coverage
## Current Shannon Coverage
- Broken Authentication
- Broken Authorization
@@ -12,12 +12,12 @@ Shannon Lite focuses on exploitable findings that can be validated against a run
## Reporting Philosophy
Shannon Lite follows a proof-by-exploitation model. Findings that cannot be demonstrated with a working proof of concept are not included in the final report.
Shannon follows a proof-by-exploitation model. Findings that cannot be demonstrated with a working proof of concept are not included in the final report.
This reduces speculative noise, but it also means Shannon Lite does not aim to report every possible security issue in a repository. In particular, many dependency, policy, configuration, and broad static-analysis findings are outside the core Shannon Lite workflow.
This reduces speculative noise, but it also means Shannon does not aim to report every possible security issue in a repository. In particular, many dependency, policy, configuration, and broad static-analysis findings are outside the core Shannon workflow.
## Roadmap Direction
Planned coverage areas should continue to live in the repository's canonical roadmap document if one exists. The README should link to that document rather than carrying detailed roadmap history inline.
For organizations that need broader static and organizational coverage now, see [Shannon Pro](shannon-pro.md).
For organizations that need broader static and organizational coverage now, see [Keygraph](keygraph-platform.md).
docs/development.md
+4 -4
View File
@@ -11,10 +11,10 @@ This guide covers the source-build workflow, common CLI commands, repository pat
## Clone and Build
Use the source-build workflow if you want to run Shannon Lite from a local clone, modify the open-source CLI, or keep the worker image built locally.
Use the source-build workflow if you want to run Shannon from a local clone, modify the open-source CLI, or keep the worker image built locally.
```bash
# 1. Clone Shannon Lite.
# 1. Clone Shannon.
git clone https://github.com/KeygraphHQ/shannon.git
cd shannon
@@ -45,7 +45,7 @@ export CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000
## Prepare Your Repository
Shannon Lite can scan any repository on your machine. Pass an absolute or relative path with `-r`.
Shannon can scan any repository on your machine. Pass an absolute or relative path with `-r`.
```bash
npx @keygraph/shannon start -u https://example.com -r /path/to/repo
@@ -76,7 +76,7 @@ Open the Temporal Web UI for detailed monitoring:
open http://localhost:8233
```
Stop Shannon Lite:
Stop Shannon:
```bash
npx @keygraph/shannon stop
docs/shannon-pro.md → docs/keygraph-platform.md
+12 -12
View File
@@ -1,12 +1,12 @@
# Shannon Pro
# Keygraph
Shannon Pro is Keygraph's commercial continuous pentesting and AppSec platform for teams running security across many repositories, services, and environments. While Shannon Lite is a local white-box pentesting CLI, Shannon Pro is a full platform: it combines parsed-code SAST, source-to-sink analysis, black-box and white-box agentic pentesting, verified remediation, CI/CD gating, SLA tracking, and reporting for security and compliance teams.
Keygraph is the commercial continuous pentesting and AppSec platform for teams running security across many repositories, services, and environments. While Shannon is a local white-box pentesting CLI, Keygraph is a full platform: it combines parsed-code SAST, source-to-sink analysis, black-box and white-box agentic pentesting, verified remediation, CI/CD gating, SLA tracking, and reporting for security and compliance teams.
This repository contains Shannon Lite, the AGPL-3.0 open-source CLI for strictly white-box pentesting. Shannon Pro supports both white-box and black-box agentic pentesting and adds static analysis, finding management, remediation workflows, reporting, and enterprise deployment options.
This repository contains Shannon, the AGPL-3.0 open-source CLI for strictly white-box pentesting. Keygraph supports both white-box and black-box agentic pentesting and adds static analysis, finding management, remediation workflows, reporting, and enterprise deployment options.
## Who Should Consider Shannon Pro
## Who Should Consider Keygraph
Shannon Pro is intended for organizations that need:
Keygraph is intended for organizations that need:
- Continuous AppSec coverage across many repositories and services
- White-box pentesting when source code is available
@@ -21,7 +21,7 @@ Shannon Pro is intended for organizations that need:
## Full Vulnerability Lifecycle
Shannon Pro is designed to cover the full vulnerability lifecycle, not only discovery:
Keygraph is designed to cover the full vulnerability lifecycle, not only discovery:
1. **Find** exploitable issues with white-box pentesting, black-box pentesting, SAST, SCA, secrets, IaC, container, and business logic testing.
2. **Normalize** results into canonical findings so duplicate scanner outputs become one tracked vulnerability per repository.
@@ -34,9 +34,9 @@ Shannon Pro is designed to cover the full vulnerability lifecycle, not only disc
## Pentesting Modes
Shannon Lite is strictly white-box: it requires access to the target application's source code and repository layout.
Shannon is strictly white-box: it requires access to the target application's source code and repository layout.
Shannon Pro supports two pentesting modes:
Keygraph supports two pentesting modes:
- **White-box agentic pentesting**: Agents use source-code context to understand architecture, identify realistic attack paths, and validate exploitability against the running application.
- **Black-box agentic pentesting**: Agents test deployed applications and APIs without source-code access, useful for third-party surfaces, production-like external validation, or environments where source access is unavailable.
@@ -45,7 +45,7 @@ Both modes follow the same core principle: do not report what might be vulnerabl
## AppSec Coverage
Shannon Pro combines agentic pentesting with broader AppSec coverage:
Keygraph combines agentic pentesting with broader AppSec coverage:
- **Agentic SAST**: Code Property Graph analysis with LLM reasoning for data flow, context, and sanitization decisions.
- **SCA with reachability**: Dependency vulnerability analysis that prioritizes issues reachable from application entry points.
@@ -62,7 +62,7 @@ The result is a finding with proof of exploitability, source context when availa
## Enterprise Deployment
Shannon Pro supports enterprise deployment patterns for teams with strict data, model, and network requirements:
Keygraph supports enterprise deployment patterns for teams with strict data, model, and network requirements:
- **Self-hosted deployments** inside the customer's cloud or infrastructure
- **Air-gapped deployments** for isolated environments
@@ -75,7 +75,7 @@ Deployments can be designed so source code, scan results, prompts, completions,
## Capability Comparison
| Need | Shannon Lite | Shannon Pro |
| Need | Shannon | Keygraph |
| --- | --- | --- |
| Licensing | AGPL-3.0 | Commercial |
| White-box pentesting | Yes; source code required | Yes; source-aware testing with platform workflows |
@@ -91,4 +91,4 @@ Deployments can be designed so source code, scan results, prompts, completions,
## Contact
Learn more on the [Keygraph website](https://keygraph.io), start a free trial, book a [Shannon Pro demo](https://cal.com/team/keygraph/shannon-pro), or contact [shannon@keygraph.io](mailto:shannon@keygraph.io).
Learn more on the [Keygraph website](https://keygraph.io), start a free trial, book a [Keygraph demo](https://cal.com/team/keygraph/shannon-pro), or contact [shannon@keygraph.io](mailto:shannon@keygraph.io).
docs/platforms.md
+4 -4
View File
@@ -4,7 +4,7 @@ This guide covers platform-specific notes and Docker networking behavior.
## Windows
Shannon Lite on Windows is supported through WSL2. Native Windows, including Git Bash, is not supported.
Shannon on Windows is supported through WSL2. Native Windows, including Git Bash, is not supported.
### Ensure WSL2
@@ -25,7 +25,7 @@ wsl --set-version <distro-name> 2
Install Docker Desktop on Windows and enable the WSL2 backend under **Settings > General > Use the WSL 2 based engine**.
Run Shannon Lite inside WSL:
Run Shannon inside WSL:
```bash
npx @keygraph/shannon setup
@@ -43,7 +43,7 @@ cp .env.example .env
To access the Temporal Web UI, run `ip addr` inside WSL to find your WSL IP address, then navigate to `http://<wsl-ip>:8233` in your Windows browser.
Windows Defender may flag exploit code in reports as false positives. Add an exclusion for the Shannon Lite directory or use Docker/WSL2 isolation.
Windows Defender may flag exploit code in reports as false positives. Add an exclusion for the Shannon directory or use Docker/WSL2 isolation.
## Linux
@@ -69,7 +69,7 @@ Source-build equivalent:
## Custom Hostnames
If your local stack uses custom hostnames mapped in `/etc/hosts`, Shannon Lite forwards those entries into the worker container at scan start.
If your local stack uses custom hostnames mapped in `/etc/hosts`, Shannon forwards those entries into the worker container at scan start.
To disable forwarding:
docs/safety.md
+12 -12
View File
@@ -1,18 +1,18 @@
# Safety and Limitations
Read this before running Shannon Lite in a new environment.
Read this before running Shannon in a new environment.
## Authorized Use Only
Shannon Lite is designed for legitimate security auditing. You must have explicit written authorization from the owner of the target system before running Shannon Lite.
Shannon is designed for legitimate security auditing. You must have explicit written authorization from the owner of the target system before running Shannon.
Unauthorized scanning or exploitation of systems you do not own is illegal. Keygraph is not responsible for misuse of Shannon Lite.
Unauthorized scanning or exploitation of systems you do not own is illegal. Keygraph is not responsible for misuse of Shannon.
## Do Not Run on Production
Shannon Lite is not a passive scanner. Exploitation agents actively execute attacks to confirm vulnerabilities. This can mutate application state and data.
Shannon is not a passive scanner. Exploitation agents actively execute attacks to confirm vulnerabilities. This can mutate application state and data.
Do not run Shannon Lite against production systems. Use sandboxed, staging, or local development environments where data integrity is not a concern.
Do not run Shannon against production systems. Use sandboxed, staging, or local development environments where data integrity is not a concern.
Potential mutative effects include:
@@ -23,17 +23,17 @@ Potential mutative effects include:
- Generating unexpected outbound traffic
- Writing exploit artifacts to reports or deliverables
For maximum isolation, run Shannon Lite inside a disposable virtual machine.
For maximum isolation, run Shannon inside a disposable virtual machine.
## LLM and Automation Caveats
- **Verification is required**: Shannon Lite uses a proof-by-exploitation methodology, but final reports can still contain weakly supported or incorrect details. Human review is essential.
- **Model support**: Shannon Lite is officially supported only with Claude models. Alternative models may be incomplete, inaccurate, or unstable.
- **Prompt injection risk**: Do not point Shannon Lite at untrusted or adversarial codebases. AI-powered tools that read source code can be influenced by malicious repository content.
- **Verification is required**: Shannon uses a proof-by-exploitation methodology, but final reports can still contain weakly supported or incorrect details. Human review is essential.
- **Model support**: Shannon is officially supported only with Claude models. Alternative models may be incomplete, inaccurate, or unstable.
- **Prompt injection risk**: Do not point Shannon at untrusted or adversarial codebases. AI-powered tools that read source code can be influenced by malicious repository content.
## Scope of Analysis
Shannon Lite currently targets exploitable vulnerabilities in these classes:
Shannon currently targets exploitable vulnerabilities in these classes:
- Broken Authentication
- Broken Authorization
@@ -41,9 +41,9 @@ Shannon Lite currently targets exploitable vulnerabilities in these classes:
- Cross-Site Scripting
- Server-Side Request Forgery
Shannon Lite's proof-by-exploitation model means it does not report issues it cannot actively exploit, such as many vulnerable dependency, insecure configuration, or broad policy findings.
Shannon's proof-by-exploitation model means it does not report issues it cannot actively exploit, such as many vulnerable dependency, insecure configuration, or broad policy findings.
For broader coverage, Shannon Pro adds black-box and white-box agentic pentesting, graph-based static analysis, SCA reachability, secrets detection, business logic testing, remediation workflows, SLA tracking, and reporting dashboards.
For broader coverage, Keygraph adds black-box and white-box agentic pentesting, graph-based static analysis, SCA reachability, secrets detection, business logic testing, remediation workflows, SLA tracking, and reporting dashboards.
## Cost and Performance
docs/workspaces.md
+2 -2
View File
@@ -1,6 +1,6 @@
# Workspaces and Resuming
Shannon Lite uses workspaces to store scan state, logs, prompts, and deliverables. Workspaces allow interrupted or failed runs to resume without re-running completed agents.
Shannon uses workspaces to store scan state, logs, prompts, and deliverables. Workspaces allow interrupted or failed runs to resume without re-running completed agents.
## How Workspaces Work
@@ -13,7 +13,7 @@ Shannon Lite uses workspaces to store scan state, logs, prompts, and deliverable
- Each agent's progress is checkpointed so resumed runs can skip completed work.
> [!NOTE]
> The URL must match the original workspace URL when resuming. Shannon Lite rejects mismatched URLs to prevent cross-target contamination.
> The URL must match the original workspace URL when resuming. Shannon rejects mismatched URLs to prevent cross-target contamination.
## Examples