mirror of
https://github.com/KeygraphHQ/shannon.git
synced 2026-06-30 10:35:36 +02:00
Compare commits
10 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
| 5a2f78c5d9 | |||
| 7abcc1d3e1 | |||
| 4be4853fd3 | |||
| cb6cbf101d | |||
| 63ca5604a1 | |||
| 8fb62a59d6 | |||
| c259a34ed9 | |||
| 10b26355be | |||
| 82b5278541 | |||
| 8b956c9972 |
@@ -30,15 +30,17 @@ jobs:
|
|||||||
run: |
|
run: |
|
||||||
set -euo pipefail
|
set -euo pipefail
|
||||||
|
|
||||||
|
BASE="2.0.0"
|
||||||
LATEST=$(npm view "@keygraph/shannon" dist-tags.beta 2>/dev/null || echo "")
|
LATEST=$(npm view "@keygraph/shannon" dist-tags.beta 2>/dev/null || echo "")
|
||||||
|
|
||||||
if [[ -z "$LATEST" ]]; then
|
if [[ "$LATEST" == "$BASE-beta."* ]]; then
|
||||||
echo "version=1.0.0-beta.1" >> "$GITHUB_OUTPUT"
|
# Same base version — increment the beta counter (e.g. 2.0.0-beta.2 -> 2.0.0-beta.3)
|
||||||
else
|
|
||||||
# Extract N from 1.0.0-beta.N and increment
|
|
||||||
N=$(echo "$LATEST" | grep -oE 'beta\.([0-9]+)' | grep -oE '[0-9]+')
|
N=$(echo "$LATEST" | grep -oE 'beta\.([0-9]+)' | grep -oE '[0-9]+')
|
||||||
NEXT=$((N + 1))
|
NEXT=$((N + 1))
|
||||||
echo "version=1.0.0-beta.$NEXT" >> "$GITHUB_OUTPUT"
|
echo "version=$BASE-beta.$NEXT" >> "$GITHUB_OUTPUT"
|
||||||
|
else
|
||||||
|
# No prior beta, or a different base (e.g. last beta was 1.0.0-beta.N) — start over.
|
||||||
|
echo "version=$BASE-beta.1" >> "$GITHUB_OUTPUT"
|
||||||
fi
|
fi
|
||||||
|
|
||||||
- name: Print version
|
- name: Print version
|
||||||
|
|||||||
@@ -4,7 +4,7 @@ on:
|
|||||||
workflow_dispatch:
|
workflow_dispatch:
|
||||||
inputs:
|
inputs:
|
||||||
version:
|
version:
|
||||||
description: "Beta version to roll back to (example: 1.0.0-beta.2)"
|
description: "Beta version to roll back to (example: 2.0.0-beta.2)"
|
||||||
required: true
|
required: true
|
||||||
type: string
|
type: string
|
||||||
|
|
||||||
@@ -31,7 +31,7 @@ jobs:
|
|||||||
VERSION="${RAW_VERSION#v}"
|
VERSION="${RAW_VERSION#v}"
|
||||||
|
|
||||||
if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+-beta\.[0-9]+$ ]]; then
|
if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+-beta\.[0-9]+$ ]]; then
|
||||||
echo "Version must be in format X.Y.Z-beta.N (e.g. 1.0.0-beta.2)"
|
echo "Version must be in format X.Y.Z-beta.N (e.g. 2.0.0-beta.2)"
|
||||||
exit 1
|
exit 1
|
||||||
fi
|
fi
|
||||||
|
|
||||||
|
|||||||
@@ -4,7 +4,7 @@ AI-powered penetration testing agent for defensive security analysis. Automates
|
|||||||
|
|
||||||
## Commands
|
## Commands
|
||||||
|
|
||||||
**Prerequisites:** Docker, AI provider credentials (`.env` for local, `shn setup` or env vars for npx)
|
**Prerequisites:** Docker, AI provider credentials (`.env` for local, `npx @keygraph/shannon setup` or env vars for npx)
|
||||||
|
|
||||||
### Dual CLI
|
### Dual CLI
|
||||||
|
|
||||||
@@ -15,8 +15,8 @@ Shannon supports two CLI modes, auto-detected based on the current working direc
|
|||||||
| **Install** | Zero-install via npm | Clone the repo |
|
| **Install** | Zero-install via npm | Clone the repo |
|
||||||
| **Image** | Pulled from Docker Hub (`keygraph/shannon:latest`) | Built locally (`shannon-worker`) |
|
| **Image** | Pulled from Docker Hub (`keygraph/shannon:latest`) | Built locally (`shannon-worker`) |
|
||||||
| **State** | `~/.shannon/` | Project directory |
|
| **State** | `~/.shannon/` | Project directory |
|
||||||
| **Credentials** | `~/.shannon/config.toml` (via `shn setup`) or env vars | `./.env` |
|
| **Credentials** | `~/.shannon/config.toml` (via `npx @keygraph/shannon setup`) or env vars | `./.env` |
|
||||||
| **Config** | `~/.shannon/config.toml` (via `shn setup`) | N/A |
|
| **Config** | `~/.shannon/config.toml` (via `npx @keygraph/shannon setup`) | N/A |
|
||||||
| **Prompts** | Bundled in Docker image | Mounted from `./apps/worker/prompts/` (live-editable) |
|
| **Prompts** | Bundled in Docker image | Mounted from `./apps/worker/prompts/` (live-editable) |
|
||||||
|
|
||||||
Mode auto-detection: local mode activates when env var `SHANNON_LOCAL=1` is set by the `./shannon` entry point (`apps/cli/src/mode.ts`). Otherwise npx mode.
|
Mode auto-detection: local mode activates when env var `SHANNON_LOCAL=1` is set by the `./shannon` entry point (`apps/cli/src/mode.ts`). Otherwise npx mode.
|
||||||
@@ -145,7 +145,7 @@ Durable workflow orchestration with crash recovery, queryable progress, intellig
|
|||||||
5. **Reporting** (`report`) — Executive-level security report
|
5. **Reporting** (`report`) — Executive-level security report
|
||||||
|
|
||||||
### Supporting Systems
|
### Supporting Systems
|
||||||
- **Configuration** — YAML configs in `apps/worker/configs/` with JSON Schema validation (`config-schema.json`). Supports auth settings (MFA/TOTP), URL/code rule scoping (`rules.avoid`/`rules.focus`), run-scope steering (`vuln_classes`, `exploit`), free-form `rules_of_engagement`, and post-hoc `report` filters (`min_severity`, `min_confidence`, `guidance`). `code_path` avoid rules are written into `~/.claude/settings.json` `permissions.deny` (`Read`/`Edit`) once per workflow by `apps/worker/src/temporal/activities.ts:syncCodePathDenyRules` so the SDK enforces them at the tool layer even in `bypassPermissions` mode. `vuln_classes`/`exploit` scope is locked into `session.json` on first run; resumes with a different scope fail fast (`persistOrValidateRunScope`). Credential resolution — local mode: env vars → `./.env`; npx mode: env vars → `~/.shannon/config.toml` (via `shn setup`)
|
- **Configuration** — YAML configs in `apps/worker/configs/` with JSON Schema validation (`config-schema.json`). Supports auth settings (MFA/TOTP), URL/code rule scoping (`rules.avoid`/`rules.focus`), run-scope steering (`vuln_classes`, `exploit`), free-form `rules_of_engagement`, and post-hoc `report` filters (`min_severity`, `min_confidence`, `guidance`). `code_path` avoid rules are written into `~/.claude/settings.json` `permissions.deny` (`Read`/`Edit`) once per workflow by `apps/worker/src/temporal/activities.ts:syncCodePathDenyRules` so the SDK enforces them at the tool layer even in `bypassPermissions` mode. `vuln_classes`/`exploit` scope is locked into `session.json` on first run; resumes with a different scope fail fast (`persistOrValidateRunScope`). Credential resolution — local mode: env vars → `./.env`; npx mode: env vars → `~/.shannon/config.toml` (via `npx @keygraph/shannon setup`)
|
||||||
- **Prompts** — Per-phase templates in `apps/worker/prompts/` with variable substitution (`{{TARGET_URL}}`, `{{CONFIG_CONTEXT}}`). Shared partials in `apps/worker/prompts/shared/` via `apps/worker/src/services/prompt-manager.ts`, including `_code-path-rules.txt` (focus/avoid `[FILE]`/`[GLOB]` routing) and `_rules-of-engagement.txt` (free-text engagement rules). When `exploit: false`, `apps/worker/src/services/findings-renderer.ts` deterministically converts each `*_exploitation_queue.json` into a `*_findings.md` for report assembly — no LLM in the loop
|
- **Prompts** — Per-phase templates in `apps/worker/prompts/` with variable substitution (`{{TARGET_URL}}`, `{{CONFIG_CONTEXT}}`). Shared partials in `apps/worker/prompts/shared/` via `apps/worker/src/services/prompt-manager.ts`, including `_code-path-rules.txt` (focus/avoid `[FILE]`/`[GLOB]` routing) and `_rules-of-engagement.txt` (free-text engagement rules). When `exploit: false`, `apps/worker/src/services/findings-renderer.ts` deterministically converts each `*_exploitation_queue.json` into a `*_findings.md` for report assembly — no LLM in the loop
|
||||||
- **SDK Integration** — Uses `@anthropic-ai/claude-agent-sdk` with `maxTurns: 10_000` and `bypassPermissions` mode. Adaptive thinking is enabled by default on Opus 4.6/4.7/4.8 (`supportsAdaptiveThinking` in `apps/worker/src/ai/models.ts`); disable per-scan via `CLAUDE_ADAPTIVE_THINKING=false` (env) or `core.adaptive_thinking = false` (npx TOML). Browser automation via `playwright-cli` with session isolation (`-s=<session>`). TOTP generation via `generate-totp` CLI tool. Login flow template at `apps/worker/prompts/shared/login-instructions.txt` supports form, SSO, API, and basic auth. On authenticated whitebox scans, the `validate-authentication` preflight performs the single real login and saves the browser session to `auth-state.json` in the per-session audit directory (path from `authStateFile()` in `apps/worker/src/audit/utils.ts`, derived from `generateAuditPath()`). The validation activity (`apps/worker/src/services/validate-authentication.ts`) removes any stale file from a prior run before the agent runs and verifies the file parses and contains cookies or storage before the preflight is marked complete; `logWorkflowComplete` deletes it when the workflow ends so authenticated cookies don't sit on disk between scans. Agent prompts opt in to session reuse by `@include(shared/_shared-session.txt)` before their `<login_instructions>` block — the partial restores the session and falls through to the full login flow if verification fails. `vuln-auth`/`exploit-auth` omit the include and own their own login
|
- **SDK Integration** — Uses `@anthropic-ai/claude-agent-sdk` with `maxTurns: 10_000` and `bypassPermissions` mode. Adaptive thinking is enabled by default on Opus 4.6/4.7/4.8 (`supportsAdaptiveThinking` in `apps/worker/src/ai/models.ts`); disable per-scan via `CLAUDE_ADAPTIVE_THINKING=false` (env) or `core.adaptive_thinking = false` (npx TOML). Browser automation via `playwright-cli` with session isolation (`-s=<session>`). TOTP generation via `generate-totp` CLI tool. Login flow template at `apps/worker/prompts/shared/login-instructions.txt` supports form, SSO, API, and basic auth. On authenticated whitebox scans, the `validate-authentication` preflight performs the single real login and saves the browser session to `auth-state.json` in the per-session audit directory (path from `authStateFile()` in `apps/worker/src/audit/utils.ts`, derived from `generateAuditPath()`). The validation activity (`apps/worker/src/services/validate-authentication.ts`) removes any stale file from a prior run before the agent runs and verifies the file parses and contains cookies or storage before the preflight is marked complete; `logWorkflowComplete` deletes it when the workflow ends so authenticated cookies don't sit on disk between scans. Agent prompts opt in to session reuse by `@include(shared/_shared-session.txt)` before their `<login_instructions>` block — the partial restores the session and falls through to the full login flow if verification fails. `vuln-auth`/`exploit-auth` omit the include and own their own login
|
||||||
- **Audit System** — Crash-safe append-only logging in `workspaces/{hostname}_{sessionId}/`. Tracks session metrics, per-agent logs, prompts, and deliverables. WorkflowLogger (`apps/worker/src/audit/workflow-logger.ts`) provides unified human-readable per-workflow logs, backed by LogStream (`apps/worker/src/audit/log-stream.ts`) shared stream primitive
|
- **Audit System** — Crash-safe append-only logging in `workspaces/{hostname}_{sessionId}/`. Tracks session metrics, per-agent logs, prompts, and deliverables. WorkflowLogger (`apps/worker/src/audit/workflow-logger.ts`) provides unified human-readable per-workflow logs, backed by LogStream (`apps/worker/src/audit/log-stream.ts`) shared stream primitive
|
||||||
|
|||||||
@@ -1,9 +1,9 @@
|
|||||||
>[!NOTE]
|
> [!NOTE]
|
||||||
> **[Better Steerability, Authentication Improvements, and the Migration to the Pi Harness](https://github.com/KeygraphHQ/shannon/discussions/348)**
|
> **[Shannon Now Runs on the Pi Harness (Beta) - run it today with `npx @keygraph/shannon@beta`](https://github.com/KeygraphHQ/shannon/discussions/358)**
|
||||||
|
|
||||||
<div align="center">
|
<div align="center">
|
||||||
|
|
||||||
<img src="./assets/github-banner.png" alt="Shannon - AI Pentester for Web Applications and APIs" width="100%">
|
<img src="./assets/github-banner.png" alt="Shannon - AI Pentester by Keygraph" width="100%">
|
||||||
|
|
||||||
# Shannon - AI Pentester by Keygraph
|
# Shannon - AI Pentester by Keygraph
|
||||||
|
|
||||||
@@ -12,6 +12,8 @@
|
|||||||
Shannon is an autonomous, white-box AI pentester for web applications and APIs. <br />
|
Shannon is an autonomous, white-box AI pentester for web applications and APIs. <br />
|
||||||
It analyzes your source code, identifies attack paths, and executes real exploits to prove vulnerabilities before they reach production.
|
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://discord.gg/9ZqQPuhJB7"><img src="./assets/discord.png" height="40" alt="Join Discord"></a>
|
||||||
@@ -26,45 +28,38 @@ It analyzes your source code, identifies attack paths, and executes real exploit
|
|||||||
## Table of Contents
|
## Table of Contents
|
||||||
|
|
||||||
- [What is Shannon?](#what-is-shannon)
|
- [What is Shannon?](#what-is-shannon)
|
||||||
- [Product Line](#product-line)
|
- [Shannon in Action](#shannon-in-action)
|
||||||
- [Shannon Lite in Action](#shannon-lite-in-action)
|
|
||||||
- [Quick Start](#quick-start)
|
- [Quick Start](#quick-start)
|
||||||
- [Key Capabilities](#key-capabilities)
|
- [Key Capabilities](#key-capabilities)
|
||||||
- [Shannon Lite and Shannon Pro](#shannon-lite-and-shannon-pro)
|
- [Editions](#editions)
|
||||||
- [Architecture](#architecture)
|
- [Architecture](#architecture)
|
||||||
- [Documentation](#documentation)
|
- [Documentation](#documentation)
|
||||||
- [Safety, Scope, and Limitations](#safety-scope-and-limitations)
|
- [Safety, Scope, and Limitations](#safety-scope-and-limitations)
|
||||||
- [License and Enterprise Licensing](#license-and-enterprise-licensing)
|
- [License and Enterprise Licensing](#license-and-enterprise-licensing)
|
||||||
|
- [About Keygraph](#about-keygraph)
|
||||||
- [Community and Support](#community-and-support)
|
- [Community and Support](#community-and-support)
|
||||||
|
|
||||||
## What is Shannon?
|
## What is Shannon?
|
||||||
|
|
||||||
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 is an autonomous 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 analyzes your web application's source code to identify potential attack vectors, then uses browser automation and command-line tools to execute real exploits against the running application and its APIs. Only vulnerabilities with a working proof-of-concept are included in the final report.
|
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 against the running application and its APIs. Only vulnerabilities with a working proof-of-concept are included in the final report.
|
||||||
|
|
||||||
|
Shannon is the agent. This repository is Shannon Open Source, the standalone pentester you run yourself. The same Shannon also powers the [Keygraph platform](https://keygraph.io), Keygraph's commercial pentesting product. See [Editions](#editions) for how the two compare.
|
||||||
|
|
||||||
### Why Shannon Exists
|
### 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.
|
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 that gap by providing on-demand, automated penetration testing that can run against every build or release.
|
Shannon closes that gap by providing on-demand, automated penetration testing that can run against every build or release.
|
||||||
|
|
||||||
## Product Line
|
## Shannon in Action
|
||||||
|
|
||||||
Shannon is developed by [Keygraph](https://keygraph.io) and available in two editions:
|
|
||||||
|
|
||||||
| Edition | License | Best For |
|
|
||||||
| --- | --- | --- |
|
|
||||||
| **Shannon Lite** | AGPL-3.0 | Local, strictly white-box testing of applications you own or are authorized to test. |
|
|
||||||
| **Shannon Pro** | Commercial | Organizations needing a continuous pentesting and AppSec platform with black-box and white-box pentesting, parsed-code SAST, CI/CD gating, verified remediation, SLA tracking, and enterprise deployment. |
|
|
||||||
|
|
||||||
## Shannon Lite in Action
|
|
||||||
|
|
||||||
<p align="center">
|
<p align="center">
|
||||||
<img src="assets/shannon-action.gif" alt="Shannon Lite running an autonomous pentest" width="100%">
|
<img src="assets/shannon-action.gif" alt="Shannon running an autonomous pentest" width="100%">
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
Sample Shannon Lite penetration test reports from intentionally vulnerable applications:
|
Sample penetration test reports from intentionally vulnerable applications, produced by Shannon Open Source:
|
||||||
|
|
||||||
| Target | Summary | Report |
|
| Target | Summary | Report |
|
||||||
| --- | --- | --- |
|
| --- | --- | --- |
|
||||||
@@ -76,14 +71,14 @@ Sample Shannon Lite penetration test reports from intentionally vulnerable appli
|
|||||||
|
|
||||||
### Prerequisites
|
### Prerequisites
|
||||||
|
|
||||||
- **Docker** - required for the worker container.
|
- **Docker**: required for the worker container.
|
||||||
- **Node.js 18+** - required for the recommended `npx` workflow.
|
- **Node.js 18+**: required for the recommended `npx` workflow.
|
||||||
- **AI provider credentials** - Anthropic is recommended; AWS Bedrock, Google Vertex AI, and compatible proxy setups are documented separately.
|
- **AI provider credentials**: Anthropic is recommended. AWS Bedrock, Google Vertex AI, and compatible proxy setups are documented separately.
|
||||||
|
|
||||||
### Run Shannon Lite
|
### Run Shannon
|
||||||
|
|
||||||
> [!WARNING]
|
> [!WARNING]
|
||||||
> Shannon Lite actively executes exploits. Run it only against applications and environments you own or have explicit written authorization to test. Do not run Shannon Lite against production systems.
|
> Shannon actively executes exploits. Run it only against applications and environments you own or have explicit written authorization to test. Do not run Shannon against production systems.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Configure credentials with the interactive wizard.
|
# Configure credentials with the interactive wizard.
|
||||||
@@ -93,52 +88,49 @@ npx @keygraph/shannon setup
|
|||||||
npx @keygraph/shannon start -u https://your-app.com -r /path/to/your-repo
|
npx @keygraph/shannon start -u https://your-app.com -r /path/to/your-repo
|
||||||
```
|
```
|
||||||
|
|
||||||
Shannon Lite 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.
|
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 source builds, authenticated scans, provider-specific setup, and platform notes, see [Documentation](#documentation).
|
For source builds, authenticated scans, provider-specific setup, and platform notes, see [Documentation](#documentation).
|
||||||
|
|
||||||
## Key Capabilities
|
## Key Capabilities
|
||||||
|
|
||||||
- **Proof-by-exploitation reports**: Shannon Lite reports validated findings with reproducible proof-of-concept steps instead of speculative warnings.
|
- **Proof-by-exploitation reports**: Shannon reports validated findings with reproducible proof-of-concept steps instead of speculative warnings.
|
||||||
- **White-box attack planning**: Shannon Lite uses source-code analysis to guide dynamic testing and focus on realistic attack paths.
|
- **White-box attack planning**: Shannon uses source-code analysis to guide dynamic testing and focus on realistic attack paths.
|
||||||
- **Autonomous execution**: Shannon Lite launches reconnaissance, vulnerability analysis, exploitation, and report generation from a single command.
|
- **Autonomous execution**: Shannon launches reconnaissance, vulnerability analysis, exploitation, and report generation from a single command.
|
||||||
- **Authenticated testing**: Shannon Lite configuration files can describe login flows, test credentials, TOTP, email-based login flows, focus areas, and rules of engagement.
|
- **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 Lite targets exploitable Injection, XSS, SSRF, Broken Authentication, and Broken Authorization issues.
|
- **OWASP-focused coverage**: Shannon targets exploitable Injection, XSS, SSRF, Broken Authentication, and Broken Authorization issues.
|
||||||
- **Resumable workspaces**: Shannon Lite can resume interrupted runs without re-running completed agents.
|
- **Resumable workspaces**: Shannon can resume interrupted runs without re-running completed agents.
|
||||||
|
|
||||||
## Shannon Lite and Shannon Pro
|
## Editions
|
||||||
|
|
||||||
This repository contains **Shannon Lite**, the AGPL-3.0 open-source CLI for strictly white-box, proof-by-exploitation testing of web applications and APIs you own or are authorized to test. Shannon Lite requires access to the target application's source code and repository layout.
|
Shannon ships in two ways: **Shannon Open Source**, the pentester you run yourself, and the **Keygraph platform**, the commercial pentesting product that runs Shannon continuously and closes the full AppSec lifecycle around it.
|
||||||
|
|
||||||
**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.
|
**Shannon Open Source** (this repository) is the standalone pentester: a CLI agent for white-box, proof-by-exploitation testing of web applications and APIs you own or are authorized to test. It reads your source, plans attacks, executes real exploits, and reports only what it can prove. It runs on demand and is complete in that lane. You point it at a target, it pentests, it reports.
|
||||||
|
|
||||||
Shannon Pro supports both **white-box and black-box agentic pentesting**: use source-aware testing when code is available, or run autonomous black-box testing against deployed applications and APIs when source access is unavailable or unnecessary.
|
The **Keygraph platform** is the enterprise-ready, continuous pentesting product powered by Shannon. In the Keygraph platform, an enhanced build of Shannon runs continuously in a hardened, orchestrated environment fed by Keygraph's full code-analysis stack. Around that engine, the platform closes the entire vulnerability lifecycle, from analysis to a verified fix:
|
||||||
|
|
||||||
Shannon Pro covers the full vulnerability lifecycle: finding exploitable issues, deduplicating and prioritizing them, syncing work into developer workflows, generating verified remediations, re-testing fixes, tracking SLAs, and producing dashboards for security reporting and compliance.
|
- **Analyze**: Code Property Graph SAST, SCA with reachability, secrets, IaC, and container scanning. First-class detection in their own right, and context that sharpens Shannon's attacks.
|
||||||
|
- **Prove**: autonomous black-box and source-aware white-box pentests turn candidate findings into proven, exploited vulnerabilities rather than speculative alerts.
|
||||||
|
- **Manage**: one canonical record per vulnerability per repository, deduplicated across every source, with ownership, status, SLA tracking, dashboards, and bidirectional Jira sync.
|
||||||
|
- **Remediate and verify**: patches written automatically and re-tested against the patched code before delivery, landing in your existing review workflow rather than auto-applied.
|
||||||
|
- **Deploy**: self-hosted and air-gapped environments, strict bring-your-own-key model access, and customer-controlled LLM gateway patterns, so source, results, and model traffic stay inside your perimeter.
|
||||||
|
|
||||||
For enterprise deployments, Shannon Pro supports self-hosted and air-gapped environments, strict bring-your-own-key model access, and customer-controlled LLM gateway patterns. Deployments can be designed so source code, scan results, prompts, completions, and model traffic remain inside your security perimeter.
|
Shannon is the proof engine at the center of the Keygraph platform. Shannon Open Source gives you that engine to run yourself. The Keygraph platform surrounds Shannon with continuous analysis, finding management, remediation, verification, and enterprise deployment.
|
||||||
|
|
||||||
Shannon Lite is a strong fit for local and project-level white-box testing. Shannon Pro is intended for organizations that need continuous AppSec coverage, black-box and white-box pentesting, centralized triage, verified remediation workflows, compliance-ready reporting, enterprise integrations, and commercial support.
|
| AppSec lifecycle stage | Shannon Open Source | Keygraph platform |
|
||||||
|
|
||||||
| Need | Shannon Lite | Shannon Pro |
|
|
||||||
| --- | --- | --- |
|
| --- | --- | --- |
|
||||||
| License | AGPL-3.0 | Commercial |
|
| Analyze | Basic LLM pass-through of source to plan attacks | Actual code-base parsing, plus Code Property Graph, SAST, SCA with reachability, secrets, IaC, and containers |
|
||||||
| White-box pentesting | Yes; source code required | Yes; source-aware testing with platform workflows |
|
| Pentest and prove | White-box only, proof by exploitation | Enhanced white-box, plus black-box and grey-box modes, run continuously |
|
||||||
| Black-box pentesting | No | Yes; autonomous testing without source-code access |
|
| Manage findings | Local Markdown report | Canonical findings system: deduplication across sources, ownership, SLA, dashboards, Jira sync, and professional pentest-grade PDF reports |
|
||||||
| Code analysis / SAST | Prompting and source pass-through to guide pentesting | Actual code parsing, Code Property Graph analysis, source-to-sink path analysis, and agentic SAST |
|
| Remediate and verify | Fix manually from the report, then re-run the full scan to verify | Automated remediation: opens a PR with the fix, verified by point re-test without re-running the full scan |
|
||||||
| AppSec coverage | OWASP-focused agentic pentesting | Agentic pentesting, SAST, SCA, secrets, IaC, containers, and business logic testing |
|
| Deploy and operate | Local CLI and Docker worker | Self-hosted, air-gapped, BYOK, continuous, enterprise integrations |
|
||||||
| CI/CD and gating | Manual/local CLI runs | Headless commercial CLI for CI/CD gating across enterprise CI/CD platforms |
|
| License and support | AGPL-3.0, community | Commercial, supported |
|
||||||
| Finding lifecycle | Local Markdown reports | Canonical findings, deduplication, ownership, status, SLA tracking, workflow sync, and reporting dashboards |
|
|
||||||
| Remediation | Manual | User-initiated remediation with verification before delivery |
|
|
||||||
| Fix verification | None; manual reruns only | Targeted verification without rerunning the entire scan, completing the remediation lifecycle |
|
|
||||||
| Enterprise deployment | Local CLI and Docker worker | Self-hosted, air-gapped, BYOK, and customer-controlled LLM gateway options |
|
|
||||||
| Support | Community | Commercial support |
|
|
||||||
|
|
||||||
Learn more on the [Keygraph website](https://keygraph.io), read the [Shannon Pro technical overview](docs/shannon-pro.md), start a free trial or 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), read the [Keygraph platform technical overview](docs/keygraph-platform.md), start a free trial or book a [demo](https://cal.com/team/keygraph/shannon-pro), or contact [shannon@keygraph.io](mailto:shannon@keygraph.io).
|
||||||
|
|
||||||
## Architecture
|
## Architecture
|
||||||
|
|
||||||
Shannon Lite uses a multi-agent workflow that combines source-code analysis with live exploitation:
|
Shannon uses a multi-agent workflow that combines source-code analysis with live exploitation:
|
||||||
|
|
||||||
```text
|
```text
|
||||||
┌──────────────────────┐
|
┌──────────────────────┐
|
||||||
@@ -199,32 +191,36 @@ Use these guides for operational detail:
|
|||||||
| [Workspaces and resuming](docs/workspaces.md) | Naming workspaces, resuming interrupted scans, and workspace storage. |
|
| [Workspaces and resuming](docs/workspaces.md) | Naming workspaces, resuming interrupted scans, and workspace storage. |
|
||||||
| [Safety and limitations](docs/safety.md) | Authorized-use requirements, non-production guidance, mutative effects, cost, and model caveats. |
|
| [Safety and limitations](docs/safety.md) | Authorized-use requirements, non-production guidance, mutative effects, cost, and model caveats. |
|
||||||
| [Coverage and roadmap](docs/coverage-roadmap.md) | Current vulnerability coverage and planned work. |
|
| [Coverage and roadmap](docs/coverage-roadmap.md) | Current vulnerability coverage and planned work. |
|
||||||
| [Shannon Pro](docs/shannon-pro.md) | Commercial platform, black-box and white-box pentesting, full lifecycle workflows, and enterprise deployment. |
|
| [Keygraph platform](docs/keygraph-platform.md) | The continuous, agentic pentesting platform: code analysis, black-box and white-box testing, finding management, remediation, verification, and enterprise deployment. |
|
||||||
|
|
||||||
## Safety, Scope, and Limitations
|
## Safety, Scope, and Limitations
|
||||||
|
|
||||||
Shannon Lite is not a passive scanner. 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 development environments with disposable data.
|
Shannon is not a passive scanner. 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 development environments with disposable data.
|
||||||
|
|
||||||
You are responsible for using Shannon Lite legally and ethically. Do not point Shannon Lite at systems, repositories, or applications you do not own or do not have explicit authorization to test.
|
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 have explicit authorization to test.
|
||||||
|
|
||||||
Important limitations:
|
Important limitations:
|
||||||
|
|
||||||
- Shannon Lite focuses on actively exploitable issues such as Injection, XSS, SSRF, Broken Authentication, and Broken Authorization. Broader static-analysis findings, including vulnerable dependencies and insecure configurations, are a core focus of Shannon Pro.
|
- 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.
|
- Findings still require human review. LLM-generated reports can contain weakly supported or incorrect details.
|
||||||
- Shannon Lite is officially supported with Claude models. Smaller, alternative, or proxied non-Claude models may be incomplete or unstable.
|
- Shannon is officially supported with Claude models. Smaller, alternative, or proxied non-Claude models may be incomplete or unstable.
|
||||||
- A full run can take roughly 1 to 1.5 hours and may incur LLM API costs depending on model pricing and application complexity.
|
- 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.
|
- Do not scan untrusted or adversarial codebases. AI-powered tools that read source code can be exposed to prompt injection.
|
||||||
|
|
||||||
Read the full [Safety and limitations](docs/safety.md) guide before running Shannon Lite in a new environment.
|
Read the full [Safety and limitations](docs/safety.md) guide before running Shannon in a new environment.
|
||||||
|
|
||||||
## License and Enterprise Licensing
|
## License and Enterprise Licensing
|
||||||
|
|
||||||
Shannon Lite is licensed under the [GNU Affero General Public License v3.0](LICENSE).
|
Shannon Open Source is licensed under the [GNU Affero General Public License v3.0](LICENSE).
|
||||||
|
|
||||||
Commercial and enterprise licensing is available for organizations that need different license terms, commercial support, private redistribution, managed-service use, or broader deployment options.
|
Commercial and enterprise licensing is available 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 [shannon@keygraph.io](mailto:shannon@keygraph.io).
|
For commercial licensing, contact [shannon@keygraph.io](mailto:shannon@keygraph.io).
|
||||||
|
|
||||||
|
## 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 engine.
|
||||||
|
|
||||||
## Community and Support
|
## Community and Support
|
||||||
|
|
||||||
**Community office hours** are available for hands-on help with bugs, deployments, and configuration questions.
|
**Community office hours** are available for hands-on help with bugs, deployments, and configuration questions.
|
||||||
@@ -233,7 +229,7 @@ For commercial licensing, contact [shannon@keygraph.io](mailto:shannon@keygraph.
|
|||||||
- Asia: Thursday, 2:00 PM IST
|
- Asia: Thursday, 2:00 PM IST
|
||||||
- [Book a slot](https://cal.com/george-flores-keygraph/shannon-community-office-hours)
|
- [Book a slot](https://cal.com/george-flores-keygraph/shannon-community-office-hours)
|
||||||
|
|
||||||
[Join Discord](https://discord.gg/cmctpMBXwE) to ask questions, share feedback, and connect with other Shannon Lite users.
|
[Join Discord](https://discord.gg/cmctpMBXwE) to ask questions, share feedback, and connect with other Shannon users.
|
||||||
|
|
||||||
At this time, Keygraph is not accepting external code contributions. Issues are welcome for bug reports and feature requests:
|
At this time, Keygraph is not accepting external code contributions. Issues are welcome for bug reports and feature requests:
|
||||||
|
|
||||||
|
|||||||
@@ -1,5 +1,5 @@
|
|||||||
/**
|
/**
|
||||||
* `shn setup` — interactive TUI wizard for one-time credential configuration.
|
* `npx @keygraph/shannon setup` — interactive TUI wizard for one-time credential configuration.
|
||||||
*
|
*
|
||||||
* Walks the user through selecting a provider and entering credentials,
|
* Walks the user through selecting a provider and entering credentials,
|
||||||
* then persists everything to ~/.shannon/config.toml with 0o600 permissions.
|
* then persists everything to ~/.shannon/config.toml with 0o600 permissions.
|
||||||
|
|||||||
@@ -1,5 +1,5 @@
|
|||||||
/**
|
/**
|
||||||
* `shn uninstall` command — remove ~/.shannon/ after confirmation (npx only).
|
* `npx @keygraph/shannon uninstall` command — remove ~/.shannon/ after confirmation (npx only).
|
||||||
*/
|
*/
|
||||||
|
|
||||||
import fs from 'node:fs';
|
import fs from 'node:fs';
|
||||||
|
|||||||
@@ -270,7 +270,7 @@ export function resolveConfig(): void {
|
|||||||
for (const err of errors) {
|
for (const err of errors) {
|
||||||
console.error(` - ${err}`);
|
console.error(` - ${err}`);
|
||||||
}
|
}
|
||||||
console.error(`\nRun 'shn setup' to reconfigure.\n`);
|
console.error(`\nRun 'npx @keygraph/shannon setup' to reconfigure.\n`);
|
||||||
process.exit(1);
|
process.exit(1);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|||||||
@@ -16,6 +16,7 @@
|
|||||||
* - Spending cap check using isSpendingCapBehavior
|
* - Spending cap check using isSpendingCapBehavior
|
||||||
* - Handle failure (rollback, audit)
|
* - Handle failure (rollback, audit)
|
||||||
* - Validate output using AGENTS[agentName].deliverableFilename
|
* - Validate output using AGENTS[agentName].deliverableFilename
|
||||||
|
* - Render the deliverable to disk via the writeDeliverable hook (if provided)
|
||||||
* - Commit on success, log metrics
|
* - Commit on success, log metrics
|
||||||
*
|
*
|
||||||
* No Temporal dependencies - pure domain logic.
|
* No Temporal dependencies - pure domain logic.
|
||||||
@@ -55,6 +56,8 @@ export interface AgentExecutionInput {
|
|||||||
promptDir?: string | undefined;
|
promptDir?: string | undefined;
|
||||||
providerConfig?: import('../types/config.js').ProviderConfig | undefined;
|
providerConfig?: import('../types/config.js').ProviderConfig | undefined;
|
||||||
mcpServers?: Record<string, import('@anthropic-ai/claude-agent-sdk').McpServerConfig>;
|
mcpServers?: Record<string, import('@anthropic-ai/claude-agent-sdk').McpServerConfig>;
|
||||||
|
// Renders the deliverable to disk; invoked after validation, before the success commit.
|
||||||
|
writeDeliverable?: (deliverablesPath: string) => Promise<void>;
|
||||||
}
|
}
|
||||||
|
|
||||||
interface FailAgentOpts {
|
interface FailAgentOpts {
|
||||||
@@ -110,6 +113,7 @@ export class AgentExecutionService {
|
|||||||
promptDir,
|
promptDir,
|
||||||
providerConfig,
|
providerConfig,
|
||||||
mcpServers,
|
mcpServers,
|
||||||
|
writeDeliverable,
|
||||||
} = input;
|
} = input;
|
||||||
|
|
||||||
// 1. Load config (pre-parsed configData → raw YAML → file path)
|
// 1. Load config (pre-parsed configData → raw YAML → file path)
|
||||||
@@ -236,7 +240,12 @@ export class AgentExecutionService {
|
|||||||
});
|
});
|
||||||
}
|
}
|
||||||
|
|
||||||
// 10. Success - commit deliverables, then capture checkpoint hash
|
// 10. Render the deliverable to disk so the success commit below stages it
|
||||||
|
if (writeDeliverable) {
|
||||||
|
await writeDeliverable(deliverablesPath);
|
||||||
|
}
|
||||||
|
|
||||||
|
// 11. Success - commit deliverables, then capture checkpoint hash
|
||||||
await commitGitSuccess(deliverablesPath, agentName, logger);
|
await commitGitSuccess(deliverablesPath, agentName, logger);
|
||||||
const commitHash = await getGitCommitHash(deliverablesPath);
|
const commitHash = await getGitCommitHash(deliverablesPath);
|
||||||
|
|
||||||
|
|||||||
@@ -12,7 +12,7 @@
|
|||||||
* time and API costs compared to failing mid-pipeline.
|
* time and API costs compared to failing mid-pipeline.
|
||||||
*
|
*
|
||||||
* Checks run sequentially, cheapest first:
|
* Checks run sequentially, cheapest first:
|
||||||
* 1. Repository path exists and contains .git
|
* 1. Repository path exists and is a directory
|
||||||
* 2. Config file parses and validates (if provided)
|
* 2. Config file parses and validates (if provided)
|
||||||
* 3. code_path rules match real entries in the repo (filesystem only)
|
* 3. code_path rules match real entries in the repo (filesystem only)
|
||||||
* 4. Credentials validate via Claude Agent SDK query (API key, OAuth, Bedrock, or Vertex AI)
|
* 4. Credentials validate via Claude Agent SDK query (API key, OAuth, Bedrock, or Vertex AI)
|
||||||
@@ -78,14 +78,12 @@ function pinnedLookup(addresses: LookupAddress[]): LookupFunction {
|
|||||||
|
|
||||||
// === Repository Validation ===
|
// === Repository Validation ===
|
||||||
|
|
||||||
async function validateRepo(
|
async function validateRepo(repoPath: string, logger: ActivityLogger): Promise<Result<void, PentestError>> {
|
||||||
repoPath: string,
|
|
||||||
logger: ActivityLogger,
|
|
||||||
skipGitCheck?: boolean,
|
|
||||||
): Promise<Result<void, PentestError>> {
|
|
||||||
logger.info('Checking repository path...', { repoPath });
|
logger.info('Checking repository path...', { repoPath });
|
||||||
|
|
||||||
// 1. Check repo directory exists
|
// Check repo directory exists. The repo is not required to be a git repository:
|
||||||
|
// multi-repo targets (a parent directory containing several repos) have no top-level
|
||||||
|
// .git, and git-based checkpoint/rollback in git-manager already no-ops on non-git dirs.
|
||||||
try {
|
try {
|
||||||
const stats = await fs.stat(repoPath);
|
const stats = await fs.stat(repoPath);
|
||||||
if (!stats.isDirectory()) {
|
if (!stats.isDirectory()) {
|
||||||
@@ -111,36 +109,6 @@ async function validateRepo(
|
|||||||
);
|
);
|
||||||
}
|
}
|
||||||
|
|
||||||
// 2. Check .git directory exists (skipped when consumer removes .git after clone)
|
|
||||||
if (!skipGitCheck) {
|
|
||||||
try {
|
|
||||||
const gitStats = await fs.stat(`${repoPath}/.git`);
|
|
||||||
if (!gitStats.isDirectory()) {
|
|
||||||
return err(
|
|
||||||
new PentestError(
|
|
||||||
`Not a git repository (no .git directory): ${repoPath}`,
|
|
||||||
'config',
|
|
||||||
false,
|
|
||||||
{ repoPath },
|
|
||||||
ErrorCode.REPO_NOT_FOUND,
|
|
||||||
),
|
|
||||||
);
|
|
||||||
}
|
|
||||||
} catch {
|
|
||||||
return err(
|
|
||||||
new PentestError(
|
|
||||||
`Not a git repository (no .git directory): ${repoPath}`,
|
|
||||||
'config',
|
|
||||||
false,
|
|
||||||
{ repoPath },
|
|
||||||
ErrorCode.REPO_NOT_FOUND,
|
|
||||||
),
|
|
||||||
);
|
|
||||||
}
|
|
||||||
} else {
|
|
||||||
logger.info('Skipping .git check (skipGitCheck enabled)');
|
|
||||||
}
|
|
||||||
|
|
||||||
logger.info('Repository path OK');
|
logger.info('Repository path OK');
|
||||||
return ok(undefined);
|
return ok(undefined);
|
||||||
}
|
}
|
||||||
@@ -618,7 +586,7 @@ async function validateTargetUrl(targetUrl: string, logger: ActivityLogger): Pro
|
|||||||
/**
|
/**
|
||||||
* Run all preflight checks sequentially (cheapest first).
|
* Run all preflight checks sequentially (cheapest first).
|
||||||
*
|
*
|
||||||
* 1. Repository path exists and contains .git
|
* 1. Repository path exists and is a directory
|
||||||
* 2. Config file parses and validates (if configPath provided)
|
* 2. Config file parses and validates (if configPath provided)
|
||||||
* 3. code_path rules match at least one entry in the repo (skipped without config)
|
* 3. code_path rules match at least one entry in the repo (skipped without config)
|
||||||
* 4. Credentials validate (API key, OAuth, Bedrock, or Vertex AI)
|
* 4. Credentials validate (API key, OAuth, Bedrock, or Vertex AI)
|
||||||
@@ -631,12 +599,11 @@ export async function runPreflightChecks(
|
|||||||
repoPath: string,
|
repoPath: string,
|
||||||
configPath: string | undefined,
|
configPath: string | undefined,
|
||||||
logger: ActivityLogger,
|
logger: ActivityLogger,
|
||||||
skipGitCheck?: boolean,
|
|
||||||
apiKey?: string,
|
apiKey?: string,
|
||||||
providerConfig?: import('../types/config.js').ProviderConfig,
|
providerConfig?: import('../types/config.js').ProviderConfig,
|
||||||
): Promise<Result<void, PentestError>> {
|
): Promise<Result<void, PentestError>> {
|
||||||
// 1. Repository check (free — filesystem only)
|
// 1. Repository check (free — filesystem only)
|
||||||
const repoResult = await validateRepo(repoPath, logger, skipGitCheck);
|
const repoResult = await validateRepo(repoPath, logger);
|
||||||
if (!repoResult.ok) {
|
if (!repoResult.ok) {
|
||||||
return repoResult;
|
return repoResult;
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -127,12 +127,11 @@ export const AGENT_PHASE_MAP: Readonly<Record<AgentName, PhaseName>> = Object.fr
|
|||||||
|
|
||||||
// Factory function for vulnerability queue validators.
|
// Factory function for vulnerability queue validators.
|
||||||
//
|
//
|
||||||
// Post-MCP-migration, the analysis_deliverable.md is rendered by the activity
|
// The analysis_deliverable.md is rendered via the writeDeliverable hook, which
|
||||||
// wrapper after validateAgentOutput runs, so the previous "both files exist"
|
// AgentExecutionService runs after validateAgentOutput but before the success
|
||||||
// check would race the renderer. The validator only checks the queue.json —
|
// commit — so a "both files exist" check here would race the renderer. The
|
||||||
// that file is written by the SDK structured-output path in agent-execution.ts
|
// validator only checks queue.json, written by the SDK structured-output path
|
||||||
// before this validator runs. The downstream checkExploitationQueue still
|
// in agent-execution.ts before this validator runs.
|
||||||
// renders the .md.
|
|
||||||
function createVulnValidator(vulnType: VulnType): AgentValidator {
|
function createVulnValidator(vulnType: VulnType): AgentValidator {
|
||||||
return async (sourceDir: string, logger: ActivityLogger): Promise<boolean> => {
|
return async (sourceDir: string, logger: ActivityLogger): Promise<boolean> => {
|
||||||
const queueFile = path.join(sourceDir, `${vulnType}_exploitation_queue.json`);
|
const queueFile = path.join(sourceDir, `${vulnType}_exploitation_queue.json`);
|
||||||
@@ -145,9 +144,9 @@ function createVulnValidator(vulnType: VulnType): AgentValidator {
|
|||||||
};
|
};
|
||||||
}
|
}
|
||||||
|
|
||||||
// Exploitation agents — validation lives in runExploitAgentWithCollector post-processing
|
// Exploitation agents — the evidence deliverable is rendered via the writeDeliverable
|
||||||
// (collector harvest + renderer write). The deliverable file is written by the renderer
|
// hook after the agent succeeds (before the success commit), so a file-existence check
|
||||||
// after the agent succeeds, so a file-existence check here would race the renderer.
|
// here would race the renderer.
|
||||||
//
|
//
|
||||||
// VulnType is kept in the import surface for createVulnValidator above; this factory
|
// VulnType is kept in the import surface for createVulnValidator above; this factory
|
||||||
// returns a no-op validator parameterized only for symmetry with the vuln-side factory.
|
// returns a no-op validator parameterized only for symmetry with the vuln-side factory.
|
||||||
|
|||||||
@@ -76,7 +76,6 @@ export interface ActivityInput {
|
|||||||
auditDir?: string;
|
auditDir?: string;
|
||||||
promptDir?: string;
|
promptDir?: string;
|
||||||
sastSarifPath?: string;
|
sastSarifPath?: string;
|
||||||
skipGitCheck?: boolean;
|
|
||||||
providerConfig?: ProviderConfig;
|
providerConfig?: ProviderConfig;
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -138,6 +137,7 @@ async function runAgentActivity(
|
|||||||
agentName: AgentName,
|
agentName: AgentName,
|
||||||
input: ActivityInput,
|
input: ActivityInput,
|
||||||
mcpServers?: Record<string, import('@anthropic-ai/claude-agent-sdk').McpServerConfig>,
|
mcpServers?: Record<string, import('@anthropic-ai/claude-agent-sdk').McpServerConfig>,
|
||||||
|
writeDeliverable?: (deliverablesPath: string) => Promise<void>,
|
||||||
): Promise<AgentMetrics> {
|
): Promise<AgentMetrics> {
|
||||||
const { repoPath, configPath, pipelineTestingMode = false, workflowId, webUrl } = input;
|
const { repoPath, configPath, pipelineTestingMode = false, workflowId, webUrl } = input;
|
||||||
|
|
||||||
@@ -193,6 +193,7 @@ async function runAgentActivity(
|
|||||||
...(input.promptDir !== undefined && { promptDir: input.promptDir }),
|
...(input.promptDir !== undefined && { promptDir: input.promptDir }),
|
||||||
...(input.configYAML !== undefined && { configYAML: input.configYAML }),
|
...(input.configYAML !== undefined && { configYAML: input.configYAML }),
|
||||||
...(mcpServers && { mcpServers }),
|
...(mcpServers && { mcpServers }),
|
||||||
|
...(writeDeliverable && { writeDeliverable }),
|
||||||
},
|
},
|
||||||
auditSession,
|
auditSession,
|
||||||
logger,
|
logger,
|
||||||
@@ -256,28 +257,21 @@ export async function runPreReconAgent(input: ActivityInput): Promise<AgentMetri
|
|||||||
const { renderPreRecon } = await import('../services/pre-recon-renderer.js');
|
const { renderPreRecon } = await import('../services/pre-recon-renderer.js');
|
||||||
|
|
||||||
const collector = createPreReconCollectorServer();
|
const collector = createPreReconCollectorServer();
|
||||||
const metrics = await runAgentActivity('pre-recon', input, { 'pre-recon-collector': collector.server });
|
|
||||||
|
|
||||||
// On resume, the agent is skipped and the collector is never populated.
|
const writeDeliverable = async (deliverablesPath: string): Promise<void> => {
|
||||||
// The cached deliverable from the prior run is the source of truth.
|
const logger = createActivityLogger();
|
||||||
if (metrics.skipped) {
|
// Skipped tools surface as renderer placeholders, not as activity failures.
|
||||||
return metrics;
|
const callStatus = collector.getCallStatus();
|
||||||
}
|
logger.info('Pre-recon tool call status', { callStatus });
|
||||||
|
|
||||||
const logger = createActivityLogger();
|
const collected = collector.getAll();
|
||||||
const dir = deliverablesDir(input.repoPath, input.deliverablesSubdir);
|
const markdown = renderPreRecon(collected);
|
||||||
|
const mdPath = path.join(deliverablesPath, 'pre_recon_deliverable.md');
|
||||||
|
await atomicWrite(mdPath, markdown);
|
||||||
|
logger.info(`Wrote pre_recon_deliverable.md from structured data (${markdown.length} bytes)`);
|
||||||
|
};
|
||||||
|
|
||||||
// Skipped tools surface as renderer placeholders, not as activity failures.
|
return runAgentActivity('pre-recon', input, { 'pre-recon-collector': collector.server }, writeDeliverable);
|
||||||
const callStatus = collector.getCallStatus();
|
|
||||||
logger.info('Pre-recon tool call status', { callStatus });
|
|
||||||
|
|
||||||
const collected = collector.getAll();
|
|
||||||
const markdown = renderPreRecon(collected);
|
|
||||||
const mdPath = path.join(dir, 'pre_recon_deliverable.md');
|
|
||||||
await atomicWrite(mdPath, markdown);
|
|
||||||
logger.info(`Wrote pre_recon_deliverable.md from structured data (${markdown.length} bytes)`);
|
|
||||||
|
|
||||||
return metrics;
|
|
||||||
}
|
}
|
||||||
|
|
||||||
export async function runReconAgent(input: ActivityInput): Promise<AgentMetrics> {
|
export async function runReconAgent(input: ActivityInput): Promise<AgentMetrics> {
|
||||||
@@ -285,28 +279,21 @@ export async function runReconAgent(input: ActivityInput): Promise<AgentMetrics>
|
|||||||
const { renderRecon } = await import('../services/recon-renderer.js');
|
const { renderRecon } = await import('../services/recon-renderer.js');
|
||||||
|
|
||||||
const collector = createReconCollectorServer();
|
const collector = createReconCollectorServer();
|
||||||
const metrics = await runAgentActivity('recon', input, { 'recon-collector': collector.server });
|
|
||||||
|
|
||||||
// On resume, the agent is skipped and the collector is never populated.
|
const writeDeliverable = async (deliverablesPath: string): Promise<void> => {
|
||||||
// The cached deliverable from the prior run is the source of truth.
|
const logger = createActivityLogger();
|
||||||
if (metrics.skipped) {
|
// Skipped tools surface as renderer placeholders, not as activity failures.
|
||||||
return metrics;
|
const callStatus = collector.getCallStatus();
|
||||||
}
|
logger.info('Recon tool call status', { callStatus });
|
||||||
|
|
||||||
const logger = createActivityLogger();
|
const collected = collector.getAll();
|
||||||
const dir = deliverablesDir(input.repoPath, input.deliverablesSubdir);
|
const markdown = renderRecon(collected);
|
||||||
|
const mdPath = path.join(deliverablesPath, 'recon_deliverable.md');
|
||||||
|
await atomicWrite(mdPath, markdown);
|
||||||
|
logger.info(`Wrote recon_deliverable.md from structured data (${markdown.length} bytes)`);
|
||||||
|
};
|
||||||
|
|
||||||
// Skipped tools surface as renderer placeholders, not as activity failures.
|
return runAgentActivity('recon', input, { 'recon-collector': collector.server }, writeDeliverable);
|
||||||
const callStatus = collector.getCallStatus();
|
|
||||||
logger.info('Recon tool call status', { callStatus });
|
|
||||||
|
|
||||||
const collected = collector.getAll();
|
|
||||||
const markdown = renderRecon(collected);
|
|
||||||
const mdPath = path.join(dir, 'recon_deliverable.md');
|
|
||||||
await atomicWrite(mdPath, markdown);
|
|
||||||
logger.info(`Wrote recon_deliverable.md from structured data (${markdown.length} bytes)`);
|
|
||||||
|
|
||||||
return metrics;
|
|
||||||
}
|
}
|
||||||
|
|
||||||
async function runVulnAgentWithCollector(
|
async function runVulnAgentWithCollector(
|
||||||
@@ -318,28 +305,21 @@ async function runVulnAgentWithCollector(
|
|||||||
const { renderVulnDeliverable } = await import('../services/vuln-renderer.js');
|
const { renderVulnDeliverable } = await import('../services/vuln-renderer.js');
|
||||||
|
|
||||||
const collector = createVulnCollector(vulnClass);
|
const collector = createVulnCollector(vulnClass);
|
||||||
const metrics = await runAgentActivity(agentName, input, { 'vuln-collector': collector.server });
|
|
||||||
|
|
||||||
// On resume, the agent is skipped and the collector is never populated.
|
const writeDeliverable = async (deliverablesPath: string): Promise<void> => {
|
||||||
// The cached deliverable from the prior run is the source of truth.
|
const logger = createActivityLogger();
|
||||||
if (metrics.skipped) {
|
// Skipped tools surface as renderer placeholders, not as activity failures.
|
||||||
return metrics;
|
const callStatus = collector.getCallStatus();
|
||||||
}
|
logger.info(`${vulnClass} vuln tool call status`, { callStatus });
|
||||||
|
|
||||||
const logger = createActivityLogger();
|
const collected = collector.getAll();
|
||||||
const dir = deliverablesDir(input.repoPath, input.deliverablesSubdir);
|
const markdown = renderVulnDeliverable(vulnClass, collected);
|
||||||
|
const mdPath = path.join(deliverablesPath, `${vulnClass}_analysis_deliverable.md`);
|
||||||
|
await atomicWrite(mdPath, markdown);
|
||||||
|
logger.info(`Wrote ${vulnClass}_analysis_deliverable.md from structured data (${markdown.length} bytes)`);
|
||||||
|
};
|
||||||
|
|
||||||
// Skipped tools surface as renderer placeholders, not as activity failures.
|
return runAgentActivity(agentName, input, { 'vuln-collector': collector.server }, writeDeliverable);
|
||||||
const callStatus = collector.getCallStatus();
|
|
||||||
logger.info(`${vulnClass} vuln tool call status`, { callStatus });
|
|
||||||
|
|
||||||
const collected = collector.getAll();
|
|
||||||
const markdown = renderVulnDeliverable(vulnClass, collected);
|
|
||||||
const mdPath = path.join(dir, `${vulnClass}_analysis_deliverable.md`);
|
|
||||||
await atomicWrite(mdPath, markdown);
|
|
||||||
logger.info(`Wrote ${vulnClass}_analysis_deliverable.md from structured data (${markdown.length} bytes)`);
|
|
||||||
|
|
||||||
return metrics;
|
|
||||||
}
|
}
|
||||||
|
|
||||||
export async function runInjectionVulnAgent(input: ActivityInput): Promise<AgentMetrics> {
|
export async function runInjectionVulnAgent(input: ActivityInput): Promise<AgentMetrics> {
|
||||||
@@ -399,34 +379,29 @@ async function runExploitAgentWithCollector(
|
|||||||
const { validIds, idToType } = await readExploitQueue(queuePath);
|
const { validIds, idToType } = await readExploitQueue(queuePath);
|
||||||
|
|
||||||
const collector = createExploitCollector({ vulnClass, validIds });
|
const collector = createExploitCollector({ vulnClass, validIds });
|
||||||
const metrics = await runAgentActivity(agentName, input, { 'exploit-collector': collector.server });
|
|
||||||
|
|
||||||
// On resume, the agent is skipped and the collector is never populated.
|
const writeDeliverable = async (deliverablesPath: string): Promise<void> => {
|
||||||
// The cached deliverable from the prior run is the source of truth.
|
const logger = createActivityLogger();
|
||||||
if (metrics.skipped) {
|
const collected = collector.getAll();
|
||||||
return metrics;
|
const emittedIds = new Set(collected.map((e) => e.vulnerability_id));
|
||||||
}
|
const missingIds = [...validIds].filter((id) => !emittedIds.has(id));
|
||||||
|
const exploitedCount = collected.filter((e) => e.status === 'exploited').length;
|
||||||
|
const blockedCount = collected.filter((e) => e.status === 'blocked').length;
|
||||||
|
|
||||||
const logger = createActivityLogger();
|
logger.info(`${vulnClass} exploit tool call metrics`, {
|
||||||
const collected = collector.getAll();
|
queueSize: validIds.size,
|
||||||
const emittedIds = new Set(collected.map((e) => e.vulnerability_id));
|
exploited: exploitedCount,
|
||||||
const missingIds = [...validIds].filter((id) => !emittedIds.has(id));
|
blocked: blockedCount,
|
||||||
const exploitedCount = collected.filter((e) => e.status === 'exploited').length;
|
missing: missingIds.length,
|
||||||
const blockedCount = collected.filter((e) => e.status === 'blocked').length;
|
});
|
||||||
|
|
||||||
logger.info(`${vulnClass} exploit tool call metrics`, {
|
const markdown = renderExploitDeliverable(vulnClass, collected, idToType);
|
||||||
queueSize: validIds.size,
|
const mdPath = path.join(deliverablesPath, `${vulnClass}_exploitation_evidence.md`);
|
||||||
exploited: exploitedCount,
|
await atomicWrite(mdPath, markdown);
|
||||||
blocked: blockedCount,
|
logger.info(`Wrote ${vulnClass}_exploitation_evidence.md from structured data (${markdown.length} bytes)`);
|
||||||
missing: missingIds.length,
|
};
|
||||||
});
|
|
||||||
|
|
||||||
const markdown = renderExploitDeliverable(vulnClass, collected, idToType);
|
return runAgentActivity(agentName, input, { 'exploit-collector': collector.server }, writeDeliverable);
|
||||||
const mdPath = path.join(dir, `${vulnClass}_exploitation_evidence.md`);
|
|
||||||
await atomicWrite(mdPath, markdown);
|
|
||||||
logger.info(`Wrote ${vulnClass}_exploitation_evidence.md from structured data (${markdown.length} bytes)`);
|
|
||||||
|
|
||||||
return metrics;
|
|
||||||
}
|
}
|
||||||
|
|
||||||
export async function runInjectionExploitAgent(input: ActivityInput): Promise<AgentMetrics> {
|
export async function runInjectionExploitAgent(input: ActivityInput): Promise<AgentMetrics> {
|
||||||
@@ -457,7 +432,7 @@ export async function runReportAgent(input: ActivityInput): Promise<AgentMetrics
|
|||||||
* Preflight validation activity.
|
* Preflight validation activity.
|
||||||
*
|
*
|
||||||
* Runs cheap checks before any agent execution:
|
* Runs cheap checks before any agent execution:
|
||||||
* 1. Repository path exists with .git
|
* 1. Repository path exists and is a directory
|
||||||
* 2. Config file validates (if provided)
|
* 2. Config file validates (if provided)
|
||||||
* 3. Credential validation (API key, OAuth, Bedrock, or Vertex AI)
|
* 3. Credential validation (API key, OAuth, Bedrock, or Vertex AI)
|
||||||
* 4. Target URL reachable from the container
|
* 4. Target URL reachable from the container
|
||||||
@@ -482,7 +457,6 @@ export async function runPreflightValidation(input: ActivityInput): Promise<void
|
|||||||
input.repoPath,
|
input.repoPath,
|
||||||
input.configPath,
|
input.configPath,
|
||||||
logger,
|
logger,
|
||||||
input.skipGitCheck,
|
|
||||||
input.apiKey,
|
input.apiKey,
|
||||||
input.providerConfig,
|
input.providerConfig,
|
||||||
);
|
);
|
||||||
|
|||||||
@@ -27,7 +27,6 @@ export interface PipelineInput {
|
|||||||
promptDir?: string; // Override prompt template directory
|
promptDir?: string; // Override prompt template directory
|
||||||
sastSarifPath?: string; // Optional path for consumer-supplied findings input
|
sastSarifPath?: string; // Optional path for consumer-supplied findings input
|
||||||
checkpointsEnabled?: boolean; // Enable checkpoint activities (default: false)
|
checkpointsEnabled?: boolean; // Enable checkpoint activities (default: false)
|
||||||
skipGitCheck?: boolean; // Skip .git directory validation in preflight (e.g. when .git is removed after clone)
|
|
||||||
providerConfig?: ProviderConfig; // LLM provider configuration (Bedrock, Vertex, etc.)
|
providerConfig?: ProviderConfig; // LLM provider configuration (Bedrock, Vertex, etc.)
|
||||||
vulnClasses?: VulnClass[]; // omitted = all five
|
vulnClasses?: VulnClass[]; // omitted = all five
|
||||||
exploit?: boolean; // false skips the exploitation phase
|
exploit?: boolean; // false skips the exploitation phase
|
||||||
|
|||||||
@@ -242,7 +242,6 @@ export async function pentestPipeline(input: PipelineInput): Promise<PipelineSta
|
|||||||
...(input.auditDir !== undefined && { auditDir: input.auditDir }),
|
...(input.auditDir !== undefined && { auditDir: input.auditDir }),
|
||||||
...(input.promptDir !== undefined && { promptDir: input.promptDir }),
|
...(input.promptDir !== undefined && { promptDir: input.promptDir }),
|
||||||
...(input.sastSarifPath !== undefined && { sastSarifPath: input.sastSarifPath }),
|
...(input.sastSarifPath !== undefined && { sastSarifPath: input.sastSarifPath }),
|
||||||
...(input.skipGitCheck !== undefined && { skipGitCheck: input.skipGitCheck }),
|
|
||||||
...(input.providerConfig !== undefined && { providerConfig: input.providerConfig }),
|
...(input.providerConfig !== undefined && { providerConfig: input.providerConfig }),
|
||||||
};
|
};
|
||||||
|
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
# AI Providers
|
# 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
|
## Anthropic
|
||||||
|
|
||||||
@@ -51,7 +51,7 @@ ANTHROPIC_MEDIUM_MODEL=us.anthropic.claude-sonnet-4-6
|
|||||||
ANTHROPIC_LARGE_MODEL=us.anthropic.claude-opus-4-8
|
ANTHROPIC_LARGE_MODEL=us.anthropic.claude-opus-4-8
|
||||||
```
|
```
|
||||||
|
|
||||||
Shannon Lite uses three model tiers:
|
Shannon uses three model tiers:
|
||||||
|
|
||||||
- **small** for summarization
|
- **small** for summarization
|
||||||
- **medium** for security analysis
|
- **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
|
## 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]
|
> [!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.
|
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.
|
||||||
|
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
# Configuration
|
# 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
|
## Credential Precedence
|
||||||
|
|
||||||
@@ -119,7 +119,7 @@ Supported placeholders:
|
|||||||
- `$email_password`
|
- `$email_password`
|
||||||
- `$email_totp`
|
- `$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
|
```yaml
|
||||||
login_flow:
|
login_flow:
|
||||||
|
|||||||
@@ -1,8 +1,8 @@
|
|||||||
# Coverage and Roadmap
|
# 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 Authentication
|
||||||
- Broken Authorization
|
- Broken Authorization
|
||||||
@@ -12,12 +12,12 @@ Shannon Lite focuses on exploitable findings that can be validated against a run
|
|||||||
|
|
||||||
## Reporting Philosophy
|
## 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
|
## 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.
|
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).
|
||||||
|
|||||||
+4
-4
@@ -11,10 +11,10 @@ This guide covers the source-build workflow, common CLI commands, repository pat
|
|||||||
|
|
||||||
## Clone and Build
|
## 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
|
```bash
|
||||||
# 1. Clone Shannon Lite.
|
# 1. Clone Shannon.
|
||||||
git clone https://github.com/KeygraphHQ/shannon.git
|
git clone https://github.com/KeygraphHQ/shannon.git
|
||||||
cd shannon
|
cd shannon
|
||||||
|
|
||||||
@@ -45,7 +45,7 @@ export CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000
|
|||||||
|
|
||||||
## Prepare Your Repository
|
## 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
|
```bash
|
||||||
npx @keygraph/shannon start -u https://example.com -r /path/to/repo
|
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
|
open http://localhost:8233
|
||||||
```
|
```
|
||||||
|
|
||||||
Stop Shannon Lite:
|
Stop Shannon:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npx @keygraph/shannon stop
|
npx @keygraph/shannon stop
|
||||||
|
|||||||
@@ -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
|
- Continuous AppSec coverage across many repositories and services
|
||||||
- White-box pentesting when source code is available
|
- White-box pentesting when source code is available
|
||||||
@@ -21,7 +21,7 @@ Shannon Pro is intended for organizations that need:
|
|||||||
|
|
||||||
## Full Vulnerability Lifecycle
|
## 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.
|
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.
|
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
|
## 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.
|
- **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.
|
- **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
|
## 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.
|
- **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.
|
- **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
|
## 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
|
- **Self-hosted deployments** inside the customer's cloud or infrastructure
|
||||||
- **Air-gapped deployments** for isolated environments
|
- **Air-gapped deployments** for isolated environments
|
||||||
@@ -75,7 +75,7 @@ Deployments can be designed so source code, scan results, prompts, completions,
|
|||||||
|
|
||||||
## Capability Comparison
|
## Capability Comparison
|
||||||
|
|
||||||
| Need | Shannon Lite | Shannon Pro |
|
| Need | Shannon | Keygraph platform |
|
||||||
| --- | --- | --- |
|
| --- | --- | --- |
|
||||||
| Licensing | AGPL-3.0 | Commercial |
|
| Licensing | AGPL-3.0 | Commercial |
|
||||||
| White-box pentesting | Yes; source code required | Yes; source-aware testing with platform workflows |
|
| 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
|
## 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).
|
||||||
+4
-4
@@ -4,7 +4,7 @@ This guide covers platform-specific notes and Docker networking behavior.
|
|||||||
|
|
||||||
## Windows
|
## 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
|
### 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**.
|
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
|
```bash
|
||||||
npx @keygraph/shannon setup
|
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.
|
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
|
## Linux
|
||||||
|
|
||||||
@@ -69,7 +69,7 @@ Source-build equivalent:
|
|||||||
|
|
||||||
## Custom Hostnames
|
## 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:
|
To disable forwarding:
|
||||||
|
|
||||||
|
|||||||
+12
-12
@@ -1,18 +1,18 @@
|
|||||||
# Safety and Limitations
|
# 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
|
## 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
|
## 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:
|
Potential mutative effects include:
|
||||||
|
|
||||||
@@ -23,17 +23,17 @@ Potential mutative effects include:
|
|||||||
- Generating unexpected outbound traffic
|
- Generating unexpected outbound traffic
|
||||||
- Writing exploit artifacts to reports or deliverables
|
- 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
|
## 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.
|
- **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 Lite is officially supported only with Claude models. Alternative models may be incomplete, inaccurate, or unstable.
|
- **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 Lite at untrusted or adversarial codebases. AI-powered tools that read source code can be influenced by malicious repository content.
|
- **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
|
## Scope of Analysis
|
||||||
|
|
||||||
Shannon Lite currently targets exploitable vulnerabilities in these classes:
|
Shannon currently targets exploitable vulnerabilities in these classes:
|
||||||
|
|
||||||
- Broken Authentication
|
- Broken Authentication
|
||||||
- Broken Authorization
|
- Broken Authorization
|
||||||
@@ -41,9 +41,9 @@ Shannon Lite currently targets exploitable vulnerabilities in these classes:
|
|||||||
- Cross-Site Scripting
|
- Cross-Site Scripting
|
||||||
- Server-Side Request Forgery
|
- 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
|
## Cost and Performance
|
||||||
|
|
||||||
|
|||||||
+2
-2
@@ -1,6 +1,6 @@
|
|||||||
# Workspaces and Resuming
|
# 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
|
## 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.
|
- Each agent's progress is checkpointed so resumed runs can skip completed work.
|
||||||
|
|
||||||
> [!NOTE]
|
> [!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
|
## Examples
|
||||||
|
|
||||||
|
|||||||
+107
-109
@@ -7,12 +7,12 @@
|
|||||||
|
|
||||||
# File: README.md
|
# File: README.md
|
||||||
|
|
||||||
>[!NOTE]
|
> [!NOTE]
|
||||||
> **[Better Steerability, Authentication Improvements, and the Migration to the Pi Harness](https://github.com/KeygraphHQ/shannon/discussions/348)**
|
> **[Shannon Now Runs on the Pi Harness (Beta) - run it today with `npx @keygraph/shannon@beta`](https://github.com/KeygraphHQ/shannon/discussions/358)**
|
||||||
|
|
||||||
<div align="center">
|
<div align="center">
|
||||||
|
|
||||||
<img src="./assets/github-banner.png" alt="Shannon - AI Pentester for Web Applications and APIs" width="100%">
|
<img src="./assets/github-banner.png" alt="Shannon - AI Pentester by Keygraph" width="100%">
|
||||||
|
|
||||||
# Shannon - AI Pentester by Keygraph
|
# Shannon - AI Pentester by Keygraph
|
||||||
|
|
||||||
@@ -21,6 +21,8 @@
|
|||||||
Shannon is an autonomous, white-box AI pentester for web applications and APIs. <br />
|
Shannon is an autonomous, white-box AI pentester for web applications and APIs. <br />
|
||||||
It analyzes your source code, identifies attack paths, and executes real exploits to prove vulnerabilities before they reach production.
|
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://discord.gg/9ZqQPuhJB7"><img src="./assets/discord.png" height="40" alt="Join Discord"></a>
|
||||||
@@ -35,45 +37,38 @@ It analyzes your source code, identifies attack paths, and executes real exploit
|
|||||||
## Table of Contents
|
## Table of Contents
|
||||||
|
|
||||||
- [What is Shannon?](#what-is-shannon)
|
- [What is Shannon?](#what-is-shannon)
|
||||||
- [Product Line](#product-line)
|
- [Shannon in Action](#shannon-in-action)
|
||||||
- [Shannon Lite in Action](#shannon-lite-in-action)
|
|
||||||
- [Quick Start](#quick-start)
|
- [Quick Start](#quick-start)
|
||||||
- [Key Capabilities](#key-capabilities)
|
- [Key Capabilities](#key-capabilities)
|
||||||
- [Shannon Lite and Shannon Pro](#shannon-lite-and-shannon-pro)
|
- [Editions](#editions)
|
||||||
- [Architecture](#architecture)
|
- [Architecture](#architecture)
|
||||||
- [Documentation](#documentation)
|
- [Documentation](#documentation)
|
||||||
- [Safety, Scope, and Limitations](#safety-scope-and-limitations)
|
- [Safety, Scope, and Limitations](#safety-scope-and-limitations)
|
||||||
- [License and Enterprise Licensing](#license-and-enterprise-licensing)
|
- [License and Enterprise Licensing](#license-and-enterprise-licensing)
|
||||||
|
- [About Keygraph](#about-keygraph)
|
||||||
- [Community and Support](#community-and-support)
|
- [Community and Support](#community-and-support)
|
||||||
|
|
||||||
## What is Shannon?
|
## What is Shannon?
|
||||||
|
|
||||||
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 is an autonomous 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 analyzes your web application's source code to identify potential attack vectors, then uses browser automation and command-line tools to execute real exploits against the running application and its APIs. Only vulnerabilities with a working proof-of-concept are included in the final report.
|
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 against the running application and its APIs. Only vulnerabilities with a working proof-of-concept are included in the final report.
|
||||||
|
|
||||||
|
Shannon is the agent. This repository is Shannon Open Source, the standalone pentester you run yourself. The same Shannon also powers the [Keygraph platform](https://keygraph.io), Keygraph's commercial pentesting product. See [Editions](#editions) for how the two compare.
|
||||||
|
|
||||||
### Why Shannon Exists
|
### 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.
|
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 that gap by providing on-demand, automated penetration testing that can run against every build or release.
|
Shannon closes that gap by providing on-demand, automated penetration testing that can run against every build or release.
|
||||||
|
|
||||||
## Product Line
|
## Shannon in Action
|
||||||
|
|
||||||
Shannon is developed by [Keygraph](https://keygraph.io) and available in two editions:
|
|
||||||
|
|
||||||
| Edition | License | Best For |
|
|
||||||
| --- | --- | --- |
|
|
||||||
| **Shannon Lite** | AGPL-3.0 | Local, strictly white-box testing of applications you own or are authorized to test. |
|
|
||||||
| **Shannon Pro** | Commercial | Organizations needing a continuous pentesting and AppSec platform with black-box and white-box pentesting, parsed-code SAST, CI/CD gating, verified remediation, SLA tracking, and enterprise deployment. |
|
|
||||||
|
|
||||||
## Shannon Lite in Action
|
|
||||||
|
|
||||||
<p align="center">
|
<p align="center">
|
||||||
<img src="assets/shannon-action.gif" alt="Shannon Lite running an autonomous pentest" width="100%">
|
<img src="assets/shannon-action.gif" alt="Shannon running an autonomous pentest" width="100%">
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
Sample Shannon Lite penetration test reports from intentionally vulnerable applications:
|
Sample penetration test reports from intentionally vulnerable applications, produced by Shannon Open Source:
|
||||||
|
|
||||||
| Target | Summary | Report |
|
| Target | Summary | Report |
|
||||||
| --- | --- | --- |
|
| --- | --- | --- |
|
||||||
@@ -85,14 +80,14 @@ Sample Shannon Lite penetration test reports from intentionally vulnerable appli
|
|||||||
|
|
||||||
### Prerequisites
|
### Prerequisites
|
||||||
|
|
||||||
- **Docker** - required for the worker container.
|
- **Docker**: required for the worker container.
|
||||||
- **Node.js 18+** - required for the recommended `npx` workflow.
|
- **Node.js 18+**: required for the recommended `npx` workflow.
|
||||||
- **AI provider credentials** - Anthropic is recommended; AWS Bedrock, Google Vertex AI, and compatible proxy setups are documented separately.
|
- **AI provider credentials**: Anthropic is recommended. AWS Bedrock, Google Vertex AI, and compatible proxy setups are documented separately.
|
||||||
|
|
||||||
### Run Shannon Lite
|
### Run Shannon
|
||||||
|
|
||||||
> [!WARNING]
|
> [!WARNING]
|
||||||
> Shannon Lite actively executes exploits. Run it only against applications and environments you own or have explicit written authorization to test. Do not run Shannon Lite against production systems.
|
> Shannon actively executes exploits. Run it only against applications and environments you own or have explicit written authorization to test. Do not run Shannon against production systems.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Configure credentials with the interactive wizard.
|
# Configure credentials with the interactive wizard.
|
||||||
@@ -102,52 +97,49 @@ npx @keygraph/shannon setup
|
|||||||
npx @keygraph/shannon start -u https://your-app.com -r /path/to/your-repo
|
npx @keygraph/shannon start -u https://your-app.com -r /path/to/your-repo
|
||||||
```
|
```
|
||||||
|
|
||||||
Shannon Lite 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.
|
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 source builds, authenticated scans, provider-specific setup, and platform notes, see [Documentation](#documentation).
|
For source builds, authenticated scans, provider-specific setup, and platform notes, see [Documentation](#documentation).
|
||||||
|
|
||||||
## Key Capabilities
|
## Key Capabilities
|
||||||
|
|
||||||
- **Proof-by-exploitation reports**: Shannon Lite reports validated findings with reproducible proof-of-concept steps instead of speculative warnings.
|
- **Proof-by-exploitation reports**: Shannon reports validated findings with reproducible proof-of-concept steps instead of speculative warnings.
|
||||||
- **White-box attack planning**: Shannon Lite uses source-code analysis to guide dynamic testing and focus on realistic attack paths.
|
- **White-box attack planning**: Shannon uses source-code analysis to guide dynamic testing and focus on realistic attack paths.
|
||||||
- **Autonomous execution**: Shannon Lite launches reconnaissance, vulnerability analysis, exploitation, and report generation from a single command.
|
- **Autonomous execution**: Shannon launches reconnaissance, vulnerability analysis, exploitation, and report generation from a single command.
|
||||||
- **Authenticated testing**: Shannon Lite configuration files can describe login flows, test credentials, TOTP, email-based login flows, focus areas, and rules of engagement.
|
- **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 Lite targets exploitable Injection, XSS, SSRF, Broken Authentication, and Broken Authorization issues.
|
- **OWASP-focused coverage**: Shannon targets exploitable Injection, XSS, SSRF, Broken Authentication, and Broken Authorization issues.
|
||||||
- **Resumable workspaces**: Shannon Lite can resume interrupted runs without re-running completed agents.
|
- **Resumable workspaces**: Shannon can resume interrupted runs without re-running completed agents.
|
||||||
|
|
||||||
## Shannon Lite and Shannon Pro
|
## Editions
|
||||||
|
|
||||||
This repository contains **Shannon Lite**, the AGPL-3.0 open-source CLI for strictly white-box, proof-by-exploitation testing of web applications and APIs you own or are authorized to test. Shannon Lite requires access to the target application's source code and repository layout.
|
Shannon ships in two ways: **Shannon Open Source**, the pentester you run yourself, and the **Keygraph platform**, the commercial pentesting product that runs Shannon continuously and closes the full AppSec lifecycle around it.
|
||||||
|
|
||||||
**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.
|
**Shannon Open Source** (this repository) is the standalone pentester: a CLI agent for white-box, proof-by-exploitation testing of web applications and APIs you own or are authorized to test. It reads your source, plans attacks, executes real exploits, and reports only what it can prove. It runs on demand and is complete in that lane. You point it at a target, it pentests, it reports.
|
||||||
|
|
||||||
Shannon Pro supports both **white-box and black-box agentic pentesting**: use source-aware testing when code is available, or run autonomous black-box testing against deployed applications and APIs when source access is unavailable or unnecessary.
|
The **Keygraph platform** is the enterprise-ready, continuous pentesting product powered by Shannon. In the Keygraph platform, an enhanced build of Shannon runs continuously in a hardened, orchestrated environment fed by Keygraph's full code-analysis stack. Around that engine, the platform closes the entire vulnerability lifecycle, from analysis to a verified fix:
|
||||||
|
|
||||||
Shannon Pro covers the full vulnerability lifecycle: finding exploitable issues, deduplicating and prioritizing them, syncing work into developer workflows, generating verified remediations, re-testing fixes, tracking SLAs, and producing dashboards for security reporting and compliance.
|
- **Analyze**: Code Property Graph SAST, SCA with reachability, secrets, IaC, and container scanning. First-class detection in their own right, and context that sharpens Shannon's attacks.
|
||||||
|
- **Prove**: autonomous black-box and source-aware white-box pentests turn candidate findings into proven, exploited vulnerabilities rather than speculative alerts.
|
||||||
|
- **Manage**: one canonical record per vulnerability per repository, deduplicated across every source, with ownership, status, SLA tracking, dashboards, and bidirectional Jira sync.
|
||||||
|
- **Remediate and verify**: patches written automatically and re-tested against the patched code before delivery, landing in your existing review workflow rather than auto-applied.
|
||||||
|
- **Deploy**: self-hosted and air-gapped environments, strict bring-your-own-key model access, and customer-controlled LLM gateway patterns, so source, results, and model traffic stay inside your perimeter.
|
||||||
|
|
||||||
For enterprise deployments, Shannon Pro supports self-hosted and air-gapped environments, strict bring-your-own-key model access, and customer-controlled LLM gateway patterns. Deployments can be designed so source code, scan results, prompts, completions, and model traffic remain inside your security perimeter.
|
Shannon is the proof engine at the center of the Keygraph platform. Shannon Open Source gives you that engine to run yourself. The Keygraph platform surrounds Shannon with continuous analysis, finding management, remediation, verification, and enterprise deployment.
|
||||||
|
|
||||||
Shannon Lite is a strong fit for local and project-level white-box testing. Shannon Pro is intended for organizations that need continuous AppSec coverage, black-box and white-box pentesting, centralized triage, verified remediation workflows, compliance-ready reporting, enterprise integrations, and commercial support.
|
| AppSec lifecycle stage | Shannon Open Source | Keygraph platform |
|
||||||
|
|
||||||
| Need | Shannon Lite | Shannon Pro |
|
|
||||||
| --- | --- | --- |
|
| --- | --- | --- |
|
||||||
| License | AGPL-3.0 | Commercial |
|
| Analyze | Basic LLM pass-through of source to plan attacks | Actual code-base parsing, plus Code Property Graph, SAST, SCA with reachability, secrets, IaC, and containers |
|
||||||
| White-box pentesting | Yes; source code required | Yes; source-aware testing with platform workflows |
|
| Pentest and prove | White-box only, proof by exploitation | Enhanced white-box, plus black-box and grey-box modes, run continuously |
|
||||||
| Black-box pentesting | No | Yes; autonomous testing without source-code access |
|
| Manage findings | Local Markdown report | Canonical findings system: deduplication across sources, ownership, SLA, dashboards, Jira sync, and professional pentest-grade PDF reports |
|
||||||
| Code analysis / SAST | Prompting and source pass-through to guide pentesting | Actual code parsing, Code Property Graph analysis, source-to-sink path analysis, and agentic SAST |
|
| Remediate and verify | Fix manually from the report, then re-run the full scan to verify | Automated remediation: opens a PR with the fix, verified by point re-test without re-running the full scan |
|
||||||
| AppSec coverage | OWASP-focused agentic pentesting | Agentic pentesting, SAST, SCA, secrets, IaC, containers, and business logic testing |
|
| Deploy and operate | Local CLI and Docker worker | Self-hosted, air-gapped, BYOK, continuous, enterprise integrations |
|
||||||
| CI/CD and gating | Manual/local CLI runs | Headless commercial CLI for CI/CD gating across enterprise CI/CD platforms |
|
| License and support | AGPL-3.0, community | Commercial, supported |
|
||||||
| Finding lifecycle | Local Markdown reports | Canonical findings, deduplication, ownership, status, SLA tracking, workflow sync, and reporting dashboards |
|
|
||||||
| Remediation | Manual | User-initiated remediation with verification before delivery |
|
|
||||||
| Fix verification | None; manual reruns only | Targeted verification without rerunning the entire scan, completing the remediation lifecycle |
|
|
||||||
| Enterprise deployment | Local CLI and Docker worker | Self-hosted, air-gapped, BYOK, and customer-controlled LLM gateway options |
|
|
||||||
| Support | Community | Commercial support |
|
|
||||||
|
|
||||||
Learn more on the [Keygraph website](https://keygraph.io), read the [Shannon Pro technical overview](docs/shannon-pro.md), start a free trial or 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), read the [Keygraph platform technical overview](docs/keygraph-platform.md), start a free trial or book a [demo](https://cal.com/team/keygraph/shannon-pro), or contact [shannon@keygraph.io](mailto:shannon@keygraph.io).
|
||||||
|
|
||||||
## Architecture
|
## Architecture
|
||||||
|
|
||||||
Shannon Lite uses a multi-agent workflow that combines source-code analysis with live exploitation:
|
Shannon uses a multi-agent workflow that combines source-code analysis with live exploitation:
|
||||||
|
|
||||||
```text
|
```text
|
||||||
┌──────────────────────┐
|
┌──────────────────────┐
|
||||||
@@ -208,32 +200,36 @@ Use these guides for operational detail:
|
|||||||
| [Workspaces and resuming](docs/workspaces.md) | Naming workspaces, resuming interrupted scans, and workspace storage. |
|
| [Workspaces and resuming](docs/workspaces.md) | Naming workspaces, resuming interrupted scans, and workspace storage. |
|
||||||
| [Safety and limitations](docs/safety.md) | Authorized-use requirements, non-production guidance, mutative effects, cost, and model caveats. |
|
| [Safety and limitations](docs/safety.md) | Authorized-use requirements, non-production guidance, mutative effects, cost, and model caveats. |
|
||||||
| [Coverage and roadmap](docs/coverage-roadmap.md) | Current vulnerability coverage and planned work. |
|
| [Coverage and roadmap](docs/coverage-roadmap.md) | Current vulnerability coverage and planned work. |
|
||||||
| [Shannon Pro](docs/shannon-pro.md) | Commercial platform, black-box and white-box pentesting, full lifecycle workflows, and enterprise deployment. |
|
| [Keygraph platform](docs/keygraph-platform.md) | The continuous, agentic pentesting platform: code analysis, black-box and white-box testing, finding management, remediation, verification, and enterprise deployment. |
|
||||||
|
|
||||||
## Safety, Scope, and Limitations
|
## Safety, Scope, and Limitations
|
||||||
|
|
||||||
Shannon Lite is not a passive scanner. 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 development environments with disposable data.
|
Shannon is not a passive scanner. 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 development environments with disposable data.
|
||||||
|
|
||||||
You are responsible for using Shannon Lite legally and ethically. Do not point Shannon Lite at systems, repositories, or applications you do not own or do not have explicit authorization to test.
|
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 have explicit authorization to test.
|
||||||
|
|
||||||
Important limitations:
|
Important limitations:
|
||||||
|
|
||||||
- Shannon Lite focuses on actively exploitable issues such as Injection, XSS, SSRF, Broken Authentication, and Broken Authorization. Broader static-analysis findings, including vulnerable dependencies and insecure configurations, are a core focus of Shannon Pro.
|
- 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.
|
- Findings still require human review. LLM-generated reports can contain weakly supported or incorrect details.
|
||||||
- Shannon Lite is officially supported with Claude models. Smaller, alternative, or proxied non-Claude models may be incomplete or unstable.
|
- Shannon is officially supported with Claude models. Smaller, alternative, or proxied non-Claude models may be incomplete or unstable.
|
||||||
- A full run can take roughly 1 to 1.5 hours and may incur LLM API costs depending on model pricing and application complexity.
|
- 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.
|
- Do not scan untrusted or adversarial codebases. AI-powered tools that read source code can be exposed to prompt injection.
|
||||||
|
|
||||||
Read the full [Safety and limitations](docs/safety.md) guide before running Shannon Lite in a new environment.
|
Read the full [Safety and limitations](docs/safety.md) guide before running Shannon in a new environment.
|
||||||
|
|
||||||
## License and Enterprise Licensing
|
## License and Enterprise Licensing
|
||||||
|
|
||||||
Shannon Lite is licensed under the [GNU Affero General Public License v3.0](LICENSE).
|
Shannon Open Source is licensed under the [GNU Affero General Public License v3.0](LICENSE).
|
||||||
|
|
||||||
Commercial and enterprise licensing is available for organizations that need different license terms, commercial support, private redistribution, managed-service use, or broader deployment options.
|
Commercial and enterprise licensing is available 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 [shannon@keygraph.io](mailto:shannon@keygraph.io).
|
For commercial licensing, contact [shannon@keygraph.io](mailto:shannon@keygraph.io).
|
||||||
|
|
||||||
|
## 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 engine.
|
||||||
|
|
||||||
## Community and Support
|
## Community and Support
|
||||||
|
|
||||||
**Community office hours** are available for hands-on help with bugs, deployments, and configuration questions.
|
**Community office hours** are available for hands-on help with bugs, deployments, and configuration questions.
|
||||||
@@ -242,7 +238,7 @@ For commercial licensing, contact [shannon@keygraph.io](mailto:shannon@keygraph.
|
|||||||
- Asia: Thursday, 2:00 PM IST
|
- Asia: Thursday, 2:00 PM IST
|
||||||
- [Book a slot](https://cal.com/george-flores-keygraph/shannon-community-office-hours)
|
- [Book a slot](https://cal.com/george-flores-keygraph/shannon-community-office-hours)
|
||||||
|
|
||||||
[Join Discord](https://discord.gg/cmctpMBXwE) to ask questions, share feedback, and connect with other Shannon Lite users.
|
[Join Discord](https://discord.gg/cmctpMBXwE) to ask questions, share feedback, and connect with other Shannon users.
|
||||||
|
|
||||||
At this time, Keygraph is not accepting external code contributions. Issues are welcome for bug reports and feature requests:
|
At this time, Keygraph is not accepting external code contributions. Issues are welcome for bug reports and feature requests:
|
||||||
|
|
||||||
@@ -276,10 +272,10 @@ This guide covers the source-build workflow, common CLI commands, repository pat
|
|||||||
|
|
||||||
## Clone and Build
|
## 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
|
```bash
|
||||||
# 1. Clone Shannon Lite.
|
# 1. Clone Shannon.
|
||||||
git clone https://github.com/KeygraphHQ/shannon.git
|
git clone https://github.com/KeygraphHQ/shannon.git
|
||||||
cd shannon
|
cd shannon
|
||||||
|
|
||||||
@@ -310,7 +306,7 @@ export CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000
|
|||||||
|
|
||||||
## Prepare Your Repository
|
## 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
|
```bash
|
||||||
npx @keygraph/shannon start -u https://example.com -r /path/to/repo
|
npx @keygraph/shannon start -u https://example.com -r /path/to/repo
|
||||||
@@ -341,7 +337,7 @@ Open the Temporal Web UI for detailed monitoring:
|
|||||||
open http://localhost:8233
|
open http://localhost:8233
|
||||||
```
|
```
|
||||||
|
|
||||||
Stop Shannon Lite:
|
Stop Shannon:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npx @keygraph/shannon stop
|
npx @keygraph/shannon stop
|
||||||
@@ -415,7 +411,7 @@ workspaces/{hostname}_{sessionId}/
|
|||||||
|
|
||||||
# Configuration
|
# 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
|
## Credential Precedence
|
||||||
|
|
||||||
@@ -534,7 +530,7 @@ Supported placeholders:
|
|||||||
- `$email_password`
|
- `$email_password`
|
||||||
- `$email_totp`
|
- `$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
|
```yaml
|
||||||
login_flow:
|
login_flow:
|
||||||
@@ -571,7 +567,7 @@ pipeline:
|
|||||||
|
|
||||||
# AI Providers
|
# 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
|
## Anthropic
|
||||||
|
|
||||||
@@ -594,6 +590,8 @@ ANTHROPIC_API_KEY=your-api-key
|
|||||||
CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000
|
CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000
|
||||||
```
|
```
|
||||||
|
|
||||||
|
Each tier can be pointed at any Claude model via `ANTHROPIC_SMALL_MODEL` / `ANTHROPIC_MEDIUM_MODEL` / `ANTHROPIC_LARGE_MODEL` (or the setup wizard). If you set a tier to `claude-fable-5`, note that Fable's safety classifiers route cybersecurity tasks to Opus 4.8, so those phases run on Opus 4.8 regardless.
|
||||||
|
|
||||||
## AWS Bedrock
|
## AWS Bedrock
|
||||||
|
|
||||||
Run `npx @keygraph/shannon setup` and select **AWS Bedrock**. The wizard prompts for region, bearer token, and model IDs.
|
Run `npx @keygraph/shannon setup` and select **AWS Bedrock**. The wizard prompts for region, bearer token, and model IDs.
|
||||||
@@ -620,7 +618,7 @@ ANTHROPIC_MEDIUM_MODEL=us.anthropic.claude-sonnet-4-6
|
|||||||
ANTHROPIC_LARGE_MODEL=us.anthropic.claude-opus-4-8
|
ANTHROPIC_LARGE_MODEL=us.anthropic.claude-opus-4-8
|
||||||
```
|
```
|
||||||
|
|
||||||
Shannon Lite uses three model tiers:
|
Shannon uses three model tiers:
|
||||||
|
|
||||||
- **small** for summarization
|
- **small** for summarization
|
||||||
- **medium** for security analysis
|
- **medium** for security analysis
|
||||||
@@ -662,10 +660,10 @@ Set `CLOUD_ML_REGION=global` for global endpoints, or use a specific region like
|
|||||||
|
|
||||||
## Custom Base URL
|
## 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]
|
> [!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.
|
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.
|
||||||
|
|
||||||
@@ -699,7 +697,7 @@ This guide covers platform-specific notes and Docker networking behavior.
|
|||||||
|
|
||||||
## Windows
|
## 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
|
### Ensure WSL2
|
||||||
|
|
||||||
@@ -720,7 +718,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**.
|
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
|
```bash
|
||||||
npx @keygraph/shannon setup
|
npx @keygraph/shannon setup
|
||||||
@@ -738,7 +736,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.
|
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
|
## Linux
|
||||||
|
|
||||||
@@ -764,7 +762,7 @@ Source-build equivalent:
|
|||||||
|
|
||||||
## Custom Hostnames
|
## 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:
|
To disable forwarding:
|
||||||
|
|
||||||
@@ -784,7 +782,7 @@ SHANNON_FORWARD_HOSTS=false
|
|||||||
|
|
||||||
# Workspaces and Resuming
|
# 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
|
## How Workspaces Work
|
||||||
|
|
||||||
@@ -797,7 +795,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.
|
- Each agent's progress is checkpointed so resumed runs can skip completed work.
|
||||||
|
|
||||||
> [!NOTE]
|
> [!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
|
## Examples
|
||||||
|
|
||||||
@@ -839,19 +837,19 @@ Source-build equivalents:
|
|||||||
|
|
||||||
# Safety and Limitations
|
# 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
|
## 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
|
## 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:
|
Potential mutative effects include:
|
||||||
|
|
||||||
@@ -862,17 +860,17 @@ Potential mutative effects include:
|
|||||||
- Generating unexpected outbound traffic
|
- Generating unexpected outbound traffic
|
||||||
- Writing exploit artifacts to reports or deliverables
|
- 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
|
## 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.
|
- **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 Lite is officially supported only with Claude models. Alternative models may be incomplete, inaccurate, or unstable.
|
- **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 Lite at untrusted or adversarial codebases. AI-powered tools that read source code can be influenced by malicious repository content.
|
- **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
|
## Scope of Analysis
|
||||||
|
|
||||||
Shannon Lite currently targets exploitable vulnerabilities in these classes:
|
Shannon currently targets exploitable vulnerabilities in these classes:
|
||||||
|
|
||||||
- Broken Authentication
|
- Broken Authentication
|
||||||
- Broken Authorization
|
- Broken Authorization
|
||||||
@@ -880,9 +878,9 @@ Shannon Lite currently targets exploitable vulnerabilities in these classes:
|
|||||||
- Cross-Site Scripting
|
- Cross-Site Scripting
|
||||||
- Server-Side Request Forgery
|
- 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
|
## Cost and Performance
|
||||||
|
|
||||||
@@ -896,9 +894,9 @@ If you use subscription-based model access, consider the rate-limit guidance in
|
|||||||
|
|
||||||
# Coverage and Roadmap
|
# 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 Authentication
|
||||||
- Broken Authorization
|
- Broken Authorization
|
||||||
@@ -908,29 +906,29 @@ Shannon Lite focuses on exploitable findings that can be validated against a run
|
|||||||
|
|
||||||
## Reporting Philosophy
|
## 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
|
## 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.
|
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).
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
# File: docs/shannon-pro.md
|
# File: docs/keygraph-platform.md
|
||||||
|
|
||||||
# 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
|
- Continuous AppSec coverage across many repositories and services
|
||||||
- White-box pentesting when source code is available
|
- White-box pentesting when source code is available
|
||||||
@@ -945,7 +943,7 @@ Shannon Pro is intended for organizations that need:
|
|||||||
|
|
||||||
## Full Vulnerability Lifecycle
|
## 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.
|
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.
|
2. **Normalize** results into canonical findings so duplicate scanner outputs become one tracked vulnerability per repository.
|
||||||
@@ -958,9 +956,9 @@ Shannon Pro is designed to cover the full vulnerability lifecycle, not only disc
|
|||||||
|
|
||||||
## Pentesting Modes
|
## 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.
|
- **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.
|
- **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.
|
||||||
@@ -969,7 +967,7 @@ Both modes follow the same core principle: do not report what might be vulnerabl
|
|||||||
|
|
||||||
## AppSec Coverage
|
## 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.
|
- **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.
|
- **SCA with reachability**: Dependency vulnerability analysis that prioritizes issues reachable from application entry points.
|
||||||
@@ -986,7 +984,7 @@ The result is a finding with proof of exploitability, source context when availa
|
|||||||
|
|
||||||
## Enterprise Deployment
|
## 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
|
- **Self-hosted deployments** inside the customer's cloud or infrastructure
|
||||||
- **Air-gapped deployments** for isolated environments
|
- **Air-gapped deployments** for isolated environments
|
||||||
@@ -999,7 +997,7 @@ Deployments can be designed so source code, scan results, prompts, completions,
|
|||||||
|
|
||||||
## Capability Comparison
|
## Capability Comparison
|
||||||
|
|
||||||
| Need | Shannon Lite | Shannon Pro |
|
| Need | Shannon | Keygraph platform |
|
||||||
| --- | --- | --- |
|
| --- | --- | --- |
|
||||||
| Licensing | AGPL-3.0 | Commercial |
|
| Licensing | AGPL-3.0 | Commercial |
|
||||||
| White-box pentesting | Yes; source code required | Yes; source-aware testing with platform workflows |
|
| White-box pentesting | Yes; source code required | Yes; source-aware testing with platform workflows |
|
||||||
@@ -1015,4 +1013,4 @@ Deployments can be designed so source code, scan results, prompts, completions,
|
|||||||
|
|
||||||
## Contact
|
## 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).
|
||||||
|
|||||||
@@ -1,15 +1,15 @@
|
|||||||
# Shannon
|
# Shannon
|
||||||
|
|
||||||
> Shannon is an autonomous AI pentesting project by Keygraph. This repository contains Shannon Lite, the AGPL-3.0 open-source white-box pentesting CLI. Shannon Pro is Keygraph's commercial continuous pentesting and AppSec platform.
|
> Shannon is an autonomous AI pentesting project by Keygraph. This repository contains Shannon, the AGPL-3.0 open-source white-box pentesting CLI. The Keygraph platform is Keygraph's commercial continuous pentesting and AppSec platform.
|
||||||
|
|
||||||
Use this file as the concise entry point for AI agents and LLMs reading this repository. For a single combined context file, use [llms-full.txt](llms-full.txt).
|
Use this file as the concise entry point for AI agents and LLMs reading this repository. For a single combined context file, use [llms-full.txt](llms-full.txt).
|
||||||
|
|
||||||
## Start Here
|
## Start Here
|
||||||
|
|
||||||
- [README](README.md): Main project overview, product line, quick start, Shannon Lite capabilities, Shannon Pro positioning, safety notes, licensing, and support links.
|
- [README](README.md): Main project overview, editions, quick start, Shannon capabilities, Keygraph platform positioning, safety notes, licensing, and support links.
|
||||||
- [Full Combined Context](llms-full.txt): README and documentation combined into one file for agents that need maximum local context.
|
- [Full Combined Context](llms-full.txt): README and documentation combined into one file for agents that need maximum local context.
|
||||||
|
|
||||||
## Shannon Lite
|
## Shannon
|
||||||
|
|
||||||
- [Development](docs/development.md): Source-build workflow, common CLI commands, repository paths, and output locations.
|
- [Development](docs/development.md): Source-build workflow, common CLI commands, repository paths, and output locations.
|
||||||
- [Configuration](docs/configuration.md): Authenticated testing, login flows, rules of engagement, report filters, credential precedence, adaptive thinking, and rate-limit settings.
|
- [Configuration](docs/configuration.md): Authenticated testing, login flows, rules of engagement, report filters, credential precedence, adaptive thinking, and rate-limit settings.
|
||||||
@@ -17,20 +17,20 @@ Use this file as the concise entry point for AI agents and LLMs reading this rep
|
|||||||
- [Platforms and Networking](docs/platforms.md): Windows/WSL2, Linux, macOS, Docker networking, local applications, and custom hostnames.
|
- [Platforms and Networking](docs/platforms.md): Windows/WSL2, Linux, macOS, Docker networking, local applications, and custom hostnames.
|
||||||
- [Workspaces and Resuming](docs/workspaces.md): Workspace storage, naming, resuming interrupted scans, and examples.
|
- [Workspaces and Resuming](docs/workspaces.md): Workspace storage, naming, resuming interrupted scans, and examples.
|
||||||
- [Safety and Limitations](docs/safety.md): Authorized-use requirements, non-production guidance, mutative effects, model caveats, scope limits, cost, and performance.
|
- [Safety and Limitations](docs/safety.md): Authorized-use requirements, non-production guidance, mutative effects, model caveats, scope limits, cost, and performance.
|
||||||
- [Coverage and Roadmap](docs/coverage-roadmap.md): Current Shannon Lite coverage and roadmap direction.
|
- [Coverage and Roadmap](docs/coverage-roadmap.md): Current Shannon coverage and roadmap direction.
|
||||||
|
|
||||||
## Shannon Pro
|
## Keygraph Platform
|
||||||
|
|
||||||
- [Shannon Pro](docs/shannon-pro.md): Commercial continuous pentesting and AppSec platform, including black-box and white-box pentesting, parsed-code SAST, source-to-sink analysis, remediation workflows, CI/CD gating, SLA tracking, reporting, and enterprise deployment.
|
- [Keygraph platform](docs/keygraph-platform.md): Commercial continuous pentesting and AppSec platform, including black-box and white-box pentesting, parsed-code SAST, source-to-sink analysis, remediation workflows, CI/CD gating, SLA tracking, reporting, and enterprise deployment.
|
||||||
|
|
||||||
## External Links
|
## External Links
|
||||||
|
|
||||||
- [Keygraph website](https://keygraph.io): Company and commercial product information.
|
- [Keygraph website](https://keygraph.io): Company and commercial product information.
|
||||||
- [Shannon Pro demo](https://cal.com/team/keygraph/shannon-pro): Demo and trial contact path.
|
- [Keygraph demo](https://cal.com/team/keygraph/shannon-pro): Demo and trial contact path.
|
||||||
- [Community Discord](https://discord.gg/cmctpMBXwE): Community support and discussion.
|
- [Community Discord](https://discord.gg/cmctpMBXwE): Community support and discussion.
|
||||||
|
|
||||||
## Optional
|
## Optional
|
||||||
|
|
||||||
- [Sample Juice Shop report](sample-reports/shannon-report-juice-shop.md): Shannon Lite sample report for OWASP Juice Shop.
|
- [Sample Juice Shop report](sample-reports/shannon-report-juice-shop.md): Shannon sample report for OWASP Juice Shop.
|
||||||
- [Sample c{api}tal API report](sample-reports/shannon-report-capital-api.md): Shannon Lite sample report for c{api}tal API.
|
- [Sample c{api}tal API report](sample-reports/shannon-report-capital-api.md): Shannon sample report for c{api}tal API.
|
||||||
- [Sample crAPI report](sample-reports/shannon-report-crapi.md): Shannon Lite sample report for OWASP crAPI.
|
- [Sample crAPI report](sample-reports/shannon-report-crapi.md): Shannon sample report for OWASP crAPI.
|
||||||
|
|||||||
Reference in New Issue
Block a user