How bc-security/empire works
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.