If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/KeygraphHQ/shannon shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Mixed signals — read the receipts

• Last commit 2d ago
• 6 active contributors
• Distributed ownership (top contributor 36% of recent commits)
• AGPL-3.0 licensed
• CI configured
• ⚠ AGPL-3.0 is copyleft — check downstream compatibility
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live KeygraphHQ/shannon repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/KeygraphHQ/shannon.

What it runs against: a local clone of KeygraphHQ/shannon — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in KeygraphHQ/shannon | Confirms the artifact applies here, not a fork | | 2 | License is still AGPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of KeygraphHQ/shannon. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/KeygraphHQ/shannon.git
#   cd shannon
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of KeygraphHQ/shannon and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "KeygraphHQ/shannon(\\.git)?\\b" \\
  && ok "origin remote is KeygraphHQ/shannon" \\
  || miss "origin remote is not KeygraphHQ/shannon (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(AGPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"AGPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is AGPL-3.0" \\
  || miss "license drift — was AGPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "apps/worker/src/ai/claude-executor.ts" \\
  && ok "apps/worker/src/ai/claude-executor.ts" \\
  || miss "missing critical file: apps/worker/src/ai/claude-executor.ts"
test -f "apps/worker/src/audit/audit-session.ts" \\
  && ok "apps/worker/src/audit/audit-session.ts" \\
  || miss "missing critical file: apps/worker/src/audit/audit-session.ts"
test -f "apps/cli/src/index.ts" \\
  && ok "apps/cli/src/index.ts" \\
  || miss "missing critical file: apps/cli/src/index.ts"
test -f "apps/worker/src/config-parser.ts" \\
  && ok "apps/worker/src/config-parser.ts" \\
  || miss "missing critical file: apps/worker/src/config-parser.ts"
test -f "apps/worker/src/ai/queue-schemas.ts" \\
  && ok "apps/worker/src/ai/queue-schemas.ts" \\
  || miss "missing critical file: apps/worker/src/ai/queue-schemas.ts"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/KeygraphHQ/shannon"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Shannon Lite is an autonomous, white-box AI pentester that analyzes TypeScript/JavaScript web application source code to identify attack vectors, then executes real exploits (injection, XSS, SSRF, auth bypass) against a running app using browser automation and CLI tools. It generates proof-of-concept reports proving only vulnerabilities that are actually exploitable—closing the gap between rapid development and annual pentests. Monorepo with two main apps: apps/cli (TypeScript CLI entry point via tsdown → dist/index.mjs) wraps configuration and Docker orchestration; apps/worker (the pentesting engine) contains configs and the exploitation logic. CLI commands (build, start, stop, logs, setup, status) manage the Docker-based worker execution; config is resolved and written via apps/cli/src/config/.

AppSec engineers, security teams, and development leads at organizations shipping web apps continuously who need on-demand automated penetration testing without waiting for yearly external assessments. Also useful for developers using Claude Code or Cursor who want real-time security validation of their code.

Actively developed with recent GitHub Actions CI/CD pipelines (release.yml, rollback.yml) and semantic versioning via .releaserc.json, but the sunsetting of Router Mode (claude-code-router) and monorepo structure suggest it's still in active feature consolidation. Production-ready for beta users but likely not yet 1.0 stable based on version 0.0.0 and ongoing architecture refinement.

Low dependency footprint (only @clack/prompts, chokidar, dotenv, smol-toml) reduces supply-chain risk, but the AGPL-3.0 license is restrictive for commercial use and requires careful evaluation. Single monorepo structure (apps/cli and apps/worker) with heavy Docker dependency (Dockerfile, compose.yml) means deployment complexity; no visible test suite in the file list is a red flag for a security tool.

