# Shannon

> Draft · awaiting review.

> Autonomous white-box AI penetration tester for web apps and APIs; reports only vulnerabilities it proves by exploitation.

- Badge: `reach 3 · not run yet`
- Type: Agent; tier: not run yet
- Tasks: Web and API testing; mission: Offensive; works with: Standalone (own model access)
- Source: https://github.com/KeygraphHQ/shannon, pinned to `f6a770d` (v3.4.0), licence AGPL-3.0
- Last checked: 2026-10-19; next check: 2027-01-17; method v0.1, reach-v0.1

## At a glance

- **What it is:** Shannon is an autonomous AI pentester for web applications and APIs. An agent is a program with its own model access that works through a task on its own.
- **Made for:** It tests web applications and their APIs by combining source-code analysis with live exploitation against the running application. +1 more
- **Runs:** In a container on your machine. Other modes: source build (local); analysis-only. Listens by default: Temporal gRPC on 127.0.0.1:7233 (sign-in not read); 2 listeners in all.
- **Sends data to:** Model provider (always), Target URL (always), Docker Hub (by default), pi model catalogue (always), Anthropic / OpenAI (by default), Anthropic (by default). Other connections not ruled out: read in the documentation and the cited code, not searched in full.
- **Can change things:** Changes, runs commands, according to the capabilities read. Partly listed: Reconciliation and miscellaneous-exploit details, Capella stage internals, login/TOTP helper scripts and CLI lifecycle commands were not listed as separate groups.
- **Needs:** Docker is required for the worker container · Node.js 18+ for the npx workflow · A key in SHANNON_AI_API_KEY for the provider SHANNON_AI_MODEL names; Bedrock uses its AWS_ variables instead · +3 more

Profile read at commit `f6a770d` on 2026-10-25; every fact cites a file and line at that commit.

## What it does

