## 1. Project Overview & Quickstart (PurpleAILAB/LICENSE)
# LICENSE
Open-source repository PurpleAILAB/LICENSE
### Repository Details
- **Repository:** [PurpleAILAB/LICENSE](https://github.com/PurpleAILAB/LICENSE)
- **Primary Language:** Code
*Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.*
## 2. Official Technical Reference & Guides (PurpleAILAB/docs)
## File: README.md
[Empty file]
---
## File: DESIGN.md
# Decepticon Documentation Brand System
Status: implementation source of truth
Brand source: `/home/catow/GIT/bitter-security/DESIGN.md`
## 1. Brand relationship
- Bitter Security is the company brand; Decepticon is its offensive security platform.
- The site title is `Decepticon by Bitter Security` so product context remains clear while the previous company identity is no longer public-facing.
- GitHub repository links use the renamed `BitterSecurity` organization.
## 2. Identity assets
- Header, light mode: `/logos/bitter-security-lockup-on-light.svg`.
- Header, dark mode: `/logos/bitter-security-lockup-on-dark.svg`.
- Browser icon: `/logos/bitter-security-favicon.svg`, using the all-path Coupled Field symbol on Carbon.
- Header lockups and the browser icon use the all-path masters from the Bitter Security logo system. They must not be replaced with the legacy raster logo or with bitmap-scaled Bitter Security artwork.
- The logo keeps its native `138:64` aspect ratio and renders at `48px` high in the Mintlify navigation so the descriptor remains legible without exceeding the header.
## 3. Color tokens
| Token | Value | Documentation role |
|---|---|---|
| Oxide | `#B82C3D` | Primary emphasis in light mode |
| Oxide bright | `#F06A76` | Accessible emphasis in dark mode |
| Oxide ink | `#8B1828` | Buttons and hover states |
| Chalk | `#F1F0EA` | Light-mode background |
| Carbon | `#08090A` | Dark-mode background |
Oxide is the only accent. Purple, security blue, neon effects, and gradients are not part of this documentation identity.
## 4. Typography and spacing
- Geist is the documentation family for headings, navigation, and body text.
- Mintlify owns the reading scale and content measure; the rebrand does not override article typography or structural spacing.
- Korean section headings use a `20px / 28px` mobile token so compact topic-predicate phrases remain intact at 375px.
- Spacing follows the Bitter Security 4px base scale. The only custom navigation size is the `48px` logo height.
## 5. Primitives and states
- `BrandLockup`: theme-specific light and dark SVG sources; default, light-mode, dark-mode, mobile, and high-density states.
- `BrandLink`: the navbar link to `https://bittersecurity.com`; default, hover, keyboard-focus, and mobile-menu states remain Mintlify-native.
- `BrandAccent`: Mintlify controls, active navigation, links, and focus states driven only by the three Oxide configuration tokens.
## 6. Responsive and accessibility constraints
- The header lockup must remain sharp and unclipped at 375px, 768px, and 1280px widths.
- The lockup's authored title/description and Mintlify's generated logo alternative text must identify Bitter Security.
- Both color modes must preserve readable navigation, visible focus states, and the original documentation hierarchy.
- Korean navigation and article text must not clip or create single-character orphan lines at the tested breakpoints.
- Korean prose keeps words intact rather than using emergency mid-word wrapping.
## 7. Accepted design debt
None.
---
## File: docs.json
{
"$schema": "https://mintlify.com/docs.json",
"theme": "almond",
"name": "Decepticon by Bitter Security",
"description": "Decepticon, the autonomous offensive security platform by Bitter Security",
"logo": {
"light": "/logos/bitter-security-lockup-on-light.svg",
"dark": "/logos/bitter-security-lockup-on-dark.svg"
},
"favicon": "/logos/bitter-security-favicon.svg",
"colors": {
"primary": "#B82C3D",
"light": "#F06A76",
"dark": "#8B1828"
},
"fonts": {
"family": "Geist"
},
"background": {
"color": {
"light": "#F1F0EA",
"dark": "#08090A"
}
},
"icons": {
"library": "lucide"
},
"navigation": {
"languages": [
{
"language": "en",
"groups": [
{
"group": "Introduction",
"pages": [
"en/introduction/overview",
"en/introduction/history-and-evolution",
"en/introduction/pentesting-vs-redteaming"
]
},
{
"group": "Getting Started",
"pages": [
"en/getting-started/quick-start",
"en/getting-started/configuration",
"en/getting-started/library-usage"
]
},
{
"group": "Vision & Philosophy",
"pages": [
"en/vision/autonomous-hacking",
"en/vision/core-philosophy",
"en/vision/why-open-source",
"en/vision/target-architecture"
]
},
{
"group": "Concepts",
"pages": [
"en/concepts/red-team-lifecycle",
"en/concepts/threat-emulation",
"en/concepts/mitre-attack",
"en/concepts/roles-and-cells",
"en/concepts/tradecraft"
]
},
{
"group": "Features",
"pages": [
"en/features/engagement-planning",
"en/features/opplan-system",
"en/features/autonomous-execution",
"en/features/dynamic-infrastructure",
"en/features/c2-integration",
"en/features/skill-system",
"en/features/multi-model-routing",
"en/features/offensive-vaccine-pipeline",
"en/features/knowledge-graph",
"en/features/benchmark-evaluation"
]
},
{
"group": "Architecture",
"pages": [
"en/architecture/infrastructure",
"en/architecture/agents",
"en/architecture/middleware-stack"
]
},
{
"group": "CLI Reference",
"pages": [
"en/cli-reference"
]
},
{
"group": "Contributing",
"pages": [
"en/contributing/developer-setup",
"en/contributing/contributing-guide"
]
}
]
},
{
"language": "ko",
"groups": [
{
"group": "소개",
"pages": [
"ko/introduction/overview",
"ko/introduction/history-and-evolution",
"ko/introduction/pentesting-vs-redteaming"
]
},
{
"group": "시작하기",
"pages": [
"ko/getting-started/quick-start",
"ko/getting-started/configuration",
"ko/getting-started/library-usage"
]
},
{
"group": "비전 & 철학",
"pages": [
"ko/vision/autonomous-hacking",
"ko/vision/core-philosophy",
"ko/vision/why-open-source",
"ko/vision/target-architecture"
]
},
{
"group": "핵심 개념",
"pages": [
"ko/concepts/red-team-lifecycle",
"ko/concepts/threat-emulation",
"ko/concepts/mitre-attack",
"ko/concepts/roles-and-cells",
"ko/concepts/tradecraft"
]
},
{
"group": "기능",
"pages": [
"ko/features/engagement-planning",
"ko/features/opplan-system",
"ko/features/autonomous-execution",
"ko/features/dynamic-infrastructure",
"ko/features/c2-integration",
"ko/features/skill-system",
"ko/features/multi-model-routing",
"ko/features/offensive-vaccine-pipeline",
"ko/features/knowledge-graph",
"ko/features/benchmark-evaluation"
]
},
{
"group": "아키텍처",
"pages": [
"ko/architecture/infrastructure",
"ko/architecture/agents",
"ko/architecture/middleware-stack"
]
},
{
"group": "CLI 레퍼런스",
"pages": [
"ko/cli-reference"
]
},
{
"group": "기여하기",
"pages": [
"ko/contributing/developer-setup",
"ko/contributing/contributing-guide"
]
}
]
}
]
},
"navbar": {
"links": [
{
"label": "Bitter Security",
"href": "https://bittersecurity.com"
},
{
"label": "GitHub",
"href": "https://github.com/BitterSecurity/Decepticon"
}
],
"primary": {
"type": "button",
"label": "Get Started",
"href": "/en/getting-started/quick-start"
}
},
"footer": {
"socials": {
"github": "https://github.com/BitterSecurity/Decepticon",
"discord": "https://discord.gg/TZUYsZgrRG",
"x": "https://x.com/v1b3xor"
}
}
}
---
## File: en/cli-reference.mdx
---
title: "CLI Reference"
---
## Overview
Decepticon is **CLI-first**. Security work belongs in the terminal — no browser tabs, no dashboards required, no context switching. The interface is a real-time streaming CLI built with [Ink](https://github.com/vadimdemedes/ink) that shows you what the agent sees, as it happens.
The CLI is delivered as a single Go-based launcher (`decepticon`) that orchestrates the underlying Docker stack and opens the React/Ink interactive UI.
## Top-Level Commands
### `decepticon`
Start all services and open the interactive CLI.
```bash
decepticon
```
Starts the full stack — agent API server, LiteLLM proxy, Kali sandbox, PostgreSQL, Neo4j, optional Sliver C2 — and opens the streaming CLI. This is the primary entry point for creating and running engagements.
### `decepticon onboard`
Run the interactive setup wizard.
```bash
decepticon onboard
decepticon onboard --reset # Reconfigure from scratch
```
Configures:
- LLM provider and API key (Anthropic, OpenAI, Google, MiniMax, Anthropic OAuth via Claude subscription)
- Authentication priority order
- Model profile (`eco`, `max`, `test`)
- LangSmith tracing toggle and key
The wizard writes `.env` and persists provider order. Use `--reset` to throw away existing configuration.
### `decepticon demo`
Run the guided demonstration.
```bash
decepticon demo
```
Launches Metasploitable 2 as a target, loads a pre-built engagement (RoE, ConOps, OPPLAN), and executes the full kill chain autonomously — port scan, vsftpd exploitation, Sliver C2 implant deployment, credential harvesting, internal reconnaissance.
The demo is the fastest way to see Decepticon in action. No additional configuration needed beyond your API key.
### `decepticon status`
Show service status.
```bash
decepticon status
```
Lists each Docker service in the stack with its current state — running, stopped, restarting — and exposed ports. Useful for verifying that the stack came up cleanly before launching the CLI.
### `decepticon logs [service]`
Tail service logs.
```bash
decepticon logs # Tail all services
decepticon logs langgraph # Tail just the LangGraph platform
decepticon logs litellm # Tail the LLM proxy
decepticon logs sandbox # Tail the Kali sandbox
decepticon logs postgres # Tail the database
decepticon logs neo4j # Tail the knowledge graph
decepticon logs web # Tail the Next.js dashboard
```
Streams logs in `docker compose logs -f` style. The most common debugging entry point — if Decepticon is misbehaving, this is where to look first.
### `decepticon kg-health`
Diagnose the knowledge graph.
```bash
decepticon kg-health
```
Runs Neo4j connectivity and schema checks. Reports orphaned nodes, missing relationships, and any constraint violations. Useful after a long engagement before exporting the deliverable.
### `decepticon stop`
Stop all services.
```bash
decepticon stop
```
Gracefully stops all Docker containers — agent API, LiteLLM proxy, sandbox, C2 server, database, knowledge graph, and web dashboard.
### `decepticon update`
Check for and apply updates.
```bash
decepticon update
```
Checks GHCR for newer pre-built images and updates the local installation. The launcher itself is updated separately via the install script.
### `decepticon remove`
Uninstall Decepticon.
```bash
decepticon remove
```
Tears down all containers, removes images, and deletes the engagement workspace. Use with care — engagement data is purged unless explicitly exported first.
### `decepticon --version`
Show the launcher version.
```bash
decepticon --version
```
## C2 Profiles
Enable C2 frameworks via Docker Compose profiles. The default install enables `c2-sliver`.
```bash
# Start with Sliver C2 (default)
COMPOSE_PROFILES=c2-sliver decepticon
# Start with Sliver C2 plus the demo target stack
COMPOSE_PROFILES=c2-sliver,demo decepticon
```
## CLI Keybindings
The interactive CLI exposes the following key shortcuts:
| Key | Action |
|---|---|
| `Ctrl+O` | Toggle Prompt ↔ Transcript view |
| `Ctrl+G` | Cycle the graph sidebar (Overview / Nodes / Flows) |
| `Ctrl+B` | Toggle the sidebar visibility |
| `Ctrl+C` | Cancel the current action / exit if at top level |
| `Esc` | Exit transcript view |
## Slash Commands
Inside the CLI prompt, you can invoke:
| Command | Action |
|---|---|
| `/help` | Show inline help |
| `/clear` | Clear the current conversation |
| `/resume [msg]` | Resume the last engagement; optional message appended |
| `/quit` | Quit the CLI (services keep running; use `decepticon stop` to halt them) |
## Developer Commands
For contributors working on Decepticon itself:
```bash
make dev # Build + start with hot-reload (docker compose watch)
make cli # Open interactive CLI (separate terminal)
make start # Start in background (production-like, no hot-reload)
make stop # Stop all services
make test # Run pytest inside the container
make lint # Lint + typecheck locally (requires: uv sync --dev)
make help # Show all available Makefile targets
```
Full development environment setup guide for contributors.
---
## File: en/architecture/agents.mdx
---
title: "Agents"
---
## Agent Architecture
Decepticon operates through **sixteen specialist agents**, each with its own tools, skills, and clean context window. Agents are spawned fresh per objective — no accumulated noise, no degraded reasoning across long engagements.
The agents are not a flat list. They are organized by the engagement phase they serve, and routed by the **Decepticon orchestrator** through the OPPLAN.
## Orchestration Layer
The central red-team coordinator. Owns the OPPLAN, sequences objectives, resolves dependencies, and dispatches specialists (`recon`, `exploit`, `postexploit`, `analyst`, `reverser`, `contract_auditor`, `cloud_hunter`, `ad_operator`) via SubAgent middleware. Runs on the most capable model tier.
Vulnerability research orchestrator — runs the five-stage pipeline (`scanner → detector → verifier → patcher → exploiter`) with state passed between stages exclusively through the knowledge graph.
Engagement planner. Standalone graph (not a sub-agent of Decepticon). Interviews the operator and generates the complete engagement package — RoE, ConOps, Deconfliction Plan, OPPLAN, and threat profile. No bash access; produces documents only.
## Reconnaissance Phase
Active and passive recon — port scanning, service enumeration, OSINT, subdomain discovery, certificate-transparency mining. Operates inside the Kali sandbox.
## Vulnerability Research Pipeline
Sub-agents of the **Vulnresearch** orchestrator. State flows between stages via the knowledge graph; each stage runs with fresh context.
Stage 1 — broad-spectrum scanner. Walks large codebases in parallel and emits CANDIDATE nodes with heuristic suspicion scores. Cheap, fast, no vulnerability reasoning.
Stage 2 — vulnerability detector. Reads source around each CANDIDATE and promotes real bugs to VULNERABILITY + HYPOTHESIS nodes, or rejects them as false positives. Read-only (no bash).
Stage 3 — two-method verification gate. Confirms candidate findings through at least two independent evidence channels before downstream work begins.
Stage 4 — reproducible PoC author. Produces working proof-of-concept exploits for verified vulnerabilities, with reliability notes.
Stage 5 — patch generator. Produces a code or configuration change that closes the vulnerability without breaking the application, plus a regression test.
## Exploitation & Post-Exploitation
Initial access and exploitation tactics. Web/AD attacks (SQLi, SSTI, Kerberoasting, ADCS abuse, credential attacks).
Privilege escalation, lateral movement, credential harvesting, persistence — often via Sliver C2 sessions once initial access is established.
## Domain Specialists
Active Directory specialist. Kerberoasting, AS-REP roasting, ADCS ESC1–ESC15, DCSync, ticket forging, ACL abuse, GPO manipulation, BloodHound path analysis.
Cloud infrastructure specialist. IAM privilege escalation, S3/Azure storage exposure, Kubernetes RBAC escapes, metadata-service abuse across AWS/Azure/GCP.
Solidity / EVM smart-contract auditor. Reentrancy, oracle manipulation, flash-loan abuse, access-control flaws; Slither static analysis + Foundry PoC harness.
Binary reverse-engineering specialist. ELF/PE/Mach-O triage, packer detection, string/symbol extraction, ROP gadget inventories, Ghidra/radare2 scripting.
## Analysis & Reporting
Vulnerability research and reporting specialist. Cross-correlates findings, queries the knowledge graph, and drafts the engagement narrative — source code review, static analysis (semgrep/bandit/gitleaks), dependency CVE sweeps, and multi-hop exploit chain construction.
## Clean Context Per Objective
Every agent spawns with a **fresh context window** for every objective:
```
Objective 1 (Recon) → New Recon agent instance → Findings saved to disk + graph
Objective 2 (Exploit) → New Exploit agent instance → Reads obj-1 findings explicitly
Objective 3 (Post-Exp) → New Post-Exploit instance → Reads obj-1+2 findings explicitly
```
- **No accumulated noise** — Context doesn't degrade across a 100-objective engagement.
- **Targeted context** — Each agent receives only the findings relevant to its objective.
- **Persistent state** — Findings live on disk and in Neo4j, not in agent memory.
## Agent Middleware Stack
Each agent runs with a stack of middleware that provides cross-cutting concerns. The exact stack depends on the agent's role.
| Agent Role | Middleware Stack |
|---|---|
| **Decepticon (Orchestrator)** | EngagementContext → Skills → Filesystem → SubAgent → OPPLAN → ModelFallback → Summarization → PromptCaching → PatchToolCalls |
| **Vulnresearch (Orchestrator)** | Skills → Filesystem → SubAgent → OPPLAN → ModelFallback → Summarization → PromptCaching → PatchToolCalls |
| **Soundwave (Planner)** | EngagementContext → Skills → Filesystem → ModelFallback → Summarization → PromptCaching → PatchToolCalls |
| **Specialist (Recon, Exploit, ...)** | Skills → Filesystem → ModelFallback → Summarization → PromptCaching → PatchToolCalls |
### What Each Layer Does
- **EngagementContext** — Injects engagement metadata (slug, target, RoE summary) into the system prompt so guardrails are evaluated continuously.
- **Skills** — Progressive-disclosure skill loading filtered by ATT&CK overlap with the active threat profile. Frontmatter loads at startup (~100 tokens/skill); full body is fetched on-demand via `read_file`.
- **Filesystem** — `FilesystemMiddlewareNoExecute` — provides `read_file`, `write_file`, `edit_file`, `ls`, `glob`, `grep` against the engagement workspace. Execute is intentionally disabled; specialists use the dedicated `bash` tool instead.
- **SubAgent** — `task()` tool for orchestrators (Decepticon, Vulnresearch) to dispatch work to specialists.
- **OPPLAN** — Five CRUD tools (`add_objective`, `get_objective`, `list_objectives`, `update_objective`, `objective_expand`) and dynamic state injection of objectives into every LLM call.
- **OpsControl** — Auto-injects workload-lifecycle state transitions (`starting → running → exited`) into the agent's next turn, so the orchestrator never polls after calling `ops_start(...)`. See [Dynamic Infrastructure](/en/features/dynamic-infrastructure).
- **SandboxNotifications** — When a `bash` command launched with `run_in_background=true` finishes, the captured output is auto-fetched and injected on the next inference turn. The agent doesn't have to remember to call `bash_output()`.
- **ModelFallback** — Provider failover when a model is rate-limited or down. Walks the fallback chain built from the user's credentials inventory.
- **Summarization** — Conversation-window compression for long-running specialists.
- **PromptCaching** — `AnthropicPromptCachingMiddleware` — places prompt-cache boundary markers; silently no-ops on non-Anthropic providers.
- **PatchToolCalls** — Sanitizes and normalizes tool-call shapes for cross-provider compatibility (Anthropic, OpenAI, Google, MiniMax, …).
## Agent–Tool Interaction
Agents interact with offensive tools through persistent tmux sessions inside the Kali sandbox:
```
Agent → Docker Socket → Kali Sandbox → tmux session → Tool (sliver-client, msfconsole, evil-winrm, ...)
↓
Prompt Detection
↓
Follow-up Commands
```
When a tool presents an interactive prompt (`sliver >`, `msf6 >`, `PS C:\>`), the agent:
1. Detects the prompt pattern.
2. Interprets the tool's output.
3. Sends the appropriate follow-up command.
4. Handles control signals (`C-c`, `C-z`) when needed.
Output is tiered:
- **Inline (≤15K)** — Returned directly to the agent.
- **Offload (15K–100K)** — Written to `/workspace/.scratch/` and referenced by path.
- **Watchdog (>5M)** — The session is killed and the agent is asked to refine.
This is how real operators work. Decepticon's specialists do the same.
The structured plan that the orchestrator dispatches to these agents.
The isolated network architecture these agents operate within.
---
## File: en/architecture/infrastructure.mdx
[Binary file]
---
## File: en/architecture/middleware-stack.mdx
---
title: "Middleware Stack"
---
Every Decepticon agent inherits a middleware stack that handles concerns common to all agents — RoE enforcement, skill loading, prompt caching, model fallback, conversation summarization. This page documents what each layer does and why it exists.
## Why Middleware
A monolithic agent prompt that tries to handle everything ends up doing nothing well. Decepticon factors cross-cutting concerns into composable middleware:
- The agent prompt focuses on its specialty.
- Behaviors common to all agents (RoE checks, skill loading) live in one place.
- Cross-provider compatibility (Anthropic, OpenAI, Google, MiniMax) is handled below the prompt, not inside it.
## The Layers
### Skills
`DecepticonSkillsMiddleware` (subclass of LangChain's `SkillsMiddleware`).
- Loads only skill *frontmatter* at startup (~100 tokens per skill).
- Filters skills by ATT&CK overlap with the active threat profile.
- Loads full skill body on-demand when the agent invokes `read_file()`.
- Enforces the **SKILL-FIRST RULE**: agents must load the relevant skill before acting on a matching trigger.
### Filesystem
`FilesystemMiddlewareNoExecute` — sandboxed file access scoped to the engagement workspace. Provides `read_file`, `write_file`, `edit_file`, `ls`, `glob`, and `grep` against `/workspace/{engagement_id}/`. Execute is intentionally disabled; specialists use the dedicated `bash` tool for command execution.
### SubAgent
Exposes the `task()` tool to the orchestrator. Lets Decepticon dispatch work to specialist agents (Recon, Exploit, Analyst, ...) without inlining their prompts. SubAgent outputs are wrapped in `StreamingRunnable` so they stream through the CLI and HTTP API.
### OPPLAN
The structural backbone of orchestration:
- Exposes five CRUD tools — `add_objective`, `get_objective`, `list_objectives`, `update_objective`, `objective_expand`.
- Injects current OPPLAN state (pending, in-progress, complete) into every LLM call.
- Resolves dependencies — refuses to dispatch objectives whose prerequisites are not complete.
- Supports the Pentesting Task Tree (PTT) via `objective_expand`.
### EngagementContext
The RoE/ConOps guard rail. On every iteration, the middleware injects:
- The active Rules of Engagement.
- The Concept of Operations.
- The current threat profile.
The agent's reasoning is therefore continuously evaluated against scope and adversary identity, not just at the start of the session.
### ModelFallback
Provider failover. Each model profile defines a fallback chain — for example: `claude-opus-4-7 → gpt-5.5 → gemini-2.5-pro → MiniMax-M2.5`. When a provider rate-limits or errors, the next provider in the chain is invoked transparently.
### Summarization
Conversation-window compression. When a specialist agent's context approaches the model's window, prior turns are summarized into a structured digest. Findings, tool outputs, and decisions are preserved; verbatim chat history is collapsed.
### PromptCaching
Anthropic's prompt-cache boundary markers. The middleware places the `CACHE_BOUNDARY` marker between static prompt sections (system prompt, skill catalog) and dynamic sections (live OPPLAN state, current iteration). This lets repeated calls hit the cache, dropping per-call cost dramatically on long engagements.
### PatchToolCalls
The cross-provider compatibility shim. Different providers represent tool calls differently — the middleware normalizes them before they hit the agent prompt and re-shapes them on the way out, so a single agent definition runs against any supported provider.
### OpsControlNotifications
Subscribes to the `opscontrol` daemon's workload-state events (ADR-0006). When a workload transitions (`starting → running → exited`), the middleware injects a `` `HumanMessage` carrying the new state onto the orchestrator's next inference. The orchestrator never polls after `ops_start("c2-sliver")` — completion comes to it. Mounted on the Decepticon orchestrator only.
### SandboxNotifications
The bash-side counterpart. When a `bash` command launched with `run_in_background=True` finishes, the middleware fetches the captured output diff from the sandbox and injects it as a `` on the agent's next turn. The specialist never has to remember to call `bash_output()`. Same shape as `OpsControlNotifications`; mounted on every agent that holds the `bash` tool.
### KG (KGMiddleware)
Owns the engagement-scoped Neo4j `KGStore` and exposes the two agent-facing graph tools — `kg_record(observations)` for atomic batch writes and `kg_ingest(scanner_kind, path)` for scanner-adapter dispatch. Enforces the engagement-label validator on every call, so two parallel engagements never bleed into each other's graph state.
### Skillogy
A thin REST client of the standalone Skillogy service. Exposes `find_skill`, `load_skill`, and `traverse` against the Neo4j-backed skill graph (port `9100`). Carries an `allowed_path_prefixes` parameter set by the agent factory; the service enforces the hard ACL ([ADR-0008](https://github.com/BitterSecurity/Decepticon/blob/main/docs/adr/0008-skillogy-hard-acl-phase1a.md)) so a specialist can't be talked into browsing another role's skills via prompt injection.
### HITL
Wraps LangGraph's native `interrupt()` pattern so the agent can pause for operator approval on consequential actions — production-targeting commands, exfiltration of sensitive data classes, anything flagged by the RoE as high blast radius. The operator sees the proposed action, can approve/redirect/abort, and the agent resumes from the same node.
## Stack Composition by Role
The exact order of middleware matters — outer layers wrap inner ones. The orchestrator and planner inject `EngagementContext` first so RoE/ConOps guardrails apply to every subsequent layer; specialists inherit those guardrails through the OPPLAN slice they receive.
```
┌─ Decepticon Orchestrator ──────────────────┐
│ EngagementContext │
│ └─ Skills │
│ └─ Filesystem │
│ └─ SubAgent │
│ └─ OPPLAN │
│ └─ ModelFallback │
│ └─ Summarization │
│ └─ PromptCache │
│ └─ Patch │
└─────────────────────────────────────────────┘
┌─ Vulnresearch Orchestrator ────────────────┐
│ Skills │
│ └─ Filesystem │
│ └─ SubAgent │
│ └─ OPPLAN │
│ └─ ModelFallback │
│ └─ Summarization │
│ └─ PromptCache │
│ └─ Patch │
└─────────────────────────────────────────────┘
┌─ Soundwave Planner ────────────────────────┐
│ EngagementContext │
│ └─ Skills │
│ └─ Filesystem │
│ └─ ModelFallback │
│ └─ Summarization │
│ └─ PromptCache │
│ └─ Patch │
└─────────────────────────────────────────────┘
┌─ Specialist (Recon, Exploit, ...) ─────────┐
│ Skills │
│ └─ Filesystem │
│ └─ ModelFallback │
│ └─ Summarization │
│ └─ PromptCache │
│ └─ Patch │
└─────────────────────────────────────────────┘
```
Specialists also bind the `bash` tool for sandbox command execution; Soundwave does not.
## Streaming Through the Stack
Sub-agent outputs do not collect-and-return — they stream. `StreamingRunnable` wraps every sub-agent so its tokens arrive at:
1. The Python CLI's `UIRenderer` (Ink terminal UI).
2. The LangGraph HTTP custom-event channel (web dashboard).
This is how the operator sees Recon enumerate ports in real time, not after the fact.
The sixteen specialist agents that this middleware stack wraps.
The structured plan that the OPPLAN middleware exposes and injects.
---
## File: en/concepts/mitre-attack.mdx
---
title: "MITRE ATT&CK"
---
MITRE's [Adversarial Tactics, Techniques, and Common Knowledge (ATT&CK)](https://attack.mitre.org/) is a curated knowledge base of cyber-adversary behavior, organized by the phases of an adversary's lifecycle and the platforms they target. Decepticon uses ATT&CK as the connective tissue between threat profiles, OPPLAN objectives, skills, and findings.
## The TTP Hierarchy
ATT&CK is built on a three-level hierarchy. Decepticon adopts this vocabulary consistently — agents, skills, and findings all reference the same identifiers.
The tactical *goals* a threat may pursue during an operation. Examples: Initial Access (TA0001), Execution (TA0002), Persistence (TA0003), Privilege Escalation (TA0004).
The *actions* threats take to achieve their tactical goals. Examples: T1566 Phishing, T1059 Command and Scripting Interpreter, T1078 Valid Accounts.
The *technical steps* required to perform a technique in a specific environment. Procedures are concrete commands, scripts, and tool invocations.
## Where ATT&CK Surfaces in Decepticon
ATT&CK is not just metadata — it is the type system Decepticon agents reason in.
| Surface | ATT&CK Use |
|---|---|
| **Threat Profile** | The profile lists in-scope techniques; Decepticon refuses out-of-profile actions. |
| **OPPLAN Objectives** | Every objective carries a `mitre_attack` field with one or more T-IDs. |
| **Skills** | Skill frontmatter includes `mitre_attack: T1590, T1591, ...` — used for filtering and trigger matching. |
| **ConOps** | The "adversary of record" section enumerates the techniques the threat is known to use. |
| **Findings** | Each finding produced by Decepticon is tagged with the technique used and the resulting evidence. |
| **Defense Brief** *(planned)* | A future defense component will map each offensive action to the corresponding detection or mitigation technique. Today, operators assemble the brief manually from Vulnresearch pipeline outputs (`Detector` rules, `Patcher` patches). |
## Skill Frontmatter Example
A Decepticon skill carries ATT&CK metadata that the orchestrator uses to load only the right skills for the active engagement:
```yaml
---
name: passive-recon
description: "Use when gathering intelligence WITHOUT touching the target"
allowed-tools: Bash Read Write
metadata:
subdomain: reconnaissance
tags: passive, dns, subdomain-enum, whois, ct-logs
mitre_attack: T1590, T1591, T1592
---
```
When a threat profile lists `T1590` as an in-scope technique, this skill becomes available. When the operator switches to a profile that does not include it, the skill is excluded from the agent's working set.
## ATT&CK Matrix Coverage
Decepticon's skill library covers the canonical attack lifecycle:
| Tactic | Decepticon Coverage |
|---|---|
| Reconnaissance | Passive recon (OSINT, CT logs, DNS), active recon (port scan, service enum) |
| Resource Development | Implant generation via Sliver C2 |
| Initial Access | Web exploitation, AD initial access, phishing-payload generation |
| Execution | Bash, PowerShell, scripting via interactive sandbox |
| Persistence | Service hijacking, scheduled tasks, WMI (via Post-Exploit) |
| Privilege Escalation | Local privesc, domain privesc (AD Operator) |
| Defense Evasion | OPSEC skill set, AMSI/ETW awareness, log evasion |
| Credential Access | Kerberoasting, LSASS dumping, cloud key extraction |
| Discovery | Internal recon, AD enumeration, cloud metadata abuse |
| Lateral Movement | Pass-the-hash, RDP, SSH pivoting, cloud session theft |
| Collection | Sensitive-data discovery, screenshot capture |
| Command and Control | Sliver mTLS / HTTPS / DNS channels, tiered callbacks |
| Exfiltration | DNS tunneling, web upload, C2 channel exfil |
| Impact | Modeled but constrained by RoE — proof-of-impact only |
## ATT&CK Navigator Export
Decepticon emits an ATT&CK Navigator-compatible JSON layer per engagement, listing exactly which techniques were used and which produced findings. This file becomes part of the engagement deliverable — the blue team can overlay it on their own detection coverage to find gaps.
The TTP hierarchy is verbatim from MITRE: *Tactics* are goals, *Techniques* are actions, *Procedures* are concrete steps. Decepticon agents are trained to use these terms precisely — never interchangeably.
How the progressive-disclosure skill loader filters by ATT&CK technique overlap.
---
## File: en/concepts/red-team-lifecycle.mdx
---
title: "Red Team Engagement Lifecycle"
---
A red team engagement is not a vulnerability scan with extra steps. It is a structured campaign against a real-world threat profile, executed in three phases, governed by formal documents (RoE, ConOps, OPPLAN), and adjudicated against the eight canonical engagement goals.
## The Three Phases
Establish initial access without tipping the blue team. The footprint is the cost — the smaller, the better. Decepticon executes Get In through the **Recon** and **Exploit** agents, driven by the OPPLAN's `INITIAL_ACCESS` objectives.
Persistence and command-and-control. The objective is survivability — beacons that survive reboots, defender response, and EDR sweeps. Decepticon establishes Sliver C2 sessions and tiered callbacks here.
Achieve the engagement goals — privilege escalation, lateral movement, credential access, data discovery, exfiltration, operational impact. Decepticon's **Post-Exploit** agent runs Act objectives, OPPLAN-tagged with MITRE ATT&CK IDs.
## C2 Tiering
During Stay In, command-and-control is structured into tiers. Each tier balances responsiveness against detection risk.
| Tier | Callback Cadence | OPSEC Profile | Use Case |
|---|---|---|---|
| `INTERACTIVE` | Seconds | High exposure | Live operator control during a hot objective |
| `SHORT_HAUL` | 1–24 hours | Moderate | Reliable operational access for ongoing objectives |
| `LONG_HAUL` | 24+ hours | Low exposure | Persistent fallback channel that survives defender hunting |
Decepticon's OPPLAN objectives are tagged with the appropriate `C2Tier` so the agent knows which channel to use for each action.
## The Eight Engagement Goals
A red team engagement is judged against canonical goals — what was the team trying to achieve, and did the blue team detect it? Decepticon adopts the same eight categories used across the industry:
Evaluate physical and badge controls — door access, tailgating, RFID cloning.
Reach a named crown-jewel system (SWIFT, ERP, prod database, code-signing infra).
Pivot across segments — DMZ to corp, corp to OT, cloud to on-prem.
Promote from low-privilege user to local admin, domain admin, or cloud-tenant root.
Locate sensitive data — secrets, source code, customer records, IP.
Move data out without DLP catching it. The route matters as much as the bytes.
Operate without triggering SIEM, EDR, NDR, or human analyst tickets.
Demonstrate the consequence — business disruption, integrity, availability.
## How Decepticon Maps to the Lifecycle
Decepticon's agent topology is built around this lifecycle, not around tools.
| Phase | Primary Agents | Skills Surface |
|---|---|---|
| **Plan** (pre-engagement) | Soundwave | RoE, ConOps, Deconfliction, OPPLAN, Threat Profile |
| **Get In** | Recon, Scanner, Exploit, Exploiter | Passive/active recon, web exploitation, AD initial access |
| **Stay In** | Post-Exploit, AD Operator, Cloud Hunter | Persistence, C2 sessions, defense evasion, OPSEC |
| **Act** | Post-Exploit, Analyst | Lateral movement, credential access, finding capture, Vulnresearch pipeline outputs (the planned Defender component will eventually generate the defense brief from these) |
The orchestrator (Decepticon agent) sequences objectives across phases and spawns specialist agents with fresh context windows so reasoning never degrades.
## Engagement Documents
Every Decepticon engagement produces — and is bound by — four documents:
Scope, restrictions, communication plan, deconfliction. Authority to operate.
Threat profile, methodology, success criteria, infrastructure plan.
How the red team separates its activity from real-world incidents during the engagement.
Objective list — each with MITRE ATT&CK IDs, kill chain phase, dependencies, acceptance criteria.
This three-phase framing is adapted from the [redteam.guide methodology](https://redteam.guide/docs/Concepts/red-teaming/) and the book *Red Team Development and Operations* by Joe Vest and James Tubberville. Decepticon's contribution is making each phase agent-executable.
---
## File: en/concepts/roles-and-cells.mdx
---
title: "Roles & Cells"
---
A red team engagement is not just "attackers versus defenders." It is a structured exercise with named roles, each with distinct responsibilities. Decepticon does not replace any of these roles — it operates as a force multiplier inside the **Red Cell**, with explicit handshakes to the others.
## The Four Cells
The offensive component. Simulates strategic and tactical responses of the threat profile. Operates within the RoE. **Decepticon executes here.**
All components defending the target — SOC analysts, IR responders, internal staff, management. The audience whose effectiveness the engagement is measuring.
The referee. Monitors RoE compliance, separates real incidents from exercise activity, and adjudicates outcomes. Trusted by both Red and Blue.
A privileged insider with detailed knowledge of engagement activities. Prevents irreversible damage and authorizes high-risk steps.
## Why the Cells Matter for an Autonomous Agent
The cells are not bureaucracy — they are the boundaries that keep an offensive engagement from turning into an incident. An autonomous agent without these handshakes is reckless. Decepticon is built to fit inside the cell structure, not around it.
| Cell | Decepticon Touchpoint |
|---|---|
| **Red Cell** | Decepticon agents are Red Cell members. They produce findings, evidence, and an attack graph attributable to the engagement. |
| **Blue Cell** | Decepticon does not interact with the Blue Cell during execution. The blue team sees only the artifacts — alerts, telemetry, lateral movement — that the agent generates. |
| **White Cell** | The operator running Decepticon acts as White Cell liaison: pausing the agent on deconfliction calls, certifying RoE compliance, declaring outcomes. The CLI exposes pause/resume primitives for exactly this. |
| **Trusted Agent** | Whoever holds the OPPLAN approval authority is the Trusted Agent for the engagement. Decepticon refuses to start an engagement without an explicitly approved RoE and OPPLAN. |
## Deconfliction
**Deconfliction** is the process that separates red team activity from real-world activity. It is what allows a SOC to ignore the red team's beacon when a real incident lights up next to it — and, more importantly, what stops them from ignoring a real incident because they thought it was the red team.
Decepticon supports deconfliction in three ways:
Every command Decepticon executes is tagged with an engagement ID. White Cell can query "what was Red doing at 03:14 UTC?" and get an authoritative answer in seconds.
The CLI exposes a graceful pause that halts new objective scheduling without tearing down running C2 sessions, so deconfliction calls don't burn the engagement.
All agent actions, tool invocations, and findings are persisted to PostgreSQL with timestamps. The log is the deconfliction record.
## Operator-as-White-Cell
In small engagements, the human running Decepticon often plays multiple cells — operator (Red), referee (White), and authority holder (Trusted Agent). Decepticon's CLI is built around this reality:
- The OPPLAN approval gate forces the operator to act as Trusted Agent before execution starts.
- The streaming transcript gives operator visibility identical to a White Cell observer.
- The pause/resume controls let the operator perform deconfliction handshakes mid-engagement.
For larger engagements, the operator can split these duties — running Decepticon under one identity (Red Cell) and providing deconfliction logs to a separate White Cell process.
The cell model is adapted from the [redteam.guide roles & relationships](https://redteam.guide/docs/Concepts/role-relationships/) page. Decepticon does not change the model — it slots into it.
How Soundwave produces the RoE and OPPLAN that the cells operate against.
---
## File: en/concepts/threat-emulation.mdx
---
title: "Threat Emulation"
---
A red team engagement that does not emulate a real threat is just a structured pentest with extra paperwork. The discipline of **threat emulation** — mimicking the TTPs of a specific adversary — is what makes red teaming meaningful.
## "The Threat Gets a Vote"
The principle, codified by [redteam.guide](https://redteam.guide/docs/Concepts/red-teaming/) and inherited from military doctrine, is simple: **engagements must be grounded in what real threats actually do, not just what defenders plan for.**
A blue team that prepares for the threat they wish they had — instead of the threat that actually exists — has prepared for nothing. Decepticon enforces this principle by requiring an explicit threat profile before generating an OPPLAN.
## The Threat Profile
Decepticon adopts the seven-field threat profile structure used across the industry. Each engagement begins by selecting or authoring a profile:
| Field | Purpose | Example (AUTOBANK) |
|---|---|---|
| **Description** | Threat level, methods, motivation | "Financially motivated APT inspired by Carbanak" |
| **Goal & Intent** | What the threat actor is trying to achieve | "Access SWIFT infrastructure for fraudulent transfers" |
| **Key IOCs** | Indicators of compromise associated with the actor | Specific C2 domains, malware families, certificate patterns |
| **C2 Overview** | Channels, tiers, callback patterns | DNS, HTTPS, SMB; long-haul fallback to cloud-fronted CDN |
| **TTPs** | Tactics, techniques, procedures (mapped to MITRE ATT&CK) | T1566.001 phishing, T1059.001 PowerShell, T1003.001 LSASS |
| **Exploitation** | Initial access methods | Spear-phishing with macro-enabled documents |
| **Persistence** | How continued presence is maintained | Scheduled tasks, WMI subscriptions, service hijacking |
The threat profile is not a wishlist — it is a constraint. Decepticon will not use techniques that are out of profile, because the value of emulation is precisely that it teaches the blue team to recognize *that adversary*.
## How Decepticon Consumes a Threat Profile
When you start an engagement, the **Soundwave** planning agent interviews the operator and produces:
Soundwave selects or composes a profile from the seven-field template, then weaves it into the Concept of Operations as the engagement's "adversary of record."
Each objective is tagged with MITRE ATT&CK IDs. The orchestrator refuses to schedule objectives whose TTPs fall outside the profile.
Decepticon's progressive-disclosure skill system loads only skills whose `mitre_attack` tags overlap with the profile. Out-of-profile skills are kept off the agent's working set.
The C2 tier and channel choices (Sliver mTLS, HTTPS, DNS) are picked to mirror the profile's actual tradecraft — so the blue team's detections fire against the right shapes.
## Threat Profile vs. Pentest Scope
A pentest scope says *"these IPs, these apps, these dates."* A threat profile says *"this adversary, with these capabilities, motivated by these goals."* The two are not interchangeable.
| Pentest Scope | Threat Profile |
|---|---|
| "Test web app X" | "Emulate AUTOBANK's path to SWIFT" |
| Bounded by asset list | Bounded by TTP catalog |
| Success = vulnerabilities found | Success = blue team measured |
| Tools picked by tester | Tools picked by adversary |
## Authoring a Custom Profile
Custom profiles live alongside the default ones in the Soundwave skills directory. A minimal profile is YAML frontmatter plus prose:
```yaml
---
name: cybersnake
description: "Espionage actor targeting energy sector — slow, patient, DNS-heavy C2"
goal_intent: "ICS reconnaissance and dwell"
c2_channels: [dns, https]
c2_tier: long_haul
mitre_attack:
- T1078.004 # Cloud Accounts
- T1090.003 # Multi-hop Proxy
- T1071.004 # DNS C2
exploitation: "Compromised contractor VPN credentials"
persistence: "Service hijacking on jump hosts"
---
CYBERSNAKE prefers patience over noise. It will dwell for weeks
inside a network before any data movement, and routes all C2 through
DNS over a multi-hop proxy chain.
```
When this profile is selected, every Decepticon agent inherits its constraints — including the orchestrator's refusal to schedule fast-callback C2 or noisy initial-access vectors.
See how progressive-disclosure skills filter by ATT&CK overlap with the active threat profile.
---
## File: en/concepts/tradecraft.mdx
---
title: "Tradecraft & OPSEC"
---
**Tradecraft** is the techniques and procedures of espionage — used in red teaming interchangeably with TTPs. **OPSEC** (Operational Security) is the discipline of identifying critical information and controlling whether your actions can be observed by the adversary (in our case, the blue team).
Decepticon does not treat tradecraft as a postscript. The DO and DON'T principles below are codified into agent middleware, skill defaults, and the bash tool's prompt detection — so the agent operates the way a competent human red teamer would, by default.
## DO
Every command, every output, every finding — to PostgreSQL, with engagement tag and timestamp. No silent actions.
The SKILL-FIRST rule: agents must load the relevant skill before acting on a matching trigger. Skills carry tradecraft warnings inline.
Each skill documents what artifacts the tool leaves — registry keys, log entries, parent-process anomalies — so OPSEC tradeoffs are explicit.
Tier C2 by exposure. Long-haul callbacks for persistence, short-haul for active objectives, interactive only when needed.
After every initial access or pivot, run lightweight enumeration before noisy actions. Know the host before you make noise on it.
Prefer PowerShell, bash, and OS utilities to dropped binaries. Smaller artifact footprint, fewer EDR signals.
## DON'T
Decepticon's skills only reference tools that have been validated in the sandbox. Novel binaries are an OPSEC failure waiting to happen.
Sliver channels default to mTLS, HTTPS, or DNS. Plaintext C2 is forbidden by default in every Decepticon profile.
Drop into `%TEMP%` or unwritable system directories with care — these are the first paths defenders look at. Skills steer toward expected locations.
The EngagementContext middleware refuses objectives that would exfiltrate regulated data. Proof-of-access is not proof-of-exfil.
If the operator pauses the engagement, the agent halts new objective scheduling. Deconfliction overrides momentum.
The EngagementContextMiddleware checks every iteration against the RoE. Out-of-scope actions are refused, not warned.
## How Tradecraft Is Codified
These principles are not aspirational — they are middleware.
| Principle | Enforcement Mechanism |
|---|---|
| Log everything | All tool calls persisted via the bash tool's tier-1 capture, then to PostgreSQL |
| RoE compliance | `EngagementContextMiddleware` injects RoE/ConOps into every LLM call and rejects out-of-scope actions |
| OPSEC defaults | Skill frontmatter `metadata.opsec_level` informs the orchestrator of risk tier per action |
| C2 tier discipline | OPPLAN objectives carry `c2_tier` (`INTERACTIVE`, `SHORT_HAUL`, `LONG_HAUL`); orchestrator enforces use |
| Built-ins first | The `shared/opsec` skill is loaded by default and steers agents toward LOLBins and OS utilities |
| Deconfliction | CLI pause primitive halts new objective scheduling without tearing down sessions |
## Tradecraft and the Threat Profile
Tradecraft is not generic — it is profile-specific. AUTOBANK's tradecraft is loud-and-fast (financially motivated, smash-and-grab); CYBERSNAKE's is slow-and-patient (espionage). Decepticon enforces *the active profile's* tradecraft, not an abstract ideal.
When the orchestrator schedules an objective, it asks: *"Would the threat actor in our profile do this, this way, at this cadence?"* If the answer is no, the objective is reframed or rejected.
The DO/DON'T taxonomy is adapted from [redteam.guide's tradecraft page](https://redteam.guide/docs/Planning/red-team-tradecraft/). Decepticon's contribution is enforcement — moving the principles from a checklist to runtime middleware.
How OPPLAN objectives carry the tradecraft constraints into agent execution.
---
## File: en/contributing/contributing-guide.mdx
---
title: "Contributing Guide"
---
## We Welcome Contributions
Whether you're a security researcher, an AI engineer, or someone who cares about making defense better — there's a place for you here.
## Ways to Contribute
Agent improvements, tool integrations, infrastructure enhancements, bug fixes, and test coverage.
New offensive techniques for the skill library — tagged with MITRE ATT&CK IDs and organized by kill chain phase.
Improve these docs, write tutorials, add examples, or translate to new languages.
Answer questions on Discord, share engagement patterns, report bugs, or discuss new features.
## Contribution Workflow
Fork the [Decepticon repository](https://github.com/BitterSecurity/Decepticon) to your GitHub account.
Branch from `main` with a descriptive name:
```bash
git checkout -b feature/add-kerberoasting-skill
```
Make your changes using the [Developer Setup](/en/contributing/developer-setup). Run tests:
```bash
make test
make lint
```
Decepticon follows the [Conventional Commits](https://www.conventionalcommits.org/) format: `type(scope): subject`. Common types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`. Write the body to explain the *why*, not just the *what*.
```text
feat(agents): add Cloud Hunter skill for AWS metadata abuse
fix(opplan): resolve dependency cycle in objective_expand
docs(features): document the offensive vaccine pipeline
```
Push your branch and open a PR against `main`. Describe what your change does and why.
## Skill Contributions
Adding new skills to the library is one of the most valuable contributions. Each skill should include:
- **Frontmatter** — Name, description, MITRE ATT&CK technique IDs, kill chain phase, required tools
- **Content** — Step-by-step technique execution, command examples, expected output
- **Detection Notes** — How defenders can detect this technique (feeds the defensive evolution vision)
- **Prerequisites** — What access or conditions are needed
## Code Style
- Follow the existing patterns in the codebase
- Run `make lint` before submitting
- Include tests for new functionality
- Document non-obvious design decisions in comments
## Community
Ask questions, share techniques, connect with the team.
Report bugs, request features, track roadmap.
Longer-form conversations about architecture, strategy, and ideas.
## License
Decepticon is licensed under [Apache-2.0](https://github.com/BitterSecurity/Decepticon/blob/main/LICENSE). By contributing, you agree that your contributions will be licensed under the same terms.
---
## File: en/contributing/developer-setup.mdx
---
title: "Developer Setup"
---
## Prerequisites
- [Docker](https://docs.docker.com/get-docker/) with Docker Compose v2
- [Git](https://git-scm.com/)
- (Optional) [uv](https://github.com/astral-sh/uv) for local linting and type checking
## Clone & Start
```bash
git clone https://github.com/BitterSecurity/Decepticon.git
cd Decepticon
```
Start the development environment with hot-reload:
```bash
# Terminal 1 — Start services with file watching
make dev
# Terminal 2 — Open the interactive CLI
make cli
```
Development runs in the **same Docker containers** as production. Source changes are automatically synced into containers via `docker compose watch` — no manual rebuilds needed.
## Make Targets
| Command | Description |
|---------|-------------|
| `make dev` | Build images + start with hot-reload (`docker compose watch`) |
| `make cli` | Open the interactive CLI (run in a separate terminal) |
| `make start` | Start in background, production-like (no hot-reload) |
| `make stop` | Stop all services |
| `make test` | Run `pytest` inside the container |
| `make lint` | Run linter + type checker locally (requires `uv sync --dev`) |
| `make help` | Show all available Makefile targets |
## Project Structure
```
Decepticon/
├── decepticon/ # Core Python package (LangGraph agents)
│ ├── agents/ # 16 specialist agent definitions + system prompts
│ ├── core/ # Schemas (RoE, ConOps, OPPLAN), engagement lifecycle, config
│ ├── llm/ # Model profiles, provider routing, LLM factory
│ ├── middleware/ # OPPLAN, Skills, EngagementContext, Filesystem, SubAgent middleware
│ ├── sandbox_kernel/ # Sandbox-side daemon, jobs, tmux session manager
│ ├── sandbox_server/ # Sandbox-side HTTP server (FastAPI)
│ ├── tools/ # bash, research (Neo4j/CVE), reversing, ad, cloud, web, contracts
│ └── backends/ # Docker / HTTP sandbox backends
├── skills/ # Skill library (18 categories: per-agent + shared + benchmark)
├── clients/
│ ├── cli/ # React 19 + Ink terminal UI (TypeScript)
│ ├── web/ # Next.js 16 web dashboard (TypeScript, Prisma)
│ ├── launcher/ # Go CLI launcher (Cobra + Charmbracelet Huh v2)
│ └── shared/ # Shared TypeScript packages
├── containers/ # Dockerfiles (sandbox, cli, web, langgraph, litellm, c2-sliver)
├── config/ # LiteLLM proxy config (litellm.yaml)
├── benchmark/ # CTF evaluation framework (xbow validation-benchmarks)
├── scripts/ # Install and launcher scripts
├── tests/ # pytest suite
├── docker-compose.yml # Infrastructure definition
├── langgraph.json # 19 graph entry points (decepticon orchestrator + soundwave planner + 17 specialists)
└── Makefile # Development workflow commands
```
## Hot Reload
`make dev` uses `docker compose watch` to monitor source files. When you edit code:
1. Changes are synced into the running containers automatically
2. Affected services restart with the new code
3. No manual `docker compose build` or restart needed
This provides the fastest development loop while maintaining the exact same Docker environment as production.
## Running Tests
```bash
# Run full test suite inside container
make test
# Local linting (requires uv)
uv sync --dev
make lint
```
Learn the contribution workflow — branching, commits, and pull requests.
---
## File: en/features/autonomous-execution.mdx
---
title: "Autonomous Execution"
---
## Kill Chain Orchestration
Once the OPPLAN is generated, Decepticon's orchestrator takes over. It iterates through objectives autonomously, executing a full kill chain — reconnaissance, exploitation, privilege escalation, lateral movement, and persistence.
This isn't a linear script. The orchestrator adapts in real time based on what each agent discovers.
## Execution Loop
The orchestrator picks the next pending objective from the OPPLAN, resolving dependencies and prioritizing based on kill chain phase.
A prompt is constructed with the objective details, RoE guard rails, available skills, and relevant findings from previously completed objectives.
A **new agent instance** is spawned with a clean context window. No accumulated noise from prior objectives — fresh reasoning every time.
The agent executes the objective using available tools and skills within the Kali sandbox. All commands run inside persistent tmux sessions with interactive prompt detection.
The orchestrator parses the agent's `PASSED` / `BLOCKED` signal, updates the objective status, and appends findings to disk.
Move to the next objective. Findings from completed objectives inform subsequent agents, enabling multi-stage attack chains.
## Fresh Context Per Objective
This is a critical design decision. Each agent spawns with a clean context window per objective — preventing context degradation across a long engagement.
Why this matters:
- **No accumulated noise** — Agent reasoning doesn't degrade as the engagement progresses
- **Clean state** — Each objective gets full attention without irrelevant context from prior phases
- **Persistent findings** — Results are saved to disk, not agent memory. The orchestrator injects only relevant prior findings into each new agent's context
## Interactive Shell Sessions
Real offensive security tools are interactive — `sliver-client`, `msfconsole`, `evil-winrm`, `sqlmap`, `impacket-psexec`. They don't just take a command and exit. They drop you into a prompt and expect a conversation.
Most AI agents can't handle this. They fire one-shot commands via `subprocess.run()` and call it a day.
Decepticon runs every command inside **persistent tmux sessions** with automatic prompt detection:
- When a tool presents an interactive prompt (`sliver >`, `msf6 >`, `PS C:\>`), the agent detects it and sends follow-up commands
- **Parallel named sessions** — multiple tool sessions running concurrently
- **Control signals** — `C-c`, `C-z` support for managing interactive processes
- **Stall detection** — recognizes when a command hangs and takes corrective action
The agent actually *operates* the tools — the same way a human operator would.
## Background Commands & Auto-Notification
Some commands take minutes — `nmap -p- -A`, a full Burp scan, a long-running fuzzer. Blocking on the prompt for ten minutes while the LLM waits is a waste of compute and turns. The agent kicks them off in the background instead and gets on with other work:
```
bash(
command="nmap -p- -A target.lan -oN scan.txt",
run_in_background=True,
session="scan-1",
)
→ { "status": "started", "session": "scan-1" }
```
While the scan runs, the agent moves on — recon other surfaces, plan the next objective, query the knowledge graph. When the scan finishes, `SandboxNotificationMiddleware` **automatically captures the output and injects it on the next inference turn**:
```
Turn N: bash(..., run_in_background=True) → returns "started"
Turn N+1: do other work
Turn N+2: on entry, agent sees:
Background command in session scan-1 finished (exit 0).
Output (2.4K):
Nmap scan report for target.lan ...
```
No `bash_output()` polling. No idle "is it done yet?" turns. The agent doesn't have to remember the command exists — completion comes to it. This is the same pattern that powers [Dynamic Infrastructure](/en/features/dynamic-infrastructure) workload-state notifications.
### Output tiering
Long-running commands often produce a lot. The sandbox tiers output so the agent's context window stays usable:
| Volume | What happens |
|--------|--------------|
| **≤ 15 KB** | Inlined directly in the notification / tool result. |
| **15 KB – 100 KB** | Written to `/workspace/.scratch/` with a path + summary inlined. The agent reads the file when needed. |
| **> 5 MB** | The runaway session is killed, the agent is told to refine the command (narrower scope, output filter). |
Combined with ANSI stripping and repetitive-line compression, this keeps token spend predictable even on day-long engagements.
## RoE Enforcement
At every iteration, the orchestrator validates that the next action falls within the Rules of Engagement. If an objective would violate scope, timing, or technique boundaries defined in the RoE, it is automatically blocked.
Learn about the progressive skill system that equips agents with ATT&CK-mapped capabilities.
---
## File: en/features/benchmark-evaluation.mdx
---
title: "Benchmark & Evaluation"
---
Claims about an autonomous red team agent are cheap. Decepticon ships with a benchmark harness that runs against public, reproducible challenges — so the claims are measurable.
## What's Benchmarked
Decepticon's benchmark suite integrates with the [xbow validation-benchmarks](https://github.com/xbow-engineering/validation-benchmarks) — a public set of CTF-style challenges across difficulty levels and tag-based categories (web, crypto, AD, cloud, etc.).
Each benchmark run measures whether Decepticon can:
1. Generate a valid OPPLAN for the challenge from a minimal prompt.
2. Execute the kill chain end-to-end without operator intervention.
3. Recover the FLAG (proof of solve) within the time budget.
## The Harness
The benchmark harness lives under `benchmark/` in the source repository. It is a separate Python package with a Typer CLI:
```bash
python -m benchmark.runner run \
--level 1 \
--tags web,sqli \
--range-start 1 --range-end 10 \
--batch-size 3 \
--timeout 1800 \
--parallel
```
| Flag | Purpose |
|---|---|
| `--level` | Challenge difficulty tier (1–3) |
| `--tags` | Filter by ATT&CK-aligned tag |
| `--range-start / --range-end` | Subset selection from the suite |
| `--batch-size` | Number of challenges per scoring batch |
| `--timeout` | Per-challenge wall-clock budget (seconds) |
| `--parallel` | Run challenges concurrently |
## Lifecycle Per Challenge
For every challenge, the harness performs the same four-step lifecycle:
Build the challenge's Docker environment and inject a unique FLAG.
Hand the challenge prompt to the LangGraph platform; Decepticon's orchestrator generates an OPPLAN and executes it.
Grep the agent's workspace for the `FLAG{...}` pattern. Match → pass; no match → fail.
`docker compose down -v` to fully reset state for the next challenge.
## Scoring
Scoring is binary per challenge — flag captured or not. The aggregate report breaks down results by:
- **Level** (1 / 2 / 3) — pass rate per difficulty tier
- **Tag** (web, ad, cloud, ...) — pass rate per category
- **Wall-clock** — median and p95 time-to-flag
## Reports
The reporter produces two artifacts per run:
- `report.json` — machine-readable result for CI
- `report.md` — human-readable summary with per-challenge transcripts and timing
These are versioned alongside the source so regressions surface in code review.
## Why Binary Scoring
A red team agent that "almost solved it" is functionally identical to one that did not. Binary scoring keeps the metric honest — the only thing that counts is whether the engagement objective was achieved.
For nuance — *how* the agent solved it, what tradecraft it used, what false starts it made — the per-challenge transcript is the artifact to read.
## Continuous Evaluation
The benchmark harness is wired into CI. Every change to the agent system, skill library, or model routing triggers a partial benchmark run. Major releases trigger the full suite. This is how Decepticon catches regressions before they ship — a model swap that improves a few tasks but breaks others is exactly the kind of failure binary scoring surfaces immediately.
Benchmark runs are also how new model profiles get validated before being made default.
---
## File: en/features/c2-integration.mdx
---
title: "C2 Integration"
---
## Overview
Decepticon integrates **Sliver C2** as its command-and-control framework, enabling real adversary-grade post-exploitation: implant deployment, session management, credential harvesting, and lateral movement through C2 channels.
C2 is not bolted on as an afterthought — it's a core component of the operational network architecture.
## Enabling C2
Sliver C2 is activated via Docker Compose profiles:
```bash
COMPOSE_PROFILES=c2-sliver decepticon
```
This adds the Sliver team server to the operational network (`sandbox-net`) alongside the Kali sandbox and any target infrastructure.
## Architecture
```
┌─────────────────────────────────────────────────┐
│ sandbox-net (operational) │
│ │
│ ┌──────────┐ ┌──────────┐ ┌───────────────┐ │
│ │ Kali │ │ Sliver │ │ Target │ │
│ │ Sandbox │←→│ Team Svr │←→│ Infrastructure│ │
│ └──────────┘ └──────────┘ └───────────────┘ │
│ ↑ │
│ sliver-client │
│ (pre-installed) │
└─────────────────────────────────────────────────┘
```
The C2 team server runs entirely on the operational network — completely isolated from the management infrastructure. No C2 traffic crosses network boundaries.
## Capabilities
### Implant Generation & Deployment
The agent generates Sliver implants tailored to the target environment and deploys them through the established access:
- **Platforms** — Windows, Linux, macOS
- **Formats** — Shellcode, executables, shared libraries
- **Evasion** — Obfuscation, custom builds
### C2 Channels
Multiple communication channels supported:
| Channel | Use Case | Stealth Level |
|---------|----------|---------------|
| **mTLS** | Default — encrypted, reliable | Medium |
| **HTTPS** | Blends with normal web traffic | High |
| **DNS** | Tunnels through DNS queries | Very High |
### Post-Exploitation via C2 Sessions
Once an implant establishes a session, the post-exploit agent operates through it:
- **Credential harvesting** — Dump credentials, tokens, and keys from compromised hosts
- **Lateral movement** — Pivot to internal systems through established C2 sessions
- **Internal reconnaissance** — Map networks, enumerate services, and discover new targets from inside the perimeter
- **Persistence** — Establish long-term access mechanisms
## Profile-Based Configuration
C2 frameworks are swappable via Docker Compose profiles. **Only Sliver is implemented and shipping today** — the profile system is designed so additional frameworks (Havoc, Mythic, etc.) can be plugged in later, but those are not yet available:
```bash
# Sliver C2 — the only supported framework today (default)
COMPOSE_PROFILES=c2-sliver
# Planned for future releases (not yet available):
# COMPOSE_PROFILES=c2-havoc
# COMPOSE_PROFILES=c2-mythic
```
Learn about the isolated network architecture that keeps C2 traffic separated from management.
---
## File: en/features/dynamic-infrastructure.mdx
---
title: "Dynamic Infrastructure"
---
## The Problem with Always-On Stacks
A serious red-team engagement can need any of the following — Sliver C2, BloodHound CE for Active Directory, Ghidra for reversing, mobile emulation, IoT firmware tooling, ICS protocol simulators. Booting every one of them on every `decepticon start` would:
- Burn minutes of cold-start time on every launch.
- Consume gigabytes of RAM the operator never asked for.
- Make `decepticon stop` take five minutes to drain.
Default-on, kitchen-sink stacks are how red-team tooling traditionally ships, and it's why operators end up writing custom wrapper scripts that shut things down they didn't want running.
## The Decepticon Model (ADR-0006)
The **agent decides when a workload is needed and asks for it on the fly**. The orchestrator carries three tools:
| Tool | What it does |
|------|--------------|
| `ops_start("c2-sliver")` | Spin up the workload's containers on `sandbox-net`. Returns immediately with `state: "starting"`. |
| `ops_stop("c2-sliver")` | Graceful shutdown when the workload is no longer needed. |
| `ops_status()` | Snapshot of every workload's current state — used for polling fallbacks. |
Specialist sub-agents do **not** carry these tools — only the orchestrator does. That keeps the lifecycle decision in one place, prevents specialists from racing each other to bring up the same workload, and avoids accidentally killing a container another specialist is mid-flight on.
### How a workload spawn flows
```
1. Orchestrator: "Objective 3 needs Active Directory exploitation. ops_start('ad')."
2. Agent tool → Unix socket → opscontrol daemon
3. opscontrol → docker compose --profile ad up -d
4. Containers → state: starting
5. Health check → state: running
6. Middleware → injects "workload ad is running"
on the agent's next turn — no polling.
7. Orchestrator: dispatches `ad_operator` sub-agent against the now-ready stack.
8. Engagement finishes → ops_stop("ad") → drain → released RAM.
```
## The opscontrol Daemon
`opscontrol` is a small per-user daemon installed alongside the launcher. It owns the host's Docker socket and runs Compose on behalf of the agent.
### Lifecycle management
Three install modes, picked in order:
1. **systemd user unit (Linux)** — `decepticon opscontrol install` writes a unit at `~/.config/systemd/user/decepticon-opscontrol.service`. The init system supervises crash-recovery and survives reboot.
2. **launchd LaunchAgent (macOS)** — Same shape, written to `~/Library/LaunchAgents/`.
3. **Launcher-spawn fallback** — On hosts without a recognized init system (Windows native, WSL2 without systemd), the launcher forks a detached daemon process and writes a PID file. Less robust than service-managed, but functional.
### Security boundary
- Daemon runs **as the operator's UID**, not root — it has only the Docker permissions the user already has via `docker` group membership.
- Agent talks to daemon over a **Unix domain socket** at `$DECEPTICON_HOME/run/ops.sock`. Never TCP. Never network-reachable.
- A **strict allowlist** caps what the agent can spawn:
```
ad, c2-sliver, c2-havoc, reversing, cloud, mobile, phishing,
forensics, ics, iot, supply-chain, wireless
```
Anything outside the list is rejected at the daemon. The agent cannot, for example, `ops_start("postgres")` to escalate against the management plane.
## Auto-Notification, Not Polling
The naive design would have the agent poll: call `ops_start("ad")`, then loop on `ops_status("ad")` until ready, burning tokens and turns on no-ops.
Decepticon ships an **`OpsControlNotificationMiddleware`** that subscribes to daemon state events and **injects state transitions directly into the agent's next turn** as a `` `HumanMessage`. The agent's logical flow is:
```
Turn N: call ops_start("c2-sliver") → returns "starting"
Turn N+1: do other work (recon, planning)
Turn N+2: on entry, sees "workload c2-sliver is now running"
and dispatches the post-exploit specialist
```
No polling, no idle waiting, no burned tokens. The same pattern wraps background bash via `SandboxNotificationMiddleware` — see [Autonomous Execution](/en/features/autonomous-execution).
## Operator Overrides
For operators who prefer "everything up at launch" — typically CI regression runs that want the full matrix online before the agent starts — set `COMPOSE_PROFILES` explicitly:
```bash
# .env
COMPOSE_PROFILES=cli,c2-sliver,ad,reversing
```
The opscontrol path is bypassed for the listed profiles; everything else still spawns on demand.
For day-to-day use, leave `COMPOSE_PROFILES` empty and let the agent drive the stack.
## What ships in OSS
The opscontrol daemon, the three `ops_*` tools, the allowlist, the auto-notification middleware, and the systemd/launchd supervisor variants all ship in the OSS release. Workload profile definitions (`c2-sliver`, `ad`, `reversing`, …) live in `docker-compose.yml` next to the default stack, so adding a workload is a Compose-file change plus an allowlist entry — no agent code changes required.
The agent's other auto-notification surface — background bash commands also push completion notices, not polling.
Where these workloads sit in the two-network topology.
---
## File: en/features/engagement-planning.mdx
---
title: "Engagement Planning"
---
## Overview
Every professional Red Team engagement starts with documentation — not exploitation. Decepticon enforces this through the **Soundwave** agent, which interviews the operator and generates a complete engagement package before any offensive action begins.
No engagement runs without proper documentation. This is what separates a professional Red Team platform from a script kiddie's toy.
## The Soundwave Agent
Soundwave is Decepticon's engagement planning specialist. Through an interactive interview, it produces:
Defines scope, timing, and boundaries. What you can and can't touch. Violate this and you're not a red teamer — you're a criminal.
Threat actor profile, attack methodology, the "who are we pretending to be" document. Defines initial access vectors and TTPs as MITRE ATT&CK IDs.
Separates red team activity from real threats. Source IPs, user-agents, time windows, and a shared code for real-time deconfliction calls with the SOC.
The full mission plan. Objectives, kill chain phases, acceptance criteria. Every action maps to a purpose.
## How It Works
Soundwave conducts a structured interview: target scope, threat model, authorized techniques, timing constraints, and success criteria.
Based on the interview, Soundwave generates the complete engagement package — RoE, ConOps, Deconfliction Plan, and OPPLAN.
Each OPPLAN objective is tagged with MITRE ATT&CK technique IDs, kill chain phase, and acceptance criteria. These feed directly into the autonomous execution loop.
The Rules of Engagement are enforced at every iteration of the autonomous loop. The agent cannot operate outside the defined boundaries.
## OPPLAN Structure
The OPPLAN is the core document that drives autonomous execution. Each objective contains:
```
Objective: Compromise external-facing web application
Phase: Initial Access
MITRE ATT&CK: T1190 (Exploit Public-Facing Application)
Acceptance Criteria: Achieve remote code execution on web server
Dependencies: Recon objective completed
Status: PENDING
```
Objectives are tracked through status transitions: `PENDING` → `IN_PROGRESS` → `PASSED` / `BLOCKED`. The orchestrator manages dependencies and adapts the attack path based on results.
Learn how the orchestrator executes OPPLAN objectives through the autonomous kill chain.
---
## File: en/features/knowledge-graph.mdx
---
title: "Knowledge Graph"
---
A long red team engagement produces hundreds of findings, credentials, hosts, services, and detection artifacts. Storing them as flat JSON loses the relationships that make red team output useful — *which credential opened which host? which detection covers which technique?* Decepticon stores them in a **Neo4j graph** instead.
## Why a Graph
Attack paths are graphs by nature. A pivot is a relationship; a credential is an edge between an account and a host; a defense brief connects a vulnerability to a detection. Modeling this as a graph means:
- The orchestrator can query *"which hosts can I reach from this credential?"* in one Cypher query, not by re-reading conversation history.
- The defender's deliverable is a structured graph, not a PDF — easy to overlay on existing detection coverage.
- Cross-engagement queries become possible: *"did this CVE show up in any prior engagement against this customer?"*
## Node Types
| Node | Represents |
|---|---|
| `Host` | A discovered host or asset (IP, hostname, OS) |
| `Service` | A network service running on a host (port, protocol, banner, version) |
| `Account` | A discovered identity (user, service, machine account) |
| `Credential` | A captured secret (password, hash, token, key) |
| `Vulnerability` | A confirmed weakness (CVE, misconfiguration) |
| `Finding` | A verified observation produced by an agent |
| `DefenseAction` | A detection rule, mitigation, or patch produced by the Vulnresearch pipeline (`Detector`, `Patcher`). The schema reserves room for the [planned Defender component](/en/features/offensive-vaccine-pipeline) to write here once it ships. |
## Edge Types
| Edge | Meaning |
|---|---|
| `RUNS_ON` | Service runs on Host |
| `OWNS` | Account owns Credential |
| `AUTHENTICATES_TO` | Credential authenticates to Host or Service |
| `EXPLOITS` | Finding exploits Vulnerability |
| `DETECTS` | DefenseAction detects Finding's technique |
| `MITIGATES` | DefenseAction mitigates Vulnerability |
| `RESPONDS_TO` | DefenseAction responds to Finding |
| `LATERAL_TO` | Host pivots to Host (with credential or technique attribution) |
## Tools the Agents Use
The graph is exposed to agents through `KGMiddleware`, which builds two tools per attaching role and dispatches them through a shared `KGStore` (`packages/decepticon/decepticon/middleware/kg_internal/`):
| Tool | Purpose |
|---|---|
| `kg_record(observations)` | Atomic batch write of nodes and edges. The middleware validates the engagement label, applies schema constraints, and wraps the call in a single transaction so partial writes never leave the graph in a torn state. |
| `kg_ingest(scanner_kind, path)` | Dispatcher into the scanner adapter registry — `nmap_xml`, `sarif`, `bloodhound_zip`, `slither_json`, and any plugin-registered scanner. Reads the file, parses, and emits node/edge observations into the same atomic write path as `kg_record`. |
Agents never write raw Cypher in their prompts. Read paths go through the middleware's typed summary projections (and through Skillogy for ATT&CK lookups); write paths go through `kg_record` / `kg_ingest`. This keeps the engagement scope, schema validation, and migration-runner contract centralized so a buggy specialist can't corrupt the graph.
The pre-middleware standalone `@tool` functions (`kg_add_node`, `kg_add_edge`, `kg_query`, `kg_neighbors`) are still importable from `decepticon.tools.research.tools` for transitional callers and emit a `DeprecationWarning`. New code should attach `KGMiddleware` and use the middleware-built surface.
## Operator Access
The graph is also exposed to the operator:
- **Browser**: Neo4j browser at `http://localhost:7474` with credentials from the onboarding wizard.
- **CLI**: `decepticon kg-health` runs diagnostics and surfaces orphan nodes or missing relationships.
- **Web Dashboard**: The attack graph canvas in the Next.js dashboard renders the live engagement graph.
## The Graph as Deliverable
At engagement out-brief, the graph becomes part of the deliverable. The blue team gets:
1. A JSON export of all nodes and edges.
2. An ATT&CK Navigator layer derived from the graph.
3. A "blue spots" overlay — vulnerabilities the engagement found that the customer's existing detections do not cover.
4. A "red spots" overlay — detections that fired against Decepticon's actions, proving the SOC works.
## Privacy and OPSEC
The graph is engagement-scoped. Customer data captured during the engagement (credential strings, service banners, sensitive paths) is encrypted at rest in Neo4j and purged when the engagement is closed unless explicitly retained for the deliverable.
Querying the graph mid-engagement is one of the highest-leverage operator actions. A Cypher query like `MATCH (a:Account)-[:OWNS]->(c:Credential)-[:AUTHENTICATES_TO]->(h:Host) WHERE NOT (h)-[:RESPONDS_TO]-() RETURN h` finds every reachable host whose blue team has no detection.
How DefenseAction nodes are produced by the Detector and Patcher agents.
---
## File: en/features/multi-model-routing.mdx
---
title: "Multi-Model Routing"
---
## Overview
Not every agent task requires the most powerful model. Decepticon uses **LiteLLM** as a proxy layer to route different agent roles to different model tiers — balancing cost, speed, and capability.
## Model Profiles
Three built-in profiles optimize for different use cases:
| Profile | Orchestrator | Exploit | Recon | Use Case |
|---------|-------------|---------|-------|----------|
| **eco** | Opus 4.7 | Sonnet 4.6 | Haiku 4.5 | Production — best cost/performance ratio (default) |
| **max** | Opus 4.7 | Opus 4.7 | Sonnet 4.6 | High-value targets — maximum capability |
| **test** | Haiku 4.5 | Haiku 4.5 | Haiku 4.5 | Development/CI — fast iteration |
The full per-tier model matrix across providers is:
| Tier | Anthropic API | Anthropic OAuth | OpenAI | Google | MiniMax |
|---|---|---|---|---|---|
| **HIGH** | claude-opus-4-7 | auth/claude-opus-4-7 | gpt-5.5 | gemini-2.5-pro | MiniMax-M2.5 |
| **MID** | claude-sonnet-4-6 | auth/claude-sonnet-4-6 | gpt-5.4 | gemini-2.5-flash | MiniMax-M2.5-lightning |
| **LOW** | claude-haiku-4-5 | auth/claude-haiku-4-5 | gpt-5-nano | gemini-2.5-flash-lite | — |
The **eco** profile is recommended for most engagements. The orchestrator needs deep reasoning (Opus), but reconnaissance tasks work well with faster, cheaper models.
## Role-Based Routing
Each agent role has different cognitive demands:
Needs deep reasoning for objective sequencing, dependency resolution, and attack path adaptation. Routes to the most capable model.
Requires strong technical reasoning for vulnerability exploitation and tool operation. Routes to mid-high tier.
Handles structured tasks — port scanning, service enumeration, output parsing. Works well with faster models.
Complex post-exploitation through C2 sessions. Routes similarly to exploit tier.
## Automatic Fallback
Each tier has a fallback chain across providers. If the primary provider hits a rate limit or experiences an outage, Decepticon seamlessly switches to the next provider in the chain:
```
HIGH: Opus 4.7 → GPT-5.5 → Gemini 2.5 Pro → MiniMax-M2.5
MID: Sonnet 4.6 → GPT-5.4 → Gemini 2.5 Flash → MiniMax-M2.5-lightning
LOW: Haiku 4.5 → GPT-5-nano → Gemini 2.5 Flash-Lite
```
Provider order is configurable via the `DECEPTICON_AUTH_PRIORITY` environment variable (e.g., `anthropic_oauth,anthropic_api,openai_api,google_api,minimax_api`). The switch is transparent — no manual intervention, no interrupted operations.
## Provider Support
Any LiteLLM-compatible backend works:
- **Anthropic** — Claude Opus 4.7, Sonnet 4.6, Haiku 4.5 (API key or Claude OAuth subscription)
- **OpenAI** — GPT-5.5, GPT-5.4, GPT-5-nano
- **Google** — Gemini 2.5 Pro / Flash / Flash-Lite
- **MiniMax** — MiniMax-M2.5 and M2.5-lightning
- **Self-hosted** — vLLM, Ollama, or any OpenAI-compatible endpoint
Configure via `decepticon onboard` or environment variables. See [Configuration](/en/getting-started/configuration) for details.
---
## File: en/features/offensive-vaccine-pipeline.mdx
---
title: "Offensive Vaccine Pipeline"
---
The **five-stage Vulnresearch pipeline** described below ships today, driven by the `Vulnresearch` orchestrator and its five sub-agents. The **defense-closing half** of the loop (the "Defender" agent, automated mitigation backends, re-attack verification) is a **planned product direction** — not an active implementation in the current codebase. The previous Defender graph and Docker defense backend have been removed and a future implementation will be rebuilt around OPPLAN middleware. See [`docs/offensive-vaccine.md`](https://github.com/BitterSecurity/Decepticon/blob/main/docs/offensive-vaccine.md) in the repo.
The **Offensive Vaccine** is the loop that gives Decepticon its name and its purpose: every offensive action becomes a defensive artifact. This page documents the five-stage Vulnresearch pipeline that ships today, and the planned defense-side components that will eventually close the loop.
## The Loop
```
attack → detection rule → verification → exploit PoC → patch
↑ │
└───────────────────────────────────────────────────────┘
regression coverage
```
Each stage is owned by a specialist agent. Together they implement what the security industry calls "purple teaming," fully automated.
## The Five Stages
Automated vulnerability scanning across the target. Output: candidate findings (CVE matches, configuration issues, exposed surfaces).
Generate a detection signal for the candidate vulnerability — Sigma rule, YARA rule, IDS signature, or telemetry-derived heuristic. Defenders need to know *what* to look for before they can detect it.
Two-method gate: confirm the vulnerability through at least two independent verification techniques. Eliminates false positives before exploit work begins.
Generate a minimal patch — code change, configuration change, compensating control — that closes the vulnerability without breaking the application, then prove the fix holds via `patch_verify`. Patching *before* PoC is the offensive-vaccine inversion: the defender's diff is the artifact under test.
Author a reproducible proof-of-concept that targets the patched candidate. If the PoC succeeds against the patched code, the patch is incomplete and the loop iterates; if the PoC fails, the patch is hardened evidence the fix held.
## The Vulnresearch Orchestrator
The five agents do not run as a fixed pipeline — they are orchestrated by a sixth agent, **Vulnresearch**, that decides the order based on findings. If the Scanner produces a high-confidence candidate, Vulnresearch may skip directly to Verifier. If the Verifier rejects a candidate, the loop terminates without burning Patcher or Exploiter resources.
| Agent | Inputs | Outputs |
|---|---|---|
| **Scanner** | Target scope | Candidate findings list |
| **Detector** | Candidate finding | Detection rule (Sigma / YARA / heuristic) |
| **Verifier** | Candidate + detection rule | Verified-yes or verified-no, with two methods of evidence |
| **Patcher** | Verified candidate | Patch (code or config) + `patch_verify` proof the fix closes the bug |
| **Exploiter** | Patched candidate | Reproducible PoC against the patch — *fails* if the patch held, *succeeds* if the patch is incomplete (loop iterates) |
## The Planned Defense Component
This component is not implemented in the current codebase — the previous Defender graph and Docker defense backend were removed, and a future replacement will be rebuilt around OPPLAN middleware and a dedicated vaccine concept. Today the Vulnresearch pipeline's artifacts (detection rules, PoCs, patches) are persisted to the workspace and knowledge graph, and a human operator hands them to the blue team.
The planned defense-closing component is *not* part of the five-stage pipeline — it is intended to be a parallel agent that consumes the artifacts and produces the **Defense Brief**: the document handed to the blue team at engagement out-brief.
The Defense Brief is planned to contain:
- The technique used (MITRE ATT&CK ID)
- The detection rule produced by the Detector
- The PoC produced by the Exploiter
- The recommended patch from the Patcher
- The verification status (did the patch break the PoC?)
- The mapping to the blue team's existing detection coverage (gaps)
This is the artifact that will eventually transform an offensive engagement into a defensive uplift. Until that component lands, operators assemble the brief manually from the workspace outputs.
## Why Two-Method Verification Matters
A single verification method can be fooled — a network scan might match a banner without the vulnerable code being reachable; a PoC might succeed against a honeypot. The Verifier requires **two independent methods**, e.g.:
- Static evidence (version banner) + dynamic evidence (PoC payload response)
- Network-side detection (IDS firing) + host-side detection (process artifact)
- Source-code analysis + runtime instrumentation
Decepticon refuses to escalate a finding to the Patcher / Exploiter stages without the two-method gate. This dramatically reduces wasted compute and false alarms in the engagement record.
## Knowledge Graph Integration
Every artifact produced by the pipeline lands in the **Neo4j attack graph**:
- Findings become `Vulnerability` nodes
- Detection rules become `DefenseAction` nodes with `DETECTS` edges
- Patches become `DefenseAction` nodes with `MITIGATES` edges
- Verifications become provenance edges
The graph is queryable mid-engagement and exportable as the engagement deliverable.
How findings, detections, and patches land in the Neo4j attack graph.
Each pipeline stage has a dedicated skill set under `skills/scanner/`, `skills/detector/`, etc.
---
## File: en/features/opplan-system.mdx
---
title: "OPPLAN System"
---
The **OPPLAN** (Operations Plan) is the bridge between human intent and autonomous execution. It is the single source of truth that the orchestrator schedules, that specialist agents consume, and that the operator approves. Without an OPPLAN, Decepticon will not run.
## What an OPPLAN Is
An OPPLAN is a structured list of **objectives** — each tagged with kill chain phase, MITRE ATT&CK IDs, OPSEC level, C2 tier, dependencies, and acceptance criteria. The Soundwave agent generates it from the operator interview; the Decepticon orchestrator executes it; the operator can edit it at any time.
```yaml
- id: obj-001
phase: RECON
title: "Identify exposed services on target subnet"
mitre_attack: [T1595, T1592]
opsec_level: low
c2_tier: null # not applicable in recon
dependencies: []
acceptance:
- "List of open ports and services per host"
- "Service banners captured"
status: pending
- id: obj-002
phase: INITIAL_ACCESS
title: "Exploit vsftpd 2.3.4 on 10.0.2.4"
mitre_attack: [T1190]
opsec_level: medium
c2_tier: short_haul
dependencies: [obj-001]
acceptance:
- "Foothold shell on target"
- "Implant deployed via Sliver"
status: pending
```
## OPPLAN Middleware
The orchestrator does not store the OPPLAN in conversation context — it lives in dedicated middleware (`OPPLANMiddleware`) that exposes structured tools and injects current state into every LLM call.
### CRUD Tools
The orchestrator and Soundwave manipulate the OPPLAN through five dedicated tools:
| Tool | Purpose |
|---|---|
| `add_objective` | Append a new objective with full schema |
| `get_objective` | Retrieve a single objective by ID |
| `list_objectives` | List all objectives, optionally filtered by phase or status |
| `update_objective` | Mutate an objective's status, evidence, or fields |
| `objective_expand` | Split an objective into sub-objectives (PTT — Pentesting Task Tree) |
This is the same structural pattern that Claude Code uses for its V2 task system — task state is a typed object, not a thread of messages.
### Dynamic State Injection
On every LLM call, the middleware injects the current OPPLAN state — which objectives are pending, in-progress, or complete — directly into the system prompt block. The orchestrator never has to re-derive plan state from chat history. This is what makes Decepticon's reasoning robust across long engagements.
## Dependency Resolution
Objectives can declare dependencies. The orchestrator schedules only objectives whose dependencies are `complete`. This gives the operator a deterministic execution order without hand-coding a workflow:
```text
obj-001 (Recon)
└─ obj-002 (Exploit, depends on obj-001)
└─ obj-003 (Post-Exploit, depends on obj-002)
└─ obj-004 (Persistence, depends on obj-002)
```
When `obj-002` completes, both `obj-003` and `obj-004` become eligible — and the orchestrator can spawn specialist agents for them in parallel.
## Pentesting Task Tree (PTT)
For complex objectives, the orchestrator can expand a single objective into a tree of sub-objectives via `objective_expand`. This is how Decepticon handles "fuzzy" goals like *"compromise the Active Directory forest"* — it decomposes them dynamically, in-flight, into concrete sub-objectives the AD Operator agent can execute.
```text
obj-005: Compromise AD forest (parent)
├─ obj-005.1: Enumerate domain via BloodHound
├─ obj-005.2: Identify Kerberoastable accounts
├─ obj-005.3: Extract TGT hashes
└─ obj-005.4: Crack hashes offline
```
Each child inherits the parent's RoE constraints and ATT&CK tag-set.
## Approval Gate
The OPPLAN is the approval contract. After Soundwave generates it, the operator reviews and approves it through the CLI. Only an approved OPPLAN can be executed. This is the **Trusted Agent** handshake encoded in software.
Engagement scope, goals, target, threat profile.
Structured documents, written to the engagement workspace.
The operator inspects each objective; the agent halts until approval is given.
Decepticon agent reads the OPPLAN, sequences objectives, and spawns specialists.
Add, remove, or update objectives via CLI commands. Changes are picked up on the next iteration.
## OPPLAN and Fresh Context
Each objective is executed by a **fresh agent instance** with a clean context window. The orchestrator passes the relevant prior findings explicitly — not the entire conversation history. This means a 200-objective engagement does not cause context degradation.
How Soundwave produces the initial OPPLAN draft.
How the orchestrator schedules and dispatches OPPLAN objectives.
---
## File: en/features/skill-system.mdx
---
title: "Skill System"
---
## Overview
Decepticon agents don't operate from hardcoded playbooks. They draw from a **skill system** — a curated library of offensive techniques organized by kill chain phase and tagged with MITRE ATT&CK identifiers.
## Progressive Disclosure
Skills use a **progressive loading** architecture to keep agent context windows clean:
1. **Initial load** — Only skill frontmatter (name, description, ATT&CK tags, phase) is loaded
2. **On-demand** — When an agent selects a skill, the full content is loaded via `read_file()`
3. **Clean context** — Agents only carry the detail they need for their current objective
This prevents context bloat. An agent working on initial access doesn't need the full content of lateral movement techniques — just their existence and metadata.
## Skill Categories
Skills are organized by **agent role**, not by a single kill-chain dimension. This lets the orchestrator load only the skills relevant to the specialist it is dispatching, while still covering the full attack lifecycle. The library currently ships these categories:
| Category | Owning Agent(s) | Coverage |
|---|---|---|
| `soundwave/` | Soundwave | RoE / ConOps / OPPLAN templates, threat profiles, deconfliction |
| `decepticon/` | Decepticon (orchestrator) | OPPLAN dispatch patterns, sub-agent routing |
| `recon/` | Recon | Passive recon, active recon, web recon, cloud recon |
| `osint/` | OSINT Operator | Open-source intelligence — leaked credentials, breach data, public footprint |
| `exploit/` | Exploit | Web exploitation, Active Directory initial access |
| `post-exploit/` | Post-Exploit | Privilege escalation, lateral movement, persistence |
| `ad/` | AD Operator | BloodHound, Kerberoasting, ticket forging, ACL abuse |
| `cloud/` | Cloud Hunter | IAM analysis, metadata abuse, cloud-key extraction |
| `contracts/` | Contract Auditor | Solidity static analysis, Foundry PoC harness |
| `reverser/` | Reverser | Binary triage, packer detection, ROP gadgets, Ghidra/radare2 |
| `phisher/` | Phisher | Pretext-aware payload generation, landing pages, harvester scaffolds |
| `mobile/` | Mobile Operator | iOS / Android app triage, MASTG checks, emulator-driven dynamic analysis |
| `wireless/` | Wireless Operator | 802.11 / Bluetooth / SDR recon and exploitation |
| `iot/` | IoT Operator | Embedded device firmware extraction, JTAG/UART, protocol reversing |
| `ics/` | ICS Operator | SCADA / DCS / PLC engagement workflows on isolated test ranges |
| `supply-chain/` | Supply-Chain Operator | Build-system, dependency, signing-key, and CI/CD compromise patterns |
| `dfir/` | Forensicator | Volatile data capture, timeline reconstruction, IOC pivoting |
| `analyst/` | Analyst | Cross-correlation, knowledge-graph queries, narrative drafting |
| `shared/` | All agents | OPSEC, defense evasion, finding protocol, adversary emulation, references, stealth infra |
The vulnresearch plugin's stage agents (`scanner`, `detector`, `verifier`, `patcher`, `exploiter`) draw their skill catalog from a separate `plugins/` tree when the bundle is loaded.
The progressive-disclosure loader filters this catalog by ATT&CK overlap with the active threat profile — out-of-profile skills are kept off the agent's working set entirely.
## Skillogy: Graph-Backed Skill Resolver
The catalog above is the **source of truth on disk**. The catalog the agent actually *queries* lives in a separate **Neo4j-backed graph** owned by a standalone **Skillogy** service. Why a graph and not just `read_file()` against a directory tree?
- Skills reference each other — `kerberoasting` builds on `ad-recon` and chains into `ticket-forging`. A graph lets the agent jump along those edges.
- Filtering by ATT&CK ID, tag, subdomain, or tactic ID needs index lookups that walking the filesystem can't answer cheaply.
- Multiple agents read concurrently; the graph centralizes consistency and avoids races on file caches.
Skillogy runs as a sibling container (port `9100` inside the management network) with three agent-facing tools, all of them thin REST clients exposed through `SkillogyMiddleware`:
| Tool | What it does |
|------|--------------|
| `find_skill(query?, subdomain?, mitre_id?, tag?, tactic_id?, limit=20)` | AND-combined relationship-aware discovery. Returns matching `:Skill` nodes with their frontmatter — body deferred. |
| `load_skill(name_or_path)` | Fetch the full body + frontmatter of one `:Skill` node. Same progressive-disclosure principle as before, just over REST. |
| `traverse(from_path, edge_types?, depth=2)` | Explicit graph BFS from a seed skill — follow `BUILDS_ON`, `CHAINS_TO`, `MITRE_RELATED` edges to find adjacent techniques. |
### Hard ACL (ADR-0008)
Skillogy isn't a flat catalog. Each agent role only sees the slice the orchestrator wants it to see — the `ad_operator` should not be browsing `contracts/` skills, the `contract_auditor` should not be reading `ad/`. ADR-0008 wires this as a **hard ACL** rather than a soft convention: every Skillogy call carries an `allowed_path_prefixes` parameter (e.g. `["skills/standard/ad/", "skills/shared/"]`) and the service rejects anything outside those prefixes at the query layer. Cross-role reads only succeed when the requested skill lives under `skills/shared/`.
The ACL is set by the agent factory (not the model), so a specialist can't be talked into widening it via prompt injection.
### How the file catalog and the graph stay in sync
The on-disk skill files remain the source of truth. The Skillogy service ingests them at container start (or via an explicit rebuild call) and projects them into Neo4j as `:Skill` nodes connected by typed edges derived from frontmatter. To add a skill: drop a `SKILL.md` into the right category directory, rebuild the graph, and it shows up to every agent whose ACL allows that prefix.
## MITRE ATT&CK Integration
ATT&CK mapping is woven into every layer of Decepticon — not added after the fact:
Each OPPLAN objective carries `mitre` technique IDs (e.g., `T1190`, `T1003.001`).
ATT&CK techniques declared in skill frontmatter, displayed inline in the agent's skill catalog.
ConOps defines `initial_access` and `ttps` as ATT&CK IDs, modeling specific adversary profiles.
## Skill Frontmatter Example
Each skill is a directory containing a `SKILL.md` (frontmatter + body) and optional `references/`, `scripts/`, and `assets/` subdirectories.
```yaml
---
name: passive-recon
description: "Use when gathering intelligence WITHOUT touching the target"
allowed-tools: Bash Read Write
metadata:
subdomain: reconnaissance
tags: passive, dns, subdomain-enum, whois, ct-logs
mitre_attack: T1590, T1591, T1592
---
```
The agent sees this metadata when browsing available skills. Only when it selects the skill does the full body — commands, detection notes, references — get loaded into context. Decepticon enforces a **SKILL-FIRST RULE**: agents must load the relevant skill before acting on a matching trigger keyword.
Learn how different agent roles are routed to optimal model tiers.
---
## File: en/getting-started/configuration.mdx
---
title: "Configuration"
---
## API Key Setup
Decepticon requires an LLM API key to power its agents. Run the interactive setup wizard:
```bash
decepticon onboard # Primary setup flow
decepticon onboard --reset # Reconfigure from scratch
```
### Supported Providers
Decepticon uses **LiteLLM** as its model proxy, supporting any compatible backend:
| Provider | Models | Notes |
|----------|--------|-------|
| **Anthropic API** | Claude Opus, Sonnet, Haiku | Recommended for best performance |
| **Anthropic OAuth** | Same models, via Claude subscription | Use Claude Code OAuth credentials |
| **OpenAI** | GPT-5.5, GPT-5.4, GPT-5-nano | Full support with automatic fallback |
| **Google** | Gemini 2.5 Pro / Flash / Flash-Lite | Via LiteLLM proxy |
| **MiniMax** | MiniMax-M2.5, MiniMax-M2.5-lightning | Alternative high/mid tier |
| **Custom** | Any LiteLLM backend | Self-hosted or alternative providers |
### Environment Variables
You can also configure via environment variables:
```bash
# Primary provider
export ANTHROPIC_API_KEY="sk-ant-..."
# Or OpenAI
export OPENAI_API_KEY="sk-..."
# Or set via LiteLLM config for custom backends
```
## Model Profiles
Decepticon routes different agent roles to different model tiers for optimal cost/performance balance:
| Profile | Orchestrator | Exploit | Recon | Use Case |
|---------|-------------|---------|-------|----------|
| **eco** | Opus 4.7 | Sonnet 4.6 | Haiku 4.5 | Production — best cost/performance ratio (default) |
| **max** | Opus 4.7 | Opus 4.7 | Sonnet 4.6 | High-value targets — maximum capability |
| **test** | Haiku 4.5 | Haiku 4.5 | Haiku 4.5 | Development/CI — fast iteration |
Each profile includes automatic fallback chains. If the primary provider is unavailable or rate-limited, Decepticon seamlessly switches to the next provider in the chain (e.g., Opus 4.7 → GPT-5.5 → Gemini 2.5 Pro → MiniMax-M2.5).
Select your profile during `decepticon onboard` or set it at any time via the `DECEPTICON_MODEL_PROFILE` environment variable. The `eco` profile is the default and recommended for most operations.
## C2 Configuration
Sliver C2 integration is profile-based via Docker Compose. The `COMPOSE_PROFILES` environment variable is read from your `.env` (or shell) before the launcher starts the stack — it is not a flag to the `decepticon` command itself. Sliver is enabled by default.
```bash
# .env (default)
COMPOSE_PROFILES=c2-sliver
# Or override per-run via shell
COMPOSE_PROFILES=c2-sliver decepticon
```
When enabled, the Sliver team server starts on the operational network with:
- Auto-generated operator configuration
- Pre-installed `sliver-client` in the sandbox
- mTLS, HTTPS, and DNS C2 channel support
Learn more about Sliver C2 integration and C2 channel configuration.
## Docker Resources
Decepticon runs entirely in Docker containers. Recommended resource allocation:
| Component | CPU | Memory | Notes |
|-----------|-----|--------|-------|
| LangGraph Platform | 1 core | 1 GB | Management network — agent orchestration |
| LiteLLM Proxy | 0.5 core | 512 MB | Management network |
| PostgreSQL | 0.5 core | 512 MB | Management network — engagement state |
| Neo4j | 1 core | 1 GB | Bridges both networks — knowledge graph |
| Web Dashboard | 0.5 core | 512 MB | Management network — Next.js |
| Kali Sandbox | 2 cores | 4 GB | Operational network — runs offensive tools |
| Sliver C2 | 1 core | 1 GB | Operational network (default profile) |
The Kali sandbox requires the most resources as it runs the full offensive toolkit. Allocate at least 4 GB of memory for stable operation during complex engagements.
---
## File: en/getting-started/library-usage.mdx
---
title: "Library & SDK Usage"
---
## Install from PyPI
Decepticon is published as a Python package. Install the core SDK:
```bash
pip install decepticon # core SDK
pip install "decepticon[neo4j]" # + the knowledge-graph attack-chain tools
```
`decepticon` is a **client SDK**, not a standalone app. It ships the agent
factories, middleware, tools, and skills — but LLM calls and sandbox
execution are routed to **runtime services** over HTTP. To actually run
agents you also need those services (the Docker stack, or your own
endpoints).
## The two tiers
| Tier | What | How it ships |
|------|------|--------------|
| **SDK (this package)** | `decepticon/` — agent factories, middleware, tools, backends, the `llm` factory, and skills (bundled as package data) | PyPI wheel — `pip install decepticon` |
| **Runtime services** | LiteLLM proxy, Kali sandbox, PostgreSQL, Neo4j | GHCR Docker images + `docker compose` |
The SDK connects to the services via environment variables:
- `DECEPTICON_LLM__PROXY_URL` — the LiteLLM proxy (default `http://localhost:4000`)
- `SAAS_SANDBOX_URL` — the sandbox HTTP daemon (e.g. `http://localhost:9999`)
For a turnkey local stack, use the [Quick Start](/en/getting-started/quick-start) installer. The pip package is for **embedding the agents into your own service**.
## Use a pre-built agent
```python
from decepticon.agents.standard.recon import create_recon_agent
agent = create_recon_agent() # default OSS configuration
```
Each of the 16 agent factories accepts langchain-style keyword overrides — `tools=`, `middleware=`, `system_prompt=`, `llm=`, and more.
## Extend with a plugin bundle
Ship proprietary tools, middleware, prompts, or sub-agents **without forking** — register a `PluginBundle` under the `decepticon.bundles` entry point:
```python
from decepticon.plugin_loader import PluginBundle
MY_BUNDLE = PluginBundle(
bundle="mybundle",
replaced_tools={"ask_user_question": my_ask_tool},
prompts={"recon": {"prepend": "..."}},
)
```
```toml
# your package's pyproject.toml
[project.entry-points."decepticon.bundles"]
mybundle = "my_pkg.bundles:MY_BUNDLE"
```
Activate it with `DECEPTICON_PLUGINS=standard,mybundle`. This is exactly how a downstream product layers proprietary capability on top of the open core — it depends on `decepticon`, it does not fork it.
## Versioning
Pin a compatible range in your `pyproject.toml`:
```toml
dependencies = ["decepticon>=1.1,<2"]
```
The full override surface — factory kwargs, declarative `PluginBundle` plugins, `build_middleware(slots=...)` for custom orchestrators, and the safety gate — is documented in [`docs/library-usage.md`](https://github.com/BitterSecurity/Decepticon/blob/main/docs/library-usage.md).
---
## File: en/getting-started/quick-start.mdx
---
title: "Quick Start"
---
## Prerequisites
You need two things:
- [Docker](https://docs.docker.com/get-docker/) (with Docker Compose v2)
- An API key (Anthropic, OpenAI, or any LiteLLM-compatible provider)
That's it. Everything else runs inside containers.
## Installation
```bash
curl -fsSL https://decepticon.red/install | bash
```
This pulls the Decepticon images, sets up the isolated network architecture, and installs the `decepticon` CLI.
## Configuration
Configure your API key:
```bash
decepticon config
```
This opens an interactive configuration wizard where you can set:
- **LLM Provider** — Anthropic, OpenAI, or other LiteLLM backends
- **API Key** — Your provider API key
- **Model Profile** — `eco`, `max`, or `test` (see [Multi-Model Routing](/en/features/multi-model-routing))
## Launch
Start Decepticon:
```bash
decepticon
```
This starts all services (agent API, LiteLLM proxy, sandbox, database) and opens the interactive CLI. You'll see the real-time streaming interface where you can create engagements and execute operations.
## Try the Demo
Want to see Decepticon in action before setting up your own engagement? Run the guided demo:
```bash
decepticon demo
```
The demo launches **Metasploitable 2** as a target, loads a pre-built engagement, and runs the full kill chain automatically:
Reconnaissance agent scans the target and identifies open services.
Exploit agent identifies and exploits the vsftpd backdoor vulnerability.
Deploys a Sliver C2 implant on the compromised target.
Post-exploit agent harvests credentials via C2 session.
Maps the internal network from the compromised host.
No additional configuration needed beyond your API key.
## Next Steps
Deep dive into API keys, model profiles, and environment settings.
Learn all available commands and options.
Explore engagement planning, kill chain execution, and C2 integration.
Understand the isolated network architecture and agent system.
---
## File: en/introduction/history-and-evolution.mdx
---
title: "History & Evolution"
---
The development of Decepticon did not start overnight. It is the culmination of years of research into applying artificial intelligence to offensive security. Understanding our past approaches provides context for why Decepticon is currently designed as an autonomous **Autonomous Hacking Agent** powered by Large Language Models (LLMs).
Here is a look back at the evolutionary milestones of Decepticon.
## 2021: Purple Team AI
In the early stages, the concept originated as a **Purple Team AI**. The fundamental idea was to create a continuous, automated feedback loop between offense and defense.
* **Red AI vs. Blue AI**: We envisioned two opposing AI models. The Red AI would launch attacks, and the Blue AI would analyze the attack vectors and issue patches.
* **The Philosophy**: Security is not static. By pitting two AIs against each other, the overarching system (the Purple Team) inherently becomes stronger over time.
## 2022: Reinforcement Learning (RL) Environment
To move beyond abstract concepts, we attempted to ground the interaction within a concrete network simulation using **Reinforcement Learning (RL)**.
* **The Virtual Network**: We built environments containing simulated servers and networks.
* **Agent-Based Learning**: The Red Team AI would issue "Attack Requests", and the environment would return the "next_state" or a "reward" based on the attack's success.
* **The Challenge**: While RL is powerful for games with defined rules (like Chess or Go), real-world network environments and "vibes" are infinitely complex. Designing accurate reward functions for every possible cyberattack vector proved to be a massive bottleneck.
## 2023: Generative Adversarial Networks (GANs)
Recognizing the difficulty of defining rigid RL environments, we explored the use of **Generative Adversarial Networks (GANs)** to simulate attack data.
* **Generator vs. Discriminator**: In this architecture, the Generator (acting offensively) tried to create "fake data" (attack payloads) that looked like normal network traffic. The Discriminator (acting defensively) tried to distinguish between real, benign traffic and the malicious fakes.
* **The Limitation**: GANs were excellent at generating payloads that bypassed signature-based WAFs (Web Application Firewalls). However, they lacked *contextual understanding*. They couldn't perform multi-stage attacks, read a server's response, or pivot through a network dynamically.
## Present: The Autonomous Hacking Agent
Through these iterative failures and successes, we realized that true offensive capability requires more than mathematical optimization or payload generation. It requires **reasoning**.
Today, Decepticon leverages advanced LLMs to act as an autonomous agent. Instead of relying on rigid environments or statistical distributions, it reads the "vibe" of the target—understanding human context, adapting to complex defenses, and executing multi-stage Red Team operations.
---
## File: en/introduction/overview.mdx
---
title: "Overview"
---
Welcome to the **Decepticon** documentation.
This documentation serves as a living record of the thoughts, vision, and architectural direction behind Decepticon prior to its major refactoring phase.
## What is Decepticon?
Decepticon is **not** a traditional vulnerability scanner or a standard pentesting tool. It is an autonomous **Autonomous Hacking Agent** built strictly for **Red Team Testing**.
While generic tools rely on static checklists to find outdated software, real-world attackers simulate unpredictable, context-aware attacks. Decepticon embraces this attacker mindset, acting autonomously to discover deep, logical, and context-based vulnerabilities (the "vibe" of the target).
Leverages LLMs to understand context, adapt strategies on the fly, and execute complex attack chains without human guidance.
Operates with stealth and persistence to achieve specific objectives, testing the Blue Team's real detection capabilities.
Learn more about why Decepticon's Autonomous Hacking strictly requires the Red Teaming methodology instead of traditional Pentesting.
## The Motivation: An Offensive Vaccine
Why are we building a relentless, AI-powered hacking agent?
**The ultimate goal of Decepticon is not to attack, but to build an impenetrable defense.**
In today's cybersecurity landscape, malicious threat actors are already leveraging AI to scale and automate their attacks. A project initiated 7 months ago has already proven that AI-driven offensive capabilities are not a future hypothesis—they are a reality right now.
To counter an AI, you need an AI. We cannot defend against infinite, machine-speed attacks using traditional human-speed defenses.
Decepticon exists to provide **infinite offensive feedback**. By deploying this Autonomous Hacking Agent against our own systems, we subject ourselves to continuous, relentless attack scenarios. It acts as an **Offensive Vaccine**:
* **Inoculation**: By absorbing infinite AI attacks in a controlled environment, we expose blind spots and logical flaws.
* **Evolution**: We force our defensive infrastructure to evolve into a vastly more robust state *before* real, malicious actors can strike.
---
## File: en/introduction/pentesting-vs-redteaming.mdx
---
title: "Pentesting vs Red Teaming"
---
To fully grasp Decepticon's identity as an **Autonomous Hacking Agent**, it is essential to understand the fundamental differences between Vulnerability Assessment, Penetration Testing, and Red Team Engagement. Decepticon explicitly targets the methodology of the last — and adds a fourth, machine-speed mode on top.
## The Three Disciplines
The security testing landscape forms an inverted pyramid: vulnerability assessments at the wide base (broad, shallow), penetration tests in the middle (targeted, deeper), and red team engagements at the apex (scenario-driven, full-organization).
Identify technical flaws across a wide attack surface. Output: a list.
Exploit those flaws to prove attack paths within a targeted scope.
Train and measure the defenders by emulating a real adversary end-to-end.
## Side-by-Side Comparison
The following framing is adapted from the canonical comparison published by [redteam.guide](https://redteam.guide/docs/Concepts/red-vs-pen-vs-vuln/) — extended with a fourth column for the autonomous-agent mode Decepticon enables.
| Aspect | Vulnerability Assessment | Penetration Test | Red Team Engagement | Autonomous Red Team (Decepticon) |
|---|---|---|---|---|
| **Goal** | Identify technical flaws | Exploit flaws to prove attack paths | Train and measure blue team effectiveness | Continuously rehearse the blue team against an AI adversary |
| **Scope** | Wide, shallow | Targeted systems | Full organization | Full organization, programmatically expandable |
| **Focus** | Technology | Technology | People, processes, and technology | People, processes, technology — driven by an OPPLAN |
| **Duration** | Days | 1–2 weeks | 2–6 weeks | Hours to continuous (machine-speed loops) |
| **Threat Model** | CVE-based | Attack surface | Adversary emulation | Adversary emulation, dynamic per engagement |
| **Risk Measurement** | Attack-surface reduction | Technical exploit impact | Security operations assessment | Operations assessment + regression coverage over time |
| **Output** | Vulnerability list | Exploit evidence and attack paths | Security operations assessment | OPPLAN-tagged findings, attack graph, remediation patches |
The fourth column is not a replacement for human red teams — it is the same discipline, scaled. Humans set the Rules of Engagement, define objectives, and adjudicate findings; Decepticon executes the kill chain inside that envelope.
## The Limitation of Traditional Pentesting
Traditional penetration testing focuses on evaluating security in silos — web, mobile, or external networks individually.
- **Siloed Evaluation**: Pentesting might find SQL injection in a single web app, but it doesn't test if defenders can detect an attacker using that web app as a proxy to pivot into the internal network.
- **The Soccer Analogy**: Pentesting is like practicing shooting, passing, and dribbling individually. These are essential skills, but practicing them in isolation for four years won't prepare a team for the World Cup if they never play an 11-vs-11 match.
- **The Real Limitation**: Pentests fail to test how the organization's overall security controls, blue team, and processes work together organically during a real, multi-stage attack.
## Red Team Testing: The "Real Match"
Red Teaming is the actual 11-vs-11 practice match — a comprehensive adversarial simulation designed to test an organization's holistic defense capabilities over an extended period (typically 4–8 weeks).
### Core Attributes of Red Teaming
1. **Holistic & Multi-Domain** — Real attackers don't attack just the web app and stop. They chain cloud, mobile, internal networks, and even physical or social engineering vectors. Red Teaming mirrors this.
2. **Stealth & Persistence** — The primary goal is to remain undetected by the blue team. Red teamers operate quietly, evading SIEMs and EDRs, and maintain access (persistence) over long periods.
3. **Realistic Objectives** — Instead of listing CVEs, the goal is practical: *Can we access the SWIFT infrastructure? Can we exfiltrate dummy customer data without the blue team noticing?*
4. **Threat Gets a Vote** — Engagements are grounded in what real threats actually do, not just what defenders plan for. The threat profile drives the TTPs.
5. **Assumed Breach** — If initial access (e.g., phishing) is blocked, red teamers shift to an "assumed breach" scenario: a beacon is planted internally to evaluate post-breach response, lateral-movement detection, and internal recon.
## The Engagement Lifecycle: Get In, Stay In, Act
A red team engagement follows three phases — a model used widely across the industry and codified in the redteam.guide methodology:
Initial access via the threat profile's preferred vectors — phishing, exposed services, supply chain, social engineering. The objective is footprint, not noise.
Establish persistence and command-and-control. Tier C2 channels (interactive / short-haul / long-haul). Maintain OPSEC. Survive defender response.
Execute the engagement objectives — privilege escalation, lateral movement, credential access, data discovery, exfiltration, operational impact — while remaining on-mission and within the Rules of Engagement.
## Why Decepticon Is an Autonomous Hacking Agent
Decepticon automates the **Red Teaming** mindset, not the pentest checklist. It does not blast a network with automated scanners — that would alert the blue team instantly.
Instead, it reads the context of the environment. It maintains stealth, performs internal reconnaissance, executes lateral movement, and simulates assumed-breach scenarios autonomously. The kill chain is driven by an **OPPLAN** — a structured operations plan the agent generates from the operator's RoE and ConOps before a single packet leaves the wire.
By taking on the role of a relentless, AI-driven red team, Decepticon provides infinite offensive feedback. It is the [Offensive Vaccine](/en/introduction/overview#the-motivation-an-offensive-vaccine) — training defense systems against the organic, stealthy realities of modern cyber threats rather than handing them a checklist of outdated software.
Get In, Stay In, Act — the three-phase lifecycle, mapped to Decepticon's agents.
Tactics, Techniques, and Procedures — the shared vocabulary between threats and Decepticon.
How Decepticon turns a threat profile into an executable engagement.
Red Cell, Blue Cell, White Cell, Trusted Agent — and where Decepticon fits.
---
## File: en/vision/autonomous-hacking.mdx
---
title: "Autonomous Hacking"
---
## What is Autonomous Hacking?
Let's be honest. The "AI + hacking" space is exhausting.
Every other week, someone drops a demo: *"Look, GPT can run nmap!"* Cool. Then what? It either ends up as a party trick that no one actually uses in production — or worse, it crosses a line nobody should cross.
> *"Yet another AI pentesting tool... cool demo. But when does it actually do something a real attacker would?"*
Fair question. Here's our answer.
**Autonomous Hacking** is the next evolution in offensive security. It's not about making hacking/pentesting easier or more accessible. It's about making **real Red Team operations** executable at machine speed — with the rigor, documentation, and legal framework that separates professionals from script kiddies.
Traditional red teaming demands hundreds of hours of manual work, such as scanning, enumerating, pivoting, documenting, etc. Most of it is repetitive and all of it is exhausting. Meanwhile, the attack surface grows faster than any human team can cover.
Autonomous Hacking changes the equation. AI agents handle the grind: running scans, analyzing output, chaining techniques, and adapting in real time. The human sets the mission, defines the rules, and focuses on what machines still can't do — intuition, judgment, and creative thinking.
> *"Delegate the repetitive. Focus on the decisive."*
## From Vibe Hacking to Autonomous Hacking
When Decepticon was first conceived, we used the term **Vibe Hacking** — the idea that an AI agent could read the "vibe" of a target environment: understanding context, adapting strategies on the fly, and executing complex attack chains without rigid playbooks.
That core capability hasn't changed. What changed is the framing.
"Vibe Hacking" captured the *how* — contextual, adaptive, reasoning-based attacks. But it didn't capture the *why* — and the "why" is what matters most.
**Autonomous Hacking** encompasses the full picture:
1. **The How** — AI agents that reason about targets, adapt to defenses, and chain multi-stage attacks autonomously
2. **The Why** — Providing infinite offensive feedback to build impenetrable defense systems
3. **The Framework** — Operating within professional Red Team methodology: RoE, OPPLAN, ConOps, formal authorization
The term "autonomous" also communicates what makes this different from every other AI security tool: the agent doesn't just run a script. It *thinks*, *adapts*, and *persists* — like a real adversary.
## "But wait — aren't you guys just the same?"
Great question. Short answer: **No.**
Here's the thing most people miss about offensive security. There's a massive difference between *hacking* and *Red Team Testing*.
Red Team Testing is a **regulated, authorized, and professionally disciplined**. Before a single packet leaves the wire, there are documents. Agreements. Rules.
- **RoE (Rules of Engagement)** — Defines what you can and can't touch. Scope, timing, boundaries. Violate this and you're not a red teamer, you're a criminal.
- **ConOps (Concept of Operations)** — Threat actor profile, attack methodology, the "who are we pretending to be" document.
- **Deconfliction Plan** — Separates red team activity from real threats. Source IPs, user-agents, time windows, and a shared code for real-time deconfliction calls with the SOC.
- **OPPLAN (Operations Plan)** — The full mission plan. Objectives, kill chain phases, acceptance criteria. Every action maps to a purpose.
Decepticon supports all of this.
Every engagement starts with proper documentation. Every objective is tracked. Every action operates within defined boundaries.
The agent doesn't just hack. It operates under a formal operations plan, respects the Rules of Engagement, and produces auditable findings. This isn't an entertaining Proof of Concept. It's a professional Red Team platform that happens to be autonomous.
## Why Decepticon?
Penetration testing finds vulnerabilities. Red teaming solves the most difficult problem: *can your organization survive a real attack?*
Most security tools stop at the scan report. Decepticon rather thinks in kill chains — reconnaissance, exploitation, privilege escalation, lateral movement, persistence — executing multi-stage operations the way a real adversary would, not the way a scanner does.
Four principles guide everything we build:
Decepticon emulates actual adversary behavior — not just running CVE checks against a list of ports. It reads an operations plan, adapts to what it finds, and pursues objectives through whatever path opens up. The goal is to test your defenses the way they'll actually be tested.
Real offensive security tools are interactive — sliver-client, msfconsole, evil-winrm, sqlmap, impacket-psexec. While most AI agents fire one-shot commands via subprocess.run() and call it a day, Decepticon runs every command inside persistent tmux sessions with automatic prompt detection. The agent actually operates the tools.
Every command runs inside a hardened Kali Linux sandbox on a dedicated operational network, fully isolated from the management infrastructure. No cross-network access. LangGraph reaches the sandbox exclusively via Docker socket — not the network.
Security work belongs in the terminal. Decepticon's interface is a real-time streaming CLI built with Ink. No browser tabs, no dashboards, no context switching. You see what the agent sees as it happens.
## The Bigger Picture: Offense Serves Defense
Here's what many "offensive AI" projects get wrong: they treat the attack as the destination.
**Decepticon is not the destination. It's Step 1.**
There are already plenty of offensive AI agents out there. The world doesn't need another "look, AI can hack things" demo. What the world actually needs is a system that turns offensive capabilities into **defensive evolution**:
Build a world-class hacking agent that executes realistic Red Team operations. **We are here.**
Deploy the agent to generate continuous, diverse attack scenarios — an endless stream of real-world threat simulation.
Channel that feedback into Blue Team capabilities — detection rules, response playbooks, hardening strategies. The defense evolves because the offense never stops.
Think of it as an **Offensive Vaccine**. Just as a biological vaccine exposes the body to weakened pathogens to build immunity, Decepticon exposes your infrastructure to relentless AI-driven attacks to build resilience.
The true value isn't in the attack. It's in the defense system that emerges from surviving it.
Learn how Decepticon's collective intelligence model turns this vision into a community-driven reality.
---
## File: en/vision/core-philosophy.mdx
---
title: "Core Philosophy"
---
Decepticon is not built on a whim. Every architectural decision stems from a set of core beliefs forged through years of research, failures, and hard-earned insights. This page outlines the philosophical pillars that define what Decepticon is—and what it deliberately is not.
## Reasoning Over Signatures
Traditional security tools operate on a **signature-based** paradigm: databases of known vulnerabilities (CVEs), known malicious payloads, and known attack patterns. If an attack doesn't match a signature, it slips through undetected.
The most dangerous vulnerabilities in production systems are almost never in a CVE database. They are **logical flaws**—unique to the target's business logic, architecture, and the assumptions humans made when building it.
Decepticon rejects the signature-first approach. Instead of pattern-matching against a static database, it **reasons** about the target:
* **Contextual Understanding**: It reads server responses, understands application flow, and identifies where human assumptions create exploitable gaps.
* **Dynamic Strategy**: Instead of running the same scan playbook every time, it adapts its approach based on the unique "vibe" of each target environment.
* **Chain-of-Thought Attacks**: It constructs multi-step attack chains, where each step informs the next—just like a real human attacker would.
## Hybrid Intelligence
Decepticon is **not** about replacing proven security tools with AI. It's about combining them intelligently.
The cybersecurity field has decades of battle-tested techniques: fuzzing, static analysis, network scanning, payload mutation. These tools are powerful within their domains. But they lack the ability to **reason**, **adapt**, and **connect the dots** across multiple attack surfaces.
Fuzzing, scanning, payload generation—proven tools that excel at structured, repetitive tasks within defined parameters.
LLM-powered reasoning that understands context, adapts strategy, and orchestrates multi-stage operations dynamically.
Decepticon's approach is to let each do what it does best:
* **Fuzzers** generate thousands of malformed inputs faster than any LLM could.
* **Scanners** enumerate services and known vulnerabilities with mechanical precision.
* **The Agent** decides *when* to deploy these tools, *interprets* their results, *chains* them into meaningful attack sequences, and *pivots* when the situation changes.
This is **Hybrid Intelligence**: the precision of automation guided by the reasoning of an AI agent.
## The Offensive Vaccine
As discussed in the [Overview](/en/introduction/overview#the-motivation-an-offensive-vaccine), Decepticon's ultimate goal is not to attack—it is to **immunize**.
Just as a biological vaccine exposes the body to weakened pathogens to build immunity, Decepticon exposes your infrastructure to relentless AI-driven attacks to build resilience.
But here's what makes this different from "just another scanner":
1. **Infinite Feedback Loop**: The agent generates an endless stream of diverse, context-aware attack scenarios—never repeating the same playbook.
2. **Realistic Threat Simulation**: To be an effective vaccine, attacks must mirror real-world threat actors. A tool that loudly port-scans and checks for default credentials is not a vaccine; it's a placebo.
3. **Measurable Evolution**: Every cycle of attack and defense produces measurable data, allowing the Blue Team to quantify their improvement over time.
## Human in the Loop
Autonomous does not mean unsupervised. Decepticon places the **human operator as the ultimate authority**—the true decision-maker and intelligence behind the operation.
The agent operates autonomously, executing its strategies and adapting in real-time. But the human is always present:
* **Real-Time Monitoring**: Like modern AI agent services, operators can watch the agent's actions as they happen—seeing what it's doing, why it's doing it, and what it plans to do next.
* **Intervention at Any Time**: The operator can pause, redirect, or override the agent's decisions at any moment. The agent is the tool; the human is the strategist.
* **Feedback-Driven Learning**: Human feedback shapes the agent's behavior. The operator isn't just watching—they're actively refining the operation.
Think of it like a self-driving car: it handles the driving, but the human can take the wheel at any moment. The human doesn't need to steer every turn, but they are always in control.
## Stealth as Foundation
Most automated security tools are inherently **noisy**. They blast thousands of requests, trigger every SIEM rule, and announce their presence to anyone watching.
This completely defeats the purpose of Red Team Testing. The whole point is to test whether the Blue Team can **detect** a sophisticated adversary. If your testing tool sets off every alarm the moment it starts, you're not testing detection—you're testing alert fatigue.
Decepticon treats stealth as a **foundational design requirement**:
* **C2-Based Operations**: The agent operates through Command & Control infrastructure—just like a real threat actor—maintaining encrypted, covert communication channels.
* **Sandbox Execution**: Commands are executed within sandboxed environments, mimicking the operational security practices of actual adversaries.
* **Low-and-Slow**: Activity is throttled and timed to blend with normal traffic patterns, not to overwhelm defenses with volume.
The value is not just finding vulnerabilities. It's answering the critical questions: *Can the Blue Team detect us? How fast do they respond? What do they miss?*
Discover how Decepticon's collective intelligence model goes beyond traditional open source—and why it matters for the entire security ecosystem.
---
## File: en/vision/target-architecture.mdx
---
title: "Target Architecture"
---
This page used to describe a future refactoring. The refactoring is **done**. What follows is the architectural target as it stands today, plus the horizons we're still climbing toward.
Living document. The shipped architecture below is current at the time of writing. The "What's Next" section describes ongoing direction, not commitments.
## What We Solved
The original monolithic agent design ran into three structural ceilings:
- **Context window saturation** — one agent juggling recon, exploitation, and post-exploit ran out of context before completing a serious engagement.
- **No specialization** — a generalist made shallow decisions on every phase.
- **Session-bound memory** — knowledge died at the end of every run; nothing carried over.
Decepticon's current architecture closes each of those gaps explicitly.
## Multi-Agent Hybrid Architecture (Shipped)
A single orchestrator (`decepticon`) plans the engagement and dispatches **fresh-context specialist sub-agents** through SubAgent middleware. Each specialist receives only the slice of state it needs and writes findings back to the knowledge graph and disk before exiting.
`decepticon` (main red-team coordinator), `vulnresearch` (5-stage vulnerability pipeline), `soundwave` (standalone engagement planner — generates RoE, ConOps, OPPLAN).
Recon, Exploit, Post-Exploit, AD Operator, Cloud Hunter, Contract Auditor, Reverser, Analyst, plus extended operators (phisher, mobile, wireless, IoT, ICS, forensicator, supply-chain, OSINT) for niche domains.
Scanner → Detector → Verifier → Patcher → Exploiter. The Patcher writes a fix; the Exploiter then tries to break it. State passes between stages through the knowledge graph, not through context.
The standard bundle ships in OSS; extra capabilities (vulnresearch, SaaS, third-party plugins) attach via entry points without forking the core.
### Hybrid Tool Integration
Each specialist orchestrates **proven security tools** alongside LLM reasoning:
- **The agent decides** which tool to deploy, when, and how to interpret the results.
- **The tools execute** — nmap, BloodHound, Slither, Sliver, sqlmap, ghidra — proven techniques that handle structured work with mechanical precision.
- **The agent adapts** based on tool output, reasons about next steps, and chains actions into coherent attack sequences.
This is not "AI replaces everything." It's **AI as the strategist, tools as the specialists**.
## Stealth-First Execution Architecture (Shipped)
Decepticon is a Red Team agent — stealth is the architecture itself. The whole point of Red Team Testing goes beyond finding vulnerabilities: can the Blue Team detect the intrusion? How quickly do they respond? What do they miss, and why? If the testing tool loudly announces itself, those questions become unanswerable.
The shipped execution path mirrors a real adversary:
- **Sandbox execution** — All bash flows through a persistent tmux-backed Kali sandbox on an isolated `sandbox-net` Docker network. The orchestrator reaches the sandbox over the Docker socket — never the network. No management traffic ever crosses into operations.
- **Dynamic infrastructure** — Heavyweight workloads (Sliver C2, BloodHound, future Havoc / Mythic) are not booted by default. The agent calls `ops_start("c2-sliver")` and a per-user **opscontrol daemon** brings the workload up on demand via Compose profiles. See [Dynamic Infrastructure](/en/features/dynamic-infrastructure).
- **C2-based communication** — When operations require it, the agent issues commands through Sliver C2 beacons exactly as a human operator would, maintaining the encrypted covert channels real threat actors use.
```mermaid
graph LR
subgraph Decepticon ["Decepticon (mgmt)"]
A[Specialist agent - LLM] --> O[Orchestrator]
O --> OPS[opscontrol daemon]
end
subgraph Execution ["Operations (sandbox-net)"]
OPS -.->|spawn on demand| C[Sliver C2 Server]
O --> S[Kali Sandbox - tmux/bash]
C --> B[Beacon on Target]
end
subgraph Monitoring
H[Human Operator] -.->|Monitor & Intervene| O
end
```
## Knowledge Graph as Shared Memory (Shipped)
Across-session memory is solved by a **Neo4j-backed knowledge graph**, owned by `KGMiddleware`. Specialists call explicit `kg_record` / `kg_ingest` tools; the middleware enforces engagement-scope isolation so two parallel engagements never bleed into each other.
- **Findings persist** between specialist invocations — Stage 4 of vulnresearch reads candidates Stage 1 emitted without ever sharing context.
- **Multi-hop reasoning** — Analyst queries the graph to construct exploit chains that span multiple agents' work.
- **Engagement scoping** — Every node is tagged with `engagement`. Tenants are isolated by composite `(key, engagement)` uniqueness at the schema level.
## Human in the Loop (Shipped)
The operator is the ultimate decision-maker. The HITL middleware wires LangGraph's native interrupt pattern so the agent can pause for approval on consequential actions:
- **Real-time visibility** — Operators see every tool call, its reasoning, and what the agent plans next, streamed over SSE.
- **Intervention at any moment** — Pause to assess, redirect strategy, override specific decisions, or provide feedback that shapes subsequent behavior.
- **Approval gates** — Actions touching production or with high blast radius prompt before executing.
The human isn't steering every turn — they're the commander watching the battlefield, ready to intervene when their judgment and experience are needed most.
## What's Next
The shipped architecture is solid. Open horizons:
`blue_cell` (defense agent) is in OSS today. The next horizon is the full attack → defend → verify loop: red findings drive blue patches, blue patches re-run the red path, and the delta is published as a vaccine signature.
Engagement-scoped graphs are the baseline. The next layer is anonymized cross-engagement signals — "this RCE pattern has been seen in three other engagements" — without violating tenant isolation.
Standard + vulnresearch bundles ship today. SDK is published; the next step is a community plugin registry so third-party operators (DFIR teams, bug-bounty automators, mobile specialists) extend Decepticon without forking core.
`DECEPTICON_STACK_NAME` already supports multiple stacks on one host. Federation across hosts (one orchestrator, sandboxes in many regions) is the next scaling axis for distributed engagements.
This roadmap is not linear — horizons overlap and inform each other. The architecture is an iterative process, much like the offensive operations Decepticon itself performs.
---
## File: en/vision/why-open-source.mdx
---
title: "Why Open Source?"
---
Open-sourcing a hacking agent is not a casual decision. This page explains why Decepticon's open-source model is fundamentally different from "just publishing code on GitHub"—and why collective intelligence is the only way to win the cybersecurity arms race.
## Beyond Traditional Open Source
Most open-source security tools follow a familiar pattern: the code is public, developers can clone it, run it locally, maybe submit a bug fix. It's a **tool** you download and use.
Decepticon aspires to something fundamentally different.
Code is public. Fork it, use it locally, maybe file an issue. The project stays a **tool**.
Code, knowledge, ideas, and real-world experience flow in all directions. The project becomes an **ecosystem**.
## Collective Intelligence
In Decepticon's world, "contribution" means far more than pull requests:
* **Code Contributions**: Reviews, feature PRs, bug fixes—the traditional open-source workflow. Absolutely welcome.
* **Knowledge Archiving**: Red Team techniques, attack methodologies, defense bypass strategies—documented and shared for the community.
* **Real-World Experience**: War stories from actual engagements. What worked, what didn't, what surprised you.
* **Simple Ideas**: Even a rough sketch of an attack concept or a "what if we tried..." suggestion has value. Not every contribution needs to be polished code.
* **Feedback Loops**: Using Decepticon against your own infrastructure and sharing what you learned—both offensively and defensively.
The security industry has a wealth of practical knowledge locked inside individual teams and closed-door engagements. Decepticon's community aims to surface that knowledge and make it collectively actionable.
## Blue Team vs. Red Team: A Living Community
This is not just a Red Team project. The ultimate purpose of Decepticon is to strengthen **defense**.
We envision a community where both sides of the security equation participate actively:
* 🔴 **Red Teamers** share attack patterns, evasion techniques, and creative exploitation chains.
* 🔵 **Blue Teamers** share detection strategies, incident response playbooks, and lessons from real encounters.
* 🟣 **Together**, the community creates a feedback loop that mirrors what Decepticon itself does: infinite, iterative improvement.
In the security industry, **practical, real-world discussions** are invaluable. The gap between academic research and what actually happens during an engagement is enormous. A community that bridges this gap benefits everyone—except the actual threat actors.
## The Bigger Picture
Here's the truth that most "offensive AI" projects miss:
> There are already many offensive AI agents. The world doesn't need another "look, AI can hack things!" demo.
What the world needs is a system that turns offensive capabilities into **defensive evolution**. Decepticon is the **first step** in building that system.
Build a world-class Autonomous Hacking Agent that simulates realistic Red Team operations. **← We are here.**
Deploy the agent to generate continuous, diverse attack scenarios against target infrastructure—creating an endless stream of offensive feedback.
Channel that feedback into Blue Team capabilities: detection rules, response playbooks, hardening strategies. The defense evolves because the offense never stops.
Decepticon is not the destination. It's the engine that powers the journey toward **impenetrable defense**.
## A Note on Responsibility
With the power of an autonomous offensive agent comes the responsibility to ensure it is used ethically.
Red Team Testing in the real world requires **agreement**—a formal consensus between all parties before any operation begins. The scope, targets, timing, and boundaries must be clearly defined and mutually agreed upon. This is not optional; it is the foundation of ethical offensive security.
Decepticon is a powerful tool that can be misused. We take this seriously. The project includes Rules of Engagement (RoE) enforcement that defines operational boundaries—but more importantly, we rely on the community's commitment to ethical use and the principle that **offense exists to serve defense**.
Just as real Red Team engagements begin with a formal agreement, every Decepticon operation should begin with clear intent, defined scope, and proper authorization.
---
## File: ko/cli-reference.mdx
[Binary file]
---
## File: ko/architecture/agents.mdx
---
title: "에이전트"
---
## 에이전트 아키텍처
Decepticon은 **16개의 전문 에이전트**를 통해 작동하며, 각각 자체 도구, 스킬, 클린 컨텍스트 윈도우를 가집니다. 에이전트는 목표마다 새로 스폰됩니다. — 축적된 노이즈가 없고, 장기 인게이지먼트 전체에서 추론이 저하되지 않습니다.
에이전트는 단순한 목록이 아닙니다. 그들은 서비스하는 인게이지먼트 단계별로 구성되며, **Decepticon 조율자**에 의해 OPPLAN을 통해 라우팅됩니다.
## 조율 계층
중앙 레드팀 조율자. OPPLAN을 소유하고, 목표를 시퀀싱하고, 의존성을 해결하며, SubAgent 미들웨어를 통해 전문가(`recon`, `exploit`, `postexploit`, `analyst`, `reverser`, `contract_auditor`, `cloud_hunter`, `ad_operator`)를 디스패치합니다. 가장 강력한 모델 티어에서 실행됩니다.
취약점 연구 조율자 — 5단계 파이프라인(`scanner → detector → verifier → patcher → exploiter`)을 실행하며, 단계 간 상태는 오직 지식 그래프를 통해서만 전달됩니다.
인게이지먼트 계획자. 독립 그래프(Decepticon의 서브 에이전트가 아님). 운영자를 인터뷰하고 완전한 인게이지먼트 패키지를 생성합니다. — RoE, ConOps, 디컨플릭션 플랜, OPPLAN, 위협 프로필. bash 접근이 없으며, 문서만 생성합니다.
## 정찰 단계
능동 및 수동 정찰 — 포트 스캔, 서비스 열거, OSINT, 부도메인 발견, 인증서-투명성 채굴. Kali 샌드박스 내에서 작동합니다.
## 취약점 연구 파이프라인
**Vulnresearch** 조율자의 서브 에이전트들. 단계 간 상태는 지식 그래프를 통해 흐르며, 각 단계는 새 컨텍스트로 실행됩니다.
Stage 1 — 광범위 스캐너. 대규모 코드베이스를 병렬로 순회하며 휴리스틱 의심도 점수와 함께 CANDIDATE 노드를 방출합니다. 저렴하고 빠르며, 취약점 추론은 하지 않습니다.
Stage 2 — 취약점 탐지기. 각 CANDIDATE 주변의 소스를 읽고 실제 버그를 VULNERABILITY + HYPOTHESIS 노드로 승격하거나, false positive로 거부합니다. 읽기 전용(bash 없음).
Stage 3 — 이중 방법 검증 게이트. 후속 작업이 시작되기 전에 최소 두 개의 독립적인 증거 채널을 통해 후보 발견사항을 확인합니다.
Stage 4 — 재현 가능한 PoC 저자. 검증된 취약점에 대한 작동하는 PoC 익스플로잇을 생성하며, 신뢰성 주석을 포함합니다.
Stage 5 — 패치 생성자. 애플리케이션을 깨지 않으면서 취약점을 해결하는 코드 또는 설정 변경을 생성하며, 회귀 테스트를 포함합니다.
## 익스플로잇 & 포스트 익스플로잇
초기 접근 및 익스플로잇 전술. 웹/AD 공격(SQLi, SSTI, Kerberoasting, ADCS 남용, 자격증명 공격).
권한 상승, 횡적 이동, 자격증명 수집, 지속성 — 초기 접근이 확립된 후 종종 Sliver C2 세션을 통해 동작합니다.
## 도메인 스페셜리스트
Active Directory 전문가. Kerberoasting, AS-REP roasting, ADCS ESC1–ESC15, DCSync, 티켓 위조, ACL 남용, GPO 조작, BloodHound 경로 분석.
클라우드 인프라 전문가. AWS/Azure/GCP에서 IAM 권한 상승, S3/Azure 스토리지 노출, Kubernetes RBAC 탈출, 메타데이터 서비스 남용.
Solidity / EVM 스마트 계약 감사자. 재진입, 오라클 조작, 플래시론 남용, 접근 제어 결함; Slither 정적 분석 + Foundry PoC 하네스.
바이너리 역공학 전문가. ELF/PE/Mach-O 분류, 팩커 탐지, 문자열/기호 추출, ROP 가젯 인벤토리, Ghidra/radare2 스크립팅.
## 분석 & 리포팅
취약점 연구 및 보고 전문가. 발견사항을 교차 상관시키고, 지식 그래프를 쿼리하고, 인게이지먼트 내러티브를 초안 작성합니다 — 소스 코드 리뷰, 정적 분석(semgrep/bandit/gitleaks), 의존성 CVE 스윕, 멀티-홉 익스플로잇 체인 구성.
## 목표별 클린 컨텍스트
모든 에이전트는 모든 목표에 대해 **새로운 컨텍스트 윈도우**로 스폰됩니다:
```
목표 1 (정찰) → 새 Recon 에이전트 인스턴스 → 발견사항 디스크 + 그래프에 저장
목표 2 (익스플로잇) → 새 Exploit 에이전트 인스턴스 → 목표 1 발견사항 명시적으로 읽음
목표 3 (포스트 익스) → 새 Post-Exploit 인스턴스 → 목표 1+2 발견사항 명시적으로 읽음
```
- **축적된 노이즈 없음** — 100개 목표 인게이지먼트에서 컨텍스트가 저하되지 않습니다.
- **대상화된 컨텍스트** — 각 에이전트는 자신의 목표와 관련된 발견사항만 수신합니다.
- **영속적 상태** — 발견사항은 에이전트 메모리가 아니라 디스크와 Neo4j에 저장됩니다.
## 에이전트 미들웨어 스택
각 에이전트는 교차 절단 관심사를 제공하는 미들웨어 스택으로 실행됩니다. 정확한 스택은 에이전트의 역할에 따라 다릅니다.
| 에이전트 역할 | 미들웨어 스택 |
|---|---|
| **Decepticon (조율자)** | EngagementContext → Skills → Filesystem → SubAgent → OPPLAN → ModelFallback → Summarization → PromptCaching → PatchToolCalls |
| **Vulnresearch (조율자)** | Skills → Filesystem → SubAgent → OPPLAN → ModelFallback → Summarization → PromptCaching → PatchToolCalls |
| **Soundwave (계획자)** | EngagementContext → Skills → Filesystem → ModelFallback → Summarization → PromptCaching → PatchToolCalls |
| **전문가 (Recon, Exploit, ...)** | Skills → Filesystem → ModelFallback → Summarization → PromptCaching → PatchToolCalls |
### 각 계층이 하는 일
- **EngagementContext** — 인게이지먼트 메타데이터(slug, 타겟, RoE 요약)를 시스템 프롬프트에 주입하여 가드레일이 지속적으로 평가됩니다.
- **Skills** — 활성 위협 프로필과 ATT&CK 중복으로 필터링된 점진적 공개 스킬 로딩. 시작 시 프론트매터(스킬당 ~100 토큰)만 로드하고, 전체 본문은 `read_file`로 필요시 가져옵니다.
- **Filesystem** — `FilesystemMiddlewareNoExecute` — 인게이지먼트 워크스페이스로 범위가 지정된 `read_file`, `write_file`, `edit_file`, `ls`, `glob`, `grep`. 실행은 의도적으로 비활성화 — 전문가는 전용 `bash` 도구로 명령을 실행합니다.
- **SubAgent** — 조율자(Decepticon, Vulnresearch)가 전문가에게 일을 디스패치하기 위한 `task()` 도구.
- **OPPLAN** — 5개의 CRUD 도구(`add_objective`, `get_objective`, `list_objectives`, `update_objective`, `objective_expand`)와 모든 LLM 호출에 목표의 동적 상태 주입.
- **OpsControl** — 워크로드 라이프사이클 상태 전이(`starting → running → exited`)를 에이전트의 다음 턴에 자동 주입. `ops_start(...)` 호출 후 폴링하지 않습니다. [동적 인프라](/ko/features/dynamic-infrastructure) 참조.
- **SandboxNotifications** — `run_in_background=True`로 실행한 `bash` 명령이 종료되면 캡처된 출력을 다음 추론 턴에 자동 주입. 에이전트가 `bash_output()`를 명시적으로 호출할 필요가 없습니다.
- **ModelFallback** — 제공자 장애 조치. 사용자의 자격증명 인벤토리에서 빌드된 폴백 체인을 따라 속도 제한이나 장애 시 다음 제공자로 전환.
- **Summarization** — 전문가 에이전트의 컨텍스트가 모델 윈도우에 접근할 때 대화 윈도우 압축.
- **PromptCaching** — `AnthropicPromptCachingMiddleware` — 프롬프트 캐시 경계 마커 배치; 비 Anthropic 제공자에서는 자동 no-op.
- **PatchToolCalls** — 교차 제공자(Anthropic, OpenAI, Google, MiniMax 등) 호환성을 위해 도구 호출 모양을 정규화·재작성.
## 에이전트-도구 상호작용
에이전트는 Kali 샌드박스 내의 영속적 tmux 세션을 통해 오펜시브 도구와 상호작용합니다:
```
에이전트 → Docker 소켓 → Kali 샌드박스 → tmux 세션 → 도구 (sliver-client, msfconsole, evil-winrm, ...)
↓
프롬프트 탐지
↓
후속 명령
```
도구가 대화형 프롬프트(`sliver >`, `msf6 >`, `PS C:\>`)를 제시할 때, 에이전트는:
1. 프롬프트 패턴을 탐지합니다.
2. 도구의 출력을 해석합니다.
3. 적절한 후속 명령을 전송합니다.
4. 필요시 제어 신호(`C-c`, `C-z`)를 처리합니다.
출력은 계층화됩니다:
- **인라인(≤15K)** — 에이전트에 직접 반환됨.
- **오프로드(15K–100K)** — `/workspace/.scratch/`에 작성되고 경로로 참조됨.
- **감시견(>5M)** — 세션이 종료되고 에이전트는 개선을 요청받습니다.
이것이 실제 운영자들이 작업하는 방식입니다. Decepticon의 전문가들도 동일하게 수행합니다.
조율자가 이 에이전트들에게 디스패치하는 구조화된 계획.
이 에이전트들이 작동하는 격리된 네트워크 아키텍처.
---
## File: ko/architecture/infrastructure.mdx
[Binary file]
---
## File: ko/architecture/middleware-stack.mdx
---
title: "미들웨어 스택"
---
모든 Decepticon 에이전트는 모든 에이전트에 공통인 관심사를 처리하는 미들웨어 스택을 상속받습니다. — RoE 강제, 스킬 로딩, 프롬프트 캐싱, 모델 장애 조치, 대화 요약. 이 페이지는 각 계층이 무엇을 하며 왜 존재하는지 설명합니다.
## 미들웨어가 필요한 이유
모놀리식 에이전트 프롬프트가 모든 것을 처리하려고 하면, 아무것도 잘 하지 못합니다. Decepticon은 교차 절단 관심사를 구성 가능한 미들웨어로 인수분해합니다:
- 에이전트 프롬프트는 그 전문성에 집중합니다.
- 모든 에이전트에 공통인 행동(RoE 확인, 스킬 로딩)은 한 곳에 존재합니다.
- 교차 제공자 호환성(Anthropic, OpenAI, Google, MiniMax)은 프롬프트 내가 아니라 아래에서 처리됩니다.
## 계층들
### 스킬
`DecepticonSkillsMiddleware` (LangChain의 `SkillsMiddleware`의 서브클래스).
- 시작 시 스킬 *프론트매터*만 로드합니다(스킬당 약 100개 토큰).
- 활성 위협 프로필과의 ATT&CK 중복으로 스킬을 필터링합니다.
- 에이전트가 `read_file()`을 호출할 때 필요시 전체 스킬 본문을 로드합니다.
- **스킬 우선 규칙** 강제: 에이전트는 일치하는 트리거에 작동하기 전에 관련 스킬을 로드해야 합니다.
### 파일시스템
`FilesystemMiddlewareNoExecute` — 인게이지먼트 워크스페이스로 범위가 지정된 샌드박스 파일 접근. `read_file`, `write_file`, `edit_file`, `ls`, `glob`, `grep`를 `/workspace/{engagement_id}/`에 대해 제공합니다. 실행은 의도적으로 비활성화 — 전문가는 명령 실행을 위해 전용 `bash` 도구를 사용합니다.
### SubAgent
조율자에게 `task()` 도구를 노출합니다. Decepticon이 전문가 에이전트(Recon, Exploit, Analyst, ...)에 일을 디스패치하게 하며, 그들의 프롬프트를 인라인하지 않습니다. SubAgent 출력은 `StreamingRunnable`로 감싸져 CLI와 HTTP API를 통해 스트림됩니다.
### OPPLAN
조율 구조의 척추:
- 5개의 CRUD 도구 노출 — `add_objective`, `get_objective`, `list_objectives`, `update_objective`, `objective_expand`.
- 모든 LLM 호출로 현재 OPPLAN 상태(보류 중, 진행 중, 완료)를 주입합니다.
- 의존성 해결 — 전제 조건이 완료되지 않은 목표의 디스패치를 거부합니다.
- `objective_expand`를 통해 모의해킹 작업 트리(PTT)를 지원합니다.
### EngagementContext
RoE/ConOps 가드레일. 모든 반복에서 미들웨어는:
- 활성 교전 규칙.
- 운영 개념.
- 현재 위협 프로필.
에이전트의 추론은 세션 시작이 아니라 연속적으로 범위 및 적대자 정체성에 대해 평가됩니다.
### ModelFallback
제공자 장애 조치. 각 모델 프로필은 장애 조치 체인을 정의합니다. — 예를 들어: `claude-opus-4-7 → gpt-5.5 → gemini-2.5-pro → MiniMax-M2.5`. 제공자가 속도 제한 또는 오류를 발생시키면, 체인의 다음 제공자가 투명하게 호출됩니다.
### 요약
대화 윈도우 압축. 전문가 에이전트의 컨텍스트가 모델 윈도우에 접근할 때, 이전 턴들이 구조화된 다이제스트로 요약됩니다. 발견사항, 도구 출력, 결정은 보존됩니다. 축어적 채팅 기록은 축소됩니다.
### PromptCaching
Anthropic의 프롬프트 캐시 경계 마커. 미들웨어는 정적 프롬프트 섹션(시스템 프롬프트, 스킬 카탈로그)과 동적 섹션(활성 OPPLAN 상태, 현재 반복) 사이에 `CACHE_BOUNDARY` 마커를 배치합니다. 이는 반복되는 호출이 캐시에 도달하게 하여 장기 인게이지먼트에서 호출당 비용을 극적으로 떨어뜨립니다.
### PatchToolCalls
교차 제공자 호환성 쉐임. 서로 다른 제공자들은 도구 호출을 다르게 표현합니다. — 미들웨어는 에이전트 프롬프트에 도달하기 전에 정규화하고, 나가는 길에 다시 모양을 변경하여 단일 에이전트 정의가 지원되는 모든 제공자에 대해 실행됩니다.
### OpsControlNotifications
`opscontrol` 데몬의 워크로드 상태 이벤트를 구독합니다 (ADR-0006). 워크로드가 전이될 때(`starting → running → exited`) 미들웨어가 새 상태를 담은 `` `HumanMessage`를 오케스트레이터의 다음 추론에 주입합니다. `ops_start("c2-sliver")` 호출 후 오케스트레이터는 폴링하지 않습니다 — 완료가 자동으로 도달합니다. Decepticon 오케스트레이터에만 장착됩니다.
### SandboxNotifications
bash 측 대응물. `run_in_background=True`로 실행된 `bash` 명령이 종료되면 미들웨어가 샌드박스로부터 캡처된 출력 diff를 가져와 에이전트의 다음 턴에 ``로 주입합니다. 전문가가 `bash_output()` 호출을 기억할 필요가 없습니다. `OpsControlNotifications`와 동일한 형태이며, `bash` 도구를 가진 모든 에이전트에 장착됩니다.
### KG (KGMiddleware)
인게이지먼트 범위의 Neo4j `KGStore`를 소유하고 두 가지 에이전트-facing 그래프 도구 — `kg_record(observations)` (원자적 배치 쓰기)와 `kg_ingest(scanner_kind, path)` (스캐너 어댑터 디스패처) — 를 노출합니다. 모든 호출에 인게이지먼트 라벨 검증기를 강제하여 두 개의 병렬 인게이지먼트가 서로의 그래프 상태를 침범하지 않게 합니다.
### Skillogy
독립 실행형 Skillogy 서비스의 얇은 REST 클라이언트. Neo4j 기반 스킬 그래프(포트 `9100`)에 대해 `find_skill`, `load_skill`, `traverse`를 노출합니다. 에이전트 팩토리가 설정하는 `allowed_path_prefixes` 파라미터를 함께 전달하며, 서비스가 강제 ACL([ADR-0008](https://github.com/BitterSecurity/Decepticon/blob/main/docs/adr/0008-skillogy-hard-acl-phase1a.md))을 적용해 전문가가 프롬프트 인젝션으로 다른 역할의 스킬을 열람하도록 설득될 수 없습니다.
### HITL
LangGraph의 네이티브 `interrupt()` 패턴을 감싸 에이전트가 중요한 행동에서 운영자 승인을 위해 일시 정지할 수 있게 합니다 — 프로덕션 대상 명령, 민감 데이터 클래스 유출, RoE가 폭발 반경이 큰 것으로 표시한 모든 것. 운영자는 제안된 행동을 보고 승인/리다이렉트/중단할 수 있으며, 에이전트는 동일한 노드에서 재개합니다.
## 역할별 스택 구성
미들웨어의 정확한 순서는 중요합니다. — 외부 계층이 내부를 감쌉니다. 조율자와 계획자는 `EngagementContext`를 먼저 주입하여 RoE/ConOps 가드레일이 이후 모든 계층에 적용되도록 합니다. 전문가는 받은 OPPLAN 슬라이스를 통해 동일한 가드레일을 상속받습니다.
```
┌─ Decepticon 조율자 ──────────────────┐
│ EngagementContext │
│ └─ Skills │
│ └─ Filesystem │
│ └─ SubAgent │
│ └─ OPPLAN │
│ └─ ModelFallback │
│ └─ Summarization
│ └─ PromptCache
│ └─ Patch
└─────────────────────────────────────┘
┌─ Vulnresearch 조율자 ────────────────┐
│ Skills │
│ └─ Filesystem │
│ └─ SubAgent │
│ └─ OPPLAN │
│ └─ ModelFallback │
│ └─ Summarization │
│ └─ PromptCache
│ └─ Patch │
└─────────────────────────────────────┘
┌─ Soundwave 계획자 ────────────────────┐
│ EngagementContext │
│ └─ Skills │
│ └─ Filesystem │
│ └─ ModelFallback │
│ └─ Summarization │
│ └─ PromptCache │
│ └─ Patch │
└─────────────────────────────────────┘
┌─ 전문가 (Recon, Exploit, ...) ──────┐
│ Skills │
│ └─ Filesystem │
│ └─ ModelFallback │
│ └─ Summarization │
│ └─ PromptCache │
│ └─ Patch │
└─────────────────────────────────────┘
```
전문가는 또한 샌드박스 명령 실행을 위해 `bash` 도구를 바인딩합니다. Soundwave는 그렇지 않습니다.
## 스택을 통한 스트리밍
서브 에이전트 출력은 수집 후 반환이 아니라 스트림합니다. `StreamingRunnable`이 모든 서브 에이전트를 감싸므로 토큰이 다음에 도달합니다:
1. Python CLI의 `UIRenderer` (Ink 터미널 UI).
2. LangGraph HTTP 커스텀 이벤트 채널(웹 대시보드).
이것이 운영자가 Recon이 포트를 실시간으로 열거하는 것을 보는 방식입니다, 사실 이후가 아니라.
이 미들웨어 스택이 감싸는 16개의 전문 에이전트.
OPPLAN 미들웨어가 노출하고 주입하는 구조화된 계획.
---
## File: ko/concepts/mitre-attack.mdx
[Binary file]
---
## File: ko/concepts/red-team-lifecycle.mdx
---
title: "레드팀 인게이지먼트 라이프사이클"
---
레드팀 인게이지먼트는 취약점 스캔에 몇 가지 단계를 더한 것이 아닙니다. 이는 실제 위협 프로파일에 대한 체계적인 캠페인으로, 세 가지 단계로 실행되며, 공식 문서(RoE, ConOps, OPPLAN)에 의해 관리되고, 8가지 정규 인게이지먼트 목표에 따라 평가됩니다.
## 세 가지 단계
블루팀에게 들키지 않으면서 초기 접근을 확보합니다. 풋프린트는 비용입니다 — 작을수록 좋습니다. Decepticon은 OPPLAN의 `INITIAL_ACCESS` 목표에 의해 주도되는 **Recon**과 **Exploit** 에이전트를 통해 Get In을 실행합니다.
지속성(Persistence)과 명령 및 제어(Command-and-Control). 목표는 생존성입니다 — 재부팅, 방어자 대응, EDR 스위프를 견디는 비콘입니다. Decepticon은 여기서 Sliver C2 세션을 설정하고 계층화된 콜백을 구성합니다.
인게이지먼트 목표를 달성합니다 — 권한 상승, 측면 이동, 크리덴셜 접근, 데이터 발견, 유출, 운영 영향. Decepticon의 **Post-Exploit** 에이전트는 MITRE ATT&CK ID로 태그된 Act 목표를 실행합니다.
## C2 계층화
Stay In 단계에서 명령 및 제어는 계층으로 구조화됩니다. 각 계층은 응답성과 탐지 위험 사이에서 균형을 맞춥니다.
| 계층 | 콜백 주기 | OPSEC 프로파일 | 사용 사례 |
|---|---|---|---|
| `INTERACTIVE` | 초 | 높은 노출 | 핫 목표 중 운영자 실시간 제어 |
| `SHORT_HAUL` | 1~24시간 | 보통 | 진행 중인 목표를 위한 신뢰성 높은 운영 접근 |
| `LONG_HAUL` | 24시간 이상 | 낮은 노출 | 방어자 사냥을 견디는 지속적 폴백 채널 |
Decepticon의 OPPLAN 목표는 에이전트가 각 작업에 어떤 채널을 사용할지 알 수 있도록 적절한 `C2Tier`로 태그됩니다.
## 8가지 인게이지먼트 목표
레드팀 인게이지먼트는 정규 목표에 따라 평가됩니다 — 팀이 무엇을 달성하려고 했는가? 그리고 블루팀이 이를 탐지했는가? Decepticon은 업계 전반에서 사용되는 동일한 8가지 범주를 채택합니다:
물리 보안 및 배지 제어 평가 — 도어 접근, 꼬리물기(Tailgating), RFID 클로닝
명명된 핵심 시스템(SWIFT, ERP, 프로덕션 데이터베이스, 코드 서명 인프라) 도달
세그먼트 간 피벗 — DMZ에서 기업망으로, 기업망에서 OT로, 클라우드에서 온프레미스로
낮은 권한 사용자에서 로컬 관리자, 도메인 관리자, 또는 클라우드 테넌트 루트로 승격
민감한 데이터 위치 파악 — 시크릿, 소스 코드, 고객 기록, IP
DLP를 회피하면서 데이터 이동. 바이트만큼 경로도 중요합니다.
SIEM, EDR, NDR 또는 인간 분석가 티켓을 발동하지 않고 운영
결과를 시연 — 비즈니스 중단, 무결성, 가용성
## Decepticon이 라이프사이클에 매핑되는 방식
Decepticon의 에이전트 토폴로지는 도구를 중심으로가 아니라 이 라이프사이클을 중심으로 구축되었습니다.
| 단계 | 주요 에이전트 | 스킬 서페이스 |
|---|---|---|
| **계획** (사전 인게이지먼트) | Soundwave | RoE, ConOps, Deconfliction, OPPLAN, Threat Profile |
| **Get In** | Recon, Scanner, Exploit, Exploiter | 수동/능동 정찰, 웹 익스플로잇, AD 초기 접근 |
| **Stay In** | Post-Exploit, AD Operator, Cloud Hunter | 지속성, C2 세션, 방어 회피, OPSEC |
| **Act** | Post-Exploit, Analyst | 측면 이동, 크리덴셜 접근, 발견 캡처, Vulnresearch 파이프라인 출력 (계획된 Defender 컴포넌트가 향후 이를 기반으로 방어 브리핑을 생성할 예정) |
오케스트레이터(Decepticon 에이전트)는 단계 전반에 목표를 시퀀싱하고 전문 에이전트를 새로운 컨텍스트 윈도우로 생성하므로 추론은 절대 성능 저하되지 않습니다.
## 인게이지먼트 문서
모든 Decepticon 인게이지먼트는 4가지 문서를 생성하며 이에 구속됩니다:
범위, 제한사항, 통신 계획, Deconfliction. 운영 권한
위협 프로파일, 방법론, 성공 기준, 인프라 계획
레드팀 활동이 인게이지먼트 중 실제 사건과 분리되는 방식
목표 목록 — 각각 MITRE ATT&CK ID, 킬 체인 단계, 의존성, 수락 기준 포함
이 3단계 프레이밍은 [redteam.guide 방법론](https://redteam.guide/docs/Concepts/red-teaming/)과 Joe Vest와 James Tubberville의 저서 *Red Team Development and Operations*에서 개작되었습니다. Decepticon의 기여는 각 단계를 에이전트 실행 가능하게 만드는 것입니다.
---
## File: ko/concepts/roles-and-cells.mdx
---
title: "역할 & 셀"
---
레드팀 인게이지먼트는 단순한 "공격자 vs 방어자"가 아닙니다. 이는 명명된 역할을 가진 구조화된 연습으로, 각각 고유한 책임이 있습니다. Decepticon은 이러한 역할을 대체하지 않습니다 — **Red Cell** 내에서 포스 멀티플라이어로 작동하며 다른 역할과 명시적 핸드셰이크를 가집니다.
## 4가지 셀
공격 구성 요소. 위협 프로파일의 전략적 및 전술적 대응을 시뮬레이션합니다. RoE 내에서 운영합니다. **Decepticon이 여기서 실행합니다.**
대상을 방어하는 모든 구성 요소 — SOC 분석가, IR 대응자, 내부 직원, 관리층. 인게이지먼트가 측정하는 효과의 대상
심판. RoE 준수를 모니터링하고, 실제 사건과 연습 활동을 분리하며, 결과를 판정합니다. Red와 Blue 모두 신뢰합니다.
인게이지먼트 활동에 대한 상세 지식을 가진 특권 인사자. 돌이킬 수 없는 손상을 방지하고 고위험 단계를 승인합니다.
## 셀이 자율 에이전트에 중요한 이유
셀은 관료주의가 아닙니다 — 공격적 인게이지먼트가 사건으로 변하지 않도록 하는 경계입니다. 이러한 핸드셰이크가 없는 자율 에이전트는 무모합니다. Decepticon은 셀 구조를 우회하지 않고 그 안에 맞도록 구축되었습니다.
| 셀 | Decepticon 터치포인트 |
|---|---|
| **Red Cell** | Decepticon 에이전트는 Red Cell 멤버입니다. 인게이지먼트로 귀속 가능한 발견, 증거, 공격 그래프를 생산합니다. |
| **Blue Cell** | Decepticon은 실행 중 Blue Cell과 상호작용하지 않습니다. 블루팀은 에이전트가 생성하는 아티팩트만 봅니다 — 알림, 텔레메트리, 측면 이동 |
| **White Cell** | Decepticon을 실행하는 운영자는 White Cell 연락담당자로 작동합니다: deconfliction 콜에서 에이전트를 일시 중지하고, RoE 준수를 인증하고, 결과를 선언합니다. CLI는 정확히 이를 위해 일시 중지/재개 프리미티브를 노출합니다. |
| **Trusted Agent** | OPPLAN 승인 권한을 보유한 사람이 인게이지먼트의 Trusted Agent입니다. Decepticon은 명시적으로 승인된 RoE와 OPPLAN 없이는 인게이지먼트를 시작하기를 거부합니다. |
## Deconfliction
**Deconfliction**은 레드팀 활동을 실제 활동과 분리하는 프로세스입니다. SOC가 실제 사건 옆에 레드팀의 비콘을 무시할 수 있게 합니다 — 그리고 더 중요하게는, 실제 사건이 레드팀이라고 생각해서 무시하는 것을 방지합니다.
Decepticon은 3가지 방식으로 deconfliction을 지원합니다:
Decepticon이 실행하는 모든 명령어는 인게이지먼트 ID로 태그됩니다. White Cell은 "Red가 03:14 UTC에 무엇을 하고 있었는가?"를 쿼리하고 몇 초 안에 권위 있는 답을 얻을 수 있습니다.
CLI는 실행 중인 C2 세션을 버리지 않으면서 새로운 목표 스케줄링을 중단하는 우아한 일시 중지를 노출하므로 deconfliction 콜이 인게이지먼트를 소모하지 않습니다.
모든 에이전트 행동, 도구 호출, 발견이 타임스탬프와 함께 PostgreSQL에 지속됩니다. 로그가 deconfliction 레코드입니다.
## 운영자-as-White-Cell
소규모 인게이지먼트에서 Decepticon을 실행하는 인간은 종종 여러 셀을 담당합니다 — 운영자(Red), 심판(White), 권한 보유자(Trusted Agent). Decepticon의 CLI는 이 현실을 중심으로 구축되었습니다:
- OPPLAN 승인 게이트는 실행이 시작되기 전에 운영자가 Trusted Agent로 행동하도록 강제합니다.
- 스트리밍 트랜스크립트는 White Cell 관찰자와 동일한 운영자 가시성을 제공합니다.
- 일시 중지/재개 제어는 운영자가 인게이지먼트 중 deconfliction 핸드셰이크를 수행하도록 합니다.
더 큰 인게이지먼트의 경우, 운영자는 이 의무를 분할할 수 있습니다 — Decepticon을 한 가지 신원으로 실행(Red Cell)하고 별도의 White Cell 프로세스에 deconfliction 로그를 제공합니다.
셀 모델은 [redteam.guide 역할 & 관계](https://redteam.guide/docs/Concepts/role-relationships/) 페이지에서 개작되었습니다. Decepticon은 모델을 변경하지 않습니다 — 그 안에 들어갑니다.
Soundwave가 셀이 운영하는 RoE와 OPPLAN을 어떻게 생산하는지 알아보세요.
---
## File: ko/concepts/threat-emulation.mdx
[Binary file]
---
## File: ko/concepts/tradecraft.mdx
[Binary file]
---
## File: ko/contributing/contributing-guide.mdx
---
title: "기여 가이드 (Contributing Guide)"
---
## 기여를 환영합니다
보안 연구자든, AI 엔지니어든, 더 나은 방어 체계를 만드는 것에 관심이 있는 분이든 — 여러분의 자리가 여기에 있습니다.
## 기여 방법
에이전트 개선, 도구 통합, 인프라 강화, 버그 수정, 테스트 커버리지.
스킬 라이브러리에 새로운 오펜시브 기법 추가 — MITRE ATT&CK ID 태그, 에이전트 역할별 구성.
이 문서를 개선하고, 튜토리얼을 작성하고, 예제를 추가하거나, 새 언어로 번역하세요.
Discord에서 질문에 답하고, 인게이지먼트 패턴을 공유하고, 버그를 보고하거나, 새로운 기능을 논의하세요.
## 기여 워크플로우
[Decepticon 저장소](https://github.com/BitterSecurity/Decepticon)를 여러분의 GitHub 계정으로 포크합니다.
`main`에서 설명적인 이름으로 브랜치를 생성합니다:
```bash
git checkout -b feature/add-kerberoasting-skill
```
[개발자 설정](/ko/contributing/developer-setup)을 사용하여 변경 사항을 작성합니다. 테스트를 실행합니다:
```bash
make test
make lint
```
Decepticon은 [Conventional Commits](https://www.conventionalcommits.org/) 형식을 따릅니다: `type(scope): subject`. 일반적인 타입: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`. 본문에서 *무엇*이 아닌 *왜*를 설명하세요.
```text
feat(agents): add Cloud Hunter skill for AWS metadata abuse
fix(opplan): resolve dependency cycle in objective_expand
docs(features): document the offensive vaccine pipeline
```
브랜치를 푸시하고 `main`에 대한 PR을 엽니다. 변경 사항이 무엇이고 왜 필요한지 설명합니다.
## 스킬 기여
스킬 라이브러리에 새로운 스킬을 추가하는 것은 가장 가치 있는 기여 중 하나입니다. 각 스킬은 다음을 포함해야 합니다:
- **프론트매터** — 이름, 설명, MITRE ATT&CK 기법 ID, 필요 도구
- **내용** — 단계별 기법 실행, 명령어 예시, 예상 출력
- **탐지 노트** — 방어자가 이 기법을 탐지할 수 있는 방법 (방어 진화 비전에 기여)
- **사전 요구사항** — 필요한 접근 권한 또는 조건
## 코드 스타일
- 코드베이스의 기존 패턴을 따르세요
- 제출 전 `make lint`를 실행하세요
- 새로운 기능에 대한 테스트를 포함하세요
- 자명하지 않은 설계 결정은 주석으로 문서화하세요
## 커뮤니티
질문하고, 기법을 공유하고, 팀과 소통하세요.
버그 보고, 기능 요청, 로드맵 추적.
아키텍처, 전략, 아이디어에 대한 심도 있는 대화.
## 라이선스
Decepticon은 [Apache-2.0](https://github.com/BitterSecurity/Decepticon/blob/main/LICENSE) 라이선스 하에 배포됩니다. 기여함으로써 여러분의 기여가 동일한 조건으로 라이선스됨에 동의합니다.
---
## File: ko/contributing/developer-setup.mdx
[Binary file]
---
## File: ko/features/autonomous-execution.mdx
---
title: "자율 실행 (Autonomous Execution)"
---
## 킬 체인 오케스트레이션
OPPLAN이 생성되면 Decepticon의 오케스트레이터가 인수합니다. 정찰, 익스플로잇, 권한 상승, 측면 이동, 지속성에 이르는 전체 킬 체인을 자율적으로 반복 실행합니다.
이것은 선형적인 스크립트가 아닙니다. 오케스트레이터는 각 에이전트가 발견한 내용을 바탕으로 실시간으로 적응합니다.
## 실행 루프
오케스트레이터가 OPPLAN에서 다음 대기 중인 목표를 선택하고, 의존성을 해결하며 킬 체인 단계에 따라 우선순위를 결정합니다.
목표 세부 정보, RoE 가드레일, 사용 가능한 스킬, 이전에 완료된 목표의 관련 발견 사항으로 프롬프트를 구성합니다.
**클린 컨텍스트 윈도우**를 가진 새 에이전트 인스턴스가 생성됩니다. 이전 목표에서 축적된 노이즈 없이 — 매번 새로운 추론을 수행합니다.
에이전트가 Kali 샌드박스 내에서 사용 가능한 도구와 스킬을 활용해 목표를 실행합니다. 모든 명령은 대화형 프롬프트 감지 기능이 있는 영속적 tmux 세션 내에서 실행됩니다.
오케스트레이터가 에이전트의 `PASSED` / `BLOCKED` 시그널을 파싱하고, 목표 상태를 업데이트하며, 발견 사항을 디스크에 추가합니다.
다음 목표로 이동합니다. 완료된 목표의 발견 사항이 후속 에이전트에 정보를 제공하여 다단계 공격 체인을 가능하게 합니다.
## 목표별 클린 컨텍스트
이것은 핵심적인 설계 결정입니다. 각 에이전트는 목표마다 클린 컨텍스트 윈도우로 스폰됩니다 — 긴 인게이지먼트에 걸친 컨텍스트 열화(Context Degradation)를 방지합니다.
이것이 왜 중요한가:
- **축적된 노이즈 없음** — 인게이지먼트가 진행되어도 에이전트의 추론 품질이 저하되지 않습니다
- **클린 상태** — 각 목표는 이전 단계의 불필요한 컨텍스트 없이 온전한 주의를 받습니다
- **영속적 발견 사항** — 결과는 에이전트 메모리가 아닌 디스크에 저장됩니다. 오케스트레이터는 각 새 에이전트의 컨텍스트에 관련된 이전 발견 사항만 주입합니다
## 대화형 셸 세션
실제 오펜시브 보안 도구들은 대화형입니다 — `sliver-client`, `msfconsole`, `evil-winrm`, `sqlmap`, `impacket-psexec`. 이 도구들은 단순히 명령을 받고 종료하지 않습니다. 프롬프트를 띄우고 대화를 기대합니다.
대부분의 AI 에이전트는 이를 처리하지 못합니다. `subprocess.run()`으로 원샷 명령을 실행하고 끝내버립니다.
Decepticon은 자동 프롬프트 감지 기능이 있는 **영속적 tmux 세션** 내에서 모든 명령을 실행합니다:
- 도구가 대화형 프롬프트(`sliver >`, `msf6 >`, `PS C:\>`)를 표시하면, 에이전트가 이를 감지하고 후속 명령을 전송합니다
- **병렬 네임드 세션** — 여러 도구 세션이 동시에 실행됩니다
- **제어 시그널** — 대화형 프로세스 관리를 위한 `C-c`, `C-z` 지원
- **지연 감지** — 명령이 멈출 때를 인식하고 교정 조치를 취합니다
에이전트가 실제로 도구를 *조작*합니다 — 인간 오퍼레이터가 하는 것과 동일한 방식으로.
## 백그라운드 명령 & 자동 알림
일부 명령은 수 분이 걸립니다 — `nmap -p- -A`, 전체 Burp 스캔, 장시간 동작하는 퍼저. LLM이 10분간 프롬프트에서 대기하는 것은 컴퓨트와 턴의 낭비입니다. 에이전트는 대신 백그라운드로 시작하고 다른 작업으로 넘어갑니다:
```
bash(
command="nmap -p- -A target.lan -oN scan.txt",
run_in_background=True,
session="scan-1",
)
→ { "status": "started", "session": "scan-1" }
```
스캔이 도는 동안 에이전트는 다른 표면을 정찰하고, 다음 목표를 계획하고, 지식 그래프를 쿼리합니다. 스캔이 끝나면 `SandboxNotificationMiddleware`가 **출력을 자동으로 캡처해 다음 추론 턴에 주입**합니다:
```
턴 N: bash(..., run_in_background=True) → "started" 반환
턴 N+1: 다른 작업 수행
턴 N+2: 진입 시 다음을 봅니다:
Background command in session scan-1 finished (exit 0).
Output (2.4K):
Nmap scan report for target.lan ...
```
`bash_output()` 폴링 없음. 유휴 "끝났나?" 턴 없음. 에이전트가 명령의 존재를 기억할 필요도 없습니다 — 완료가 에이전트로 옵니다. 이것은 [동적 인프라](/ko/features/dynamic-infrastructure)의 워크로드 상태 알림을 구동하는 동일한 패턴입니다.
### 출력 계층화
장시간 명령은 많은 출력을 생성합니다. 샌드박스는 에이전트 컨텍스트 윈도우를 사용 가능한 상태로 유지하기 위해 출력을 계층화합니다:
| 분량 | 처리 |
|------|------|
| **≤ 15 KB** | 알림/도구 결과에 인라인. |
| **15 KB – 100 KB** | `/workspace/.scratch/`에 기록되고 경로 + 요약만 인라인. 에이전트가 필요할 때 파일을 읽음. |
| **> 5 MB** | 폭주 세션을 죽이고 명령을 다듬도록 에이전트에 통지(범위 축소, 출력 필터). |
ANSI 스트리핑 및 반복 라인 압축과 결합되어, 장시간 인게이지먼트에서도 토큰 지출이 예측 가능하게 유지됩니다.
## RoE 강제
모든 반복에서 오케스트레이터는 다음 행동이 교전 규칙의 범위 내에 있는지 검증합니다. 목표가 RoE에 정의된 범위, 시간, 또는 기법 경계를 위반할 경우, 자동으로 차단됩니다.
ATT&CK 매핑된 역량으로 에이전트를 무장시키는 프로그레시브 스킬 시스템을 알아보세요.
---
## File: ko/features/benchmark-evaluation.mdx
[Binary file]
---
## File: ko/features/c2-integration.mdx
---
title: "C2 통합 (C2 Integration)"
---
## 개요
Decepticon은 **Sliver C2**를 커맨드 앤 컨트롤 프레임워크로 통합하여, 실제 적대적 수준의 포스트 익스플로잇을 가능하게 합니다: 임플란트 배포, 세션 관리, 크리덴셜 수집, C2 채널을 통한 측면 이동.
C2는 사후에 덧붙여진 것이 아닙니다 — 작전 네트워크 아키텍처의 핵심 구성 요소입니다.
## C2 활성화
Sliver C2는 Docker Compose 프로파일을 통해 활성화됩니다:
```bash
COMPOSE_PROFILES=c2-sliver decepticon
```
이 명령은 Kali 샌드박스 및 타겟 인프라와 함께 작전 네트워크(`sandbox-net`)에 Sliver 팀 서버를 추가합니다.
## 아키텍처
```
┌─────────────────────────────────────────────────┐
│ sandbox-net (작전) │
│ │
│ ┌──────────┐ ┌──────────┐ ┌───────────────┐ │
│ │ Kali │ │ Sliver │ │ 타겟 │ │
│ │ 샌드박스 │←→│ 팀 서버 │←→│ 인프라 │ │
│ └──────────┘ └──────────┘ └───────────────┘ │
│ ↑ │
│ sliver-client │
│ (사전 설치됨) │
└─────────────────────────────────────────────────┘
```
C2 팀 서버는 전적으로 작전 네트워크에서 실행됩니다 — 관리 인프라와 완전히 격리되어 있습니다. C2 트래픽은 네트워크 경계를 넘지 않습니다.
## 기능
### 임플란트 생성 및 배포
에이전트가 타겟 환경에 맞춤화된 Sliver 임플란트를 생성하고 확보된 접근 경로를 통해 배포합니다:
- **플랫폼** — Windows, Linux, macOS
- **형식** — 셸코드, 실행파일, 공유 라이브러리
- **회피** — 난독화, 커스텀 빌드
### C2 채널
다양한 통신 채널을 지원합니다:
| 채널 | 용도 | 은닉 수준 |
|------|------|----------|
| **mTLS** | 기본값 — 암호화, 안정적 | 중간 |
| **HTTPS** | 일반 웹 트래픽에 혼합 | 높음 |
| **DNS** | DNS 쿼리를 통한 터널링 | 매우 높음 |
### C2 세션을 통한 포스트 익스플로잇
임플란트가 세션을 수립하면, 포스트 익스플로잇 에이전트가 이를 통해 작동합니다:
- **크리덴셜 수집** — 침해된 호스트에서 크리덴셜, 토큰, 키를 덤프
- **측면 이동** — 수립된 C2 세션을 통해 내부 시스템으로 피벗
- **내부 정찰** — 경계 내부에서 네트워크를 매핑하고, 서비스를 열거하며, 새로운 타겟을 발견
- **지속성** — 장기 접근 메커니즘 수립
## 프로파일 기반 설정
C2 프레임워크는 Docker Compose 프로파일을 통해 교체 가능합니다. **현재 Sliver만 구현되었으며 배포되고 있습니다** — 프로파일 시스템은 추가 프레임워크(Havoc, Mythic 등)를 나중에 플러그인할 수 있도록 설계되었지만, 그들은 아직 이용 불가능합니다:
```bash
# Sliver C2 — 유일하게 지원되는 프레임워크 (기본값)
COMPOSE_PROFILES=c2-sliver
# 향후 릴리스를 위한 계획 (아직 이용 불가능):
# COMPOSE_PROFILES=c2-havoc
# COMPOSE_PROFILES=c2-mythic
```
C2 트래픽을 관리 영역과 분리하는 격리된 네트워크 아키텍처를 알아보세요.
---
## File: ko/features/dynamic-infrastructure.mdx
[Binary file]
---
## File: ko/features/engagement-planning.mdx
---
title: "인게이지먼트 계획 (Engagement Planning)"
---
## 개요
모든 전문적인 레드팀 인게이지먼트는 익스플로잇이 아닌 **문서화**에서 시작됩니다. Decepticon은 **Soundwave** 에이전트를 통해 이를 강제합니다. Soundwave는 오퍼레이터를 인터뷰하고, 어떠한 공격 행위가 시작되기 전에 완전한 인게이지먼트 패키지를 생성합니다.
적절한 문서화 없이는 어떤 인게이지먼트도 실행되지 않습니다. 이것이 전문적인 레드팀 플랫폼과 스크립트 키디의 장난감을 구분하는 기준입니다.
## Soundwave 에이전트
Soundwave는 Decepticon의 인게이지먼트 계획 전문가입니다. 대화형 인터뷰를 통해 다음을 생성합니다:
범위, 시간, 경계를 정의합니다. 무엇을 건드릴 수 있고 없는지. 이를 위반하면 레드팀이 아니라 범죄자입니다.
위협 행위자 프로파일, 공격 방법론, "우리가 누구를 모방하는가"를 정의하는 문서. 초기 접근 벡터와 TTP를 MITRE ATT&CK ID로 정의합니다.
레드팀 활동과 실제 위협을 분리합니다. 소스 IP, 유저 에이전트, 시간대, SOC와의 실시간 디컨플릭션 콜을 위한 공유 코드를 포함합니다.
전체 임무 계획. 목표, 킬 체인 단계, 수락 기준. 모든 행동은 목적에 매핑됩니다.
## 작동 방식
Soundwave가 구조화된 인터뷰를 수행합니다: 타겟 범위, 위협 모델, 승인된 기법, 시간 제약, 성공 기준.
인터뷰를 바탕으로 Soundwave가 완전한 인게이지먼트 패키지를 생성합니다 — RoE, ConOps, 디컨플릭션 플랜, OPPLAN.
각 OPPLAN 목표에는 MITRE ATT&CK 기법 ID, 킬 체인 단계, 수락 기준이 태그됩니다. 이것들이 자율 실행 루프에 직접 투입됩니다.
교전 규칙은 자율 루프의 모든 반복에서 강제됩니다. 에이전트는 정의된 경계 밖에서 작동할 수 없습니다.
## OPPLAN 구조
OPPLAN은 자율 실행을 구동하는 핵심 문서입니다. 각 목표는 다음을 포함합니다:
```
Objective: 외부 노출 웹 애플리케이션 침해
Phase: Initial Access
MITRE ATT&CK: T1190 (Exploit Public-Facing Application)
Acceptance Criteria: 웹 서버에서 원격 코드 실행 달성
Dependencies: 정찰 목표 완료
Status: PENDING
```
목표는 상태 전이를 통해 추적됩니다: `PENDING` → `IN_PROGRESS` → `PASSED` / `BLOCKED`. 오케스트레이터가 의존성을 관리하고 결과에 따라 공격 경로를 적응시킵니다.
오케스트레이터가 자율 킬 체인을 통해 OPPLAN 목표를 실행하는 방법을 알아보세요.
---
## File: ko/features/knowledge-graph.mdx
[Binary file]
---
## File: ko/features/multi-model-routing.mdx
---
title: "멀티 모델 라우팅 (Multi-Model Routing)"
---
## 개요
모든 에이전트 작업에 가장 강력한 모델이 필요한 것은 아닙니다. Decepticon은 **LiteLLM**을 프록시 레이어로 사용하여, 에이전트 역할별로 서로 다른 모델 티어에 라우팅합니다 — 비용, 속도, 역량의 균형을 최적화합니다.
## 모델 프로파일
세 가지 내장 프로파일이 각기 다른 용도에 최적화되어 있습니다:
| 프로파일 | 오케스트레이터 | 익스플로잇 | 정찰 | 용도 |
|---------|-------------|---------|------|------|
| **eco** | Opus 4.7 | Sonnet 4.6 | Haiku 4.5 | 프로덕션 — 최상의 비용/성능 비율 (기본값) |
| **max** | Opus 4.7 | Opus 4.7 | Sonnet 4.6 | 고가치 타겟 — 최대 성능 |
| **test** | Haiku 4.5 | Haiku 4.5 | Haiku 4.5 | 개발/CI — 빠른 반복 |
제공자별 전체 티어당 모델 매트릭스:
| 티어 | Anthropic API | Anthropic OAuth | OpenAI | Google | MiniMax |
|---|---|---|---|---|---|
| **HIGH** | claude-opus-4-7 | auth/claude-opus-4-7 | gpt-5.5 | gemini-2.5-pro | MiniMax-M2.5 |
| **MID** | claude-sonnet-4-6 | auth/claude-sonnet-4-6 | gpt-5.4 | gemini-2.5-flash | MiniMax-M2.5-lightning |
| **LOW** | claude-haiku-4-5 | auth/claude-haiku-4-5 | gpt-5-nano | gemini-2.5-flash-lite | — |
대부분의 인게이지먼트에서는 **eco** 프로파일을 권장합니다. 오케스트레이터는 깊은 추론이 필요하지만(Opus), 정찰 작업은 더 빠르고 저렴한 모델로도 충분합니다.
## 역할 기반 라우팅
각 에이전트 역할은 서로 다른 인지적 요구사항을 가집니다:
목표 시퀀싱, 의존성 해결, 공격 경로 적응을 위한 깊은 추론이 필요합니다. 가장 역량 있는 모델에 라우팅됩니다.
취약점 익스플로잇 및 도구 조작을 위한 강력한 기술적 추론이 필요합니다. 중상위 티어에 라우팅됩니다.
포트 스캔, 서비스 열거, 출력 파싱 등 구조화된 작업을 처리합니다. 더 빠른 모델로도 잘 작동합니다.
C2 세션을 통한 복잡한 포스트 익스플로잇. 익스플로잇 티어와 유사하게 라우팅됩니다.
## 자동 폴백
각 티어는 제공자별 폴백 체인을 가지고 있습니다. 기본 프로바이더가 레이트 리밋에 걸리거나 장애가 발생하면, Decepticon이 원활하게 전환합니다:
```
HIGH: Opus 4.7 → GPT-5.5 → Gemini 2.5 Pro → MiniMax-M2.5
MID: Sonnet 4.6 → GPT-5.4 → Gemini 2.5 Flash → MiniMax-M2.5-lightning
LOW: Haiku 4.5 → GPT-5-nano → Gemini 2.5 Flash-Lite
```
제공자 순서는 `DECEPTICON_AUTH_PRIORITY` 환경 변수를 통해 구성 가능합니다 (예: `anthropic_oauth,anthropic_api,openai_api,google_api,minimax_api`). 전환은 투명합니다 — 수동 개입 없이, 작전이 중단되지 않습니다.
## 프로바이더 지원
LiteLLM 호환 모든 백엔드가 작동합니다:
- **Anthropic** — Claude Opus 4.7, Sonnet 4.6, Haiku 4.5 (API 키 또는 Claude OAuth 구독)
- **OpenAI** — GPT-5.5, GPT-5.4, GPT-5-nano
- **Google** — Gemini 2.5 Pro / Flash / Flash-Lite
- **MiniMax** — MiniMax-M2.5 및 M2.5-lightning
- **자체 호스팅** — vLLM, Ollama, 또는 OpenAI 호환 엔드포인트
`decepticon onboard`나 환경 변수를 통해 설정하세요. 자세한 내용은 [설정](/ko/getting-started/configuration)을 참조하세요.
---
## File: ko/features/offensive-vaccine-pipeline.mdx
---
title: "오펜시브 백신 파이프라인"
---
아래에 설명된 **5단계 Vulnresearch 파이프라인**은 오늘 출시된 상태이며, `Vulnresearch` 조율자와 그 5개의 서브 에이전트가 구동합니다. 루프를 닫는 **방어 측 절반** ("Defender" 에이전트, 자동 완화 백엔드, 재공격 검증)은 현재 코드베이스에 활성 구현되지 않은 **계획된 제품 방향**입니다. 이전 Defender 그래프와 Docker 방어 백엔드는 제거되었고, 향후 구현은 OPPLAN 미들웨어 위에 재구축될 예정입니다. 자세한 내용은 repo의 [`docs/offensive-vaccine.md`](https://github.com/BitterSecurity/Decepticon/blob/main/docs/offensive-vaccine.md) 참조.
**오펜시브 백신**은 Decepticon에 이름과 목적을 부여하는 루프입니다: 모든 오펜시브 행동이 방어적 산출물이 됩니다. 이 페이지는 오늘 출시된 5단계 Vulnresearch 파이프라인과, 향후 루프를 종료할 계획된 방어 측 컴포넌트를 문서화합니다.
## 루프
```
공격 → 탐지 규칙 → 검증 → 익스플로잇 PoC → 패치
↑ │
└───────────────────────────────────────────────────────┘
회귀 테스트 커버리지
```
각 단계는 전문가 에이전트가 소유합니다. 함께 보안 산업이 "퍼플 팀 활동"이라고 부르는 것을 완전히 자동화합니다.
## 5단계
타겟 전체의 자동 취약점 스캔. 출력: 후보 발견 (CVE 매치, 설정 문제, 노출된 표면).
후보 취약점의 탐지 신호 생성 — Sigma 규칙, YARA 규칙, IDS 서명 또는 텔레메트리 기반 휴리스틱. 방어자들은 탐지하기 전에 무엇을 찾아야 할지 알아야 합니다.
2-메서드 게이트: 최소 2가지의 독립적인 검증 기법을 통해 취약점 확인. 익스플로잇 작업을 시작하기 전에 거짓 양성을 제거합니다.
취약점을 애플리케이션을 깨지 않고 닫는 최소 패치 — 코드 변경, 설정 변경, 보상 통제 — 를 생성하고, `patch_verify`로 패치가 버그를 닫았음을 증명합니다. PoC 이전 패치는 offensive-vaccine 역전 — 방어자의 diff가 테스트 대상이 됩니다.
패치된 후보를 대상으로 재현 가능한 PoC를 작성합니다. PoC가 패치된 코드에 대해 성공하면 패치가 불완전하므로 루프가 반복되고, PoC가 실패하면 패치가 견고했음을 입증합니다.
## Vulnresearch 오케스트레이터
5개의 에이전트는 고정 파이프라인으로 실행되지 않습니다 — 발견 사항을 기반으로 순서를 결정하는 6번째 에이전트 **Vulnresearch**에 의해 오케스트레이션됩니다. Scanner가 높은 신뢰도의 후보를 생성하면, Vulnresearch는 Verifier로 직접 스킵할 수 있습니다. Verifier가 후보를 거부하면, Patcher나 Exploiter 리소스를 낭비하지 않고 루프는 종료됩니다.
| 에이전트 | 입력 | 출력 |
|---|---|---|
| **Scanner** | 타겟 범위 | 후보 발견 목록 |
| **Detector** | 후보 발견 | 탐지 규칙 (Sigma / YARA / 휴리스틱) |
| **Verifier** | 후보 + 탐지 규칙 | 검증됨-예 또는 검증됨-아니요, 2가지 증거 방법 포함 |
| **Patcher** | 검증된 후보 | 패치 (코드 또는 설정) + 패치가 버그를 닫았음을 증명하는 `patch_verify` |
| **Exploiter** | 패치된 후보 | 패치에 대한 재현 가능한 PoC — 패치가 견고하면 *실패*, 패치가 불완전하면 *성공* (루프 반복) |
## 계획된 방어 컴포넌트
이 컴포넌트는 현재 코드베이스에 구현되어 있지 않습니다 — 이전 Defender 그래프와 Docker 방어 백엔드는 제거되었고, 향후 대체는 OPPLAN 미들웨어와 전용 백신 개념 위에 재구축될 예정입니다. 오늘은 Vulnresearch 파이프라인의 산출물(탐지 규칙, PoC, 패치)이 워크스페이스와 지식 그래프에 영속화되며, 사람 운영자가 이를 블루팀에 전달합니다.
계획된 방어 종결 컴포넌트는 5단계 파이프라인의 일부가 *아닙니다* — 산출물을 소비하는 병렬 에이전트로 의도되어 있으며 **방어 브리프**를 생성하도록 설계되어 있습니다: 작전 최종 보고에서 블루팀에 전달되는 문서.
계획된 방어 브리프에는:
- 사용된 기법 (MITRE ATT&CK ID)
- Detector가 생성한 탐지 규칙
- Exploiter가 생성한 PoC
- Patcher의 권장 패치
- 검증 상태 (패치가 PoC를 깨뜨렸나요?)
- 블루팀의 기존 탐지 커버리지로의 매핑 (갭)
이것은 결국 오펜시브 작전을 방어적 개선으로 변환할 산출물입니다. 이 컴포넌트가 도착할 때까지는 운영자가 워크스페이스 출력에서 브리프를 수동으로 조립합니다.
## 2-메서드 검증이 중요한 이유
단일 검증 방법은 속일 수 있습니다 — 네트워크 스캔은 취약한 코드가 도달 가능하지 않아도 배너와 일치할 수 있습니다; PoC는 허니팟에 대해 성공할 수 있습니다. Verifier는 **2가지 독립적인 메서드**를 요구합니다. 예:
- 정적 증거 (버전 배너) + 동적 증거 (PoC 페이로드 응답)
- 네트워크측 탐지 (IDS 발화) + 호스트측 탐지 (프로세스 아티팩트)
- 소스 코드 분석 + 런타임 계측
Decepticon은 2-메서드 게이트 없이 발견을 Patcher / Exploiter 단계로 escalate하지 않습니다. 이는 작전 기록의 낭비된 계산과 거짓 경보를 대폭 감소시킵니다.
## 지식 그래프 통합
파이프라인이 생성한 모든 산출물은 **Neo4j 공격 그래프**에 도착합니다:
- 발견은 `Vulnerability` 노드가 됩니다
- 탐지 규칙은 `DETECTS` 에지를 가진 `DefenseAction` 노드가 됩니다
- 패치는 `MITIGATES` 에지를 가진 `DefenseAction` 노드가 됩니다
- 검증은 프로비넌스 에지가 됩니다
그래프는 작전 중에 쿼리 가능하고 작전 산출물로 내보낼 수 있습니다.
발견, 탐지 및 패치가 Neo4j 공격 그래프에 어떻게 도착하는지.
각 파이프라인 단계는 `skills/scanner/`, `skills/detector/` 등의 전용 스킬 세트를 가집니다.
---
## File: ko/features/opplan-system.mdx
---
title: "OPPLAN 시스템"
---
**OPPLAN**(작전 계획, Operations Plan)은 인간의 의도와 자율적 실행을 연결하는 다리입니다. 오케스트레이터가 스케줄링하는 단일 정보 소스이며, 전문가 에이전트가 소비하고, 운영자가 승인합니다. OPPLAN 없이는 Decepticon이 실행되지 않습니다.
## OPPLAN이란
OPPLAN은 구조화된 **목표 목록**입니다 — 각각 킬 체인 단계, MITRE ATT&CK ID, OPSEC 수준, C2 티어, 의존성 및 수용 기준으로 태그됩니다. Soundwave 에이전트가 운영자 인터뷰에서 생성하고, Decepticon 오케스트레이터가 실행하며, 운영자는 언제든 편집할 수 있습니다.
```yaml
- id: obj-001
phase: RECON
title: "타겟 서브넷의 노출된 서비스 식별"
mitre_attack: [T1595, T1592]
opsec_level: low
c2_tier: null # 정찰에서는 해당 없음
dependencies: []
acceptance:
- "호스트당 개방 포트 및 서비스 목록"
- "서비스 배너 캡처됨"
status: pending
- id: obj-002
phase: INITIAL_ACCESS
title: "10.0.2.4의 vsftpd 2.3.4 익스플로잇"
mitre_attack: [T1190]
opsec_level: medium
c2_tier: short_haul
dependencies: [obj-001]
acceptance:
- "타겟의 초기 접근 셸"
- "Sliver를 통해 임플란트 배포됨"
status: pending
```
## OPPLAN 미들웨어
오케스트레이터는 OPPLAN을 대화 컨텍스트에 저장하지 않습니다 — 구조화된 도구를 노출하고 모든 LLM 호출에 현재 상태를 주입하는 전용 미들웨어(`OPPLANMiddleware`)에 있습니다.
### CRUD 도구
오케스트레이터와 Soundwave는 5개의 전용 도구를 통해 OPPLAN을 조작합니다:
| 도구 | 목적 |
|---|---|
| `add_objective` | 전체 스키마를 사용하여 새 목표 추가 |
| `get_objective` | ID로 단일 목표 검색 |
| `list_objectives` | 모든 목표를 나열하며, 선택적으로 단계나 상태로 필터링 |
| `update_objective` | 목표의 상태, 증거 또는 필드 변경 |
| `objective_expand` | 목표를 하위 목표로 분해 (PTT — Pentesting Task Tree) |
이는 Claude Code의 V2 작업 시스템이 사용하는 것과 동일한 구조적 패턴입니다 — 작업 상태는 메시지 스레드가 아닌 타입 객체입니다.
### 동적 상태 주입
모든 LLM 호출에서 미들웨어는 현재 OPPLAN 상태 — 어떤 목표가 대기 중, 진행 중 또는 완료된 상태 — 를 직접 시스템 프롬프트 블록에 주입합니다. 오케스트레이터는 채팅 기록에서 계획 상태를 다시 유도할 필요가 없습니다. 이것이 Decepticon의 추론이 긴 작전 기간에 걸쳐 강력한 이유입니다.
## 의존성 해결
목표는 의존성을 선언할 수 있습니다. 오케스트레이터는 의존성이 `complete`인 목표만 스케줄합니다. 이는 운영자에게 워크플로우를 손으로 코딩하지 않고도 결정론적 실행 순서를 제공합니다:
```text
obj-001 (정찰)
└─ obj-002 (익스플로잇, obj-001에 의존)
└─ obj-003 (포스트-익스플로잇, obj-002에 의존)
└─ obj-004 (지속성, obj-002에 의존)
```
`obj-002`가 완료되면, `obj-003`과 `obj-004` 모두 적격이 되며 — 오케스트레이터는 이들을 위해 전문가 에이전트를 병렬로 스폰할 수 있습니다.
## Pentesting Task Tree (PTT)
복잡한 목표의 경우, 오케스트레이터는 `objective_expand`를 통해 단일 목표를 하위 목표의 트리로 확장할 수 있습니다. 이는 Decepticon이 *"Active Directory 포리스트 공략"*과 같은 "모호한" 목표를 처리하는 방법입니다 — AD 오퍼레이터 에이전트가 실행할 수 있는 구체적인 하위 목표로 동적으로, 비행 중에 분해합니다.
```text
obj-005: AD 포리스트 공략 (부모)
├─ obj-005.1: BloodHound을 통해 도메인 열거
├─ obj-005.2: Kerberoastable 계정 식별
├─ obj-005.3: TGT 해시 추출
└─ obj-005.4: 오프라인 해시 크래킹
```
각 자식은 부모의 RoE 제약과 ATT&CK 태그 집합을 상속받습니다.
## 승인 게이트
OPPLAN은 승인 계약입니다. Soundwave가 생성한 후, 운영자는 CLI를 통해 검토하고 승인합니다. 승인된 OPPLAN만 실행될 수 있습니다. 이는 **신뢰할 수 있는 에이전트** 핸드셰이크가 소프트웨어로 인코딩된 것입니다.
작전 범위, 목표, 타겟, 위협 프로파일.
구조화된 문서, 작전 워크스페이스에 작성됨.
운영자가 각 목표를 검사합니다; 승인이 주어질 때까지 에이전트는 중단됩니다.
Decepticon 에이전트가 OPPLAN을 읽고, 목표를 순서화하며, 전문가를 스폰합니다.
CLI 명령을 통해 목표를 추가, 제거 또는 업데이트합니다. 다음 반복에서 변경 사항이 반영됩니다.
## OPPLAN과 신선한 컨텍스트
각 목표는 **신선한 에이전트 인스턴스**로 실행되며 깨끗한 컨텍스트 윈도우를 가집니다. 오케스트레이터는 관련된 이전 발견을 명시적으로 전달합니다 — 전체 대화 기록이 아닙니다. 이는 200개 목표 작전이 컨텍스트 열화를 일으키지 않는다는 의미입니다.
Soundwave가 초기 OPPLAN 초안을 생성하는 방법.
오케스트레이터가 OPPLAN 목표를 어떻게 스케줄링하고 디스패치하는지.
---
## File: ko/features/skill-system.mdx
[Binary file]
---
## File: ko/getting-started/configuration.mdx
---
title: "설정 (Configuration)"
---
## API 키 설정
Decepticon의 에이전트를 구동하려면 LLM API 키가 필요합니다. 대화형 설정 마법사를 실행하세요:
```bash
decepticon onboard # 기본 설정 흐름
decepticon onboard --reset # 처음부터 다시 설정
```
### 지원 프로바이더
Decepticon은 **LiteLLM**을 모델 프록시로 사용하며, 호환되는 모든 백엔드를 지원합니다:
| 프로바이더 | 모델 | 비고 |
|-----------|------|------|
| **Anthropic API** | Claude Opus, Sonnet, Haiku | 최상의 성능을 위해 권장 |
| **Anthropic OAuth** | 동일 모델, Claude 구독을 통해 | Claude Code OAuth 크리덴셜 사용 |
| **OpenAI** | GPT-5.5, GPT-5.4, GPT-5-nano | 자동 폴백과 함께 완전 지원 |
| **Google** | Gemini 2.5 Pro / Flash / Flash-Lite | LiteLLM 프록시를 통해 지원 |
| **MiniMax** | MiniMax-M2.5, MiniMax-M2.5-lightning | 대체 상위/중위 티어 |
| **커스텀** | 모든 LiteLLM 백엔드 | 자체 호스팅 또는 대안 프로바이더 |
### 환경 변수
환경 변수를 통해서도 설정할 수 있습니다:
```bash
# 기본 프로바이더
export ANTHROPIC_API_KEY="sk-ant-..."
# 또는 OpenAI
export OPENAI_API_KEY="sk-..."
# 또는 커스텀 백엔드를 위한 LiteLLM 설정
```
## 모델 프로파일
Decepticon은 에이전트 역할별로 서로 다른 모델 티어에 라우팅하여 비용/성능의 최적 균형을 맞춥니다:
| 프로파일 | 오케스트레이터 | 익스플로잇 | 정찰 | 용도 |
|---------|-------------|---------|------|------|
| **eco** | Opus 4.7 | Sonnet 4.6 | Haiku 4.5 | 프로덕션 — 최상의 비용/성능 비율 (기본값) |
| **max** | Opus 4.7 | Opus 4.7 | Sonnet 4.6 | 고가치 타겟 — 최대 성능 |
| **test** | Haiku 4.5 | Haiku 4.5 | Haiku 4.5 | 개발/CI — 빠른 반복 |
각 프로파일에는 자동 폴백 체인이 포함되어 있습니다. 기본 프로바이더가 사용 불가하거나 레이트 리밋에 걸리면, Decepticon이 다음 프로바이더로 원활하게 전환합니다 (예: Opus 4.7 → GPT-5.5 → Gemini 2.5 Pro → MiniMax-M2.5).
`decepticon onboard` 실행 시 프로파일을 선택하거나 언제든 `DECEPTICON_MODEL_PROFILE` 환경 변수를 통해 변경할 수 있습니다. `eco` 프로파일이 기본값이며 대부분의 작전에서 권장됩니다.
## C2 설정
Sliver C2 통합은 Docker Compose 프로파일 방식으로 활성화됩니다. `COMPOSE_PROFILES` 환경 변수는 런처가 스택을 시작하기 전에 `.env` (또는 쉘)에서 읽히며, decepticon 명령어의 플래그가 아닙니다. Sliver는 기본적으로 활성화됩니다.
```bash
# .env (기본값)
COMPOSE_PROFILES=c2-sliver
# 또는 실행 시 쉘을 통해 재정의
COMPOSE_PROFILES=c2-sliver decepticon
```
활성화 시, Sliver 팀 서버가 작전 네트워크에서 다음과 함께 시작됩니다:
- 자동 생성된 오퍼레이터 설정
- 샌드박스에 사전 설치된 `sliver-client`
- mTLS, HTTPS, DNS C2 채널 지원
Sliver C2 통합 및 C2 채널 설정에 대해 더 자세히 알아보세요.
## Docker 리소스
Decepticon은 전적으로 Docker 컨테이너에서 실행됩니다. 권장 리소스 할당:
| 컴포넌트 | CPU | 메모리 | 비고 |
|---------|-----|--------|------|
| LangGraph Platform | 1 코어 | 1 GB | 관리 네트워크 — 에이전트 조율 |
| LiteLLM Proxy | 0.5 코어 | 512 MB | 관리 네트워크 |
| PostgreSQL | 0.5 코어 | 512 MB | 관리 네트워크 — 인게이지먼트 상태 |
| Neo4j | 1 코어 | 1 GB | 양 네트워크 연결 — 지식 그래프 |
| Web Dashboard | 0.5 코어 | 512 MB | 관리 네트워크 — Next.js |
| Kali Sandbox | 2 코어 | 4 GB | 작전 네트워크 — 오펜시브 도구 실행 |
| Sliver C2 | 1 코어 | 1 GB | 작전 네트워크 (기본 프로파일) |
Kali 샌드박스는 전체 오펜시브 툴킷을 실행하므로 가장 많은 리소스가 필요합니다. 복잡한 인게이지먼트의 안정적인 운영을 위해 최소 4 GB의 메모리를 할당하세요.
---
## File: ko/getting-started/library-usage.mdx
---
title: "라이브러리 · SDK 사용"
---
## PyPI 에서 설치
Decepticon 은 Python 패키지로 배포됩니다. 코어 SDK 를 설치하세요:
```bash
pip install decepticon # 코어 SDK
pip install "decepticon[neo4j]" # + 지식그래프 공격체인 도구
```
`decepticon` 은 **클라이언트 SDK** 이지 단독 실행 앱이 아닙니다. 에이전트
팩토리·미들웨어·도구·스킬을 담고 있지만, LLM 호출과 샌드박스 실행은
**런타임 서비스**로 HTTP 라우팅됩니다. 에이전트를 실제로 돌리려면 그
서비스들(Docker 스택 또는 직접 운영하는 엔드포인트)이 필요합니다.
## 두 개의 tier
| Tier | 무엇 | 배포 방식 |
|------|------|-----------|
| **SDK (이 패키지)** | `decepticon/` — 에이전트 팩토리·미들웨어·도구·backends·`llm` 팩토리·스킬(package data 로 동봉) | PyPI wheel — `pip install decepticon` |
| **런타임 서비스** | LiteLLM 프록시, Kali sandbox, PostgreSQL, Neo4j | GHCR Docker 이미지 + `docker compose` |
SDK 는 환경변수로 서비스에 연결됩니다:
- `DECEPTICON_LLM__PROXY_URL` — LiteLLM 프록시 (기본 `http://localhost:4000`)
- `SAAS_SANDBOX_URL` — sandbox HTTP 데몬 (예: `http://localhost:9999`)
턴키 로컬 스택은 [빠른 시작](/ko/getting-started/quick-start) 설치 스크립트를 쓰세요. pip 패키지는 **에이전트를 당신의 서비스에 임베드**하기 위한 것입니다.
## 미리 빌드된 에이전트 사용
```python
from decepticon.agents.standard.recon import create_recon_agent
agent = create_recon_agent() # 기본 OSS 구성
```
16개 에이전트 팩토리 각각은 langchain 스타일 키워드 오버라이드를 받습니다 — `tools=`, `middleware=`, `system_prompt=`, `llm=` 등.
## 플러그인 번들로 확장
포크 없이 상용 도구·미들웨어·프롬프트·서브에이전트를 얹으세요 — `decepticon.bundles` entry-point 에 `PluginBundle` 을 등록합니다:
```python
from decepticon.plugin_loader import PluginBundle
MY_BUNDLE = PluginBundle(
bundle="mybundle",
replaced_tools={"ask_user_question": my_ask_tool},
prompts={"recon": {"prepend": "..."}},
)
```
```toml
# 당신 패키지의 pyproject.toml
[project.entry-points."decepticon.bundles"]
mybundle = "my_pkg.bundles:MY_BUNDLE"
```
`DECEPTICON_PLUGINS=standard,mybundle` 로 활성화. 다운스트림 제품이 오픈 코어 위에 상용 기능을 얹는 방식이 정확히 이것입니다 — `decepticon` 에 *의존*할 뿐 포크하지 않습니다.
## 버전 관리
`pyproject.toml` 에 호환 범위를 핀:
```toml
dependencies = ["decepticon>=1.1,<2"]
```
전체 오버라이드 surface — 팩토리 kwargs, 선언적 `PluginBundle` 플러그인, 커스텀 오케스트레이터용 `build_middleware(slots=...)`, 안전 게이트 — 는 [`docs/library-usage.md`](https://github.com/BitterSecurity/Decepticon/blob/main/docs/library-usage.md) 에 문서화돼 있습니다.
---
## File: ko/getting-started/quick-start.mdx
---
title: "빠른 시작 (Quick Start)"
---
## 사전 요구사항
두 가지만 필요합니다:
- [Docker](https://docs.docker.com/get-docker/) (Docker Compose v2 포함)
- API 키 (Anthropic, OpenAI, 또는 LiteLLM 호환 프로바이더)
그게 전부입니다. 나머지는 모두 컨테이너 안에서 실행됩니다.
## 설치
```bash
curl -fsSL https://decepticon.red/install | bash
```
Decepticon 이미지를 다운로드하고, 격리된 네트워크 아키텍처를 구성하며, `decepticon` CLI를 설치합니다.
## 설정
API 키를 설정합니다:
```bash
decepticon config
```
대화형 설정 마법사에서 다음을 구성할 수 있습니다:
- **LLM 프로바이더** — Anthropic, OpenAI, 또는 기타 LiteLLM 백엔드
- **API 키** — 프로바이더 API 키
- **모델 프로파일** — `eco`, `max`, 또는 `test` ([멀티 모델 라우팅](/ko/features/multi-model-routing) 참조)
## 실행
Decepticon을 시작합니다:
```bash
decepticon
```
모든 서비스(에이전트 API, LiteLLM 프록시, 샌드박스, 데이터베이스)를 시작하고 대화형 CLI를 엽니다. 에이전트가 보는 것을 실시간으로 확인할 수 있는 스트리밍 인터페이스가 표시됩니다.
## 데모 실행
직접 인게이지먼트를 설정하기 전에 Decepticon의 동작을 먼저 확인하고 싶으신가요? 가이드 데모를 실행하세요:
```bash
decepticon demo
```
데모는 **Metasploitable 2**를 타겟으로 배포하고, 사전 구성된 인게이지먼트를 로드한 후, 전체 킬 체인을 자동으로 실행합니다:
정찰(Recon) 에이전트가 타겟을 스캔하고 열린 서비스를 식별합니다.
익스플로잇 에이전트가 vsftpd 백도어 취약점을 식별하고 공격합니다.
공격 성공 후 Sliver C2 임플란트를 타겟에 배포합니다.
포스트 익스플로잇 에이전트가 C2 세션을 통해 크리덴셜을 수집합니다.
침해된 호스트에서 내부 네트워크를 매핑합니다.
API 키 외에 추가 설정은 필요 없습니다.
## 다음 단계
API 키, 모델 프로파일, 환경 설정을 자세히 알아보세요.
사용 가능한 모든 명령어와 옵션을 확인하세요.
인게이지먼트 계획, 킬 체인 실행, C2 통합을 살펴보세요.
격리된 네트워크 아키텍처와 에이전트 시스템을 이해하세요.
---
## File: ko/introduction/history-and-evolution.mdx
---
title: "역사와 진화 (History & Evolution)"
---
Decepticon은 하루아침에 만들어진 것이 아닙니다. 오펜시브 시큐리티(Offensive Security)에 인공지능을 결합하고자 했던 수년간의 연구와 시행착오의 산물입니다. 우리가 과거에 시도했던 접근 방식들을 이해하면, 현재 Decepticon이 왜 대형 언어 모델(LLM) 기반의 자율형 **Autonomous Hacking Agent (자율 해킹 에이전트)**로 설계되었는지 그 철학적 배경을 알 수 있습니다.
Decepticon이 걸어온 진화의 이정표를 되짚어 보겠습니다.
## 2021년: 퍼플팀 AI (Purple Team AI)
초기 단계에서 이 프로젝트는 **퍼플팀 AI(Purple Team AI)**라는 컨셉에서 출발했습니다. 근본적인 아이디어는 공격과 방어 사이에 지속적이고 자동화된 피드백 루프를 구축하는 것이었습니다.
* **Red AI vs. Blue AI**: 우리는 서로 대립하는 두 개의 AI 모델을 구상했습니다. Red AI는 공격을 수행하고, Blue AI는 그 공격 벡터를 분석하여 패치를 발행합니다.
* **핵심 철학**: 보안은 정적인 상태가 아닙니다. 두 AI를 서로 경쟁시킴으로써, 이를 아우르는 전체 시스템(퍼플팀)은 시간이 지남에 따라 필연적으로 더욱 강력해진다는 철학이었습니다.
## 2022년: 강화학습 환경 (RL Environment)
추상적인 컨셉을 넘어 실제 네트워크 시뮬레이션 환경에 이를 적용하기 위해, 우리는 **강화학습(Reinforcement Learning, RL)**을 도입했습니다.
* **가상 네트워크 (Virtual Network)**: 시뮬레이션된 서버와 네트워크로 구성된 환경(Environment)을 구축했습니다.
* **에이전트 기반 학습 (Agent-Based Learning)**: 레드팀 AI(에이전트)가 "공격 요청(Attack Request)"을 보내면, 환경은 공격의 성공 여부에 따라 "초기 상태(next_state)" 혹은 "보상(Reward)"을 반환합니다.
* **한계점**: 체스나 바둑처럼 규칙이 명확한 게임에서 강화학습은 강력하지만, 현실 세계의 네트워크 환경과 문맥("Vibe")은 무한히 복잡합니다. 현존하는 수많은 사이버 공격 벡터 각각에 대해 정확한 보상 함수(Reward function)를 설계하는 것은 엄청난 병목(Bottleneck)이었습니다.
## 2023년: 적대적 생성 신경망 (GANs)
강대한 RL 환경 구축의 어려움을 깨닫고, 우리는 공격 데이터를 시뮬레이션하기 위해 **적대적 생성 신경망(GANs, Generative Adversarial Networks)**의 사용을 연구했습니다.
* **생성자 vs 판별자 (Generator vs. Discriminator)**: 이 아키텍처에서는 오펜시브 역할을 맡은 생성자(Generator)가 정상적인 네트워크 트래픽처럼 보이는 "가짜 데이터(공격 페이로드)"를 만들려고 시도합니다. 반대로 방어 역할을 맡은 판별자(Discriminator)는 실제 정상 트래픽과 악성 가짜 트래픽을 구분하려고 시도합니다.
* **한계점**: GAN은 서명 기반(Signature-based)의 웹 방화벽(WAF)을 우회하는 페이로드를 생성하는 데는 탁월했습니다. 하지만 **문맥에 대한 이해(Contextual understanding)**가 결여되어 있었습니다. 여러 단계에 걸친 복잡한 공격을 수행하거나, 서버의 응답을 읽고 방향을 틀어 동적으로 내부망을 탐색(Pivoting)하는 것은 불가능했습니다.
## 현재: Autonomous Hacking Agent (자율 해킹 에이전트)
이러한 일련의 뼈아픈 실패와 성공을 거치며, 우리는 진정한 오펜시브 역량은 단순한 수학적 최적화나 페이로드 생성을 넘어선다는 것을 깨달았습니다. 그것은 **추론(Reasoning)**을 필요로 합니다.
오늘날, Decepticon은 고도화된 대형 언어 모델(LLM)을 활용하여 자율적인 에이전트로 활동합니다. 더 이상 딱딱하게 굳어진 시뮬레이션 환경이나 통계적 분포에 의존하지 않고, 타겟의 "바이브(Vibe)"를 직접 읽어냅니다. 인간이 만든 시스템의 문맥을 이해하고, 복잡한 방어망에 적응하며, 실시간으로 여러 단계의 레드팀 오퍼레이션을 수행합니다.
---
## File: ko/introduction/overview.mdx
[Binary file]
---
## File: ko/introduction/pentesting-vs-redteaming.mdx
---
title: "모의해킹 vs 레드팀 테스팅"
---
**Autonomous Hacking Agent(자율 해킹 에이전트)**로서의 Decepticon의 정체성을 온전히 이해하기 위해서는, 취약점 평가(Vulnerability Assessment), 모의해킹(Penetration Testing), 레드팀 테스팅(Red Team Engagement)의 본질적인 차이를 명확히 아는 것이 필수적입니다. Decepticon은 마지막 학문의 방법론을 명확하게 지향하며, 그 위에 기계 속도의 네 번째 모드를 추가합니다.
## 세 가지 학문 분야
보안 테스팅 환경은 역피라미드 형태를 이룹니다: 넓은 기반의 취약점 평가(광범위하고 얕음), 중간의 모의해킹(표적화되고 깊음), 정점의 레드팀 테스팅(시나리오 기반, 조직 전체).
광범위한 공격 표면에서 기술적 결함을 식별합니다. 산출물: 목록.
그러한 결함을 악용하여 표적화된 범위 내에서 공격 경로를 증명합니다.
실제 적대자를 모방하여 방어팀을 훈련시키고 평가합니다.
## 나란히 비교
다음 틀은 [redteam.guide](https://redteam.guide/docs/Concepts/red-vs-pen-vs-vuln/)에서 발표한 표준 비교에 기반하고 있으며, Decepticon이 가능하게 하는 자율 에이전트 모드를 위한 네 번째 열로 확장되었습니다.
| 측면 | 취약점 평가 | 모의해킹 | 레드팀 테스팅 | 자율 레드팀 (Decepticon) |
|---|---|---|---|---|
| **목표** | 기술적 결함 식별 | 결함을 악용하여 공격 경로 증명 | 블루팀 효과성 훈련 및 평가 | AI 적대자에 대해 블루팀을 지속적으로 훈련 |
| **범위** | 넓고 얕음 | 표적화된 시스템 | 조직 전체 | 조직 전체, 프로그래밍 방식으로 확장 가능 |
| **초점** | 기술 | 기술 | 사람, 프로세스, 기술 | 사람, 프로세스, 기술 — OPPLAN에 의해 주도됨 |
| **기간** | 일 단위 | 1~2주 | 2~6주 | 시간에서 지속적 (기계 속도 루프) |
| **위협 모델** | CVE 기반 | 공격 표면 | 적대자 모방 | 적대자 모방, 인게이지먼트별 동적 |
| **위험 측정** | 공격 표면 감소 | 기술적 악용 영향 | 보안 운영 평가 | 운영 평가 + 시간 경과에 따른 회귀 커버리지 |
| **산출물** | 취약점 목록 | 악용 증거 및 공격 경로 | 보안 운영 평가 | OPPLAN 태그 지정 발견사항, 공격 그래프, 교정 패치 |
네 번째 열은 인간 레드팀의 대체물이 아닙니다. — 동일한 학문을 규모화한 것입니다. 인간이 교전 규칙을 설정하고, 목표를 정의하며, 발견사항을 판정합니다. Decepticon은 그 경계 내에서 킬 체인을 실행합니다.
## 전통적 모의해킹의 한계
전통적인 모의해킹은 웹, 모바일, 또는 외부 네트워크를 개별적으로 평가하는 데 중점을 둡니다.
- **사일로화된 평가**: 모의해킹은 단일 웹 앱의 SQL 인젝션을 찾을 수 있지만, 공격자가 그 웹 앱을 프록시로 사용하여 내부 네트워크로 피벗하는 것을 방어팀이 탐지할 수 있는지는 테스트하지 않습니다.
- **축구 비유**: 모의해킹은 슈팅, 패스, 드리블을 개별적으로 연습하는 것과 같습니다. 이러한 기술들은 필수적이지만, 실전 11대11 경기를 한 번도 하지 않고 4년을 개별 훈련만 해서는 월드컵에서 우승할 수 없습니다.
- **실제 한계**: 모의해킹은 조직의 전반적인 보안 통제, 블루팀, 프로세스가 실제 다단계 공격 중에 유기적으로 함께 작동하는지 테스트하지 못합니다.
## 레드팀 테스팅: "실전 경기"
레드팀 테스팅은 실제의 11대11 실전 연습 경기입니다. — 조직의 전체적인 방어 능력을 오랜 기간(일반적으로 4~8주) 동안 테스트하도록 설계된 포괄적인 적대적 시뮬레이션입니다.
### 레드팀 테스팅의 핵심 속성
1. **전체적이고 다중 도메인** — 실제 공격자들은 웹 앱만 공격하고 멈추지 않습니다. 그들은 클라우드, 모바일, 내부 네트워크, 심지어 물리적 또는 사회공학적 벡터를 연결합니다. 레드팀 테스팅이 이를 반영합니다.
2. **은닉과 지속성** — 주요 목표는 블루팀의 탐지를 피하는 것입니다. 레드팀 요원들은 조용히 작동하며, SIEMs과 EDRs를 회피하고, 오랜 기간 동안 접근을 유지(지속성)합니다.
3. **현실적인 목표** — CVE 나열 대신, 목표는 실질적입니다: *SWIFT 인프라에 접근할 수 있는가? 블루팀이 알아채지 못하는 동안 더미 고객 데이터를 유출할 수 있는가?*
4. **위협이 투표를 받는다** — 인게이지먼트는 방어자들이 계획한 것뿐만 아니라 실제 위협이 실제로 수행하는 것에 기반합니다. 위협 프로필이 TTPs를 주도합니다.
5. **가정된 침투** — 초기 접근(예: 피싱)이 차단되면, 레드팀 요원들은 "가정된 침투" 시나리오로 전환합니다: 비콘이 내부적으로 심어져 침투 후 대응, 횡적 이동 탐지, 내부 정찰을 평가합니다.
## 인게이지먼트 라이프사이클: 진입, 잔류, 행동
레드팀 인게이지먼트는 세 가지 단계를 따릅니다. — redteam.guide 방법론에서 광범위하게 사용되고 성문화된 모델:
위협 프로필이 선호하는 벡터를 통한 초기 접근 — 피싱, 노출된 서비스, 공급망, 사회공학. 목표는 흔적이지, 소음이 아닙니다.
지속성과 명령-통제 수립. 티어 C2 채널(대화형 / 단거리 / 장거리). OPSEC 유지. 방어자 대응에서 생존.
인게이지먼트 목표 실행 — 권한 상승, 횡적 이동, 자격증명 접근, 데이터 발견, 유출, 작전 영향 — 동시에 임무에 충실하고 교전 규칙 내에서.
## Decepticon이 자율 해킹 에이전트인 이유
Decepticon은 모의해킹 체크리스트가 아니라 **레드팀 테스팅** 마인드셋을 자동화합니다. 네트워크를 자동화된 스캐너로 폭주시키지 않습니다. — 이는 블루팀을 즉시 경고합니다.
대신, 환경의 맥락을 읽습니다. 은닉을 유지하고, 내부 정찰을 수행하고, 횡적 이동을 실행하고, 가정된 침투 시나리오를 자율적으로 시뮬레이션합니다. 킬 체인은 **OPPLAN** — 운영자의 RoE와 ConOps에서 단일 패킷이 나가기 전에 에이전트가 생성하는 구조화된 작전 계획에 의해 주도됩니다.
무정하고 AI 기반의 레드팀 역할을 맡음으로써, Decepticon은 무한한 공격 피드백을 제공합니다. 이것이 [공격 백신](/ko/introduction/overview#the-motivation-an-offensive-vaccine)입니다. — 오래된 소프트웨어의 체크리스트를 제공하기보다는, 현대적 사이버 위협의 유기적이고 은닉된 현실에 대항하여 방어 시스템을 훈련시킵니다.
진입, 잔류, 행동 — 세 단계 라이프사이클, Decepticon의 에이전트에 매핑됨.
전술, 기법, 절차 — 위협과 Decepticon 사이의 공유 어휘.
Decepticon이 위협 프로필을 실행 가능한 인게이지먼트로 변환하는 방법.
레드 세포, 블루 세포, 화이트 세포, 신뢰할 수 있는 에이전트 — 그리고 Decepticon의 위치.
---
## File: ko/vision/autonomous-hacking.mdx
---
title: "Autonomous Hacking (자율 해킹)"
---
## Autonomous Hacking이란 무엇인가?
솔직하게 말하겠습니다. "AI + 해킹" 분야는 지치게 만듭니다.
매주 누군가 데모를 내놓습니다: *"봐, GPT가 nmap을 돌려!"* 멋지군요. 그래서? 결국 실제 프로덕션에서는 아무도 쓰지 않는 파티 트릭이 되거나 — 더 심하면 누구도 넘어서는 안 될 선을 넘는 도구가 됩니다.
> *"또 하나의 AI 모의해킹 도구... 멋진 데모네. 근데 실제 공격자가 할 법한 걸 언제 하는 건데?"*
타당한 질문입니다. 우리의 답입니다.
**Autonomous Hacking (자율 해킹)**은 오펜시브 시큐리티의 다음 진화입니다. 해킹/모의해킹을 더 쉽거나 더 접근 가능하게 만드는 것이 아닙니다. **실제 레드팀 작전**을 기계 속도로 실행 가능하게 만드는 것입니다 — 전문가와 스크립트 키디를 구분하는 엄격함, 문서화, 법적 프레임워크와 함께.
전통적인 레드팀 테스팅은 스캐닝, 열거, 피벗, 문서화 등 수백 시간의 수작업을 요구합니다. 대부분은 반복적이고, 전부 지치는 작업입니다. 그 사이에도 공격 표면은 어떤 인간 팀보다 빠르게 확장됩니다.
Autonomous Hacking은 이 방정식을 바꿉니다. AI 에이전트가 반복 작업을 처리합니다: 스캔 실행, 출력 분석, 기법 체이닝, 실시간 적응. 인간은 미션을 설정하고, 규칙을 정의하며, 기계가 아직 할 수 없는 것에 집중합니다 — 직관, 판단, 그리고 창의적 사고.
> *"반복을 위임하라. 결정에 집중하라."*
## 바이브 해킹에서 Autonomous Hacking으로
Decepticon이 처음 구상되었을 때, 우리는 **바이브 해킹(Vibe Hacking)**이라는 용어를 사용했습니다 — AI 에이전트가 타겟 환경의 "바이브"를 읽는다는 아이디어: 문맥을 이해하고, 즉석에서 전략을 적응시키며, 고정된 플레이북 없이 복잡한 공격 체인을 수행하는 것.
그 핵심 역량은 변하지 않았습니다. 변한 것은 프레이밍입니다.
"바이브 해킹"은 *어떻게(How)*를 포착했습니다 — 문맥적이고, 적응적이며, 추론 기반의 공격. 하지만 *왜(Why)*는 포착하지 못했습니다 — 그리고 "왜"가 가장 중요합니다.
**Autonomous Hacking**은 전체 그림을 포괄합니다:
1. **어떻게 (The How)** — 타겟에 대해 추론하고, 방어에 적응하며, 다단계 공격을 자율적으로 체이닝하는 AI 에이전트
2. **왜 (The Why)** — 뚫리지 않는 방어 시스템을 구축하기 위한 무한한 오펜시브 피드백 제공
3. **프레임워크 (The Framework)** — 전문적인 레드팀 방법론 안에서 운영: RoE, OPPLAN, ConOps, 공식 승인
"자율(Autonomous)"이라는 단어는 다른 모든 AI 보안 도구와의 차별점도 전달합니다: 에이전트는 단순히 스크립트를 실행하지 않습니다. 실제 적처럼 *생각하고*, *적응하고*, *지속*합니다.
## "잠깐, 너희도 결국 똑같은 거 아냐?"
좋은 질문입니다. 짧은 답: **아닙니다.**
대부분의 사람들이 오펜시브 시큐리티에서 놓치는 것이 있습니다. *해킹*과 *레드팀 테스팅* 사이에는 거대한 차이가 있습니다.
레드팀 테스팅은 **규제되고, 승인된, 전문적인 규율이 적용되는 분야**입니다. 단 하나의 패킷이 전송되기 전에, 문서가 있습니다. 합의가 있습니다. 규칙이 있습니다.
- **RoE (교전 규칙)** — 무엇을 건드릴 수 있고 없는지를 정의합니다. 범위, 시간, 경계. 이것을 위반하면 레드팀이 아니라 범죄자입니다.
- **ConOps (작전 개념)** — 위협 행위자 프로파일, 공격 방법론, "우리가 누구를 모방하는가"를 정의하는 문서.
- **디컨플릭션 플랜** — 레드팀 활동과 실제 위협을 분리합니다. 소스 IP, 유저 에이전트, 시간대, SOC와의 실시간 디컨플릭션 콜을 위한 공유 코드.
- **OPPLAN (작전 계획)** — 전체 임무 계획. 목표, 킬 체인 단계, 수락 기준. 모든 행동은 목적에 매핑됩니다.
Decepticon은 이 모든 것을 지원합니다.
모든 인게이지먼트는 적절한 문서화로 시작됩니다. 모든 목표가 추적됩니다. 모든 행동이 정의된 경계 안에서 운영됩니다.
에이전트는 단순히 해킹하지 않습니다. 공식 작전 계획 아래 운영되고, 교전 규칙을 준수하며, 감사 가능한 결과물을 생산합니다. 이것은 재미있는 PoC(Proof of Concept)가 아닙니다. 자율적으로 작동하는 전문 레드팀 플랫폼입니다.
## 왜 Decepticon인가?
모의해킹은 취약점을 찾습니다. 레드팀은 가장 어려운 문제를 해결합니다: *당신의 조직이 실제 공격에서 살아남을 수 있는가?*
대부분의 보안 도구는 스캔 리포트에서 멈춥니다. Decepticon은 오히려 킬 체인으로 사고합니다 — 정찰, 익스플로잇, 권한 상승, 측면 이동, 지속성 — 스캐너가 아닌 실제 적이 하는 방식으로 다단계 작전을 수행합니다.
네 가지 원칙이 우리가 만드는 모든 것을 이끕니다:
Decepticon은 실제 적대자 행동을 모방합니다 — 포트 목록에 CVE 체크를 돌리는 것이 아닙니다. 작전 계획을 읽고, 발견한 것에 적응하며, 어떤 경로가 열리든 목표를 추구합니다. 목표는 실제로 테스트될 방식으로 방어를 시험하는 것입니다.
실제 오펜시브 보안 도구는 대화형입니다 — sliver-client, msfconsole, evil-winrm, sqlmap, impacket-psexec. 대부분의 AI 에이전트가 subprocess.run()으로 원샷 명령을 실행하고 끝내는 반면, Decepticon은 자동 프롬프트 감지가 있는 영속적 tmux 세션 내에서 모든 명령을 실행합니다. 에이전트가 실제로 도구를 조작합니다.
모든 명령은 전용 작전 네트워크의 강화된 Kali Linux 샌드박스에서 실행되며, 관리 인프라와 완전히 격리됩니다. 교차 네트워크 접근 없음. LangGraph는 네트워크가 아닌 Docker 소켓을 통해서만 샌드박스에 접근합니다.
보안 작업은 터미널에서 이루어져야 합니다. Decepticon의 인터페이스는 Ink로 구축된 실시간 스트리밍 CLI입니다. 브라우저 탭도, 대시보드도, 컨텍스트 스위칭도 없습니다. 에이전트가 보는 것을 실시간으로 봅니다.
## 큰 그림: 공격이 방어를 섬긴다
많은 "오펜시브 AI" 프로젝트가 잘못 이해하는 것이 있습니다: 공격을 목적지로 취급한다는 것.
**Decepticon은 목적지가 아닙니다. Step 1입니다.**
이미 수많은 오펜시브 AI 에이전트가 존재합니다. 세상에 "봐, AI가 해킹할 수 있어" 데모가 하나 더 필요한 것이 아닙니다. 세상이 진정으로 필요로 하는 것은 오펜시브 역량을 **방어 진화**로 전환하는 시스템입니다:
현실적인 레드팀 작전을 수행하는 세계 최고 수준의 해킹 에이전트를 구축한다. **우리는 여기에 있습니다.**
에이전트를 배포하여 지속적이고 다양한 공격 시나리오를 생성한다 — 끝없는 실제 위협 시뮬레이션 스트림.
그 피드백을 블루팀 역량으로 전환한다 — 탐지 룰, 대응 플레이북, 하드닝 전략. 공격이 멈추지 않기 때문에 방어도 진화를 멈추지 않는다.
이것을 **오펜시브 백신(Offensive Vaccine)**이라고 생각하세요. 생물학적 백신이 약화된 병원체에 신체를 노출시켜 면역력을 구축하듯, Decepticon은 끊임없는 AI 기반 공격에 인프라를 노출시켜 회복력을 구축합니다.
진정한 가치는 공격에 있지 않습니다. 그것을 견뎌내며 탄생하는 방어 시스템에 있습니다.
Decepticon의 집단지성 모델이 이 비전을 커뮤니티 기반의 현실로 만드는 방법을 알아보세요.
---
## File: ko/vision/core-philosophy.mdx
---
title: "핵심 철학 (Core Philosophy)"
---
Decepticon은 즉흥적으로 만들어진 것이 아닙니다. 모든 아키텍처 결정은 수년간의 연구와 실패, 그리고 값비싼 교훈으로부터 단조된 핵심 철학 위에 세워져 있습니다. 이 페이지에서는 Decepticon이 무엇인지, 그리고 의도적으로 무엇이 *아닌지*를 정의하는 철학적 기둥들을 소개합니다.
## 시그니처가 아닌 추론 (Reasoning Over Signatures)
전통적인 보안 도구들은 **시그니처 기반(Signature-based)** 패러다임으로 작동합니다. 알려진 취약점(CVE) 데이터베이스, 알려진 악성 페이로드, 알려진 공격 패턴을 기반으로 대조합니다. 만약 공격이 시그니처에 매칭되지 않으면, 그대로 탐지를 피해 통과합니다.
실제 운영 시스템에서 가장 위험한 취약점은 CVE 데이터베이스에 거의 등록되어 있지 않습니다. 그것들은 **논리적 결함(Logical Flaw)**으로, 타겟의 비즈니스 로직과 아키텍처, 그리고 시스템을 만든 인간의 사고 맹점에서 비롯되는 고유한 취약점입니다.
Decepticon은 시그니처 우선 접근 방식을 거부합니다. 정적 데이터베이스에 대한 패턴 매칭 대신, 타겟에 대해 **추론(Reasoning)**합니다:
* **문맥 이해 (Contextual Understanding)**: 서버 응답을 읽고, 애플리케이션 흐름을 파악하며, 인간의 사고 맹점이 만드는 공격 가능 지점을 식별합니다.
* **동적 전략 수립 (Dynamic Strategy)**: 매번 같은 스캔 플레이북을 돌리는 것이 아니라, 각 타겟 환경의 고유한 "바이브"에 맞게 접근 방식을 적응시킵니다.
* **사고 연쇄 공격 (Chain-of-Thought Attacks)**: 각 단계가 다음 단계에 정보를 제공하는 다단계 공격 체인을 구성합니다—실제 인간 공격자가 하는 것처럼.
## 하이브리드 지능 (Hybrid Intelligence)
Decepticon은 검증된 보안 도구를 AI로 **대체**하는 것이 아닙니다. 이들을 **지능적으로 결합**하는 것입니다.
사이버 보안 분야에는 수십 년에 걸쳐 검증된 기법들이 존재합니다: 퍼징(Fuzzing), 정적 분석, 네트워크 스캐닝, 페이로드 변이 등. 이 도구들은 각자의 영역에서 강력합니다. 하지만 **추론**하고, **적응**하고, 여러 공격 표면에 걸쳐 **맥락을 연결**하는 능력은 없습니다.
퍼징, 스캐닝, 페이로드 생성 등—정의된 범위 내에서 구조화된 반복 작업에 탁월한 검증된 도구들.
문맥을 이해하고, 전략을 적응시키며, 다단계 작전을 동적으로 조율하는 LLM 기반 추론 능력.
Decepticon의 접근 방식은 각각이 가장 잘 하는 것을 하도록 하는 것입니다:
* **퍼저**는 어떤 LLM보다 빠르게 수천 개의 변형된 입력을 생성합니다.
* **스캐너**는 기계적 정밀함으로 서비스를 열거하고 알려진 취약점을 식별합니다.
* **에이전트**는 이 도구들을 *언제* 배포할지 결정하고, 결과를 *해석*하며, 이를 의미 있는 공격 시퀀스로 *체이닝*하고, 상황이 바뀌면 *피벗*합니다.
이것이 **하이브리드 지능(Hybrid Intelligence)**입니다: AI 에이전트의 추론이 이끄는 자동화의 정밀함.
## 오펜시브 백신 (The Offensive Vaccine)
[개요](/ko/introduction/overview#리팩토링-동기-오펜시브-백신-offensive-vaccine)에서 논의한 바와 같이, Decepticon의 궁극적 목표는 공격이 아닌 **면역**입니다.
생물학적 백신이 약화된 병원체에 신체를 노출시켜 면역력을 구축하듯, Decepticon은 끊임없는 AI 기반 공격에 인프라를 노출시켜 회복력을 구축합니다.
하지만 이것이 "또 하나의 스캐너"와 다른 이유가 있습니다:
1. **무한 피드백 루프**: 에이전트는 동일한 플레이북을 반복하지 않는, 다양하고 문맥을 인식하는 공격 시나리오를 끝없이 생성합니다.
2. **현실적인 위협 시뮬레이션**: 효과적인 백신이 되려면, 공격은 실제 위협 행위자를 충실히 모방해야 합니다. 시끄럽게 포트 스캔하고 기본 패스워드를 체크하는 도구는 백신이 아니라 위약(Placebo)입니다.
3. **측정 가능한 진화**: 공격과 방어의 모든 사이클은 측정 가능한 데이터를 생산하여, 블루팀이 시간에 따른 자신의 성장을 정량적으로 파악할 수 있게 합니다.
## 사람이 중심에 서다 (Human in the Loop)
자율적이라는 것은 감독되지 않는다는 의미가 아닙니다. Decepticon은 **인간 오퍼레이터를 궁극적 권위자**—작전의 진정한 의사결정자이자 지성체로 위치시킵니다.
에이전트는 자율적으로 전략을 실행하고 실시간으로 적응합니다. 하지만 사람은 항상 그 자리에 있습니다:
* **실시간 모니터링**: 현대의 AI 에이전트 서비스처럼, 오퍼레이터는 에이전트의 행동을 실시간으로 관찰할 수 있습니다—무엇을 하고 있는지, 왜 하는지, 다음에 무엇을 할 계획인지.
* **언제든 개입 가능**: 오퍼레이터는 작전의 어떤 시점에서든 에이전트의 결정을 일시정지, 방향 전환, 또는 직접 개입할 수 있습니다. 에이전트는 도구이고, 인간이 전략가입니다.
* **피드백 기반 학습**: 인간의 피드백이 에이전트의 행동을 형성합니다. 오퍼레이터는 단순히 지켜보는 것이 아니라 작전을 적극적으로 다듬고 있는 것입니다.
자율주행차를 생각해보세요: 차가 운전을 담당하지만, 인간은 언제든 핸들을 잡을 수 있습니다. 매 커브를 직접 돌 필요는 없지만, 언제나 통제권은 사람에게 있습니다.
## 은닉이 기반이다 (Stealth as Foundation)
대부분의 자동화된 보안 도구는 본질적으로 **시끄럽습니다**. 수천 개의 요청을 퍼붓고, 모든 SIEM 룰을 트리거하며, 자신의 존재를 만천하에 알립니다.
이것은 레드팀 테스팅의 목적을 완전히 무력화합니다. 핵심은 정교한 적을 블루팀이 **탐지할 수 있는지** 테스트하는 것입니다. 테스팅 도구가 시작하자마자 모든 알람을 울린다면, 탐지 역량을 테스트하는 것이 아니라 알람 피로도를 테스트하는 것입니다.
Decepticon은 은닉을 **근본적인 설계 요구사항**으로 취급합니다:
* **C2 기반 운영**: 에이전트는 실제 위협 행위자처럼 C2(Command & Control) 인프라를 통해 운영되며, 암호화된 은밀한 통신 채널을 유지합니다.
* **샌드박스 실행**: 명령어는 샌드박스 환경에서 실행되며, 실제 공격자가 실천하는 작전 보안(OPSEC) 훈련을 그대로 따릅니다.
* **저속-지속 (Low-and-Slow)**: 활동은 정상 트래픽 패턴에 녹아들도록 조절되며, 볼륨으로 방어를 압도하지 않습니다.
단순히 취약점을 찾는 것이 가치가 아닙니다. 핵심 질문에 답하는 것입니다: *블루팀이 우리를 탐지할 수 있는가? 얼마나 빨리 대응하는가? 무엇을 놓치는가?*
Decepticon의 집단지성 모델이 전통적인 오픈소스를 어떻게 넘어서는지, 그리고 이것이 보안 생태계 전체에 왜 중요한지 알아보세요.
---
## File: ko/vision/target-architecture.mdx
[Binary file]
---
## File: ko/vision/why-open-source.mdx
[Binary file]