ReadBeforeRunAgentic Security Field Guide

Catalog / Agent

Shannon

Draft · awaiting review

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

For Web and API testingWorks with Standalone (own model access)Maintained KeygraphHQ, last push 2026-10-15

AgentAn agent is a program with its own model access that works through a task on its own. by KeygraphHQ · read from the code at f6a770d (v3.4.0) on 2026-10-19The date we last read the tool’s files. The code after “at” names the exact version (the git commit) we read; a newer version may differ. · Not run yet.Whether we have run the tool in our lab. “Did more than it said” means the run used rights its description does not name; “did no more than it said” means it stayed within them.

Code showsWhat a reading of the code found the tool can do, at the checked version, in the words of the rights table in the record. It is a ceiling, not what the tool did. A right marked unknown has no evidence either way, and that never counts as harmless.

What the code shows, worst first. No run advice yet: the one word needs a read under the full rule.

  1. Approval. The worker container runs with seccomp unconfined and the agent runs with an allow-all permission posture and no per-step approval.

    docker.ts L497

  2. Files. The agent permission posture allows reads and writes outside the read-only repo.

    permission-system.ts L90

  3. Network. An arbitrary user-supplied target URL is passed to the worker, which makes outbound requests to it.

    docker.ts L503

  4. Execution. Every agent gets a free bash tool plus write and edit.

    pi-executor.ts L60

  5. Persistence. The CLI rewrites the Temporal namespace retention and runs a persistent container with a named volume.

    docker.ts L230

Before first useSettings for your AI client that limit the tool to the rights its task needs; derived from the code unless marked tested. derived from the code, not tested

  1. Run only against systems you are authorised to test, inside the ephemeral Docker worker, and never point it at an untrusted codebase.
  2. For maximum isolation run it inside a disposable VM, as its own safety guide advises.

What we checked, and what we foundDisagree?

Agent · code showsreach 3 · privileged
222123FilesNetworkExecutionSecretsPersistenceApproval

What the code can reach, 0 to 3 per right; a dashed point means no evidence, never zero. The three readings

Is it for you?

Made for
  • It tests web applications and their APIs by combining source-code analysis with live exploitation against the running application.
  • It is meant to run exploitation-backed tests against staging environments and releases as part of the development lifecycle.
Use it when
  • Test a running web app and its API for injection, XSS, SSRF, broken authentication and broken authorization Web and API testing
  • Run Shannon through the GitHub Action or GitLab CI/CD component and gate releases on proven vulnerabilities Finding validation
  • Run agentic static analysis that reads the repository for vulnerabilities before the pentest Code review and static analysis (SAST)
Not for
  • Only for applications and environments the user owns or has explicit written authorization to test.
  • Not to be run against production systems.
  • Not for untrusted or adversarial codebases, because source-reading AI tools can be steered by malicious repository content.
You need
  • 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

Details

Install

linked, not distributed: the Field Guide does not bundle agents or MCP servers

Upstream (linked)

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

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

End of the card. Below: what we checked, and what we found.MarkdownJSON

The record · every value with its evidence

What we checked, and what we found.

Profile read at commit f6a770d on 2026-10-25: 61 facts, each with its quoted line confirmed by script; not installed, not run in the lab.Each fact was read from the tool's files at the checked version and links to the line it comes from. Where nothing was found, the page says so instead of assuming “none”.

Selected by criteria v0.1, approved by Ilja Schlak: awaiting approval. Each section opens with the answer; the file and line of every fact follow it.

What it can change the capability groups as upstream groups them, worst first

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.

