Empire - PowerShell Post-Exploitation Agent

Monday, August 31, 2015

Empire is a pure PowerShell post-exploitation agent built on cryptologically-secure communications and a flexible architecture. 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.

Why PowerShell?

PowerShell offers a multitude of offensive advantages, including full .NET access, application whitelisting, direct access to the Win32 API, the ability to assemble malicious binaries in memory, and a default installation on Windows 7+. Offensive PowerShell had a watershed year in 2014, but despite the multitude of useful projects, many pentesters still struggle to integrate PowerShell into their engagements in a secure manner.

Initial Setup

Run the ./setup/install.sh script. This will install the few dependencies and run the ./setup/setup_database.py script. The setup_database.py file contains various setting that you can manually modify, and then initializes the ./data/empire.db backend database. No additional configuration should be needed- hopefully everything works out of the box.
Running ./empire will start Empire, and ./empire –debug will generate a verbose debug log at ./empire.debug. The included ./data/reset.sh will reset/reinitialize the database and launch Empire in debug mode.

Main Menu

Once you hit the main menu, you’ll see the number of active agents, listeners, and loaded modules.

The help command should work for all menus, and almost everything that can be tab-completable is (menu commands, agent names, local file paths where relevant, etc.).

You can ctrl+C to rage quit at any point. Starting Empire back up should preserve existing communicating agents, and any existing listeners will be restarted (as their config is stored in the sqlite backend database).

Listeners 101

The first thing you need to do it set up a local listener. The listeners command will jump you to the listener management menu. Any active listeners will be displayed, and this information can be redisplayed at any time with the list command. The info command will display the currently set listener options.

The info command will display the currently configured listener options. Set your host/port by doing something like set Host This is tab-completable, and you can also use domain names here). The port will automatically be pulled out, and the backend will detect if you’re doing a HTTP or HTTPS listener. For HTTPS listeners, you must first set the CertPath to be a local .pem file. The provided ./data/cert.sh script will generate a self-signed cert and place it in ./data/empire.pem.

Set optional and WorkingHours, KillDate, DefaultDelay, and DefaultJitter for the listener, as well as whatever name you want it to be referred to as. You can then type execute to start the listener. If the name is already taken, a nameX variant will be used, and Empire will alert you if the port is already in use.

Stagers 101

The staging process and a complete description of the available stagers is detailed here and here.

Empire implements various stagers in a modular format in ./lib/stagers/*. These include dlls, macros, one-liners, and more. To use a stager, from the main, listeners, or agents menu, use usestager <tab> to tab-complete the set of available stagers, and you’ll be taken to the individual stager’s menu. The UI here functions similarly to the post module menu, i.e set/unset/info and generate to generate the particular output code.

For UserAgent and proxy options, default uses the system defaults, none clears that option from being used in the stager, and anything else is assumed to be a custom setting (note, this last bit isn’t properly implemented for proxy settings yet). From the Listeners menu, you can run the launcher [listener ID/name]alias to generate the stage0 launcher for a particular listener (this is the stagers/launcher module in the background). This command can be run from a command prompt on any machine to kick off the staging process. (NOTE: you will need to right click cmd.exe and choose “run as administrator” before pasting/running this command if you want to use modules that require administrative privileges). Our PowerShell version of BypassUAC module is in the works but not 100% complete yet.

Agents 101

You should see a status message when an agent checks in (i.e. [+] Initial agent CGUBKC1R3YLHZM4V from now active). Jump to the Agents menu with agents. Basic information on active agents should be displayed. Various commands can be executed on specific agent IDs or all from the agent menu, i.e. kill all. To interact with an agent, use interact AGENT_NAME. Agent names should be tab-completable for all commands.

In an Agent menu, info will display more detailed agent information, and help will display all agent commands. If a typed command isn’t resolved, Empire will try to interpret it as a shell command (like ps). You can cd directories, upload/download files, and rename NEW_NAME.
For each registered agent, a ./downloads/AGENT_NAME/ folder is created (this folder is renamed with an agent rename). An ./agent.log is created here with timestamped commands/results for agent communication. Downloads/module outputs are broken out into relevant folders here as well.
When you’re finished with an agent, use exit from the Agent menu or kill NAME/all from the Agents menu. You’ll get a red notification when the agent exits, and the agent will be removed from the interactive list after.

Modules 101

To see available modules, type usemodule <tab>. To search module names/descriptions, use searchmodule privesc and matching module names/descriptions will be output.

To use a module, for example netview from PowerView, type usemodule situational_awareness/network/sharefinder and press enter. info will display all current module options.

To set an option, like the domain for sharefinder, use set Domain testlab.local. The Agent argument is always required, and should be auto-filled from jumping to a module from an agent menu. You can also set Agent <tab> to tab-complete an agent name. execute will task the agent to execute the module, and back will return you to the agent’s main menu. Results will be displayed as they come back.


In addition to formalized modules, you are able to simply import and use a .ps1 script in your remote empire agent. Use the scriptimport ./path/ command to import the script. The script will be imported and any functions accessible to the script will now be tab completable using the “scriptcmd” command in the agent. This works well for very large scripts with lots of functions that you do not want to break into a module.

Subscribe via e-mail for updates!