# jm33-m0/emp3r0r architecture

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

- Interactive diagram: https://gitdiagram.com/jm33-m0/emp3r0r
- Repository: https://github.com/jm33-m0/emp3r0r

## Overview

emp3r0r is a cross-platform, memory-only command-and-control framework. An operator uses the console to issue work; the C2 server admits authenticated agents, routes commands and streams, and returns agent responses for operator handling. Agents execute through command handlers and extensible script/native-module runtimes, while transport and mesh subsystems provide resilient links and peer relaying. The README also documents file transfer, listeners/stagers, PFS, and Linux eBPF capabilities. Edges are limited to relationships visible in excerpts or documented in the README; unsampled subsystem links are omitted where not explicit.

Main entry points: [`core/internal/cc/server/server_main.go`](https://github.com/jm33-m0/emp3r0r/blob/v4/core/internal/cc/server/server_main.go) (C2 server), [`core/internal/cc/server/handler_messagetun.go`](https://github.com/jm33-m0/emp3r0r/blob/v4/core/internal/cc/server/handler_messagetun.go) (Message tunnel), [`core/internal/agent/handler/handler.go`](https://github.com/jm33-m0/emp3r0r/blob/v4/core/internal/agent/handler/handler.go) (Command handling), [`core/internal/agent/modules/mod.go`](https://github.com/jm33-m0/emp3r0r/blob/v4/core/internal/agent/modules/mod.go) (Agent modules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operator["Operator control"]
  node_console["C2 console<br/>[main.go]"]
  node_operator_cmd["Operator commands<br/>[cmd.go]"]
  node_job_mgr[("Job tracking<br/>[manager.go]")]
  node_operator_client["Operator API client<br/>[client.go]"]
end

subgraph group_server["C2 services"]
  node_c2_server["C2 server<br/>[server_main.go]"]
  node_checkin["Agent check-in<br/>[handler_checkin.go]"]
  node_message_tunnel["Message tunnel"]
  node_agent_store[("Agent trust and state<br/>[agentdb.go]")]
  node_ftp_server["File transfer service<br/>[handler_ftp.go]"]
end

subgraph group_agent["Agent runtime"]
  node_agent_entry["Agent process<br/>[agent.go]"]
  node_agent_handler["Command handling<br/>[handler.go]"]
  node_agent_c2["Agent C2 transport<br/>[connector.go]"]
end

subgraph group_network["Transport and mesh"]
  node_mesh_service["Peer mesh<br/>[service.go]"]
  node_transport["C2 transport<br/>[c2transport.go]"]
  node_listeners["Listeners<br/>[manager.go]"]
  node_preflight["Preflight gate<br/>[server.go]"]
end

subgraph group_extensions["Execution extensions"]
  node_script_engine["Starlark runtime<br/>[engine.go]"]
  node_agent_modules["Agent modules<br/>[mod.go]"]
  node_coff_loader["COFF and ELF loaders<br/>[loader_linux.go]"]
  node_memmod["In-memory libraries"]
  node_ebpf["Linux eBPF APIs<br/>[libbpf_linux.go]"]
  node_module_collection["Bundled modules"]
end

node_operator_actor(("Operator"))
node_external_network(("Agent network"))

node_operator_actor -->|"operates"| node_console
node_console -->|"starts or connects"| node_c2_server
node_console -.->|"dispatches commands"| node_operator_cmd
node_operator_cmd -.->|"issues requests"| node_operator_client
node_operator_cmd -.->|"tracks jobs"| node_job_mgr
node_c2_server -.->|"routes check-ins"| node_checkin
node_checkin -->|"checks identity"| node_agent_store
node_c2_server -.->|"handles tunnels"| node_message_tunnel
node_message_tunnel -->|"authenticates sessions"| node_agent_store
node_message_tunnel -.->|"receives output"| node_job_mgr
node_c2_server -.->|"serves transfers"| node_ftp_server
node_agent_entry -.->|"dispatches commands"| node_agent_handler
node_agent_handler -->|"uses transport"| node_agent_c2
node_agent_c2 -->|"communicates over"| node_transport
node_transport -.->|"sends traffic"| node_external_network
node_external_network -.->|"reaches C2"| node_checkin
node_message_tunnel -.->|"returns responses"| node_operator_client
node_agent_entry -->|"runs peer mesh"| node_mesh_service
node_mesh_service -->|"gossips with peers"| node_external_network
node_agent_handler -.->|"runs scripts"| node_script_engine
node_agent_handler -.->|"dispatches modules"| node_agent_modules
node_agent_modules -.->|"loads native objects"| node_coff_loader
node_agent_modules -.->|"maps libraries"| node_memmod
node_script_engine -.->|"exposes eBPF"| node_ebpf
node_agent_modules -.->|"loads bundled modules"| node_module_collection
node_listeners -.->|"accepts connections"| node_external_network
node_agent_entry -.->|"checks admission"| node_preflight

click node_console "https://github.com/jm33-m0/emp3r0r/blob/v4/core/cmd/cc/main.go"
click node_operator_cmd "https://github.com/jm33-m0/emp3r0r/blob/v4/core/internal/cc/operator/cmd.go"
click node_job_mgr "https://github.com/jm33-m0/emp3r0r/blob/v4/core/internal/cc/jobs/manager.go"
click node_c2_server "https://github.com/jm33-m0/emp3r0r/blob/v4/core/internal/cc/server/server_main.go"
click node_checkin "https://github.com/jm33-m0/emp3r0r/blob/v4/core/internal/cc/server/handler_checkin.go"
click node_message_tunnel "https://github.com/jm33-m0/emp3r0r/blob/v4/core/internal/cc/server/handler_messagetun.go"
click node_agent_store "https://github.com/jm33-m0/emp3r0r/blob/v4/core/internal/cc/base/agents/agentdb.go"
click node_ftp_server "https://github.com/jm33-m0/emp3r0r/blob/v4/core/internal/cc/base/ftp/handler_ftp.go"
click node_operator_client "https://github.com/jm33-m0/emp3r0r/blob/v4/core/internal/cc/api/client/client.go"
click node_agent_entry "https://github.com/jm33-m0/emp3r0r/blob/v4/core/cmd/agent/agent.go"
click node_agent_handler "https://github.com/jm33-m0/emp3r0r/blob/v4/core/internal/agent/handler/handler.go"
click node_agent_c2 "https://github.com/jm33-m0/emp3r0r/blob/v4/core/internal/agent/base/c2transport/connector.go"
click node_mesh_service "https://github.com/jm33-m0/emp3r0r/blob/v4/core/internal/agent/mesh/service.go"
click node_transport "https://github.com/jm33-m0/emp3r0r/blob/v4/core/internal/transport/c2transport.go"
click node_listeners "https://github.com/jm33-m0/emp3r0r/blob/v4/core/lib/listener/manager.go"
click node_preflight "https://github.com/jm33-m0/emp3r0r/blob/v4/core/lib/preflight/server.go"
click node_script_engine "https://github.com/jm33-m0/emp3r0r/blob/v4/core/lib/script/engine.go"
click node_agent_modules "https://github.com/jm33-m0/emp3r0r/blob/v4/core/internal/agent/modules/mod.go"
click node_coff_loader "https://github.com/jm33-m0/emp3r0r/blob/v4/core/lib/coffloader/loader_linux.go"
click node_memmod "https://github.com/jm33-m0/emp3r0r/blob/v4/core/lib/memmod/memmod_elf_linux.go"
click node_ebpf "https://github.com/jm33-m0/emp3r0r/blob/v4/core/lib/libbpf/libbpf_linux.go"
click node_module_collection "https://github.com/jm33-m0/emp3r0r/tree/v4/core/modules"

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_console,node_operator_cmd,node_job_mgr,node_operator_client toneBlue
class node_c2_server,node_checkin,node_message_tunnel,node_agent_store,node_ftp_server toneAmber
class node_agent_entry,node_agent_handler,node_agent_c2 toneMint
class node_mesh_service,node_transport,node_listeners,node_preflight toneRose
class node_script_engine,node_agent_modules,node_coff_loader,node_memmod,node_ebpf,node_module_collection,node_operator_actor,node_external_network toneIndigo
```

## Components

### Operator control

- [C2 console](https://github.com/jm33-m0/emp3r0r/blob/v4/core/cmd/cc/main.go): `core/cmd/cc/main.go`
- [Operator commands](https://github.com/jm33-m0/emp3r0r/blob/v4/core/internal/cc/operator/cmd.go): `core/internal/cc/operator/cmd.go`
- [Job tracking](https://github.com/jm33-m0/emp3r0r/blob/v4/core/internal/cc/jobs/manager.go): `core/internal/cc/jobs/manager.go`
- [Operator API client](https://github.com/jm33-m0/emp3r0r/blob/v4/core/internal/cc/api/client/client.go): `core/internal/cc/api/client/client.go`

### C2 services

- [C2 server](https://github.com/jm33-m0/emp3r0r/blob/v4/core/internal/cc/server/server_main.go): `core/internal/cc/server/server_main.go`
- [Agent check-in](https://github.com/jm33-m0/emp3r0r/blob/v4/core/internal/cc/server/handler_checkin.go): `core/internal/cc/server/handler_checkin.go`
- [Message tunnel](https://github.com/jm33-m0/emp3r0r/blob/v4/core/internal/cc/server/handler_messagetun.go): `core/internal/cc/server/handler_messagetun.go`
- [Agent trust and state](https://github.com/jm33-m0/emp3r0r/blob/v4/core/internal/cc/base/agents/agentdb.go): `core/internal/cc/base/agents/agentdb.go`
- [File transfer service](https://github.com/jm33-m0/emp3r0r/blob/v4/core/internal/cc/base/ftp/handler_ftp.go): `core/internal/cc/base/ftp/handler_ftp.go`

### Agent runtime

- [Agent process](https://github.com/jm33-m0/emp3r0r/blob/v4/core/cmd/agent/agent.go): `core/cmd/agent/agent.go`
- [Command handling](https://github.com/jm33-m0/emp3r0r/blob/v4/core/internal/agent/handler/handler.go): `core/internal/agent/handler/handler.go`
- [Agent C2 transport](https://github.com/jm33-m0/emp3r0r/blob/v4/core/internal/agent/base/c2transport/connector.go): `core/internal/agent/base/c2transport/connector.go`

### Transport and mesh

- [Peer mesh](https://github.com/jm33-m0/emp3r0r/blob/v4/core/internal/agent/mesh/service.go): `core/internal/agent/mesh/service.go`
- [C2 transport](https://github.com/jm33-m0/emp3r0r/blob/v4/core/internal/transport/c2transport.go): `core/internal/transport/c2transport.go`
- [Listeners](https://github.com/jm33-m0/emp3r0r/blob/v4/core/lib/listener/manager.go): `core/lib/listener/manager.go`
- [Preflight gate](https://github.com/jm33-m0/emp3r0r/blob/v4/core/lib/preflight/server.go): `core/lib/preflight/server.go`

### Execution extensions

- [Starlark runtime](https://github.com/jm33-m0/emp3r0r/blob/v4/core/lib/script/engine.go): `core/lib/script/engine.go`
- [Agent modules](https://github.com/jm33-m0/emp3r0r/blob/v4/core/internal/agent/modules/mod.go): `core/internal/agent/modules/mod.go`
- [COFF and ELF loaders](https://github.com/jm33-m0/emp3r0r/blob/v4/core/lib/coffloader/loader_linux.go): `core/lib/coffloader/loader_linux.go`
- [In-memory libraries](https://github.com/jm33-m0/emp3r0r/blob/v4/core/lib/memmod/memmod_elf_linux.go): `core/lib/memmod/memmod_elf_linux.go`
- [Linux eBPF APIs](https://github.com/jm33-m0/emp3r0r/blob/v4/core/lib/libbpf/libbpf_linux.go): `core/lib/libbpf/libbpf_linux.go`
- [Bundled modules](https://github.com/jm33-m0/emp3r0r/tree/v4/core/modules): `core/modules`

### Other components

- **Operator**
- **Agent network**

## Connections

- Operator → C2 console: operates
- C2 console → C2 server: starts or connects (evidence: `core/cmd/cc/main.go`)
- C2 console → Operator commands: dispatches commands
- Operator commands → Operator API client: issues requests
- Operator commands → Job tracking: tracks jobs
- C2 server → Agent check-in: routes check-ins
- Agent check-in → Agent trust and state: checks identity (evidence: `core/internal/cc/server/handler_checkin.go`)
- C2 server → Message tunnel: handles tunnels
- Message tunnel → Agent trust and state: authenticates sessions (evidence: `core/internal/cc/server/handler_messagetun.go`)
- Message tunnel → Job tracking: receives output
- C2 server → File transfer service: serves transfers
- Agent process → Command handling: dispatches commands
- Command handling → Agent C2 transport: uses transport (evidence: `core/internal/agent/handler/handler.go`)
- Agent C2 transport → C2 transport: communicates over
- C2 transport → Agent network: sends traffic
- Agent network → Agent check-in: reaches C2
- Message tunnel → Operator API client: returns responses
- Agent process → Peer mesh: runs peer mesh
- Peer mesh → Agent network: gossips with peers (evidence: `core/internal/agent/mesh/service.go`)
- Command handling → Starlark runtime: runs scripts
- Command handling → Agent modules: dispatches modules
- Agent modules → COFF and ELF loaders: loads native objects
- Agent modules → In-memory libraries: maps libraries
- Starlark runtime → Linux eBPF APIs: exposes eBPF (evidence: `README.md`)
- Agent modules → Bundled modules: loads bundled modules (evidence: `README.md`)
- Listeners → Agent network: accepts connections
- Agent process → Preflight gate: checks admission
