cogensec/gideon

1. Repository shape

Gideon is a Bun/TypeScript monorepo centered on an autonomous cybersecurity agent. The runtime product is a terminal-first operator experience, while docs/ is a separate Astro documentation site. The codebase is organized around one core loop: accept a security goal, plan work, invoke tools/services, validate findings, and emit a report or answer.

2. Operator interface layer

The entry points in src/cli.tsx and src/index.tsx, plus src/components/ and src/hooks/, form the interactive shell/UI layer. It handles prompt entry, command history, model selection, debug output, and progress indicators. This layer is mostly orchestration and presentation; it does not own the analysis logic.

3. Agent core

src/agent/ contains the ReAct-style execution engine: planning, phase management, approvals, prompts, scratchpad state, and a red-team mode switch. This is the central control loop that turns a user request into a sequence of actions, observations, and reflections. It is the main boundary between user intent and the rest of the system.

4. Tool and data-source boundary

src/tools/ and src/utils/llm-* provide the external I/O adapters. They connect to LLM providers and research sources such as OpenRouter, OpenAI, Anthropic, Google, Ollama, Exa, Tavily, NVD, VirusTotal, and AbuseIPDB. In architecture terms, this is the outbound integration layer for model inference, threat intel lookup, and search.

5. Domain capabilities

The product’s primary security workflows live in src/gideon/, src/scanner/, src/output/, src/graph/, and the command handlers under src/commands/. These subsystems cover CVE research, IOC reputation checks, briefing/report generation, scanning, and graph-based correlation. Commands like brief, cve, ioc, policy, scan, and redteam are just thin entry points into these domain engines.

6. Skills subsystem

src/skills/ is a modular capability system. Each skill directory represents a specialized subdomain with its own commands and behavior, such as security research, post-exploitation, weaponization, voice, governance, threat detection, and OpenClaw Sentinel. The registry.ts file indicates skills are dynamically discoverable and act like pluggable sub-agents rather than a flat command list.

7. Safety, governance, and audit

src/governance/ and src/openclaw/ implement the defensive control plane: policy enforcement, access control, agent monitoring, audit logging, prompt-injection defense, credential guarding, memory integrity checks, and hardening audits. These modules sit on the critical path for both normal and red-team operations, so they are not optional decoration; they enforce scope, record actions, and block unsafe behavior.

8. Red-team execution path

src/redteam/ contains the offensive simulation stack: attack definitions, campaign management, scoring, and report generation. This path is distinct from the defensive research path and is intended for authorized engagements. The readme’s sandboxing and engagement-scope rules imply this subsystem must be diagrammed as gated by governance and isolated execution boundaries.

9. C2 and post-exploitation integration

src/c2/ plus the Sliver adapter connect Gideon to command-and-control style session infrastructure. This is the bridge from planning and analysis into post-exploitation session awareness, host mapping, and controlled operator actions. It is an external-security boundary and should be shown separately from general threat-intel tooling.

10. MCP extensibility

src/mcp/ and mcp-servers/ provide Model Context Protocol integration for external tools. The repository includes a Python MCP server container, which means tool expansion is meant to happen through a protocol boundary rather than only in-process code. In diagrams, MCP should be treated as a plugin surface that feeds additional tools into the agent loop.

11. Configuration, state, and cross-cutting utilities

src/utils/ contains the shared support systems: configuration loading, environment handling, caching, rate limiting, redaction, logger, chat history, and provider-specific helpers. gideon.config.yaml and .env determine runtime behavior, enabled providers, security integrations, and model routing. These utilities are the common substrate used by nearly every subsystem.

12. Supporting infrastructure

docker-compose.yml and the mcp-servers/Dockerfile indicate containerized auxiliary services, especially for sandboxed or protocol-based integrations. The docs site under docs/ is a separate application with its own build/runtime. The architecture therefore has three distinct deployment surfaces: the Bun CLI app, optional containerized support services, and the documentation site.