Skip to content

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.

Prerequisites

Section titled “Prerequisites”
  • Docker: required for the worker container.
  • Node.js: 18+ for the npx workflow, or 20.19+ for a build from source.
  • pnpm: required for a build from source.
  • AI provider credentials: Shannon runs on Anthropic, OpenAI, xAI, AWS Bedrock, and any other provider in the Pi harness catalogue, and any of them can point at a proxy or LLM gateway through a custom base URL. You bring your own key, and Keygraph never proxies your model traffic. See AI Providers.
  • Cyber safeguards cleared with your provider: Anthropic and OpenAI apply real-time safeguards to security workloads, which can stop a scan partway through. Complete their guidance for legitimate security testers before your first run. See AI Providers.

Run Shannon

Section titled “Run Shannon”

The quickest start is the interactive launcher, which walks you through setup and your first pentest:

Terminal window
npx @keygraph/shannon@latest

Or run each step yourself:

  1. Configure credentials with the interactive wizard:

    Terminal window
    npx @keygraph/shannon@latest setup

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

    Terminal window
    npx @keygraph/shannon@latest 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.

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). Add --follow to stream the log in the same terminal until the scan finishes.

What happens during a run

Section titled “What happens during a run”

Shannon runs autonomously through authentication validation (skipped when no login is configured), pre-reconnaissance, reconnaissance, per-class vulnerability analysis, exploitation, and reporting. If you enable security code analysis, its candidates are reconciled with the pentest’s own before exploitation. A full run typically takes a few hours and may incur LLM API costs depending on model pricing and application complexity.

Monitor progress

Section titled “Monitor progress”

From another terminal, check live phase-by-phase progress, tail the log, or list scans. With no workspace given, status and logs follow the single running scan, or the most recent one when none is running.

Terminal window
npx @keygraph/shannon status [<workspace>]
npx @keygraph/shannon logs [<workspace>]
npx @keygraph/shannon scans

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

Terminal window
open http://localhost:8233

Find your report

Section titled “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 written to the workspace root as a PDF and in Markdown:

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

Exploit-mode runs also write report.sarif (SARIF 2.1.0) for GitHub code scanning or any SARIF consumer, alongside structured JSON.

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

Section titled “Stop Shannon”
Terminal window
npx @keygraph/shannon stop [<workspace>]   # Stop one scan (defaults to the single running scan; confirms first, add --yes to skip).
npx @keygraph/shannon stop --all           # Stop every scan (Temporal stays up).
npx @keygraph/shannon reset                # Stop everything and permanently remove all Temporal data (you must type confirm).

A stopped or interrupted scan resumes when you re-run start with the same -w workspace name. See Workspaces & Resuming.

Next steps

Section titled “Next steps”