GroupWhat it coversEffectOn by default
Pre-Recon / ReconPre-recon analyzes source code to build an architectural baseline; recon maps the attack surface from those initial findings. CLAUDE.md L151-152reads, runs commandsyes
Vulnerability AnalysisFive parallel vulnerability analysis agents cover injection, xss, auth, authz and ssrf. CLAUDE.md L153reads, runs commandsyes
ExploitationExploitation agents actively execute attacks to confirm vulnerabilities, which can mutate application state and data. safety.md L13changes, runs commandsyes
Agent tools (pi harness)Every agent gets the built-in tools read, bash, edit, write, grep, find and ls. pi-executor.ts L60reads, changes, runs commandsyes
playwright-cliA playwright-cli skill lets agents drive a real browser through the playwright-cli binary to navigate and click. pi-executor.ts L70reads, runs commandsyes
ReportingReporting produces PDF and Markdown reports plus JSON and SARIF 2.1.0. README.md L177reads, changesyes
Agentic SAST (Capella)Optional agentic static analysis runs as a child workflow before the pentest when agentic_sast.enabled is "true". CLAUDE.md L159readsno, optional

Where it sends data and who can connect to it

6 outside connections found in the files read: Model provider, Target URL, Docker Hub, pi model catalogue, Anthropic / OpenAI, Anthropic.

2 listeners in the files read.

Other connections not ruled out: read in the documentation and the cited code, not searched in full.

How it runs generated from the files read, never drawn by hand

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

Your machine

Programs and files on the machine where you run the tool.

Container on your machine

Parts inside a container that the tool starts on your machine.

Outside your machine

Remote services: vendor APIs, model providers, targets, telemetry endpoints. Data sent here leaves your machine.

The six rights, read three waysThe six rights a tool can take (files, network, execution, secrets, persistence, approval), each read three ways and rated 0 to 3. 0 never means safe; “?” means no evidence. what the author says, what the code shows, what one lab run showed

Level 3 (privileged), read from the code. Not run in our lab yet.

RightAuthor sayswhat the author saysCode showswhat static analysis findsRun showedwhat one lab run showed
Fileswhere does it read and write?
Networkwhom does it talk to?
Executionwhat does it run?
Secretswhich credentials does it touch?
Persistencewhat survives the run?
Approvaldoes it ask before acting?

0 contained · 1 scoped · 2 open · 3 privileged · ? no evidence · 0 never means safe · zero means: none declared (Declared), none found (Code), none observed (Lab)

Author says: the evidence

  • Files · 1_target.txt L4 author declares the target repo is mounted read-only
  • Network · 1_exploit-scope.txt L2 author constrains exploitation to the single declared target URL
  • Execution · 2README.md L77 author states the agent runs command-line tools and browser automation to execute real exploits
  • Secrets · 1README.md L134 author states the user supplies one provider key and Keygraph never proxies traffic
  • Persistence · 2development.md L95 author declares a persistent local Temporal service that stays up across scans
  • Approval · 2README.md L171 author declares end-to-end autonomous execution from a single command

Code shows: the evidence

  • Files · 2permission-system.ts L90 the agent permission posture allows reads and writes outside the read-only repo
  • Network · 2docker.ts L503 an arbitrary user-supplied target URL is passed to the worker, which makes outbound requests to it
  • Execution · 2pi-executor.ts L60 every agent gets a free bash tool plus write and edit
  • Secrets · 1env.ts L103 forwards only the selected provider's named credential variables into the container, not the whole environment
  • Persistence · 2docker.ts L230 the CLI rewrites the Temporal namespace retention and runs a persistent container with a named volume
  • Approval · 3docker.ts L497 the worker container runs with seccomp unconfined and the agent runs with an allow-all permission posture and no per-step approval

Valid for commit f6a770d (v3.4.0) · checked 2026-10-19 · method reach-v0.1The published rules we follow: how tools are selected, how their rights are read and rated, how a lab run is done.

Limits and risks what the files say that fits nowhere else, and what this reading does not cover

What you need and what the documented installer does

KindWhat
AI clientStandalone (own model access)
Container runtimeDocker is required for the worker container. README.md L132
RuntimeNode.js 18+ for the npx workflow. README.md L133
Model keyA key in SHANNON_AI_API_KEY for the provider SHANNON_AI_MODEL names; Bedrock uses its AWS_ variables instead. ai-providers.md L20
AccountWhen 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
AuthorisationExplicit written authorization from the owner of the target system. safety.md L7
Operating systemOn Windows it needs WSL2; native Windows is not supported. platforms.md L7

