How purpleailab/decepticon works
1. Overall shape
Decepticon is split into a Python control plane and a TypeScript terminal client. The Python side contains the autonomous agent runtime, tool integrations, planning, and state/observability. The CLI is an Ink-based TUI that streams progress, renders messages, and exposes engagement controls. The repo is designed around two isolated Docker networks: a management plane and an operational sandbox plane.
2. Operator entrypoint
The main user-facing entrypoint is the CLI under clients/cli. It provides the REPL, keyboard shortcuts, status panels, and a local graph/canvas view. It is not just a shell wrapper; it is the operator console for starting, stopping, and monitoring engagements while the backend executes objectives.
3. Engagement planning subsystem
decepticon/agents/soundwave.py and the related skills/soundwave/* content generate the mission package: ConOps, Rules of Engagement, Deconfliction Plan, and OPPLAN. This is the planning boundary in the system. The OPPLAN becomes the structured input to the autonomous loop, while the RoE acts as a guardrail throughout execution.
4. Autonomous orchestration loop
The core control logic lives in decepticon/core/engagement.py, engagement_loop.py, and orchestrator.py. The loop selects the next pending objective, assembles a prompt from the objective plus prior findings and constraints, spawns a fresh agent context, and interprets the result as success, blocked, or pending. State is persisted outside the model context so objectives do not depend on long-lived agent memory.
5. Specialized agent model
The repository defines multiple specialist agents under decepticon/agents/ such as recon, exploit, post-exploit, analyst, defender, patcher, and research-oriented roles. Each agent has its own prompt material in decepticon/agents/prompts/ and is intended to run with a clean context window. This creates a clear boundary between planning, execution, analysis, and reporting responsibilities.
6. Skills as on-disk knowledge packs
The skills/ tree is a major subsystem. Skills are organized by domain and kill-chain phase, and they are loaded progressively rather than all at once. This gives the agents a curated knowledge base for AD, cloud, web, contracts, reversing, post-exploit, and shared workflow/OPSEC material, with MITRE ATT&CK metadata embedded where relevant.
7. Tool execution layer
decepticon/tools/ contains the concrete action surface used by agents: bash command execution, web, cloud, Active Directory, contracts, reversing, research, defense, and reporting tools. These tools are what turn a model’s plan into measurable actions and artifacts. The split by domain is important for the architecture diagram because it shows where capabilities are isolated and how different agent roles access different toolsets.
8. Sandbox and interactive sessions
Execution is intentionally separated from management. decepticon/backends/docker_sandbox.py and the container assets under containers/ point to a hardened operational sandbox, with interactive shell session handling and prompt detection built for long-lived tools like C2 clients or shells. The README’s Sliver profile indicates an optional C2 subsystem running in the operational network, with the sandbox using preconfigured client access to interact with it.
9. LLM access and routing
The decepticon/llm/ package and config/litellm.yaml form the model-access boundary. A LiteLLM proxy routes requests to different providers/models, and the router/factory layer selects models by role with fallback behavior. This means the orchestrator does not talk to a single model backend directly; it goes through a configurable abstraction that supports profile-based model choice.
10. Knowledge, graphs, and findings
decepticon/tools/research/, decepticon/tools/references/, and decepticon/schemas/ support structured knowledge and evidence handling. The presence of neo4j_store.py, attack-graph docs, and graph-related CLI code suggests a graph-backed view of findings, relationships, and attack paths. Findings are also surfaced in reporting tools, so the data flow is: tool output → structured state/graph → CLI/report output.
11. Guardrails, observability, and safety
decepticon/middleware/ enforces operational constraints such as OPPLAN hierarchy, safe command execution, and skill exposure rules. decepticon/observability/ adds activity logging, metrics, and tracing, which is important because the system is autonomous and needs an audit trail. This is the boundary that keeps the agent loop inspectable and policy-aware.
12. Build, runtime, and deployment
The repo is designed to run via Docker Compose, with separate images for the CLI, sandbox, LangGraph-related orchestration, and optional C2 components. The Python package is the backend runtime, while the TypeScript client is the operator interface. CI, tests, and container definitions are all present, which indicates the system is meant to be exercised as an integrated multi-service platform rather than as a single library.
Main entry points: decepticon.py Specialist Agents · engagement_loop.py Engagement Loop · REPL.tsx CLI REPL · tools.py Research Tools
Components 28
TypeScript CLI
Operator-facing terminal client and local canvas UI.
- CLI REPL · Ink-based operator console, commands, keybindings, and engagement controls.
clients/cli/src/screens/REPL.tsx - UI State · Client-side store, hooks, and session state for rendering engagement progress.
clients/cli/src/state/store.ts - Graph Canvas · Local graph/canvas rendering for objectives, events, and subagent activity.
clients/cli/src/canvas/graphView.ts - Message Views · Typed message and status components for tool calls, agents, and reports.
clients/cli/src/components/messages/AIMessage.tsx
Python control plane
Autonomous engagement runtime, agents, middleware, and orchestration.
- Orchestrator · Process entrypoint that wires the runtime together.
decepticon/orchestrator.py - Engagement Loop · Selects objectives, builds prompts, interprets results, and persists state.
decepticon/core/engagement_loop.py - Engagement Core · Core engagement coordination, objective tracking, and lifecycle management.
decepticon/core/engagement.py - Specialist Agents · Role-specific agents for recon, exploit, post-exploit, analysis, defense, and research.
decepticon/agents/decepticon.py - Mission Planning · Builds ConOps, Rules of Engagement, deconfliction, and OPPLAN inputs.
decepticon/agents/soundwave.py - Guardrails · OPPLAN hierarchy, safe command execution, and skill exposure rules.
decepticon/middleware/opplan.py
Skills library
On-disk knowledge packs and mission templates loaded by agents.
- Planning Skills · Mission templates for threat profile, ConOps, RoE, and OPPLAN conversion.
skills/soundwave/conops-template/SKILL.md - Recon Skills · Passive, active, cloud, OSINT, and web recon knowledge packs.
skills/recon/active-recon/SKILL.md - Exploit Skills · Web, AD, and general exploit workflows and references.
skills/exploit/web/SKILL.md - Post-Exploit Skills · Credential access, lateral movement, privilege escalation, and C2 guidance.
skills/post-exploit/c2/SKILL.md - Shared Skills · Workflow, OPSEC, defense-evasion, and finding-protocol material shared by agents.
skills/shared/workflow/SKILL.md
Tool surface
Domain-specific action tools used by agents to execute work.
- Research Tools · Research, CVE, graph, fuzzing, patching, and scanner utilities.
decepticon/tools/research/tools.py - Web Tools · HTTP, GraphQL, OAuth, JWT, and session-oriented web tooling.
decepticon/tools/web/tools.py - AD Tools · Active Directory enumeration, Kerberos, DCSync, and BloodHound-oriented actions.
decepticon/tools/ad/tools.py - Cloud Tools · AWS, Kubernetes, metadata, and Terraform-oriented cloud actions.
decepticon/tools/cloud/tools.py - Contract Tools · Smart contract analysis, patterns, Foundry, and Slither helpers.
decepticon/tools/contracts/tools.py - Bash Tools · Shell command execution and prompt handling for local or sandboxed actions.
decepticon/tools/bash/bash.py
Runtime & deployment
Model routing, sandboxing, containers, and compose-level runtime wiring.
- LLM Router · Role-based model selection, provider routing, and fallback handling.
decepticon/llm/router.py - Sandbox Backend · Operational sandbox execution and interactive session management.
decepticon/backends/docker_sandbox.py - Container Stack · Dockerfiles and entrypoints for CLI, sandbox, orchestration, and optional C2.
containers/sandbox.Dockerfile
State & evidence
Structured findings, graphs, reporting, and observability.
- Plan Schema · Structured engagement plan and finding schemas used across the runtime.
decepticon/core/schemas.py - Observability · Activity logging, metrics, and tracing for autonomous execution.
decepticon/observability/activity.py - Evidence Graph · Structured research state, Neo4j-backed graphing, and relationship storage.
decepticon/tools/research/graph.py - Reporting · Executive, timeline, and platform-specific report outputs.
decepticon/tools/reporting/executive.py
Connections 32
- Orchestrator → Engagement Loop: starts · Bootstraps the engagement runtime.
- Engagement Loop → Engagement Core: drives · Loop delegates lifecycle and objective coordination.
- Engagement Loop → Mission Planning: plans · Consumes mission package and OPPLAN inputs.
- Engagement Loop → Specialist Agents: spawns · Creates fresh specialist contexts per objective.
- Engagement Loop → LLM Router: routes prompts · Uses model routing instead of direct provider access.
- Engagement Loop → Guardrails: constrained by · Execution and skill exposure are policy-checked.
- Specialist Agents → Recon Skills: loads · Recon role pulls recon skills and references.
- Specialist Agents → Exploit Skills: loads · Exploit-oriented roles use exploit skills.
- Specialist Agents → Post-Exploit Skills: loads · Post-exploit roles use post-exploit skills.
- Specialist Agents → Shared Skills: loads · All roles share workflow and OPSEC guidance.
- Mission Planning → Planning Skills: uses · Planning templates and rules come from soundwave skills.
- Guardrails → Plan Schema: validates · Enforces plan hierarchy and objective constraints.
- Specialist Agents → Bash Tools: executes · Agents can invoke shell execution through the tool layer.
- Specialist Agents → Research Tools: uses · Research and triage roles access research tooling.
- Specialist Agents → Web Tools: uses · Web-focused agents use HTTP and auth tooling.
- Specialist Agents → AD Tools: uses · AD roles use directory and Kerberos tooling.
- Specialist Agents → Cloud Tools: uses · Cloud roles use cloud inspection and access tooling.
- Specialist Agents → Contract Tools: uses · Contract roles use contract analysis tooling.
- Research Tools → Evidence Graph: writes · Research outputs feed graph-backed evidence state.
- Research Tools → Reporting: summarizes · Findings are converted into reports and briefs.
- Evidence Graph → Reporting: feeds · Graph-backed findings drive reporting artifacts.
- Observability → Engagement Loop: observes · Logs, metrics, and traces cover the autonomous loop.
- Observability → Specialist Agents: observes · Captures agent activity and subagent streaming.
- CLI REPL → UI State: updates · UI renders from local client state and hooks.
- CLI REPL → Message Views: renders · Shows agent, tool, and system messages.
- CLI REPL → Graph Canvas: shows · Operator can inspect graph/canvas views.
- CLI REPL → Orchestrator: controls · CLI starts, stops, and monitors engagements.
- Graph Canvas → Evidence Graph: visualizes · Canvas presents relationships and findings.
- Sandbox Backend → Bash Tools: hosts · Interactive execution happens inside sandboxed sessions.
- Container Stack → Sandbox Backend: packages · Container assets define the sandbox runtime.
- Container Stack → CLI REPL: packages · CLI container builds the operator console.
- LLM Router → Plan Schema: consumes · Model prompts are shaped by the structured plan.