forked from BC-SECURITY/empire-docs
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
b247cbd
commit fcdf14f
Showing
26 changed files
with
3,772 additions
and
2 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,2 +1,26 @@ | ||
| # README | ||
| # Empire | ||
|
|
||
|
|
||
|
|
||
|  | ||
|
|
||
|      [](https://twitter.com/BCSecurity1) | ||
|
|
||
| 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](https://www.youtube.com/watch?v=Pq9t59w0mUI) 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](https://github.com/BC-SECURITY/DEFCON27). | ||
|
|
||
| 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](http://www.powershellempire.com/?page_id=2) 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 [Empire@BC-Security.org](mailto:Empire@BC-Security.org). | ||
|
|
||
| Empire is currently being developed and maintained by [@Cx01N](https://twitter.com/Cx01N_), [@Hubbl3](https://twitter.com/_Hubbl3), & [@Vinnybod](https://twitter.com/_vinnybod). While the original Empire project is no longer maintained, this fork is maintained by [@bcsecurity1](https://twitter.com/BCSecurity1). Please reach out to us on our [Discord](https://discord.gg/P8PZPyf) if you have any questions or want to talk about offensive security. | ||
|
|
||
| Thank you to the original team of developers: [@harmj0y](https://twitter.com/harmj0y), [@sixdub](https://twitter.com/sixdub), [@enigma0x3](https://twitter.com/enigma0x3), [@rvrsh3ll](https://twitter.com/424f424f), [@killswitch\_gui](https://twitter.com/killswitch_gui), & [@xorrior](https://twitter.com/xorrior) | ||
|
|
||
| Please reach out to us on our [Discord](https://discord.gg/P8PZPyf) if you have any questions or talk about offensive security. | ||
|
|
||
| ### Help us Improve! | ||
|
|
||
| This documentation was organized and built by the PowerShell Empire development team. It is neither complete nor perfect, so any suggestions, corrections, or additions from the community would be greatly appreciated. Please submit any Wiki changes as [Empire Pull Requests](https://github.com/BC-SECURITY/Empire/pulls) using the [Wiki directory](wiki). | ||
|
|
||
| Contact us by email at Empire@BC-Security.org with any drafted wiki pages or suggested modifications. | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,4 +1,28 @@ | ||
| # Table of contents | ||
|
|
||
| * [README](README.md) | ||
| * [Empire](README.md) | ||
| * [Quickstart](quickstart/README.md) | ||
| * [Installation](quickstart/installation.md) | ||
| * [Staging](quickstart/staging.md) | ||
| * [Configuration](quickstart/configuration.md) | ||
| * [RESTful API](restful-api/README.md) | ||
| * [Admin-Functionality](restful-api/admin-functionality.md) | ||
| * [Listeners](restful-api/listeners.md) | ||
| * [Stagers](restful-api/stagers.md) | ||
| * [Agents](restful-api/agents.md) | ||
| * [Modules](restful-api/modules.md) | ||
| * [Credentials](restful-api/credentials.md) | ||
| * [Reporting](restful-api/reporting.md) | ||
| * [User-Management](restful-api/user-management.md) | ||
| * [Listeners](listeners/README.md) | ||
| * [Dropbox](listeners/dropbox.md) | ||
| * [OneDrive](listeners/onedrive.md) | ||
| * [Malleable C2](listeners/malleable-c2.md) | ||
| * [Interfaces](interfaces/README.md) | ||
| * [Client](interfaces/client.md) | ||
| * [Starkiller](interfaces/starkiller.md) | ||
| * [Plugins](plugins.md) | ||
| * [C\#](c.md) | ||
| * [Module Development](module-development.md) | ||
| * [Release Notes](release-notes.md) | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,82 @@ | ||
| # C\# | ||
|
|
||
| Empire 4 combines the power of [Covenant ](https://github.com/cobbr/Covenant)and [Sharpire](https://github.com/0xbadjuju/Sharpire) to give us C\# agents. In order to be able to run the C\# plugin and Covenant compiler, you need to have the dotnet 3.1 SDK installed on your computer. You can follow the [Microsoft Documentation](https://docs.microsoft.com/en-us/dotnet/core/install/linux-debian#supported-distributions) or run the install script mentioned above. When prompted for dotnet, type `y`. | ||
|
|
||
| ## Quickstart | ||
|
|
||
| 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: | ||
|
|
||
| ```text | ||
| useplugin csharpserver | ||
| set status start | ||
| execute | ||
| ``` | ||
|
|
||
|  | ||
|
|
||
| To get a stager for a C\# agent: | ||
|
|
||
| ```text | ||
| 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/`. | ||
|
|
||
|  | ||
|
|
||
| We found that not every engagement requires the use of installing dotnet. Since it takes up a non-trivial amount of space, we decided that we would make installing dotnet and using the C\# functionality in Empire optional, at least for the moment. At some point, we may integrate the C\# server directly into the Empire codebase, but for now, it is contained in a plugin. When you first boot up the C\# server, it will generate the backend compiler. | ||
|
|
||
| ## Shared Code Components \(Covenant Roslyn Compiler\) | ||
|
|
||
| When deciding to add in C\# capability, we wanted to support in-place compilation instead of requiring a user to launch a secondary program and open an outputted project file to be able to use the resources. This process is tedious and not really workable for an engagement. Instead, we wanted to implement something like Covenant. After some work, we realized that instead of having something LIKE the Covenant Roslyn Compiler, we could just use the Covenant compiler. | ||
|
|
||
| This saved us a lot of work but, more importantly, enabled us to further our goal of making Empire interoperable with as many open source projects as possible. We think that making projects interoperable encourages more community contributions, makes upgrades easier and provides more flexibility for operators to move between projects as engagements require without having to relearn entire new codebases and project nuances. So with the integration of the Covenant Roslyn Compiler, Empire now supports the use of Covenant Task files. These tasks can be used with BOTH the C\# agent and PowerShell agents. Now we will explore all the features currently available for the C\# agent. | ||
|
|
||
| ## Setting up a Launcher | ||
|
|
||
| You will need to start a listener for the agent to communicate with. You’ll notice that the “set” command now offers a dropdown list of suggested options and values. You can type `uselistener` to get a list of available listener options, but we will be using the http listener for this example. | ||
|
|
||
|  | ||
|
|
||
| Once the listener is started, you will need to generate a launcher to deploy the agent. The command `usestager` will display all the available stager options. At the moment, C\# agents will only work with the csharp\_exe stager. | ||
|
|
||
|  | ||
|
|
||
| The csharp\_exe stager was originally created by [Elitest](https://github.com/elitest) as a C\# stage 0 that launched a PowerShell agent. Hubbl3 created a purely C\# stager that leverages the [Sharpire Project](https://github.com/0xbadjuju/Sharpire), which was an implementation of the Empire Agent in C\#. The C\# launcher, known as Sharpire, is packaged within this stager and can be changed based on setting the stager language to PowerShell or CSharp. | ||
|
|
||
|  | ||
|
|
||
|  | ||
|
|
||
| Many of the options traditionally used by PowerShell launchers are not currently available when creating a C\# payload. For example, setting the Obfuscation and Bypasses will not affect the launchers generation and will be ignored. | ||
|
|
||
|  | ||
|
|
||
| New in Empire 4.0, files that are generated within Empire will be loaded into a client folder called “generated-stagers” which is located in the client directory. | ||
|
|
||
|  | ||
|
|
||
| ## Using the CSharp Agent | ||
|
|
||
| Launching the C\# launcher is relatively simple. All that is needed is loading the file to the target machine and executing the .EXE. This will trigger the agent to execute and will initialize the staging in memory. The client will get a notification when the agent checks back in and will be displayed on the agents page. | ||
|
|
||
|  | ||
|
|
||
| Typing `interact` will allow users to interact with the agent and send commands to it. A dropdown list of active agents will be displayed, so going to the agents page will not be necessary and so agent interaction can happen from any menu. | ||
|
|
||
|  | ||
|
|
||
| The command `usemodule` is how users will select modules to execute on the agent. Usemodule uses a keyword search to assist in selecting the correct module. Previously, a user had to type out the entire path to the module. The C\# modules are compiled on the fly and sent across the C2 channel to the agent on the other side. A huge advantage of the way the C\# modules were implemented is that it will allow C\# agents to run either PowerShell or C\# modules and vise versa. | ||
|
|
||
|  | ||
|
|
||
|  | ||
|
|
||
|  | ||
|
|
||
| The interactive shell menu is a new feature that creates a session for a user to send PowerShell commands within. The interactive shell parses its current working directory and allows the user to get a similar feel to a PowerShell window. | ||
|
|
||
|  | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,2 @@ | ||
| # Interfaces | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,100 @@ | ||
| # Client | ||
|
|
||
| ## **Main Menu** | ||
|
|
||
| When first loading Empire-Cli, the user will be dropped into the main menu. The only command available is `connect`. The "short way" to connect is to load the server into config.yaml and call it like `connect -c localhost`. The "long way" to connect is to provide the host, port, username, password as parameters... todo. | ||
|
|
||
|  | ||
|
|
||
| ## **Admin Menu** | ||
|
|
||
| The admin menu is an administrative menu which gives the team server admin the options to manage users and server options. The admin menu can be accessed by typing `admin` into the console. Once on this page, the admin can add/remove users from the team server and can modify the types of obfuscation the agents will use. | ||
|
|
||
| Regular users will not be able to modify settings, but will have access to accessing the notes features. Notes allow users to record information within their session and have them stored on the server. They can access their notes from any session once they are sent to the server. | ||
|
|
||
|  | ||
|
|
||
| ## **Listener Menu** | ||
|
|
||
| The listener menu gives an overview list of all active listeners. A listener can be killed by typing the command `kill <listener_name>`. | ||
|
|
||
| ## **Use Listener Menu** | ||
|
|
||
| The listener commands include: | ||
|
|
||
| * View the listener info: `info` | ||
| * Set listener settings: `set <listener_option>` | ||
| * Execute/generate the current listener: `execute` | ||
|
|
||
|  | ||
|
|
||
| ## **Use Stager Menu** | ||
|
|
||
| Empire implements various stagers in a modular format in ./lib/stagers/\*. These include DLLs, macros, one-liners, and more. To use a stager type `usestager <stager_name>` or tap tab-complete to select an available stager. The stager commands include: | ||
|
|
||
| * View the stager info: `info` | ||
| * Set stager settings: `set <stager_option>` | ||
| * Execute/generate the current stager: `execute` | ||
|
|
||
|  | ||
|
|
||
| ## **Plugin Menu** | ||
|
|
||
| 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 as long as the plugin follows the [template example](https://github.com/BC-SECURITY/Empire-Cli/blob/master/plugins/example.py). A list of Empire Plugins is located [here](https://github.com/BC-SECURITY/Empire-Cli/blob/master/plugins/PLUGINS.md). | ||
|
|
||
| The Plugins Menu, is displays all of the currently loaded plugins available to the user. You will then need to call `useplugin` to be able to access the functionality of a plugin. | ||
|
|
||
|  | ||
|
|
||
| ## **Use Plugin Menu** | ||
|
|
||
| Interacting with plugins will look very similar to you interact with modules. You will type `useplugin <plugi_name>` to load a specific plugin. Next, you can edit the options using the `set` command. Once you are done, `execute` will launch the plugin's functionality. | ||
|
|
||
|  | ||
|
|
||
| ## **Agent Menu** | ||
|
|
||
| Agents are Empire's implants that are used to interact and assign tasks and collect information. A list of active agents is displayed when entering this page and highlghts active agents green and stale agents red. From this menu, you can kill, remove, rename, and clear an agent using their respective commands. | ||
|
|
||
|  | ||
|
|
||
| ## **Interact Menu** | ||
|
|
||
| Interacting with an agent is how operators manage their implants. Usemodule is accessible from inside an agent and will prepopulate the agent in the options. The interactive shell menu can be accessed by typing `shell`, or you can run a command directly by `shell <command>`. Other options are downloading and uploading files, managing agent comms, and agent configurations. | ||
|
|
||
|  | ||
|
|
||
| ## **Shell Menu** | ||
|
|
||
| The interactive shell menu opens a shell-like environment for an agent that gives the look/feel of a real shell session. This window includes the current working directory being displayed to the user. All commands will be sent to the agent and returned to the interactive shell window. To run the interactive shell, just type `shell` inside of any agent and to exit the shell session, type `exit` to return to the agent. | ||
|
|
||
|  | ||
|
|
||
| ## **Credential Menu** | ||
|
|
||
| Empire will attempt to parse standard Mimikatz outputs and keep them in an internal credential store. Credentials can be viewed from anywhere with the `credentials` command. The credential store can effectively operate as a golden and silver ticket catalog generating the appropriate ticket on demand, storing passwords, and hashes. Credentials can be added to the database by typing `add <domain> <username> <password>`. | ||
|
|
||
|  | ||
|
|
||
| ## **Use Module Menu** | ||
|
|
||
| Modules are containers for embedding programs into PowerShell and Python scripts. This includes the following module categories: | ||
|
|
||
| * Code Execution | ||
| * Collection | ||
| * Credentials | ||
| * Lateral Movements | ||
| * Management | ||
| * Persistence | ||
| * Privilege Escalation | ||
| * Situational Awareness | ||
| * Trollsploit | ||
|
|
||
|  | ||
|
|
||
| ## **Chat Menu** | ||
|
|
||
| The chat menu interacts with the chat server in Empire. This allows users to drop in and out of the chatroom by typing `chat`. The 20 most recent messages will be displayed when you login to the room. When you are ready to return to your previous task,type `back` and you return to your previous menu. | ||
|
|
||
|  | ||
|
|
Oops, something went wrong.