# bc-security/empire architecture

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

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

## Overview

##### Major System Components
- Empire Server – The heart of the framework, written in Python. It includes service layers, APIs, core functionalities, and modules.
- API Layer – Located in the “empire/server/api” directory (with a v2 subdirectory that further splits endpoints for administrative tasks, agent communications, file handling, credentials management, etc.). This component handles incoming requests (REST API) and routes them to appropriate services.
- Core Services – Found under “empire/server/core,” these represent services such as agent communication, file services, bypass and obfuscation management, agent and host services, and module processing. They combine business logic, configuration (from config.yaml and the configuration manager), and database calls.
- Data Storage & Persistence – The “empire/server/core/db” directory shows that models, defaults, and database access are integrated into the system.
- Common Utilities – Utility modules (in “empire/server/common” and “empire/server/utils”) cover encryption, templating, helper functions, and malleable communication profiles.
- Listeners – In “empire/server/listeners” you have various listener implementations (HTTP, SMB, port-forwarding etc.) which are the endpoints for connecting with agents.
- Modules and Plugins – The “empire/server/modules” and “empire/server/plugins” directories illustrate the modular design for executing post-exploitation techniques, running custom tasks, and integrating external tools. Notice that modules are provided in different languages and categories (BOF, C#, PowerShell, Python, etc.).
- Agent Stagers – Under “empire/server/stagers” are components that generate payloads for different agents (Windows, Linux, macOS) supporting multiple languages and stager types.
- Command Line Interface and Setup Scripts – With files like “ps-empire,” “empire.py,” and subdirectories (e.g., “setup/”), the project supports both interactive CLI operation, testing, and Docker-driven installation.
- External Interfaces – The README describes the built-in Starkiller GUI (a submodule) that interfaces remotely with Empire through its API.

##### Relationships and Data/Command Flows
- Data and Utility Layer: Show supporting utilities (encryption helpers, templating, common libraries) and database services (models, configuration manager, persistence layer) that feed into the core services.
- “Listeners” as endpoints that receive agent check-ins, and then forward communications to the Core Services.

##### Architectural Patterns and Design Principles
- Modular Design: Emphasize that each functionality (e.g., agent handling, module execution, listener management) is separated into independent components, making it extensible (as seen in the “modules” and “plugins” directories).
- Plugin and Module Interface: Highlight the plugin architecture allowing for the dynamic addition of custom tools (for example, for obfuscation, credential harvesting, etc.).
- Security and Encryption: Mark the modules responsible for encryption, in-memory execution, and customizable bypasses.

##### Relevant Technologies and Frameworks
- Python 3 – for server implementation.
- RESTful API – for service interaction.
- Docker – files like Dockerfile, .dockerignore, and various container configurations indicate containerized deployment.
- External Integration – Tools like ConfuserEx 2, Invoke-Obfuscation, Donut (for shellcode), and Roslyn compiler integration for in-memory .NET assembly execution.
- Multiple Agent Languages – Represent that agents exist in PowerShell, Python, C#, IronPython, and Go.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Empire Framework"
        %% Presentation/Interface Layer
        subgraph "Presentation/Interface Layer"
            CLI["CLI Client"]:::external
            GUI["Starkiller GUI"]:::external
        end

        %% API Gateway Layer
        subgraph "API Gateway Layer"
            API["REST API v2 (API Layer)"]:::api
        end

        %% Business Logic Layer
        subgraph "Business Logic Layer"
            ES["Empire Server"]:::server
            CS["Core Services"]:::services
            LI["Listeners"]:::listeners
            subgraph "Modules & Plugins"
                MOD["Modules"]:::modules
                PLG["Plugins"]:::plugins
            end
            AS["Agent Stagers"]:::stagers
        end

        %% Data & Utility Layer
        subgraph "Data & Utility Layer"
            DB["Database/Persistence"]:::database
            UTIL["Common Utilities"]:::utility
        end

        %% Deployment Layer
        subgraph "Deployment Layer"
            SETUP["Setup Scripts"]:::setup
        end
    end

    %% Relationships / Data Flows
    CLI -->|"sends requests"| API
    GUI -->|"sends requests"| API
    API -->|"routes request to"| ES
    ES -->|"invokes"| CS
    CS -->|"queries"| DB
    CS -->|"utilizes"| UTIL
    LI -->|"forwards data to"| CS
    CS -->|"invokes"| MOD
    CS -->|"invokes"| PLG
    CS -->|"generates payloads for"| AS
    CLI ---|"associated with"| SETUP

    %% Click Events
    click ES "https://github.com/bc-security/empire/blob/main/empire/server/server.py"
    click API "https://github.com/bc-security/empire/tree/main/empire/server/api"
    click CS "https://github.com/bc-security/empire/tree/main/empire/server/core"
    click DB "https://github.com/bc-security/empire/tree/main/empire/server/core/db"
    click UTIL "https://github.com/bc-security/empire/tree/main/empire/server/common"
    click LI "https://github.com/bc-security/empire/tree/main/empire/server/listeners"
    click MOD "https://github.com/bc-security/empire/tree/main/empire/server/modules"
    click PLG "https://github.com/bc-security/empire/tree/main/empire/server/plugins"
    click AS "https://github.com/bc-security/empire/tree/main/empire/server/stagers"
    click CLI "https://github.com/bc-security/empire/blob/main/empire.py"
    click SETUP "https://github.com/bc-security/empire/tree/main/setup/"
    click GUI "https://github.com/bc-security/empire/tree/main/docs/starkiller"

    %% Styles
    classDef external fill:#F9E79F,stroke:#7D6608,stroke-width:2px
    classDef api fill:#AED6F1,stroke:#1B4F72,stroke-width:2px
    classDef server fill:#FAD7A0,stroke:#7D6608,stroke-width:2px
    classDef services fill:#A9DFBF,stroke:#196F3D,stroke-width:2px
    classDef listeners fill:#FCF3CF,stroke:#7D6608,stroke-width:2px
    classDef modules fill:#F5B7B1,stroke:#922B21,stroke-width:2px
    classDef plugins fill:#F5B7B1,stroke:#922B21,stroke-width:2px
    classDef stagers fill:#D6EAF8,stroke:#1B4F72,stroke-width:2px
    classDef database fill:#D1E0E0,stroke:#1B4F72,stroke-width:2px
    classDef utility fill:#E8DAEF,stroke:#6C3483,stroke-width:2px
    classDef setup fill:#E6E6FA,stroke:#4A235A,stroke-width:2px
```