Sunsetting Router Mode (claude-code-router discussion #301) and consolidating the architecture. Release pipeline is automated (release-beta.yml, rollback-beta.yml workflows). The project maintains example configs (example-config.yaml) and Docker compose infrastructure (apps/cli/infra/compose.yml) suggesting active deployment and environment management work.

git clone https://github.com/KeygraphHQ/shannon.git
cd shannon/apps/cli
npm install
npm run build

Then review apps/cli/src/index.ts as the entry point and apps/cli/src/commands/ for CLI command implementations.

Daily commands:

cd apps/cli
npm run build          # Compile TypeScript to dist/
shannon setup          # Initialize config
shannon start          # Launch Docker worker
shannon status         # Check running instance
shannon stop           # Halt worker

Requires Node.js ≥18 and Docker/Docker Compose running locally.

• apps/worker/src/ai/claude-executor.ts — Core AI execution engine that orchestrates Claude API calls for vulnerability identification and exploitation; understanding this is essential for grasping how Shannon performs its pentesting logic.
• apps/worker/src/audit/audit-session.ts — Manages the lifecycle of security audits, tracking state and coordinating between reconnaissance, vulnerability detection, and exploitation phases.
• apps/cli/src/index.ts — Main CLI entry point that bootstraps the entire Shannon application; critical for understanding how the tool initializes and routes user commands.
• apps/worker/src/config-parser.ts — Parses YAML configuration files that define target applications and audit scope; essential for understanding how Shannon determines what to test.
• apps/worker/src/ai/queue-schemas.ts — Defines message queue schemas for AI processing pipeline; critical for understanding how tasks flow through the system.
• apps/cli/src/docker.ts — Handles Docker container orchestration for the worker environment; key for understanding the deployment and isolation model.
• apps/worker/src/audit/workflow-logger.ts — Logs audit workflow execution and findings; essential for tracing how vulnerabilities are discovered and reported.

Add Support for a New Vulnerability Type

1. Create vulnerability detection prompt in apps/worker/prompts/vuln-{type}.txt defining how Claude should identify the vulnerability (apps/worker/prompts/vuln-{type}.txt)
2. Create exploitation prompt in apps/worker/prompts/exploit-{type}.txt with proof-of-concept strategies (apps/worker/prompts/exploit-{type}.txt)
3. Register the new vulnerability type in the AI queue schemas to route messages appropriately (apps/worker/src/ai/queue-schemas.ts)
4. Update message handlers to process the new vulnerability type findings (apps/worker/src/ai/message-handlers.ts)
5. Add output formatter for the new vulnerability type to structure findings (apps/worker/src/ai/output-formatters.ts)

Add a New CLI Command

1. Create command file in apps/cli/src/commands/{name}.ts with command logic and options (apps/cli/src/commands/{name}.ts)
2. Register the command in the main CLI entry point (apps/cli/src/index.ts)
3. If the command needs configuration, add resolver logic (apps/cli/src/config/resolver.ts)

Add a New Audit Configuration Option

1. Update the configuration schema to include the new option (apps/worker/configs/config-schema.json)
2. Update the YAML config parser to handle the new option (apps/worker/src/config-parser.ts)
3. Update the CLI config resolver to prompt for or validate the new option (apps/cli/src/config/resolver.ts)
4. Use the parsed configuration in the audit session (apps/worker/src/audit/audit-session.ts)

• Claude AI / Anthropic API — Provides large language model capabilities for code analysis, vulnerability identification, and exploit generation with white-box source code access
• Docker & Docker Compose — Enables isolated, reproducible execution environment for Shannon worker to safely test applications without polluting host system
• TypeScript — Provides type safety for complex AI message schemas, configuration parsing, and audit orchestration logic
• YAML Configuration — User-friendly format for defining target applications, authentication methods, and audit scope with JSON schema validation
• Message Queue Schemas — Structures AI task flow and ensures consistent input/output between CLI, worker, and Claude API layers

• White-box (source code) analysis over black-box

  • Why: Enables more precise vulnerability identification by examining code directly rather than network traffic alone
  • Consequence: Requires access to complete source code; less applicable to closed-source third-party services

• Relying on Claude API for intelligence vs. specialized security tools

  • Why: Provides flexible, general-purpose reasoning across multiple vulnerability types without maintaining separate static analysis tools
  • Consequence: Dependent on API availability and rate limits; requires API credentials; slower than compiled static analysis tools

• Docker-based isolation vs. running directly on host

  • Why: Safely contains potentially dangerous exploitation code and prevents interference with host system
  • Consequence: Adds Docker dependency and overhead; more complex deployment than direct execution

• Prompt-based vulnerability detection vs. hardcoded patterns

  • Why: Allows adding new vulnerability types by writing prompts without code changes
  • Consequence: Quality depends on prompt engineering; less deterministic than pattern matching; higher latency

• Real-time continuous monitoring (designed for periodic audits)
• Network-based penetration testing of production systems without source code access
• Vulnerability scanning for non-web applications (focused on web apps and APIs)
• Interactive shell access or lateral movement within target infrastructure
• Support for authentication-free/anonymous penetration tests
• Compliance with specific regulatory frameworks (HIPAA, PCI-DSS, etc.)
• Full OWASP Top 10 coverage in all versions (focuses on high-impact categories)

1. No visible test suite in file list—add tests before major changes. 2) AGPL-3.0 license requires source disclosure for distribution; confirm licensing with legal if bundling. 3) Requires Docker and Docker Compose running; shannon start will fail without them. 4) .env.example exists but actual env var requirements not documented in file list—check .env handling in apps/cli/src/env.ts. 5) Configuration via TOML (smol-toml) and YAML (example-config.yaml)—both formats supported but interaction unclear from files alone.