Shannon is an autonomous AI pentester for web applications and APIs. (README.md#L14)

Made for (the author says):

- It tests web applications and their APIs by combining source-code analysis with live exploitation against the running application. (README.md#L75)
- It is meant to run exploitation-backed tests against staging environments and releases as part of the development lifecycle. (README.md#L109)

Documented uses:

- Test a running web app and its API for injection, XSS, SSRF, broken authentication and broken authorization. [Web and API testing] (README.md#L174)
- Run Shannon through the GitHub Action or GitLab CI/CD component and gate releases on proven vulnerabilities. [Finding validation] (README.md#L176)
- Run agentic static analysis that reads the repository for vulnerabilities before the pentest. [Code review and static analysis (SAST)] (docs/configuration.md#L123)

Not for (the author says):

- Only for applications and environments the user owns or has explicit written authorization to test. (README.md#L142)
- Not to be run against production systems. (docs/safety.md#L15)
- Not for untrusted or adversarial codebases, because source-reading AI tools can be steered by malicious repository content. (docs/safety.md#L32)

## What it can do

| Group | What it covers | Effect | On by default |
|---|---|---|---|
| Pre-Recon / Recon | Pre-recon analyzes source code to build an architectural baseline; recon maps the attack surface from those initial findings. (CLAUDE.md#L151-152) | reads, runs commands | yes |
| Vulnerability Analysis | Five parallel vulnerability analysis agents cover injection, xss, auth, authz and ssrf. (CLAUDE.md#L153) | reads, runs commands | yes |
| Exploitation | Exploitation agents actively execute attacks to confirm vulnerabilities, which can mutate application state and data. (docs/safety.md#L13) | changes, runs commands | yes |
| Agentic SAST (Capella) | Optional agentic static analysis runs as a child workflow before the pentest when agentic_sast.enabled is "true". (CLAUDE.md#L159) | reads | no |
| Reporting | Reporting produces PDF and Markdown reports plus JSON and SARIF 2.1.0. (README.md#L177) | reads, changes | yes |
| Agent tools (pi harness) | Every agent gets the built-in tools read, bash, edit, write, grep, find and ls. (apps/worker/src/ai/pi/pi-executor.ts#L60) | reads, changes, runs commands | yes |
| playwright-cli | A playwright-cli skill lets agents drive a real browser through the playwright-cli binary to navigate and click. (apps/worker/src/ai/pi/pi-executor.ts#L70) | reads, runs commands | yes |

Partly listed: Reconciliation and miscellaneous-exploit details, Capella stage internals, login/TOTP helper scripts and CLI lifecycle commands were not listed as separate groups.

## How it runs

Temporal infrastructure runs via docker-compose.yml, and each scan runs in its own ephemeral docker run --rm worker container with a unique task queue and isolated volume mounts. (CLAUDE.md#L124)

- Starts: In a container on your machine. Runs in an ephemeral Docker worker container started by the CLI. (README.md#L278)
- Can also run: In a container on your machine (source build (local), switch `SHANNON_LOCAL=1`). Local (source-build) mode activates when the ./shannon entry point sets SHANNON_LOCAL=1; otherwise the CLI runs in npx mode. (CLAUDE.md#L22)
- Can also run: In a container on your machine (analysis-only, switch `exploit: "false"`). Setting exploit: "false" in the YAML configuration skips the exploitation phase. (docs/configuration.md#L51-52)
- Your machine: **shannon CLI**: The CLI's Docker orchestration handles the compose lifecycle, network, image pull or build, and worker spawning. (apps/cli/src/docker.ts#L2)
- Container on your machine: **Temporal (shannon-temporal)**: Temporal server container started from the temporalio/temporal:1.7.0 image. (docker-compose.yml#L7)
- Container on your machine: **Worker container**: Per-scan worker container that runs apps/worker/dist/temporal/worker.js with the target URL and the repository path inside the container. (apps/cli/src/docker.ts#L503)
- Outside your machine: **Model provider**: The model provider or endpoint the user configures; model requests go straight to it and carry source and application context. (README.md#L366)
- Outside your machine: **Target application**: The running target application, against which exploitation agents attempt proof-of-concept attacks. (README.md#L272)
- Listens: Temporal gRPC on 127.0.0.1:7233.: this machine only (loopback), sign-in not read, by default (docker-compose.yml#L11)
- Listens: Temporal Web UI on 127.0.0.1:8233.: this machine only (loopback), sign-in not read, by default (docker-compose.yml#L12)
- Sends data to Model provider (model provider, always): Model requests carrying source and application context go to the configured provider or endpoint. (README.md#L366)
- Sends data to Target URL (your targets, always): Attacks and browser sessions go to the target URL given with -u. (apps/cli/src/help.ts#L29)
- Sends data to Docker Hub (download, by default): With the documented npx launch, Shannon pulls the worker image from Docker Hub and starts local infrastructure. (README.md#L154)
- Sends data to pi model catalogue (download, always): The worker builds its model runtime with allowModelNetwork: true, letting pi fetch its model catalogue over the network. (apps/worker/src/ai/models.ts#L243)
- Sends data to Anthropic / OpenAI (model provider, by default): For Anthropic and OpenAI, a preflight cyber-access verification request checks whether the provider's cyber safeguards allow the workload. (docs/ai-providers.md#L62)
- Sends data to Anthropic (model provider, by default): If SHANNON_AI_MODEL is unset, Shannon uses anthropic:claude-sonnet-4-6 as its model. (docs/ai-providers.md#L20)

## What you need

- Container runtime: Docker is required for the worker container. (README.md#L132)
- Runtime: Node.js 18+ for the npx workflow. (README.md#L133)
- Model key: A key in SHANNON_AI_API_KEY for the provider SHANNON_AI_MODEL names; Bedrock uses its AWS_ variables instead. (docs/ai-providers.md#L20)
- Account: When the provider is Anthropic or OpenAI, their real-time cyber safeguards apply and can interrupt a scan; their guidance for security testers is to be completed before the first run. (README.md#L135)
- Authorisation: Explicit written authorization from the owner of the target system. (docs/safety.md#L7)
- Operating system: On Windows it needs WSL2; native Windows is not supported. (docs/platforms.md#L7)
- Installer: The documented launch runs the latest npm release through npx, without pinning a version. (README.md#L23)
- Installer: saveConfig writes the CLI config to ~/.shannon/config.toml with 0o600 permissions. (apps/cli/src/config/writer.ts#L22)
- Installer: The CLI removes local keygraph/shannon Docker images whose tag does not match the current version. (apps/cli/src/docker.ts#L660-669)
- Installer: The CLI creates its workspaces directory under ~/.shannon/workspaces in npx mode and under ./workspaces in local mode. (apps/cli/src/home.ts#L33-38)
- Installer: In npx mode the setup wizard saves the provider credentials in ~/.shannon/config.toml, which the CLI reads after environment variables. (docs/configuration.md#L12-15)

## Limits and risks

- The worker container runs with seccomp=unconfined for every process inside it. (apps/cli/src/docker.ts#L497)
- The pi-permission-system config Shannon writes sets '*': 'allow' and external_directory: 'allow' for agent tools. (apps/worker/src/ai/pi/permission-system.ts#L87-91)
- The host's /etc/hosts entries are forwarded into the worker unless SHANNON_FORWARD_HOSTS is false. (apps/cli/src/docker.ts#L362)
- If a pi auth host path is set, it is bind-mounted into the worker at PI_AUTH_CONTAINER_PATH without the :ro flag. (apps/cli/src/docker.ts#L487)
- Reports can contain weakly supported or incorrect details and need human review. (README.md#L308)
- A full run takes about 1 to 1.5 hours and incurs LLM API costs. (docs/safety.md#L50)
- Issues it cannot exploit, such as many dependency, configuration or policy findings, are not reported. (docs/safety.md#L44)
- Exploitation agents can create users, submit forms, mutate application state, trigger outbound requests and otherwise affect the target system. (README.md#L301)
- The worker writes a Playwright cli.config.json with stealth defaults that playwright-cli open loads for browser sessions; an existing config is not overwritten. (apps/worker/src/ai/playwright-config-writer.ts#L7-10)
- The worker mounts the target repository into the container read-only. (apps/cli/src/docker.ts#L453-455)
- The host workspaces directory is mounted into the worker at /app/workspaces without the :ro flag, so the worker can write to it. (apps/cli/src/docker.ts#L453-454)
- Four writable mounts backed by the run's workspace folder shadow .shannon/deliverables, .shannon/scratchpad, .shannon/.playwright-cli and .playwright inside the read-only repository mount. (apps/cli/src/docker.ts#L457-463)
- On Linux without Podman, the worker starts with --add-host host.docker.internal:host-gateway, so that name resolves to the host. (apps/cli/src/docker.ts#L309-314)
- Loopback entries (127.x, ::1) forwarded from the host's /etc/hosts are rewritten to host-gateway, so those names point to the host instead of the container. (apps/cli/src/docker.ts#L386-389)
- The author's safety guide recommends running Shannon inside a disposable virtual machine for maximum isolation. (docs/safety.md#L26)

## Rights in plain language

- Declared: files 1 (reads outside the project), network 1 (talks only to declared hosts), execution 2 (runs shell commands or eval), secrets 1 (uses one scoped token), persistence 2 (changes config or installs globally), approval 2 (has broad pre-approvals).
- Code: reach 3 (privileged): files 2 (writes outside the project), network 2 (talks to any host), execution 2 (runs shell commands or eval), persistence 2 (changes config or installs globally), approval 3 (bypasses approval).
- Lab: not run yet.

Why three columns? Declarations are often incomplete and scanners can be bypassed, so we run each tool once and compare.

## Privilege Reach

Reach level 3 (privileged).

| Right | Declared | Code | Lab |
|---|---|---|---|
| Files: where does it read and write? | 1 reads outside the project | 2 writes outside the project | not run yet |
| Network: whom does it talk to? | 1 talks only to declared hosts | 2 talks to any host | not run yet |
| Execution: what does it run? | 2 runs shell commands or eval | 2 runs shell commands or eval | not run yet |
| Secrets: which credentials does it touch? | 1 uses one scoped token | 1 uses one scoped token | not run yet |
| Persistence: what survives the run? | 2 changes config or installs globally | 2 changes config or installs globally | not run yet |
| Approval: does it ask before acting? | 2 has broad pre-approvals | 3 bypasses approval | not run yet |

0 contained · 1 scoped · 2 open · 3 privileged · ? no evidence · 0 never means safe

## Install

### Upstream (linked)

Quoted from `README.md#L146-151` at the pinned commit (not a command to copy): `npx @keygraph/shannon@latest setup
npx @keygraph/shannon@latest start \
  -u https://your-app.com \
  -r /path/to/your/repo`


### Run it with least privilege

- note: `derived from the code, not tested in the lab; run only against systems you are authorised to test, inside the ephemeral Docker worker, and never point it at an untrusted codebase; for maximum isolation run it inside a disposable VM, as its own safety guide advises`

- derived, not tested: proposed from the code analysis

## Lab runs

Not run yet.

## Questions and answers

**Why compare declared, code and lab?**

Declarations are often incomplete and scanners can be bypassed, so we run each tool once and compare.

**What rights does Shannon declare?**

files 1 (reads outside the project), network 1 (talks only to declared hosts), execution 2 (runs shell commands or eval), secrets 1 (uses one scoped token), persistence 2 (changes config or installs globally), approval 2 (has broad pre-approvals).

**What does its code suggest?**

reach 3 (privileged): files 2 (writes outside the project), network 2 (talks to any host), execution 2 (runs shell commands or eval), persistence 2 (changes config or installs globally), approval 3 (bypasses approval).

**What did it use when it ran in the lab?**

not run yet.

**Was it tried, and when?**

Not yet (tier listed).

**What changed since the last check?**

Upstream last pushed 2026-10-15; 0 release(s) since the pinned version.

**How do I run it with least privilege?**

Derived, not tested: note: derived from the code, not tested in the lab; run only against systems you are authorised to test, inside the ephemeral Docker worker, and never point it at an untrusted codebase; for maximum isolation run it inside a disposable VM, as its own safety guide advises

Method: https://readbeforerun.ai/method/