$ show KeygraphHQ/shannon
Shannon is an autonomous, white-box AI penetration testing platform that orchestrates multi-agent workflows via Temporal to analyze source code, identify attack vectors, and execute real exploits against running web applications. The system is structured as a pnpm monorepo with two primary applications: a CLI (`apps/cli`) that provides the user-facing interface for launching scans, and a worker (`apps/worker`) that runs the actual pentest pipeline inside Docker containers. The architecture follows a multi-agent pipeline pattern with 13 specialized agents (pre-recon, recon, 5 vulnerability analyzers, 5 exploiters, and a report generator) coordinated through Temporal workflows for reliability and resumability. The codebase demonstrates strong software engineering practices with a clear separation of concerns between Temporal orchestration (activities/workflows), pure domain logic (services), and infrastructure concerns. The worker implements a sophisticated DI container pattern, comprehensive audit logging with crash-safe append-only streams, and a custom error classification system that maps errors to Temporal retry behavior. The system supports multiple LLM providers (Anthropic direct, AWS Bedrock, Google Vertex AI, custom proxies) and implements defense-in-depth billing detection, git checkpointing for workspace rollback, and parallel agent execution with mutex-protected shared state. Key architectural strengths include the deterministic renderer pattern (MCP tool calls → markdown without LLM in the loop), the injectable provider interfaces for extensibility, and the sophisticated session management that enables resumable workspaces. The codebase uses TypeScript with strict compiler options, implements a Result type for explicit error handling, and maintains comprehensive type definitions. The CI/CD pipeline includes semantic releases, Docker image signing with cosign, and multi-platform builds. The system processes vulnerability queues through Zod-validated structured outputs and maintains forensic audit trails of all agent executions with timing, cost, and model metadata.
The LLM identified 8 files worth highlighting for reuse:
Implements a per-workflow DI container with explicit constructor injection and injectable provider interfaces (CheckpointProvider, FindingsProvider, ReportOutputProvider). The container manages service lifecycle scoped to workflow execution and supports custom factory injection for enterprise extensions. Demonstrates proper separation between workflow-scoped services and per-agent instances (AuditSession passed explicitly for parallel safety).
Provides crash-safe, append-only log stream management with proper backpressure handling via drain events and atomic cleanup on failure. The stream abstraction encapsulates the common pattern of opening files in append mode, handling write backpressure without blocking, and ensuring proper resource cleanup. This pattern is reused across AgentLogger and WorkflowLogger for consistent behavior.
Implements a sophisticated error classification system that maps errors to Temporal retry behavior using both code-based (ErrorCode enum) and pattern-matching approaches. The PentestError class carries structured context, retry classification, and specific error codes. The classifyErrorForTemporal function implements priority-based classification with billing errors (retryable with backoff), permanent errors (auth, config), and transient errors (network, rate limits) handled differently.
Provides consolidated billing/spending cap detection with defense-in-depth strategy combining API error patterns, text content patterns, and behavioral heuristics (low turns + zero cost + billing text). The module exports shared pattern lists to prevent drift between detection points in message handlers and the executor. This solves the real problem of inconsistent billing error responses from AI providers.
Implements a functional validation pipeline using asyncPipe composition for validating vulnerability queue files. The code uses a Result type for explicit error handling, pure functions for validation rules, and immutable data structures. The pipeline validates file existence symmetry (deliverable + queue must coexist), JSON structure, and determines exploitation decisions. Demonstrates how to compose complex validation logic from simple, testable functions.
Manages session.json with comprehensive timing, cost, and validation metrics using atomic writes and mutex-protected updates. The tracker maintains attempt-level data for forensic trails, recalculates phase and session-level aggregations, and supports resume attempts tracking. The reload-then-write pattern inside mutex protection prevents lost updates during parallel agent execution.
Provides git-based workspace isolation with checkpoint/rollback capabilities for agent retry safety. Implements a GitSemaphore to serialize git operations and prevent index.lock conflicts during parallel execution. The executeGitCommandWithRetry function uses exponential backoff for transient lock conflicts. The two-phase reset (hard reset + clean) ensures workspace cleanliness between retry attempts.
Implements a model tier resolution system mapping small/medium/large tiers to concrete model IDs with environment override support. Includes capability detection (adaptive thinking support, Fable model detection) that affects execution behavior. The abstraction works across all providers (direct, Bedrock, Vertex) while maintaining consistent tier semantics.