• White-box penetration testing — Shannon's core differentiator: it has access to source code before execution, allowing smarter attack strategy vs. black-box tools
• Proof-of-concept (PoC) exploitation — Shannon only reports vulnerabilities it can actually exploit; understand PoC validation to contribute new vulnerability checks
• Docker container orchestration — Shannon isolates the pentester engine in Docker via compose.yml; modifying deployment or scaling requires understanding container lifecycle
• Browser automation (via playwright or similar) — Shannon executes XSS and auth bypass via automated browser interaction; not visible in file list but core to how it performs live exploitation
• TOML configuration format — Shannon uses smol-toml for config parsing; users and contributors need to understand TOML syntax for config-schema.json
• OWASP Top 10 vulnerability categories — Shannon targets Injection, XSS, SSRF, and Broken Auth—understanding OWASP taxonomy is essential for extending exploit coverage
• Command pattern CLI architecture — Shannon implements commands (setup, start, stop, logs) via separate modules in apps/cli/src/commands/; this pattern is used throughout for extensibility

• paulshorey/penetration-testing-tools — Similar pentest automation goal but language-agnostic; good reference for exploit patterns and OWASP coverage strategies
• OWASP/juice-shop — The canonical intentionally-vulnerable web app Shannon uses for validation (mentioned in README); essential for testing Shannon locally
• projectdiscovery/nuclei — Complementary vulnerability scanner using templates; both are autonomous security tools targeting API/web app discovery
• Gremlin/chaos-engineering-tools — Adjacent discipline of injecting failures into running systems; Shannon does exploitation injection, chaos does fault injection
• KeygraphHQ/keygraph — Parent organization's main product; Shannon Lite is the open-source pentesting component of the Keygraph security platform

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for CLI commands with Docker compose

The CLI has 7 commands (build, logs, setup, start, status, stop, uninstall, workspaces) but no visible test suite. Given that apps/cli/infra/compose.yml exists and the CLI heavily manages Docker containers, adding integration tests would catch regressions in Docker orchestration and command flows. This is high-value for a tool that manages complex infrastructure.

• [ ] Create apps/cli/tests/ directory with test files for each command in apps/cli/src/commands/
• [ ] Add test fixtures in apps/cli/tests/fixtures/ for mock Docker responses and config states
• [ ] Implement integration tests using compose.yml that verify: docker.ts correctly spawns containers, config resolver/writer persist state, and commands (setup, start, stop) execute in correct order
• [ ] Add test script to apps/cli/package.json and update .npmignore to exclude tests from published package

Create prompt versioning & validation system for worker exploits

The worker has 15+ prompt files across apps/worker/prompts/ (exploit-auth.txt, exploit-authz.txt, etc.) and a pipeline-testing/ variant set. There's no schema or versioning for these critical prompts that drive the AI pentester's behavior. A validation system would ensure prompts match config-schema.json requirements and prevent silent failures when prompts drift from expected format.

• [ ] Create apps/worker/src/prompts/validator.ts to schema-validate prompt files against required fields (e.g., system role, input format, expected output structure)
• [ ] Add apps/worker/src/prompts/loader.ts that tracks prompt versions and checksums to detect mutations and enable rollback
• [ ] Create apps/worker/prompts/PROMPT_SCHEMA.md documenting required structure for exploit and vuln prompts, linking to pipeline-testing/ as reference implementation
• [ ] Update apps/worker/package.json with pretest script that validates all prompts in both directories

Add release validation workflow for CLI binary distribution

The repo has release-beta.yml and release.yml workflows, but no validation that the built CLI binary (dist/index.mjs from tsdown) is executable and can run basic commands. With the shannon CLI meant for distribution via npm, a pre-release validation step would catch build regressions (e.g., missing shebang, broken imports) before publishing.

