# empireproject/empire architecture

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

- Interactive diagram: https://gitdiagram.com/empireproject/empire
- Repository: https://github.com/empireproject/empire

## Overview

Empire is a post-exploitation command-and-control framework for PowerShell Windows agents and Python Linux/macOS agents. Its principal workflow is operator tasking through the controller, listener-mediated agent communications, and returned results; the README also highlights secure communications, deployable modules, and adaptable transports. The graph preserves those capabilities alongside staging, plugins, events, and shared protocol services. Source excerpts and the index establish several module references, but do not expose all runtime dispatch paths, so uncertain links are dashed.

Main entry points: [`lib/common/empire.py`](https://github.com/empireproject/empire/blob/master/lib/common/empire.py) (Empire controller), [`data/agent/agent.py`](https://github.com/empireproject/empire/blob/master/data/agent/agent.py) (Agent runtime), [`lib/common/listeners.py`](https://github.com/empireproject/empire/blob/master/lib/common/listeners.py) (Listener manager), [`lib/common/agents.py`](https://github.com/empireproject/empire/blob/master/lib/common/agents.py) (Agent registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Operator control"]
  node_controller["Empire controller<br/>[empire.py]"]
  node_agent_store[("Agent registry<br/>[agents.py]")]
end

subgraph group_communications["Agent communications"]
  node_listener_manager["Listener manager<br/>[listeners.py]"]
  node_http_listener["HTTP listener<br/>[http.py]"]
  node_dropbox_listener["Dropbox listener<br/>[dbx.py]"]
  node_redirector["Redirector listener<br/>[redirector.py]"]
end

subgraph group_execution["Agent execution"]
  node_agent_runtime["Agent runtime<br/>[agent.py]"]
  node_agent_stagers["Agent communication stagers"]
  node_stager_manager["Stager manager<br/>[stagers.py]"]
  node_platform_stagers["Platform stagers"]
end

subgraph group_capabilities["Post-exploitation capabilities"]
  node_module_catalog["Module catalog<br/>[modules.py]"]
  node_powershell_modules["PowerShell modules"]
  node_python_modules["Python modules"]
end

subgraph group_services["Shared services"]
  node_crypto["Encryption services<br/>[encryption.py]"]
  node_packet_protocol["Packet protocol<br/>[packets.py]"]
  node_event_bus["Event dispatch<br/>[events.py]"]
  node_plugin_system["Plugin system<br/>[plugins.py]"]
  node_terminal_messages["Operator messages<br/>[messages.py]"]
  node_template_engine["Template engine<br/>[templating.py]"]
end

node_operator(("Operator"))
node_external_targets(("Managed hosts"))
node_dropbox_service(("Dropbox service"))

node_operator -.->|"issues commands"| node_controller
node_controller -.->|"manages agents"| node_agent_store
node_controller -.->|"manages listeners"| node_listener_manager
node_controller -.->|"manages modules"| node_module_catalog
node_controller -.->|"manages stagers"| node_stager_manager
node_controller -.->|"loads plugins"| node_plugin_system
node_controller -.->|"displays status"| node_terminal_messages
node_module_catalog -.->|"catalogs"| node_powershell_modules
node_module_catalog -.->|"catalogs"| node_python_modules
node_controller -.->|"dispatches events"| node_event_bus
node_listener_manager -.->|"provides listener"| node_http_listener
node_listener_manager -.->|"provides listener"| node_dropbox_listener
node_listener_manager -.->|"provides listener"| node_redirector
node_http_listener -.->|"communicates"| node_external_targets
node_dropbox_listener -.->|"uses API"| node_dropbox_service
node_dropbox_listener -.->|"stages agent"| node_agent_runtime
node_http_listener -.->|"stages agent"| node_agent_runtime
node_agent_runtime -.->|"uses transport code"| node_agent_stagers
node_stager_manager -.->|"generates payloads"| node_platform_stagers
node_platform_stagers -.->|"delivers agent"| node_agent_runtime
node_agent_runtime -.->|"exchanges packets"| node_packet_protocol
node_packet_protocol -->|"encrypts packets"| node_crypto
node_agent_store -->|"uses encryption"| node_crypto
node_agent_store -->|"processes agent packets"| node_packet_protocol
node_controller -.->|"uses templates"| node_template_engine
node_controller -.->|"tasks capabilities"| node_powershell_modules
node_controller -.->|"tasks capabilities"| node_python_modules
node_agent_runtime -.->|"executes operations"| node_external_targets

click node_controller "https://github.com/empireproject/empire/blob/master/lib/common/empire.py"
click node_agent_store "https://github.com/empireproject/empire/blob/master/lib/common/agents.py"
click node_listener_manager "https://github.com/empireproject/empire/blob/master/lib/common/listeners.py"
click node_http_listener "https://github.com/empireproject/empire/blob/master/lib/listeners/http.py"
click node_dropbox_listener "https://github.com/empireproject/empire/blob/master/lib/listeners/dbx.py"
click node_redirector "https://github.com/empireproject/empire/blob/master/lib/listeners/redirector.py"
click node_agent_runtime "https://github.com/empireproject/empire/blob/master/data/agent/agent.py"
click node_agent_stagers "https://github.com/empireproject/empire/tree/master/data/agent/stagers"
click node_stager_manager "https://github.com/empireproject/empire/blob/master/lib/common/stagers.py"
click node_platform_stagers "https://github.com/empireproject/empire/tree/master/lib/stagers"
click node_module_catalog "https://github.com/empireproject/empire/blob/master/lib/common/modules.py"
click node_powershell_modules "https://github.com/empireproject/empire/tree/master/lib/modules/powershell"
click node_python_modules "https://github.com/empireproject/empire/tree/master/lib/modules/python"
click node_crypto "https://github.com/empireproject/empire/blob/master/lib/common/encryption.py"
click node_packet_protocol "https://github.com/empireproject/empire/blob/master/lib/common/packets.py"
click node_event_bus "https://github.com/empireproject/empire/blob/master/lib/common/events.py"
click node_plugin_system "https://github.com/empireproject/empire/blob/master/lib/common/plugins.py"
click node_terminal_messages "https://github.com/empireproject/empire/blob/master/lib/common/messages.py"
click node_template_engine "https://github.com/empireproject/empire/blob/master/lib/common/templating.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_controller,node_agent_store toneBlue
class node_listener_manager,node_http_listener,node_dropbox_listener,node_redirector toneAmber
class node_agent_runtime,node_agent_stagers,node_stager_manager,node_platform_stagers toneMint
class node_module_catalog,node_powershell_modules,node_python_modules toneRose
class node_crypto,node_packet_protocol,node_event_bus,node_plugin_system,node_terminal_messages,node_template_engine,node_operator,node_external_targets,node_dropbox_service toneIndigo
```

## Components

### Operator control

- [Empire controller](https://github.com/empireproject/empire/blob/master/lib/common/empire.py): `lib/common/empire.py`
- [Agent registry](https://github.com/empireproject/empire/blob/master/lib/common/agents.py): `lib/common/agents.py`

### Agent communications

- [Listener manager](https://github.com/empireproject/empire/blob/master/lib/common/listeners.py): `lib/common/listeners.py`
- [HTTP listener](https://github.com/empireproject/empire/blob/master/lib/listeners/http.py): `lib/listeners/http.py`
- [Dropbox listener](https://github.com/empireproject/empire/blob/master/lib/listeners/dbx.py): `lib/listeners/dbx.py`
- [Redirector listener](https://github.com/empireproject/empire/blob/master/lib/listeners/redirector.py): `lib/listeners/redirector.py`

### Agent execution

- [Agent runtime](https://github.com/empireproject/empire/blob/master/data/agent/agent.py): `data/agent/agent.py`
- [Agent communication stagers](https://github.com/empireproject/empire/tree/master/data/agent/stagers): `data/agent/stagers`
- [Stager manager](https://github.com/empireproject/empire/blob/master/lib/common/stagers.py): `lib/common/stagers.py`
- [Platform stagers](https://github.com/empireproject/empire/tree/master/lib/stagers): `lib/stagers`

### Post-exploitation capabilities

- [Module catalog](https://github.com/empireproject/empire/blob/master/lib/common/modules.py): `lib/common/modules.py`
- [PowerShell modules](https://github.com/empireproject/empire/tree/master/lib/modules/powershell): `lib/modules/powershell`
- [Python modules](https://github.com/empireproject/empire/tree/master/lib/modules/python): `lib/modules/python`

### Shared services

- [Encryption services](https://github.com/empireproject/empire/blob/master/lib/common/encryption.py): `lib/common/encryption.py`
- [Packet protocol](https://github.com/empireproject/empire/blob/master/lib/common/packets.py): `lib/common/packets.py`
- [Event dispatch](https://github.com/empireproject/empire/blob/master/lib/common/events.py): `lib/common/events.py`
- [Plugin system](https://github.com/empireproject/empire/blob/master/lib/common/plugins.py): `lib/common/plugins.py`
- [Operator messages](https://github.com/empireproject/empire/blob/master/lib/common/messages.py): `lib/common/messages.py`
- [Template engine](https://github.com/empireproject/empire/blob/master/lib/common/templating.py): `lib/common/templating.py`

### Other components

- **Operator**
- **Managed hosts**
- **Dropbox service**

## Connections

- Operator → Empire controller: issues commands
- Empire controller → Agent registry: manages agents (evidence: `lib/common/empire.py`)
- Empire controller → Listener manager: manages listeners (evidence: `lib/common/empire.py`)
- Empire controller → Module catalog: manages modules (evidence: `lib/common/empire.py`)
- Empire controller → Stager manager: manages stagers (evidence: `lib/common/empire.py`)
- Empire controller → Plugin system: loads plugins (evidence: `lib/common/empire.py`)
- Empire controller → Operator messages: displays status (evidence: `lib/common/empire.py`)
- Module catalog → PowerShell modules: catalogs (evidence: `lib/common/modules.py`)
- Module catalog → Python modules: catalogs (evidence: `lib/common/modules.py`)
- Empire controller → Event dispatch: dispatches events (evidence: `lib/common/empire.py`)
- Listener manager → HTTP listener: provides listener (evidence: `lib/common/listeners.py`)
- Listener manager → Dropbox listener: provides listener (evidence: `lib/common/listeners.py`)
- Listener manager → Redirector listener: provides listener (evidence: `lib/common/listeners.py`)
- HTTP listener → Managed hosts: communicates
- Dropbox listener → Dropbox service: uses API (evidence: `lib/listeners/dbx.py`)
- Dropbox listener → Agent runtime: stages agent (evidence: `lib/listeners/dbx.py`)
- HTTP listener → Agent runtime: stages agent (evidence: `lib/listeners/http.py`)
- Agent runtime → Agent communication stagers: uses transport code
- Stager manager → Platform stagers: generates payloads (evidence: `lib/common/stagers.py`)
- Platform stagers → Agent runtime: delivers agent
- Agent runtime → Packet protocol: exchanges packets
- Packet protocol → Encryption services: encrypts packets (evidence: `lib/common/packets.py`)
- Agent registry → Encryption services: uses encryption (evidence: `lib/common/agents.py`)
- Agent registry → Packet protocol: processes agent packets (evidence: `lib/common/agents.py`)
- Empire controller → Template engine: uses templates (evidence: `lib/common/empire.py`)
- Empire controller → PowerShell modules: tasks capabilities
- Empire controller → Python modules: tasks capabilities
- Agent runtime → Managed hosts: executes operations