Shannon Quick Start

There are two ways to run Shannon: the npx workflow (fastest, no clone) and a build from source using a local clone. Pick a tab below. Your choice is remembered across every page on this site.

Authorized use only

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. See Safety & Limitations.

Prerequisites

• Docker: required for the worker container.
• Node.js 18+: required for the npx workflow.
• pnpm: required for a build from source.
• AI provider credentials: Anthropic is recommended. AWS Bedrock, Google Vertex AI, and compatible proxy setups are documented in AI Providers.

Run Shannon

npx (recommended)

1. Configure credentials with the interactive wizard:

   npx @keygraph/shannon setup

2. Run a pentest against a source-available target:

   npx @keygraph/shannon start -u https://your-app.com -r /path/to/your-repo

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.

Build from source

1. Clone and build Shannon:

   git clone https://github.com/KeygraphHQ/shannon.git
   cd shannon
   cp .env.example .env      # add your ANTHROPIC_API_KEY
   pnpm install
   pnpm build

2. Run a pentest against a source-available target:

   ./shannon start -u https://your-app.com -r /path/to/your-repo

See Build from source & CLI for the full local-development workflow.

The -u flag is the target URL. The -r flag is the path to the target’s source repository (mounted read-only inside the worker).

What happens during a run

Shannon runs autonomously through pre-reconnaissance, reconnaissance, per-class vulnerability analysis, exploitation, and reporting. A full run typically takes roughly 1 to 1.5 hours and may incur LLM API costs depending on model pricing and application complexity.

Monitor progress

Stream logs or check status from another terminal:

npx (recommended)

npx @keygraph/shannon logs <workspace>
npx @keygraph/shannon status

Build from source

./shannon logs <workspace>
./shannon status

For detailed, per-step monitoring, open the Temporal Web UI:

open http://localhost:8233

Find your report

Results are saved to the workspaces directory: ~/.shannon/workspaces/ in npx mode, or ./workspaces/ in source-build mode. The final report is surfaced at the workspace root:

workspaces/{hostname}_{sessionId}/Security-Assessment-Report.md

Run internals (deliverables, logs, prompts, and session state) live under a hidden .shannon/ directory inside the workspace. Use the -o <path> flag to copy deliverables to a custom output directory after a run completes.

Stop Shannon

npx (recommended)

npx @keygraph/shannon stop                 # Stop the running scan and infrastructure.
npx @keygraph/shannon stop --clean         # Stop and clean up (confirms first; add --yes to skip).
npx @keygraph/shannon uninstall            # Remove Shannon's local infrastructure (confirms first; add --yes to skip).

Build from source

./shannon stop                 # Stop the running scan and infrastructure.
./shannon stop --clean         # Stop and clean up (confirms first; add --yes to skip).

Next steps

• Test a login-gated application with the Configuration and Authenticated Testing guides.
• Prefer running from a local clone? See Build from source & CLI.
• Testing an app on your own machine? See Platforms & Networking for the host.docker.internal workaround.