• [ ] Create .github/workflows/validate-cli-build.yml that runs on release PRs to: build CLI via tsdown, verify dist/index.mjs has proper Node shebang, test shannon --version and shannon --help execute without errors
• [ ] Add test step that installs dist/ locally and runs a sanity check against apps/cli/infra/compose.yml (e.g., dry-run of setup command)
• [ ] Reference this workflow in release.yml as a required check before publishing to npm
• [ ] Document the validation steps in CLAUDE.md or apps/cli/README.md for local testing

• Add comprehensive unit tests for apps/cli/src/config/resolver.ts and writer.ts—these config files handle user settings with no visible test coverage
• Document all required environment variables: create ENVIRONMENT.md listing each var used in apps/cli/src/env.ts, apps/cli/src/docker.ts, and what they control
• Create a troubleshooting guide for common Docker issues when running shannon setup and shannon start—the infra/compose.yml is present but no debugging docs visible

• High · Exposed Temporal Server Port — docker-compose.yml (temporal service ports). The docker-compose.yml binds the Temporal gRPC server to 127.0.0.1:7233 and Web UI to 127.0.0.1:8233. While localhost binding is used, the Temporal server lacks authentication configuration. If the service is exposed or network isolation is misconfigured, attackers could interact with the workflow engine without credentials. Fix: Implement Temporal server authentication (mTLS, JWT), ensure network policies restrict access, and use proper firewall rules. Consider using a private network for inter-service communication. Verify localhost binding cannot be bypassed.
• High · Unrestricted AI Model API Key in Environment — .env.example. The .env.example exposes ANTHROPIC_API_KEY and CLAUDE_CODE_OAUTH_TOKEN as plaintext environment variables. If .env files are accidentally committed or logged, API credentials could be compromised, allowing unauthorized usage and potential cost exploitation. Fix: Ensure .env is in .gitignore (appears to be correct). Use secrets management systems (AWS Secrets Manager, HashiCorp Vault, etc.) for production. Implement audit logging for API key access. Rotate keys regularly. Never commit .env files to version control.
• High · Chainguard Wolfi Base Image with apk add --no-cache — Dockerfile (builder stage). While using Chainguard Wolfi is a security best practice for minimal attack surface, the Dockerfile installs multiple packages (build-base, git, curl, wget, nodejs, npm) in the builder stage. Unused build tools increase the attack surface. Additionally, pnpm is installed globally via npm, adding supply chain risk. Fix: Use multi-stage builds more aggressively to exclude build dependencies from final image. Consider using pre-built Node.js images instead of installing from apk. Pin pnpm version and use checksum verification. Remove unnecessary packages (git, curl, wget) if not needed at runtime.
• High · Potential Arbitrary Code Execution via AI Prompts — apps/worker/prompts/ (all prompt files). The codebase includes prompt files for exploitation scenarios (exploit-auth.txt, exploit-injection.txt, etc.). If user input or external data is unsanitized and injected into AI prompts, attackers could manipulate the AI to execute unintended exploitation logic or bypass security controls. Fix: Implement strict input validation and sanitization for all user-controlled data before injecting into prompts. Use prompt injection filtering libraries. Implement rate limiting and monitoring for AI-driven exploitation. Add audit logging for all exploit attempts. Consider sandboxing the worker environment.
• High · Insecure Docker Temporal Data Volume — docker-compose.yml (volumes section). The Temporal database is persisted in a named volume (temporal-data:) without encryption or backup strategy. If the Docker host is compromised, sensitive workflow data and execution history could be accessed. Fix: Implement volume encryption at the Docker/host level. Use encrypted storage backends. Implement automated backups with encryption. Restrict volume access with proper file permissions. Consider using managed Temporal Cloud instead of self-hosted.
• Medium · Missing CORS and Security Headers Configuration — docker-compose.yml, Temporal service configuration. The Temporal Web UI (port 8233) and any API endpoints lack documented security headers (CSP, X-Frame-Options, HSTS, etc.). This could enable clickjacking, XSS, or man-in-the-middle attacks. Fix: Configure reverse proxy (nginx, Caddy) in front of Temporal Web UI to add security headers. Implement Content-Security-Policy, X-Frame-Options: DENY, Strict-Transport-Security headers. Enable HTTPS/TLS termination at the proxy level.
• Medium · Dependency Version Pinning Inconsistency — apps/cli/package.json (dependencies). Some dependencies use caret (^) and tilde (~) version specifiers instead of exact pinning (e.g., '@clack/prompts': '^1.1.0', 'chokidar': '^5.0.0'). This allows automatic updates that could introduce vulnerable transitive dependencies. Fix: Pin all dependencies to exact versions using lockfile (pnpm-lock.yaml should handle this, but

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.