# terminalkid09/phantom architecture

> Architecture diagram of the GitHub repository terminalkid09/phantom, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/terminalkid09/phantom
- Repository: https://github.com/terminalkid09/phantom

## Overview

Phantom is an offensive-security framework combining an operator shell, pentest modules, an autonomous engagement engine, and a cross-platform C2 system, with an Electron campaign-management app. The documented workflow is target and scope selection, reconnaissance and adaptive planning, execution, beacon handoff, persistence, and reporting. The graph preserves additional documented subsystems such as social engineering, swarm runs, learning, and desktop controls. Some implementation paths are directory-level because their source was not sampled; relationships are shown only where the README or indexed excerpts support them.

Main entry points: [`phantom/core/automode.py`](https://github.com/terminalkid09/phantom/blob/main/phantom/core/automode.py) (Auto Mode), [`phantom/main.py`](https://github.com/terminalkid09/phantom/blob/main/phantom/main.py) (CLI Shell), [`phantom/api/server.py`](https://github.com/terminalkid09/phantom/blob/main/phantom/api/server.py) (Local API), [`phantom/automation/agent.py`](https://github.com/terminalkid09/phantom/blob/main/phantom/automation/agent.py) (Autonomous Agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operator["Operator Experience"]
  node_shell["CLI Shell<br/>[main.py]"]
  node_desktop["Desktop App"]
  node_api["Local API<br/>[server.py]"]
end

subgraph group_engagement["Engagement Engine"]
  node_manual["Pentest Modules"]
  node_automode["Auto Mode<br/>[automode.py]"]
  node_targets["Target Guidance<br/>[targets.py]"]
  node_recon["Social Recon<br/>[recon.py]"]
  node_social["Social Campaigns<br/>[engine.py]"]
  node_planner["Autonomous Agent<br/>[agent.py]"]
  node_swarm["Swarm Runs"]
  node_execution["Command Execution<br/>[executor.py]"]
  node_toolchain["Toolchain<br/>[toolchain.py]"]
  node_persistence["Post-Exploitation"]
end

subgraph group_c2["C2 Operations"]
  node_beacon["Beacon Payload<br/>[main.cpp]"]
  node_c2["C2 Server<br/>[c2_server.py]"]
  node_c2d["C2 Daemon<br/>[server.go]"]
end

subgraph group_support["State and Intelligence"]
  node_scope["Scope and Session<br/>[scope.py]"]
  node_reports["Reporting<br/>[reporting.py]"]
  node_bundles["Session Bundles<br/>[session_bundle.py]"]
  node_learning[("Learning Memory")]
  node_advisor["LLM Advisor<br/>[llm_advisor.py]"]
end

node_operator(("Operator"))

node_operator -->|"starts"| node_shell
node_operator -->|"manages campaigns"| node_desktop
node_desktop -->|"uses local bridge"| node_api
node_shell -->|"launches"| node_automode
node_shell -->|"offers manual mode"| node_manual
node_shell -->|"sets target and scope"| node_scope
node_api -->|"starts runs"| node_automode
node_api -->|"uses engagement state"| node_scope
node_automode -->|"uses target guidance"| node_targets
node_automode -->|"runs agent"| node_planner
node_automode -->|"supports swarm engine"| node_swarm
node_targets -.->|"guides reconnaissance"| node_recon
node_planner -.->|"executes actions"| node_execution
node_execution -->|"uses toolchain"| node_toolchain
node_execution -->|"deploys beacon"| node_beacon
node_beacon -->|"checks in"| node_c2
node_c2 -->|"supports follow-on"| node_persistence
node_automode -->|"produces reports"| node_reports
node_automode -->|"exports handoff"| node_bundles
node_shell -->|"imports and exports"| node_bundles
node_social -->|"calls deep recon"| node_recon
node_automode -.->|"supports social capabilities"| node_social
node_automode -.->|"uses experience memory"| node_learning
node_planner -.->|"consults optionally"| node_advisor
node_api -->|"delegates C2 controls"| node_c2
node_c2d -.->|"serves C2 role"| node_beacon

click node_shell "https://github.com/terminalkid09/phantom/blob/main/phantom/main.py"
click node_desktop "https://github.com/terminalkid09/phantom/tree/main/electron/src"
click node_api "https://github.com/terminalkid09/phantom/blob/main/phantom/api/server.py"
click node_manual "https://github.com/terminalkid09/phantom/tree/main/phantom/modules"
click node_scope "https://github.com/terminalkid09/phantom/blob/main/phantom/core/scope.py"
click node_automode "https://github.com/terminalkid09/phantom/blob/main/phantom/core/automode.py"
click node_targets "https://github.com/terminalkid09/phantom/blob/main/phantom/automation/guidance/targets.py"
click node_recon "https://github.com/terminalkid09/phantom/blob/main/phantom/automation/social/recon.py"
click node_social "https://github.com/terminalkid09/phantom/blob/main/phantom/automation/social/engine.py"
click node_planner "https://github.com/terminalkid09/phantom/blob/main/phantom/automation/agent.py"
click node_swarm "https://github.com/terminalkid09/phantom/tree/main/phantom/automation/swarm"
click node_execution "https://github.com/terminalkid09/phantom/blob/main/phantom/core/executor.py"
click node_toolchain "https://github.com/terminalkid09/phantom/blob/main/phantom/automation/runtime/toolchain.py"
click node_beacon "https://github.com/terminalkid09/phantom/blob/main/phantom/payloads/beacon/src/main.cpp"
click node_c2 "https://github.com/terminalkid09/phantom/blob/main/phantom/core/c2_server.py"
click node_c2d "https://github.com/terminalkid09/phantom/blob/main/c2d/server.go"
click node_persistence "https://github.com/terminalkid09/phantom/tree/main/phantom/automation/post"
click node_reports "https://github.com/terminalkid09/phantom/blob/main/phantom/automation/reporting.py"
click node_bundles "https://github.com/terminalkid09/phantom/blob/main/phantom/utils/session_bundle.py"
click node_learning "https://github.com/terminalkid09/phantom/tree/main/phantom/automation/brain/experience"
click node_advisor "https://github.com/terminalkid09/phantom/blob/main/phantom/automation/llm_advisor.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_shell,node_desktop,node_api toneBlue
class node_manual,node_automode,node_targets,node_recon,node_social,node_planner,node_swarm,node_execution,node_toolchain,node_persistence toneAmber
class node_beacon,node_c2,node_c2d toneMint
class node_scope,node_reports,node_bundles,node_learning,node_advisor toneRose
class node_operator toneIndigo
```

## Components

### Operator Experience

- [CLI Shell](https://github.com/terminalkid09/phantom/blob/main/phantom/main.py): `phantom/main.py`
- [Desktop App](https://github.com/terminalkid09/phantom/tree/main/electron/src): `electron/src`
- [Local API](https://github.com/terminalkid09/phantom/blob/main/phantom/api/server.py): `phantom/api/server.py`

### Engagement Engine

- [Pentest Modules](https://github.com/terminalkid09/phantom/tree/main/phantom/modules): `phantom/modules`
- [Auto Mode](https://github.com/terminalkid09/phantom/blob/main/phantom/core/automode.py): `phantom/core/automode.py`
- [Target Guidance](https://github.com/terminalkid09/phantom/blob/main/phantom/automation/guidance/targets.py): `phantom/automation/guidance/targets.py`
- [Social Recon](https://github.com/terminalkid09/phantom/blob/main/phantom/automation/social/recon.py): `phantom/automation/social/recon.py`
- [Social Campaigns](https://github.com/terminalkid09/phantom/blob/main/phantom/automation/social/engine.py): `phantom/automation/social/engine.py`
- [Autonomous Agent](https://github.com/terminalkid09/phantom/blob/main/phantom/automation/agent.py): `phantom/automation/agent.py`
- [Swarm Runs](https://github.com/terminalkid09/phantom/tree/main/phantom/automation/swarm): `phantom/automation/swarm`
- [Command Execution](https://github.com/terminalkid09/phantom/blob/main/phantom/core/executor.py): `phantom/core/executor.py`
- [Toolchain](https://github.com/terminalkid09/phantom/blob/main/phantom/automation/runtime/toolchain.py): `phantom/automation/runtime/toolchain.py`
- [Post-Exploitation](https://github.com/terminalkid09/phantom/tree/main/phantom/automation/post): `phantom/automation/post`

### C2 Operations

- [Beacon Payload](https://github.com/terminalkid09/phantom/blob/main/phantom/payloads/beacon/src/main.cpp): `phantom/payloads/beacon/src/main.cpp`
- [C2 Server](https://github.com/terminalkid09/phantom/blob/main/phantom/core/c2_server.py): `phantom/core/c2_server.py`
- [C2 Daemon](https://github.com/terminalkid09/phantom/blob/main/c2d/server.go): `c2d/server.go`

### State and Intelligence

- [Scope and Session](https://github.com/terminalkid09/phantom/blob/main/phantom/core/scope.py): `phantom/core/scope.py`
- [Reporting](https://github.com/terminalkid09/phantom/blob/main/phantom/automation/reporting.py): `phantom/automation/reporting.py`
- [Session Bundles](https://github.com/terminalkid09/phantom/blob/main/phantom/utils/session_bundle.py): `phantom/utils/session_bundle.py`
- [Learning Memory](https://github.com/terminalkid09/phantom/tree/main/phantom/automation/brain/experience): `phantom/automation/brain/experience`
- [LLM Advisor](https://github.com/terminalkid09/phantom/blob/main/phantom/automation/llm_advisor.py): `phantom/automation/llm_advisor.py`

### Other components

- **Operator**

## Connections

- Operator → CLI Shell: starts (evidence: `README.md`)
- Operator → Desktop App: manages campaigns (evidence: `README.md`)
- Desktop App → Local API: uses local bridge (evidence: `phantom/api/server.py`)
- CLI Shell → Auto Mode: launches (evidence: `phantom/main.py`)
- CLI Shell → Pentest Modules: offers manual mode (evidence: `README.md`)
- CLI Shell → Scope and Session: sets target and scope (evidence: `README.md`)
- Local API → Auto Mode: starts runs (evidence: `phantom/api/server.py`)
- Local API → Scope and Session: uses engagement state (evidence: `phantom/api/server.py`)
- Auto Mode → Target Guidance: uses target guidance (evidence: `phantom/core/automode.py`)
- Auto Mode → Autonomous Agent: runs agent (evidence: `phantom/core/automode.py`)
- Auto Mode → Swarm Runs: supports swarm engine (evidence: `phantom/core/automode.py`)
- Target Guidance → Social Recon: guides reconnaissance (evidence: `phantom/automation/social/recon.py`)
- Autonomous Agent → Command Execution: executes actions
- Command Execution → Toolchain: uses toolchain (evidence: `phantom/core/executor.py`)
- Command Execution → Beacon Payload: deploys beacon (evidence: `README.md`)
- Beacon Payload → C2 Server: checks in (evidence: `phantom/payloads/beacon/src/main.cpp`)
- C2 Server → Post-Exploitation: supports follow-on (evidence: `README.md`)
- Auto Mode → Reporting: produces reports (evidence: `README.md`)
- Auto Mode → Session Bundles: exports handoff (evidence: `README.md`)
- CLI Shell → Session Bundles: imports and exports (evidence: `phantom/main.py`)
- Social Campaigns → Social Recon: calls deep recon (evidence: `phantom/automation/social/engine.py`)
- Auto Mode → Social Campaigns: supports social capabilities
- Auto Mode → Learning Memory: uses experience memory
- Autonomous Agent → LLM Advisor: consults optionally
- Local API → C2 Server: delegates C2 controls (evidence: `phantom/api/server.py`)
- C2 Daemon → Beacon Payload: serves C2 role
