Keep up-to-date on our blog at https://www.bc-security.org/blog

Empire

Empire 4 is a post-exploitation framework that includes a pure-PowerShell Windows agents, Python 3.x Linux/OS X agents, and C# agents. It is the merger of the previous PowerShell Empire and Python EmPyre projects. The framework offers cryptologically-secure communications and flexible architecture.

On the PowerShell side, Empire implements the ability to run PowerShell agents without needing powershell.exe, rapidly deployable post-exploitation modules ranging from key loggers to Mimikatz, and adaptable communications to evade network detection, all wrapped up in a usability-focused framework. PowerShell Empire premiered at BSidesLV in 2015 and Python EmPyre premiered at HackMiami 2016. BC Security presented updates to further evade Microsoft Antimalware Scan Interface (AMSI) and JA3/S signatures at DEF CON 27.

Empire relies heavily on the work from several other projects for its underlying functionality. We have tried to call out a few of those people we've interacted with heavily here and have included author/reference link information in the source of each Empire module as appropriate. If we have failed to properly cite existing or prior work, please let us know at [email protected].

Empire is currently being developed and maintained by @Cx01N, @Hubbl3, & @Vinnybod. While the main Empire project is no longer maintained, this fork is maintained by @bcsecurity1. Please reach out to us on our Discord if you have any questions or want talk about offensive security.

Thank you to the original team of developers: @harmj0y, @sixdub, @enigma0x3, @rvrsh3ll, @killswitch_gui, & @xorrior

Sponsors

Release Notes

Please see our Releases or Changelog page for detailed release notes.

Empire 4.0 Alpha Documentation

Note: Some things are subject to change before the GA release, and this documentation will (hopefully ;) ) be built out to the wiki before then.

Empire 4 made some changes to the crypto libraries. Run these commands to refresh your virtual environment,
if you already have one.

poetry run python -m pip uninstall PyCrypto
poetry run python -m pip uninstall pycryptodome
poetry install

You will want to run the install script to get the latest OS dependencies. It has been tested and runs properly on Ubuntu 20.04, Debian 10, and Kali Rolling release. When prompted for dotnet, type y to get the required dependencies for C# agents.

cd setup
./install.sh

Quickstart

Empire 4 introduces a new run command for the server and client. The API and SocketIO servers run by default and are no longer needed to be provided as parameters.

# Old
poetry run python empire --server --rest --notifications

# New
poetry run python empire.py server

# Or a shortcut
./ps-empire server

# Help menus
./ps-empire server -h

The old embedded client has been removed. To run the new command line client.

poetry run python empire.py client

# Or a shortcut
./ps-empire client

# Help menus
./ps-empire client -h

Check out the Empire wiki for more instructions on getting started with Empire.

C# agents

Empire 4 combines the power of Covenant and Sharpire to give us C# agents.

Currently, the C# functionality is contained in a plugin. The plugin MUST be running to generate the stager and execute C# tasks. To start the server:

# from the client
useplugin csharpserver
set status start
execute

To get a stager for a C# agent

usestager windows/csharp_exe
set Listener <listener_name>
generate

Drop the stager on your windows box and execute it. You should see a callback just like any other Empire stager. Covenant modules have also been loaded into Empire. They can be executed both against the C# agent and the PowerShell agent. You can find them prefixed with csharp/.

For a complete list of the 4.0 changes, see the changelog.

Join us in our Discord to with any comments, questions, concerns, or problems!

Install

We recommend the use of Kali, Poetry, or our Docker images to run Empire. Kali Linux users and Direct Sponsors will receive 30-day early access to new Empire and Starkiller features.

The following operating systems have been tested for Empire compatibility. We will be unable to provide support for other OSs at this time. Consider using our Prebuilt Docker containers which can run on any system.

• Kali Linux Rolling
• Ubuntu 20.04
• Debian 10

As of Empire 4.0, Python 3.7 is the minimum Python version required.

Kali

You can install the latest version of Empire by running the following:

sudo apt install powershell-empire

Note: Newer versions of Kali require you to run sudo before starting Empire.

Github

Poetry is a dependency and virtual environment management tool. This is highly recommended if using the SocketIO notification feature introduced in 3.5.0. To install Poetry, please follow the installation guide in the documentation or run sudo pip3 install poetry.

To install and run:

git clone --recursive https://github.com/BC-SECURITY/Empire.git
cd Empire
sudo ./setup/install.sh
sudo poetry install

Docker

If you want to run Empire using a pre-built docker container: Note: For size savings on the image, it is not pre-built with the libraries needed for jar and dmg stagers or the needed libraries for csharp agents and modules. To add these to your image, run the install.sh script in the container and answer y to the prompts.

docker pull bcsecurity/empire:{version}
docker run -it -p 1337:1337 -p 5000:5000 bcsecurity/empire:{version}

# with persistent storage
docker pull bcsecurity/empire:{version}
docker create -v /empire --name data bcsecurity/empire:{version}
docker run -it -p 1337:1337 -p 5000:5000 --volumes-from data bcsecurity/empire:{version}

# if you prefer to be dropped into bash instead of directly into empire
docker run -it -p 1337:1337 -p 5000:5000 --volumes-from data bcsecurity/empire:{version} /bin/bash

All image versions can be found at: https://hub.docker.com/r/bcsecurity/empire/

• The last commit from master will be deployed to the latest tag
• The last commit from the dev branch will be deployed to the dev tag
• All github tagged releases will be deployed using their version numbers (v3.0.0, v3.1.0, etc)

Plugins

Plugins are an extension of Empire that allow for custom scripts to be loaded. This allows anyone to easily build or add community projects to extend Empire functionality. Plugins can be accessed from the Empire CLI or the API as long as the plugin follows the template example. A list of Empire Plugins is located here.

Starkiller

Starkiller is a GUI for PowerShell Empire that interfaces remotely with Empire via its API. Starkiller can be ran as a replacement for the Empire client or in a mixed environment with Starkiller and Empire clients.

Contribution Rules

Contributions are more than welcome! The more people who contribute to the project the better Empire will be for everyone. Below are a few guidelines for submitting contributions.

• As of Empire 3.1.0, Empire only officially supports Python 3. If you still need Python 2 support, please use the 3.0.x branch or releases.
• Submit pull requests to the dev branch. After testing, changes will be merged to master.
• Depending on what you're working on, base your module on ./lib/modules/powershell_template.py or ./lib/modules/python_template.py. Note that for some modules you may need to massage the output to get it into a nicely displayable text format with Out-String.
• Cite previous work in the 'Comments' module section.
• If your script.ps1 logic is large, may be reused by multiple modules, or is updated often, consider implementing the logic in the appropriate data/module_source/* directory and pulling the script contents into the module on tasking.
• Use approved PowerShell verbs for any functions.
• PowerShell Version 2 compatibility is STRONGLY preferred.
• TEST YOUR MODULE! Be sure to run it from an Empire agent and test Python 3.x functionality before submitting a pull to ensure everything is working correctly.
• For additional guidelines for your PowerShell code itself, check out the PowerSploit style guide.

Official Discord Channel