# KeygraphHQ/shannon: an autonomous AI pentester that runs from your CLI > Shannon Open Source is a white-box pentester that reads your repository, plans attack paths and executes exploits in a Docker worker. Here is what it does, how to run it, and where it stops being the right tool. **KeygraphHQ/shannon** — Shannon is an autonomous white-box AI pentester that analyzes source code, finds attack paths and runs real exploits to prove vulnerabilities pre-production. - Repository: https://github.com/KeygraphHQ/shannon - Website: https://keygraph.io/ - Stars: 48,484 · Forks: 5,553 - Language: TypeScript - License: AGPL-3.0 - Published: 2026-08-08 · Updated: 2026-08-18 · Language: en - Canonical page: https://hysenlabs.com/projects/keygraphhq-shannon ## The gap Shannon was built to fill The README makes the pitch in one paragraph: AI coding tools let a team ship continuously, while a penetration test happens once a year. That leaves roughly 364 days in which vulnerable code can reach production unnoticed. Shannon is aimed at that window. It is not a scanner that flags patterns and leaves triage to a human; the README describes it as combining source-code analysis with live exploitation, and states that only vulnerabilities with a working proof-of-concept appear in the final report. The intended user is a team that owns the application source and can run Docker locally or in CI. Because Shannon reads the repository, it is white-box: the source guides which dynamic tests are worth attempting, rather than crawling a black-box target and guessing. The repository ships sample reports against OWASP Juice Shop, c{api}tal API and OWASP crAPI, which is the project's own demonstration of the report format rather than independent evidence of detection rates. ## How the agent, the worker container and Temporal fit together The layout is a pnpm monorepo. The root package.json is private and delegates to Turbo, with apps/ holding the CLI and the worker. The Dockerfile builds the worker on Chainguard Wolfi, installs Node.js 22, pnpm 10.33.0, Python 3 and Chromium, and carries the label shannon.worker-protocol="workflow-id-v1", which the CLI consumes before it trusts a container workflow-id label. That label is a compatibility contract between the two halves: a worker image without it will not be accepted. Orchestration runs on Temporal. The docker-compose.yml starts a single service, temporalio/temporal:1.7.0 in dev mode, exposing gRPC on 127.0.0.1:7233 and the built-in web UI on 127.0.0.1:8233, with a health check against the cluster. The worker process is started with the temporal:worker and temporal:start scripts, both of which run apps/worker/dist/temporal/worker.js. The data flow is therefore: CLI parses your flags, brings up the local stack, mounts the target repository read-only inside an ephemeral worker container, and the worker drives reconnaissance, analysis, exploitation and report writing as Temporal workflows. Results land in a local workspace. Model access is provider-agnostic. .env.example defines SHANNON_AI_API_KEY and SHANNON_AI_MODEL, where the model string is : split on the first colon, defaulting to anthropic:claude-sonnet-4-6. Anthropic, OpenAI, xAI, AWS Bedrock and any provider the Pi harness supports are listed, plus a custom SHANNON_AI_BASE_URL for gateways that speak the Anthropic Messages API or the OpenAI Chat Completions or Responses API. Keygraph states it never proxies your model traffic, so you bring the key. ## Installing Shannon and running a first scan The prerequisites are Docker for the worker container, Node.js 18 or newer for the npx workflow, and credentials for one supported AI provider. The README also warns that Anthropic and OpenAI apply real-time safeguards to cyber-security workloads that can interrupt a scan mid-run, and points to provider guidance for legitimate security testers. Do that before the first run, not after a scan dies halfway. The recommended path starts with an interactive wizard that writes your credentials: ```bash npx @keygraph/shannon setup ``` You should end up with a populated .env rather than a template. If you prefer to edit it by hand, copy .env.example and uncomment exactly one provider block, setting SHANNON_AI_API_KEY and SHANNON_AI_MODEL. The model value is split on the first colon, so amazon-bedrock:us.anthropic.claude-opus-4-8 and openrouter:moonshotai/kimi-k3 both parse the same way. Then start a pentest against a target you own, passing the live URL and the repository path: ```bash npx @keygraph/shannon start -u https://your-app.com -r /path/to/your-repo ``` Shannon pulls the worker image from Docker Hub, starts the local infrastructure, mounts the repository read-only in an ephemeral container, and writes results to a local workspace. The README's warning is unambiguous: run it only against applications and environments you own or have written authorization to test, and never against production systems. If you would rather not pay per token, the README notes that ChatGPT Plus and Pro subscriptions work through the OpenAI Codex setup guide, and xAI subscriptions through the Grok guide. Claude Code subscriptions are a different story: the README states the latest version does not support them, and that 1.9.0 is the final release built on the Claude Agent SDK. ## Authenticated scans, scope rules and the configuration surface Unauthenticated scanning of a login-gated app produces thin results, and the README addresses this through configuration files that describe login flows, test credentials, TOTP and email-based login, plus focus areas and rules. That is the mechanism for keeping the agent inside scope and getting it past authentication. The README does not document rollback of a partially completed run, so if a scan is interrupted by a provider safeguard or a container failure, the recovery path is not spelled out in the documentation. The safety posture is worth stating plainly. The README calls Shannon an agent that actively executes exploits, and the Dockerfile builds a worker that contains Chromium, Python and git. That combination is powerful and it is also the reason the read-only repository mount and the ephemeral container matter: the worker has tooling sufficient to do real damage if pointed at the wrong host. Treat the target URL as the primary control, not the configuration file. ## Where Shannon is the wrong tool The scope is web applications and their underlying APIs. Nothing in the README claims coverage of mobile binaries, desktop clients, network infrastructure or cloud control planes, and the worker image is built around Chromium and command-line tooling aimed at HTTP surfaces. If your risk lives in IAM policy, Kubernetes admission or a thick client, this is not the instrument. There is a second boundary that is less obvious. Shannon needs your source. A team testing a third-party product, a compiled service, or an application whose repository it cannot mount loses the white-box advantage that distinguishes it from a crawler-based scanner, and the README's architecture assumes the repository is mounted into the worker. There is also a cost dimension the README does not quantify: an autonomous agent that plans, exploits and writes reports consumes model tokens across a long run, and the project publishes no per-scan cost figure. Budget accordingly and watch the first few runs. Finally, the safeguards point cuts both ways. A provider that interrupts a cyber-security workload mid-scan is a real operational risk for unattended CI use, and the README tells you to clear that with the provider first rather than offering a workaround. ## How it differs from a traditional DAST scanner A conventional dynamic scanner such as OWASP ZAP works black-box: it crawls the running application, mutates requests, and reports findings ranked by confidence. It never reads your code, so it cannot tell that a particular endpoint reaches a raw SQL string three call frames deep, and it produces a volume of low-confidence alerts that a human must triage. Shannon inverts that. The README describes source-code analysis guiding dynamic testing to focus on realistic attack paths, and the exploitation step exists to convert a hypothesis into a reproducible proof of concept. The practical difference is the report: fewer entries, each one backed by steps someone can replay, at the cost of needing repository access, a model key and a disposable environment. If you need broad, cheap, code-free coverage of a deployed surface, a classic DAST scanner is still the simpler choice. ## Licence, editions and what upgrades cost you Shannon Open Source is licensed AGPL-3.0, and the repository carries a LICENSES/ directory and a THIRD_PARTY_NOTICES.md alongside the LICENSE file. AGPL-3.0 is a strong copyleft licence with a network clause, which matters for anyone who might expose a modified Shannon or a service built on it to remote users. Whether your specific deployment triggers those obligations is a question for your own counsel; what can be said from the repository is that the licence is AGPL-3.0, not a permissive one, and that the worker image is built and distributed through Docker Hub. The project also distinguishes editions. The README states that the same Shannon powers the Keygraph platform, a commercial pentesting product, while this repository is the standalone agent you run yourself. That split is the upgrade consideration: features can land on the platform first, and the README already documents one such divergence, the removal of Claude Code subscription support after version 1.9.0. Maintenance looks current rather than dormant: the last push was on 2026-08-28, the same day as the v2.7.0 release, following v2.6.0 on 2026-08-27 and v2.5.4 on 2026-08-26. Frequent releases mean you should pin the npx package version in CI rather than tracking latest, or a container protocol change can break a pipeline you did not touch. ## Conclusion Shannon fits teams that ship web applications and APIs continuously, own the source, and want validated exploit evidence between annual manual tests. It does not fit anyone who cannot give it a disposable environment, cannot clear their provider's cyber safeguards, or needs coverage of thick clients, mobile binaries or infrastructure outside the web surface. Before adopting it, run the setup wizard, point a scan at one non-production target with a known vulnerability, and confirm the report contains a reproducible proof of concept rather than a speculative warning. Then check the AGPL-3.0 obligations against how you intend to distribute anything built on the worker image. ## FAQ ### How do I install Shannon AI? Install Docker and Node.js 18 or newer, then run npx @keygraph/shannon setup to configure provider credentials interactively. After that, npx @keygraph/shannon start pulls the worker image and starts the local infrastructure. ### How do I use Shannon? Run the setup wizard, then start a pentest with the -u flag for the target URL and the -r flag for the repository path, for example npx @keygraph/shannon start -u https://your-app.com -r /path/to/your-repo. The README states results are written to a local workspace. ### What is Shannon AI from Keygraph? It is an autonomous AI pentester for web applications and APIs that analyzes source code to identify attack vectors and then executes real exploits. According to the README, only vulnerabilities with a working proof-of-concept are included in the final report. ### Which AI providers can Shannon use? The README lists Anthropic, OpenAI, xAI, AWS Bedrock, any other provider in the Pi harness catalogue, and any endpoint that speaks the Anthropic Messages API or the OpenAI Chat Completions or Responses API through a custom base URL. You supply your own key and Keygraph states it does not proxy model traffic. ### Can Shannon run against a production application? No. The README carries an explicit warning to run it only against applications and environments you own or have written authorization to test, and not against production systems, because it actively executes exploits. ## Sources - [Official documentation](https://keygraph.io/) - [Official README](https://github.com/KeygraphHQ/shannon#readme) - [Project repository](https://github.com/KeygraphHQ/shannon) - [Release notes](https://github.com/KeygraphHQ/shannon/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/keygraphhq-shannon