CalvinBackup/shannon
1
0
Fork 0
mirror of https://github.com/KeygraphHQ/shannon.git synced 2026-07-25 05:50:52 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/main' into feat/pi-harness-migration

Browse Source 
# Conflicts:
#	CLAUDE.md
#	README.md
#	apps/cli/src/commands/start.ts
#	apps/cli/src/commands/uninstall.ts
#	apps/worker/src/services/agent-execution.ts
#	apps/worker/src/services/preflight.ts
#	apps/worker/src/session-manager.ts
#	apps/worker/src/temporal/activities.ts
#	apps/worker/src/temporal/shared.ts
#	apps/worker/src/temporal/workflows.ts
#	docs/ai-providers.md
#	llms-full.txt
This commit is contained in:
ezl-keygraph
2026-07-16 18:58:18 +05:30
parent d0b0ec3378 00e56455df
commit 934a0ddd79
22 changed files with 246 additions and 288 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 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 and custom Anthropic-compatible endpoints.
## Anthropic
@@ -50,7 +50,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
@@ -60,10 +60,10 @@ Set `ANTHROPIC_SMALL_MODEL`, `ANTHROPIC_MEDIUM_MODEL`, and `ANTHROPIC_LARGE_MODE
## 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 has been removed. If you previously relied on it, migrate to an Anthropic-compatible proxy such as LiteLLM.
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 [the Keygraph platform](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
@@ -43,7 +43,7 @@ export ANTHROPIC_API_KEY="your-api-key"
## 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 Platform
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.
The Keygraph platform is Keygraph's 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, the Keygraph platform is a complete AppSec system: 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. The Keygraph platform 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 the Keygraph Platform
Shannon Pro is intended for organizations that need:
The Keygraph platform 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:
The Keygraph platform 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:
The Keygraph platform 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:
The Keygraph platform 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:
The Keygraph platform 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 platform |
| --- | --- | --- |
| 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, the Keygraph platform 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
@@ -14,7 +14,7 @@ Shannon Lite uses workspaces to store scan state, logs, prompts, and deliverable
- The final report is surfaced at the workspace root as `Security-Assessment-Report.md`. Run internals — deliverables, logs, prompts, and session state — live under a hidden `.shannon/` directory.
> [!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