What the documented installer does

Lab runs one run is an observation, not a benchmark

No lab run yet. Once we run it, this section shows what it did and whether it did more than it said.

About this entry

AutonomyHow much the tool decides on its own, from 0 (every step is yours) to 5 (runs a whole task unattended), as the author describes it.
level 3 of 5
Source
github.com/KeygraphHQ/shannon · AGPL-3.0 · manifest package.json
Version readThe install command installs exactly the version we checked (the pinned git commit), so what you get is what the card describes.
f6a770d · v3.4.0 · last upstream push 2026-10-15 · no release since the pinned commit (current v3.4.0)
In the catalog
listed · added 2026-10-19 · last checked 2026-10-19 · next check 2027-01-17 · fresh
ScannersA scan of the tool's files with a scanner for malicious patterns. “Pending” means it has not run yet.
cisco-skill-scanner: not run, pending
Changes
none since the entry was added on 2026-10-19
MethodThe published rules we follow: how tools are selected, how their rights are read and rated, how a lab run is done.
v0.1 · reach-v0.1 · badge · the rules

Disagree?

Dispute a value with evidence (file, line, commit): write to hello@readbeforerun.ai. A dispute is checked against the pinned commit; a changed value is logged under Changes.

This entry as Markdownas JSON

How this entry was checked, and how to cite it

Selected by the published criteria (method v0.1). What the author says comes only from author statements; what the code shows comes from the code and manifests at commit f6a770d, each with one evidence line. A “?” means no evidence, never zero; zero never means safe.

The descriptive profile (what it does, can do, how it runs, what it needs) was read through the same isolated pipeline at commit f6a770d on 2026-10-25: one reader proposed every fact with a quoted line, a script confirmed each quoted line (61 of 61), and a second reader checked each sentence against its lines. Where nothing was found, the page says so instead of assuming “none”.

Known issues and limits: remote server-side behaviour stays “?”; the lab is not your production; static analysis can miss runtime behaviour.

Placement, badges or fast tracks are not for sale. The author is employed by an IT consultancy; the company has no influence on selection, execution or result.

Cite this:

Ilja Schlak. "Shannon". Agentic Security Field Guide, checked 2026-10-19, method reach-v0.1. https://readbeforerun.ai/catalog/keygraph-shannon/

The method · the rules

For maintainers

Badge for your README (reach 3 · not run yet):

[![reach 3 · not run yet](https://readbeforerun.ai/badge/keygraph-shannon.svg)](https://readbeforerun.ai/catalog/keygraph-shannon/)

Dispute a value with evidence (file, line, commit): write to hello@readbeforerun.ai. A dispute is checked against the pinned commit; a changed value is logged under Changes.

Claim the entry with a fieldguide.yaml in your repository: planned.

Other tools for the same task

Task: Web and API testing. The task pages compare every tool side by side.
  1. 21223?
    Webapp Testing ChecklistSkill · by AccessITGroup · reach 3, privilegedDraft · awaiting review

    Agent skill that walks an authorized web application test through the OWASP WSTG checklist and writes a findings report.

    Can add autostart, users or keys · write outside the project · run shell commands or eval · +1 more · Approval: no evidence · not run yet · checked 2026-10-21

    Code shows
  2. 222222
    hackingBuddyGPTAgent · by ipa-lab · reach 2, openDraft · awaiting review

    Open-source framework for building LLM-driven security-testing agents, with use cases for Linux privilege escalation and web API testing.

    Can write outside the project · talk to any host · run shell commands or eval · +3 more · not run yet · checked 2026-10-19

    Code shows
  3. 233232
    StrixAgent · by usestrix · reach 3, privilegedDraft · awaiting review

    Autonomous AI penetration-testing agents that run offensive tools in a container sandbox and validate findings with a proof of concept.

    Can tunnel or exfiltrate · use sudo or the docker socket · add autostart, users or keys · +3 more · not run yet · checked 2026-10-19

    Code shows