thepowerofagod / empire

Empire is a PowerShell and Python 3.x post-exploitation framework.

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

Documentation

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 original 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 to 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.

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 Docs for more instructions on installing and using with Empire. 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!

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.

• 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.
• 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