{"owner":"KeygraphHQ","repo":"shannon","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md","llms.txt"],"files":{"CLAUDE.md":"# CLAUDE.md\n\nAI-powered penetration testing agent for defensive security analysis. Automates vulnerability assessment by combining reconnaissance tools with AI-powered code analysis.\n\n## Commands\n\n**Prerequisites:** Docker, AI provider credentials (`.env` for local, `npx @keygraph/shannon setup` or env vars for npx)\n\n### Dual CLI\n\nShannon supports two CLI modes, auto-detected based on the current working directory:\n\n| | **npx** (`npx @keygraph/shannon`) | **Local** (`./shannon`) |\n|---|---|---|\n| **Install** | Zero-install via npm | Clone the repo |\n| **Image** | Pulled from Docker Hub (`keygraph/shannon:latest`) | Built locally (`shannon-worker`) |\n| **State** | `~/.shannon/` | Project directory |\n| **Credentials** | `~/.shannon/config.toml` (via `npx @keygraph/shannon setup`) or env vars | `./.env` |\n| **Config** | `~/.shannon/config.toml` (via `npx @keygraph/shannon setup`) | N/A |\n| **Prompts** | Bundled in Docker image | Mounted from `./apps/worker/prompts/` (live-editable) |\n\nMode auto-detection: local mode activates when env var `SHANNON_LOCAL=1` is set by the `./shannon` entry point (`apps/cli/src/mode.ts`). Otherwise npx mode.\n\n### npx Quick Start\n\n```bash\n# Configure credentials (interactive wizard)\nnpx @keygraph/shannon setup\n\n# Or export env vars directly (non-interactive / CI)\nexport ANTHROPIC_API_KEY=your-key\n\n# Run\nnpx @keygraph/shannon start -u <url> -r /path/to/repo\n```\n\n### Local (Development) Quick Start\n\n```bash\n# Setup\necho \"ANTHROPIC_API_KEY=your-key\" > .env\n\n# Build (auto-runs if image missing)\n./shannon build\n\n# Run\n./shannon start -u <url> -r my-repo\n./shannon start -u <url> -r my-repo -c ./apps/worker/configs/my-config.yaml\n./shannon start -u <url> -r /any/path/to/repo\n```\n\n### Common Commands\n\n```bash\n# Setup (npx mode only — one-time credential configuration)\nnpx @keygraph/shannon setup\n\n# Workspaces & Resume\n./shannon start -u <url> -r my-repo -w my-audit    # New named workspace\n./shannon start -u <url> -r my-repo -w my-audit    # Resume (same command)\n./shannon workspaces                                 # List all workspaces\n\n# Monitor\n./shannon logs <workspace>            # Show a scan's live log\n./shannon status                      # Show running scans\n# Dashboard: http://localhost:8233\n\n# Stop\n./shannon stop                        # Preserves scan data\n./shannon stop --clean                # Full cleanup including volumes (confirms first; --yes/-y to skip)\n\n# Version\n./shannon version                     # npx: package version; local: git SHA\n\n# Image management\n./shannon build [--no-cache]          # Local mode: build worker image\nnpx @keygraph/shannon uninstall             # npx mode: remove ~/.shannon/ (confirms first; --yes/-y to skip)\n\n# Build TypeScript (development)\npnpm run build                       # Build all packages via Turborepo\npnpm run check                       # Type-check all packages\npnpm biome                           # Biome lint + format + import sorting check\npnpm biome:fix                       # Auto-fix lint, format, and import sorting\n```\n\n**Monorepo tooling:** pnpm workspaces, Turborepo for task orchestration, Biome for linting/formatting. TypeScript compiler options shared via `tsconfig.base.json` at the root. All packages extend it, overriding only `rootDir` and `outDir`. Shared devDependencies (`typescript`, `@types/node`, `turbo`, `@biomejs/biome`) are hoisted to the root workspace.\n\n**Options:** `-c <file>` (YAML config), `-o <path>` (output directory), `-w <name>` (named workspace; auto-resumes if exists), `--pipeline-testing` (minimal prompts, 10s retries), `--debug` (preserve worker container after exit for log inspection), `--yes`/`-y` (skip the confirmation prompt on `stop --clean`/`uninstall`; required for non-interactive use)\n\n## Architecture\n\n### Monorepo Layout\n\n```\napps/cli/        — @keygraph/shannon (published to npm, bundled with tsdown)\napps/worker/     — @shannon/worker (private, Temporal worker + pipeline logic)\n```\n\n### CLI Package (`apps/cli/`)\nPublished as `@keygraph/shannon` on npm. Contains only Docker orchestration logic — no Temporal SDK, business logic, or prompts. Bundled with tsdown for single-file ESM output.\n\n- `apps/cli/src/index.ts` — CLI dispatcher (`setup`, `start`, `stop`, `logs`, `workspaces`, `status`, `build`, `uninstall`, `version`)\n- `apps/cli/src/mode.ts` — Auto-detection: local mode if `SHANNON_LOCAL=1` env var is set\n- `apps/cli/src/docker.ts` — Compose lifecycle, image pull/build, ephemeral `docker run` worker spawning\n- `apps/cli/src/home.ts` — State directory management (`~/.shannon/` for npx, `./` for local)\n- `apps/cli/src/env.ts` — `.env` loading, TOML fallback (npx only) via `apps/cli/src/config/resolver.ts`, credential validation, provider-scoped env flag building\n- `apps/cli/src/model-spec.ts` — `SHANNON_AI_MODEL` (`<provider>:<model-id>`) parsing; mirrors `apps/worker/src/ai/models.ts`\n- `apps/cli/src/config/resolver.ts` — Cascading config (npx only): env vars → `~/.shannon/config.toml` (parsed with `smol-toml`)\n- `apps/cli/src/config/writer.ts` — TOML serialization and secure file persistence (0o600)\n- `apps/cli/src/commands/setup.ts` — Interactive TUI wizard (`@clack/prompts`) for provider credential setup (npx only)\n- `apps/cli/src/paths.ts` — Repo/config path resolution (bare name → `./repos/<name>`, or any absolute/relative path)\n- `apps/cli/src/version.ts` — Version reporting (npx: `package.json` version; local: `git-<sha>`)\n- `apps/cli/src/tty.ts` — Terminal capability detection: `requireInteractive` guard (fails fast off-TTY instead of hanging on a prompt), `supportsColor` color gating (`NO_COLOR`/`FORCE_COLOR`), and `stdoutIsTerminal` for spinner/cursor output\n- `apps/cli/src/commands/` — Command handlers\n- `apps/cli/infra/compose.yml` — Bundled Temporal compose file for npx mode\n- `apps/cli/tsdown.config.ts` — tsdown bundler config\n- `shannon` — Node.js entry point (`#!/usr/bin/env node`) that delegates to `apps/cli/dist/index.mjs`\n\n### Docker Architecture\nInfra (Temporal) runs via `docker-compose.yml`. Workers are ephemeral `docker run --rm` containers, one per scan, each with a unique task queue and isolated volume mounts.\n\n- `docker-compose.yml` — Infra only: `shannon-temporal` (port 7233/8233). Network: `shannon-net`\n- `Dockerfile` — 2-stage build (builder + Chainguard Wolfi runtime). Uses pnpm. Entrypoint: `CMD [\"node\", \"apps/worker/dist/temporal/worker.js\"]`\n- No `docker-compose.docker.yml` — host gateway handled via `--add-host` flag in CLI\n- `/etc/hosts` forwarding — at worker spawn, `forwardEtcHostsFlags` in `apps/cli/src/docker.ts` reads the host's `/etc/hosts` and emits one `--add-host` flag per valid user-added entry. Loopback IPs (`127.x`, `::1`) are rewritten to `host-gateway`; IPv6 addresses are bracketed. Disable per-scan via `SHANNON_FORWARD_HOSTS=false`. No-op on Windows native (WSL2 reads its own `/etc/hosts` via the Linux path).\n\n### Worker Package (`apps/worker/`)\n- `apps/worker/src/paths.ts` — Centralized path constants (`PROMPTS_DIR`, `CONFIGS_DIR`, `WORKSPACES_DIR`)\n- `apps/worker/src/session-manager.ts` — Agent definitions (`AGENTS` record). Agent types in `apps/worker/src/types/agents.ts`\n- `apps/worker/src/config-parser.ts` — YAML config parsing with JSON Schema validation\n- `apps/worker/src/ai/pi/pi-executor.ts` — pi harness integration (agent-level retry disabled so Temporal owns restarts; provider-level retry on, see `apps/worker/src/ai/pi/retry-settings.ts`)\n- `apps/worker/src/services/` — Business logic layer (Temporal-agnostic). Activities delegate here. Key: `agent-execution.ts`, `error-handling.ts`, `container.ts`\n- `apps/worker/src/types/` — Consolidated types: `Result<T,E>`, `ErrorCode`, `AgentName`, `ActivityLogger`, etc.\n- `apps/worker/src/utils/` — Shared utilities (file I/O, formatting, concurrency)\n\n### Temporal Orchestration\nDurable workflow orchestration with crash recovery, queryable progress, intelligent retry, and parallel execution (5 concurrent agents in vuln/exploit phases).\n\n- `apps/worker/src/temporal/workflows.ts` — Main workflow (`pentestPipelineWorkflow`)\n- `apps/worker/src/temporal/activities.ts` — Thin wrappers — heartbeat loop, error classification, container lifecycle. Business logic delegated to `apps/worker/src/services/`\n- `apps/worker/src/temporal/activity-logger.ts` — `TemporalActivityLogger` implementation of `ActivityLogger` interface\n- `apps/worker/src/temporal/summary-mapper.ts` — Maps `PipelineSummary` to `WorkflowSummary`\n- `apps/worker/src/temporal/worker.ts` — Combined worker + client entry point (per-invocation task queue, submits workflow, waits for result)\n- `apps/worker/src/temporal/shared.ts` — Types, interfaces, query definitions\n### Five-Phase Pipeline\n\n1. **Pre-Recon** (`pre-recon`) — Source code analysis to build the architectural baseline\n2. **Recon** (`recon`) — Attack surface mapping from initial findings\n3. **Vulnerability Analysis** (5 parallel agents) — injection, xss, auth, authz, ssrf\n4. **Exploitation** (5 parallel agents, conditional) — Exploits confirmed vulnerabilities\n5. **Reporting** (`report`) — Executive-level security report\n\n### Supporting Systems\n- **Configuration** — YAML configs in `apps/worker/configs/` with JSON Schema validation (`config-schema.json`). Supports auth settings (MFA/TOTP), URL/code rule scoping (`rules.avoid`/`rules.focus`), run-scope steering (`vuln_classes`, `exploit`), free-form `rules_of_engagement`, and post-hoc `report` options (`min_severity`, `min_confidence`, `guidance`, and `sarif` to emit a SARIF 2.1.0 log via `apps/worker/src/services/sarif-renderer.ts`; exploit-only). `code_path` avoid rules are enforced via the `@gotgenes/pi-permission-system` extension: `apps/worker/src/temporal/activities.ts:syncCodePathDenyRules` writes a global `path` deny config once per workflow (`apps/worker/src/ai/pi/permission-system.ts:syncPermissionSystemConfig`), and the executor loads the extension when that config is present (`apps/worker/src/ai/pi/pi-executor.ts`), so denies fire across every tool and child `task` session. `vuln_classes`/`exploit` scope is locked into `session.json` on first run; resumes with a different scope fail fast (`persistOrValidateRunScope`). Credential resolution — local mode: env vars → `./.env`; npx mode: env vars → `~/.shannon/config.toml` (via `npx @keygraph/shannon setup`)\n- **Prompts** — Per-phase templates in `apps/worker/prompts/` with variable substitution (`{{TARGET_URL}}`, `{{CONFIG_CONTEXT}}`). Shared partials in `apps/worker/prompts/shared/` via `apps/worker/src/services/prompt-manager.ts`, including `_code-path-rules.txt` (focus/avoid `[FILE]`/`[GLOB]` routing) and `_rules-of-engagement.txt` (free-text engagement rules). When `exploit: false`, `apps/worker/src/services/findings-renderer.ts` deterministically converts each `*_exploitation_queue.json` into a `*_findings.md` for report assembly — no LLM in the loop\n- **Agent Harness (pi)** — Uses the **pi harness** (`@earendil-works/pi-coding-agent`, requires Node ≥ 22.19) via `apps/worker/src/ai/pi/pi-executor.ts` (`runPiPrompt` → `createAgentSession`). Retry is split in `apps/worker/src/ai/pi/retry-settings.ts`: pi's agent-level loop is off so Temporal owns agent restarts, while `provider.maxRetries` stays on — pi reads the `provider` block independently of the `enabled` flag — so transport faults are absorbed in-session rather than costing a full agent re-run. `maxRetryDelayMs` is left at pi's 60s default. One model runs every phase, named by `SHANNON_AI_MODEL=<provider>:<model-id>` (default `anthropic:claude-sonnet-4-6`). `apps/worker/src/ai/models.ts` parses the spec — splitting on the **first** colon only, so Bedrock IDs keep theirs — and resolves it through pi's `ModelRuntime`. pi ships the `CredentialStore` interface but no in-memory implementation (its own reads `auth.json` from disk), so `RuntimeCredentialStore` in that file supplies one: credentials arrive as env vars in an ephemeral container and must never touch disk. `createModelRuntime(providerId, apiKey)` builds the runtime; `allowModelNetwork` stays at its default `false` so a scan never blocks on a catalog refresh. `resolveModelSelection()` is **async** because `ModelRuntime.create()` is. Any pi-ai provider id is accepted — `parseModelSpec` no longer rejects against a hardcoded list, so pi's registry is the authority (an unknown provider/model surfaces as a clear \"not found in pi registry\" error at preflight, which points to the browsable catalogue at `pi.dev/models` — `PI_CATALOG_URL` in `apps/worker/src/ai/models.ts`, appended to the not-found errors and shown in the setup wizard's \"Other provider\" hint). Four providers are **curated** (`CURATED_PROVIDERS`: `anthropic`, `openai`, `xai`, `amazon-bedrock`) with their own credential variables, config sections, and setup flows; each provider's API key env var is declared once in `PROVIDER_API_KEY_ENV` — Shannon uses each vendor's own variable name (`OPENAI_API_KEY`, `XAI_API_KEY`, …), never an invented one; Bedrock's entry is `AWS_BEARER_TOKEN_BEDROCK`, paired with `AWS_REGION`, which preflight requires separately as provider config rather than a credential. Any other provider uses the **generic** credential path: `SHANNON_AI_API_KEY` (`GENERIC_API_KEY_ENV`) supplies the key for any provider whose credential is a plain API key. Curated providers' own variables take precedence over it, and it also works as a fallback for them — Bedrock is the sole exception (it authenticates through its AWS_ variables, so the generic key never stands in for it). The CLI forwards `SHANNON_AI_API_KEY` in `COMMON_FORWARD_VARS` (it is provider-neutral, binding to whatever `SHANNON_AI_MODEL` names, so the \"only one provider configured\" guard counts only named credentials), and stores it under a generic `[provider]` config.toml section (`provider.api_key`). `npx @keygraph/shannon setup` exposes this as the \"Other provider\" option: free-text provider id + model id + key (a curated provider id is rejected there, since it has its own option). `SHANNON_AI_BASE_URL` overrides the endpoint for any provider (proxies/gateways); the credential is unchanged. `pointAtGateway` (`apps/worker/src/ai/models.ts`) applies the one dialect change: behind a base URL, `openai` follows `SHANNON_AI_OPENAI_FORMAT` (`chat-completions` default, or `responses`). On `chat-completions` it switches the API to `openai-completions` and drops the catalogue's Responses-shaped `compat` block so pi's `detectCompat` derives completions settings; on `responses` the descriptor is unchanged but for the endpoint. `resolveGatewayFormat` rejects the variable when the provider is not `openai` or no base URL is set, since it cannot take effect there. All other providers keep their API. The CLI mirrors the accepted values in `apps/cli/src/model-spec.ts`, forwards the variable in `COMMON_FORWARD_VARS`, and maps it to `openai.format` in config.toml. `buildEnvFlags` forwards only the selected provider's credential into the worker container. The CLI mirrors the parse rule and the provider/credential tables in `apps/cli/src/model-spec.ts` (it cannot import from the worker package); the two must stay in sync. pi ships no JSON-schema output or `Task`/`TodoWrite` built-ins, so structured queues are captured via a `submit_exploitation_queue` custom tool (`apps/worker/src/ai/queue-schemas.ts`), and `task` (child sessions scoped to `read`, `grep`, `find`, `ls`, `write`, and `bash` — no nested `task` or collector tools; `CHILD_TOOLS` in `apps/worker/src/ai/pi/task-tool.ts`) + `todo_write` (`apps/worker/src/ai/pi/session-tools.ts`) are provided as custom tools; the per-phase collectors are pi custom tools (TypeBox `defineTool` in `apps/worker/src/collectors/`). Shannon sets no thinking configuration at all — no `thinkingLevel` is passed to any `createAgentSession` call, so pi's own default applies. There is no adaptive-thinking support and no `CLAUDE_ADAPTIVE_THINKING` / `core.adaptive_thinking` setting. Browser automation via `playwright-cli` with session isolation (`-s=<session>`). TOTP generation via `generate-totp` CLI tool. Login flow template at `apps/worker/prompts/shared/login-instructions.txt` supports form, SSO, API, and basic auth. On authenticated whitebox scans, the `validate-authentication` preflight performs the single real login and saves the browser session to `auth-state.json` in the per-session audit directory (path from `authStateFile()` in `apps/worker/src/audit/utils.ts`, derived from `generateAuditPath()`). The validation activity (`apps/worker/src/services/validate-authentication.ts`) removes any stale file from a prior run before the agent runs and verifies the file parses and contains cookies or storage before the preflight is marked complete; `logWorkflowComplete` deletes it when the workflow ends so authenticated cookies don't sit on disk between scans. Agent prompts opt in to session reuse by `@include(shared/_shared-session.txt)` before their `<login_instructions>` block — the partial restores the session and falls through to the full login flow if verification fails. `vuln-auth`/`exploit-auth` omit the include and own their own login\n- **Pi Credential Reuse** — `SHANNON_USE_PI_AUTH=1` opts into reusing the host's Pi login, including an `openai-codex` ChatGPT Plus/Pro subscription selected with `SHANNON_AI_MODEL=openai-codex:<model-id>`. `apps/cli/src/env.ts` requires `~/.pi/agent/auth.json`; `start.ts` passes its path to `spawnWorker`, which mounts only that file read-write at `/tmp/.pi/agent/auth.json`. The flag itself is not forwarded: the worker detects the file with `piAuthPresent()` and passes its path to `ModelRuntime.create`. CLI and worker API-key presence checks are skipped on this path, but the normal preflight model probe still validates the credential. The image and UID-remapping entrypoint keep `/tmp/.pi/agent` owned by `pentest` so adjacent Pi/Shannon configuration remains writable. Refreshed OAuth state is persisted to the host for subsequent scans.\n- **Audit System** — Crash-safe append-only logging in `workspaces/{hostname}_{sessionId}/`. The run directory's top level holds only the human-facing PDF report (`Security-Assessment-Report.pdf`, `FINAL_REPORT_PDF_FILENAME` in `apps/worker/src/paths.ts`); everything else — deliverables, per-agent logs, prompts, `session.json`, `workflow.log`, and browser artifacts — is nested under a hidden `.shannon/` internals dir (`INTERNAL_DIR`) so a customer sees only the report. Audit path helpers route through `generateInternalPath` (`apps/worker/src/audit/utils.ts`); the CLI nests the overlay backing dirs under the same `.shannon/` (`apps/cli/src/docker.ts`, `start.ts`). `session.json`/`workflow.log` reads use dual-read resolvers (`resolveSessionJsonPath`, `resolveRunFile`) that prefer `.shannon/` and fall back to the legacy run-root layout, so pre-restructure workspaces stay listable (`workspaces`/`logs`) without migration. Resuming a pre-restructure workspace upgrades it in place first: `migrateLegacyWorkspaceLayout` (`apps/cli/src/commands/start.ts`) renames the flat deliverables/logs/session entries into `.shannon/` (carrying the deliverables `.git` along) before the overlay dirs are mounted, so resume finds the old checkpoints instead of re-running every agent. The report agent writes structured findings to `report.json`, from which `report-renderer.ts` renders the assembled markdown and `report-json-adapter.ts` produces the Typst-shaped JSON that `pdf-renderer.ts` compiles into `comprehensive_security_assessment_report.pdf` using the bundled `apps/worker/templates/typst/report.typ` template (the `typst` binary is installed in the worker image). `copyReportToRunRoot` (`apps/worker/src/services/reporting.ts`) surfaces the PDF to the run root as `Security-Assessment-Report.pdf`; the markdown stays in the deliverables dir and is not surfaced. PDF compilation is best-effort — a failure is logged and the run still completes. WorkflowLogger (`apps/worker/src/audit/workflow-logger.ts`) provides unified human-readable per-workflow logs, backed by LogStream (`apps/worker/src/audit/log-stream.ts`) shared stream primitive\n- **Deliverables** — Saved to `.shannon/deliverables/` in the target repo via the `save-deliverable` CLI script (`apps/worker/src/scripts/save-deliverable.ts`)\n- **Workspaces & Resume** — Named workspaces via `-w <name>` or auto-named from URL+timestamp. Resume detects completed agents via `session.json`. `loadResumeState()` in `apps/worker/src/temporal/activities.ts` validates deliverable existence, restores git checkpoints, and cleans up incomplete deliverables. Workspace listing via `apps/worker/src/temporal/workspaces.ts`\n\n## Development Notes\n\n### Adding a New Agent\n1. Define agent in `apps/worker/src/session-manager.ts` (add to `AGENTS` record). `ALL_AGENTS`/`AgentName` types live in `apps/worker/src/types/agents.ts`\n2. Create prompt template in `apps/worker/prompts/` (e.g., `vuln-newtype.txt`)\n3. Two-layer pattern: add a thin activity wrapper in `apps/worker/src/temporal/activities.ts` (heartbeat + error classification). `AgentExecutionService` in `apps/worker/src/services/agent-execution.ts` handles the agent lifecycle automatically via the `AGENTS` registry\n4. Register activity in `apps/worker/src/temporal/workflows.ts` within the appropriate phase\n\n### Modifying Prompts\n- Variable substitution: `{{TARGET_URL}}`, `{{CONFIG_CONTEXT}}`, `{{LOGIN_INSTRUCTIONS}}`\n- Shared partials in `apps/worker/prompts/shared/` included via `apps/worker/src/services/prompt-manager.ts`\n- Test with `--pipeline-testing` for fast iteration\n\n### Key Design Patterns\n- **Configuration-Driven** — YAML configs with JSON Schema validation\n- **Progressive Analysis** — Each phase builds on previous results\n- **Harness-First** — the pi harness (`@earendil-works/pi-coding-agent`) handles autonomous analysis\n- **Modular Error Handling** — `ErrorCode` enum, `Result<T,E>` for explicit error propagation, automatic retry (3 attempts per agent)\n- **Services Boundary** — Activities are thin Temporal wrappers; `apps/worker/src/services/` owns business logic, accepts `ActivityLogger`, returns `Result<T,E>`. No Temporal imports in services\n- **DI Container** — Per-workflow in `apps/worker/src/services/container.ts`. `AuditSession` excluded (parallel safety)\n- **Ephemeral Workers** — Each scan runs in its own `docker run --rm` container with a per-invocation task queue. Temporal routes activities by queue name, so per-scan queues ensure activities never land on a worker with the wrong repo mounted\n\n### Security\nDefensive security tool only. Use only on systems you own or have explicit permission to test.\n\n## Code Style Guidelines\n\n### Formatting\nBiome handles formatting and linting. Run `pnpm biome:fix` to auto-fix. Config in `biome.json`: single quotes, semicolons, trailing commas, 2-space indent, 120 char line width.\n\n### Clarity Over Brevity\n- Optimize for readability, not line count — three clear lines beat one dense expression\n- Use descriptive names that convey intent\n- Prefer explicit logic over clever one-liners\n\n### Structure\n- Keep functions focused on a single responsibility\n- Use early returns and guard clauses instead of deep nesting\n- Never use nested ternary operators — use if/else or switch\n- Extract complex conditions into well-named boolean variables\n\n### TypeScript Conventions\n- Use `function` keyword for top-level functions (not arrow functions)\n- Explicit return type annotations on exported/top-level functions\n- Prefer `readonly` for data that shouldn't be mutated\n- `exactOptionalPropertyTypes` is enabled — use spread for optional props, not direct `undefined` assignment\n\n### Avoid\n- Combining multiple concerns into a single function to \"save lines\"\n- Dense callback chains when sequential logic is clearer\n- Sacrificing readability for DRY — some repetition is fine if clearer\n- Abstractions for one-time operations\n- Backwards-compatibility shims, deprecated wrappers, or re-exports for removed code — delete the old code, don't preserve it\n\n### Comments\nComments must be **timeless** — no references to this conversation, refactoring history, or the AI.\n\n**Patterns used in this codebase:**\n- `/** JSDoc */` — file headers (after license) and exported functions/interfaces\n- `// N. Description` — numbered sequential steps inside function bodies. Use when a\n  function has 3+ distinct phases where at least one isn't immediately obvious from the\n  code. Each step marks the start of a logical phase. Reference: `AgentExecutionService.execute`\n  (steps 1-9) and `injectModelIntoReport` (steps 1-5)\n- `// === Section ===` — high-level dividers between groups of functions in long files,\n  or to label major branching/classification blocks (e.g., `// === SPENDING CAP SAFEGUARD ===`).\n  Not for sequential steps inside function bodies — use numbered steps for that\n- `// NOTE:` / `// WARNING:` / `// IMPORTANT:` — gotchas and constraints\n\n**Never:** obvious comments, conversation references (\"as discussed\"), history (\"moved from X\")\n\n## Key Files\n\n**CLI:** `shannon` (entry point), `apps/cli/src/index.ts` (dispatcher), `apps/cli/src/docker.ts` (orchestration), `apps/cli/src/mode.ts` (auto-detection)\n\n**Entry Points:** `apps/worker/src/temporal/workflows.ts`, `apps/worker/src/temporal/activities.ts`, `apps/worker/src/temporal/worker.ts`\n\n**Core Logic:** `apps/worker/src/session-manager.ts`, `apps/worker/src/ai/pi/pi-executor.ts`, `apps/worker/src/ai/pi/permission-system.ts` (writes `code_path` deny rules to the `@gotgenes/pi-permission-system` global config), `apps/worker/src/config-parser.ts`, `apps/worker/src/services/` (incl. `preflight.ts`, `findings-renderer.ts`, `reporting.ts`), `apps/worker/src/audit/`\n\n**Config:** `docker-compose.yml`, `apps/cli/infra/compose.yml`, `apps/worker/configs/`, `apps/worker/prompts/`, `tsconfig.base.json` (shared compiler options), `turbo.json`, `biome.json`\n\n**CI/CD:** `.github/workflows/release.yml` (Docker Hub push + npm publish + GitHub release, manual dispatch)\n\n## Package Installation\n\nPackage managers are configured with a minimum release age (7 days). Requires pnpm >= 10.16.0. If `pnpm install` fails due to a package being too new, **do not attempt to bypass it** — report the blocked package to the user and stop.\n\n## Troubleshooting\n\n- **\"Repository not found\"** — Pass a bare name (`-r my-repo`) for `./repos/my-repo`, or a path (`-r /path/to/repo`) for any directory\n- **\"Temporal not ready\"** — Wait for health check or `docker compose logs temporal`\n- **Worker not processing** — Check `docker ps --filter \"name=shannon-worker-\"`\n- **Reset state** — `./shannon stop --clean`\n- **Local apps unreachable** — Use `host.docker.internal` instead of `localhost`\n- **Container permissions** — On Linux, may need `sudo` for docker commands\n","llms.txt":"# Shannon\n\n> Shannon is an autonomous AI pentesting project by Keygraph. This repository contains Shannon, the AGPL-3.0 open-source white-box pentesting CLI. The Keygraph platform is Keygraph's commercial continuous pentesting and AppSec platform.\n\nUse this file as the concise entry point for AI agents and LLMs reading this repository. For a single combined context file, use [llms-full.txt](llms-full.txt).\n\n## Start Here\n\n- [README](README.md): Main project overview, editions, quick start, Shannon capabilities, Keygraph platform positioning, safety notes, licensing, and support links.\n- [Full Combined Context](llms-full.txt): README and documentation combined into one file for agents that need maximum local context.\n\n## Shannon\n\n- [Development](docs/development.md): Source-build workflow, common CLI commands, repository paths, and output locations.\n- [Configuration](docs/configuration.md): Authenticated testing, login flows, rules of engagement, report filters, credential precedence, adaptive thinking, and rate-limit settings.\n- [AI Providers](docs/ai-providers.md): Anthropic, OpenAI, xAI, AWS Bedrock, any other Pi-supported provider, and custom gateway setup.\n- [Platforms and Networking](docs/platforms.md): Windows/WSL2, Linux, macOS, Docker networking, local applications, and custom hostnames.\n- [Workspaces and Resuming](docs/workspaces.md): Workspace storage, naming, resuming interrupted scans, and examples.\n- [Safety and Limitations](docs/safety.md): Authorized-use requirements, non-production guidance, mutative effects, model caveats, scope limits, cost, and performance.\n- [Coverage and Roadmap](docs/coverage-roadmap.md): Current Shannon coverage and roadmap direction.\n\n## Keygraph Platform\n\n- [Keygraph platform](docs/keygraph-platform.md): Commercial continuous pentesting and AppSec platform, including black-box and white-box pentesting, parsed-code SAST, source-to-sink analysis, remediation workflows, CI/CD gating, SLA tracking, reporting, and enterprise deployment.\n\n## External Links\n\n- [Keygraph website](https://keygraph.io): Company and commercial product information.\n- [Keygraph demo](https://cal.com/team/keygraph/shannon-pro): Demo and trial contact path.\n- [Community Discord](https://discord.gg/cmctpMBXwE): Community support and discussion.\n\n## Optional\n\n- [Sample Juice Shop report](sample-reports/shannon-report-juice-shop.md): Shannon sample report for OWASP Juice Shop.\n- [Sample c{api}tal API report](sample-reports/shannon-report-capital-api.md): Shannon sample report for c{api}tal API.\n- [Sample crAPI report](sample-reports/shannon-report-crapi.md): Shannon sample report for OWASP crAPI.\n"}}