mirror of https://github.com/KeygraphHQ/shannon.git synced 2026-07-05 04:38:03 +02:00

Files

T

ezl-keygraph 00e56455df feat(cli): restructure run folder and improve terminal UX (#384 )

* feat: surface report at run root and nest run internals under .shannon

* feat: use plain-language wording in user-facing terminal messages

* feat(cli): guide users to watch scan progress and surface report path on start

* docs: sync run-folder layout and CLI wording across docs and comments

* feat(cli): add version command reporting package version or git SHA

* feat(cli): detect TTY for interactive prompts, color, and progress output

* docs: document --yes flag, version command, and tty module

* fix(cli): FORCE_COLOR precedence and plain uninstall --yes output

* fix(cli): respect empty NO_COLOR

* fix(cli): let NO_COLOR take precedence over FORCE_COLOR

* docs: mark claude-code-router integration as removed

2026-07-04 21:14:04 +05:30

3.8 KiB

Raw Blame History

Source Build and CLI Commands

This guide covers the source-build workflow, common CLI commands, repository paths, and output locations. For the fastest first run, use the npx workflow in the main README.

Prerequisites

Docker
Node.js 18+
pnpm
AI provider credentials

Clone and Build

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.

# 1. Clone Shannon.
git clone https://github.com/KeygraphHQ/shannon.git
cd shannon

# 2. Configure credentials.
cp .env.example .env

# 3. Install dependencies and build.
pnpm install
pnpm build

# 4. Run a pentest.
./shannon start -u https://your-app.com -r /path/to/your-repo

At minimum, your .env file should include one supported AI provider credential, such as:

ANTHROPIC_API_KEY=your-api-key
CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000

Environment variables can also be exported directly:

export ANTHROPIC_API_KEY="your-api-key"
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000

Prepare Your Repository

Shannon can scan any repository on your machine. Pass an absolute or relative path with -r.

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

The target repository is mounted read-only inside the worker container.

Common Commands

Monitor progress:

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

Source-build equivalents:

./shannon logs <workspace>
./shannon status
./shannon version

Open the Temporal Web UI for detailed monitoring:

open http://localhost:8233

Stop Shannon:

npx @keygraph/shannon stop
npx @keygraph/shannon stop --clean       # confirms first; add --yes (or -y) to skip
npx @keygraph/shannon uninstall          # confirms first; add --yes (or -y) to skip

Source-build equivalents:

./shannon stop
./shannon stop --clean                   # add --yes (or -y) to skip the confirmation

Usage examples:

# Basic pentest.
npx @keygraph/shannon start -u https://example.com -r /path/to/repo

# With a configuration file.
npx @keygraph/shannon start -u https://example.com -r /path/to/repo -c /path/to/my-config.yaml

# Custom output directory.
npx @keygraph/shannon start -u https://example.com -r /path/to/repo -o ./my-reports

# Named workspace.
npx @keygraph/shannon start -u https://example.com -r /path/to/repo -w q1-audit

# List all workspaces.
npx @keygraph/shannon workspaces

Source-build examples:

./shannon start -u https://example.com -r /path/to/repo
./shannon start -u https://example.com -r /path/to/repo -c /path/to/my-config.yaml
./shannon start -u https://example.com -r /path/to/repo -o ./my-reports
./shannon start -u https://example.com -r /path/to/repo -w q1-audit
./shannon workspaces

# Rebuild the worker image.
./shannon build --no-cache

Output and Results

Results are saved to the workspaces directory:

./workspaces/ in source-build mode
~/.shannon/workspaces/ in npx mode

Use -o <path> to copy deliverables to a custom output directory after a run completes.

Output structure — the run directory's top level holds only the final report; everything else is nested under a hidden .shannon/ directory:

workspaces/{hostname}_{sessionId}/
|-- Security-Assessment-Report.md   # the final report (the deliverable)
`-- .shannon/                       # internals
    |-- deliverables/               # report source, per-phase analysis, queues
    |-- agents/                     # per-agent logs
    |-- prompts/                    # rendered prompts
    |-- scratchpad/                 # screenshots, scripts
    |-- session.json                # resume state
    `-- workflow.log

3.8 KiB Raw Blame History