Combine docs

.github/CONTRIBUTING.md

@@ -17,12 +17,24 @@ The more information you provide in a Github issue the easier it will be for us
   * Please post a screenshot of the error, a link to a Pastebin dump of the error, or embedded text of the error.
 * Any additional information.
 
-## Where should I branch my code?
+## Documentation
+
+Documentation is the `docs/` directory and syncs with [GitBook](https://bc-security.gitbook.io/empire-wiki/).
+The documentation is written in [Markdown](https://www.markdownguide.org/basic-syntax/).
+Please submit your documentation with your code changes if applicable.
+The `main` branch in `BC-SECURITY/Empire` automatically syncs.
+
+
+## Submitting Code
+
+### Where should I branch my code?
+
 * Submit pull requests to the [main branch](https://github.com/BC-SECURITY/Empire/tree/main). After testing, changes will be merged to `main`.
   * Sponsors Repo: Submit pull requests to `private-main` for most cases. `sponsors-main` for sponsor specific changes, `kali-main` for kali specific changes.
 
 
-## Submitting Modules
+### Modules
+
 * Depending on what you're working on, base your module on [powershell_template.py](https://github.com/BC-SECURITY/Empire/blob/master/empire/server/modules/powershell_template.py) or [python_template.py](https://github.com/BC-SECURITY/Empire/blob/master/empire/server/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](https://github.com/PowerShellEmpire/Empire/blob/0cbdb165a29e4a65ad8dddf03f6f0e36c33a7350/lib/modules/situational_awareness/network/powerview/get_user.py#L111).
 * 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](https://github.com/PowerShellEmpire/Empire/blob/0cbdb165a29e4a65ad8dddf03f6f0e36c33a7350/lib/modules/situational_awareness/network/powerview/get_user.py#L85-L95).
@@ -31,7 +43,8 @@ The more information you provide in a Github issue the easier it will be for us
 * For additional guidelines for your PowerShell code itself, check out the [PowerSploit style guide](https://github.com/PowerShellMafia/PowerSploit/blob/master/README.md).
 * For more in-depth docs on developing modules, see the [Module Development docs](https://bc-security.gitbook.io/empire-wiki/module-development)
 
-## Code Formatting and Linting
+### Code Formatting and Linting
+
 * As of Empire 4.4, we are using [psf/black](https://github.com/psf/black) for code formatting.
     * Black is a Python code formatter that helps to keep the codebase uniform and easy to read
 * As of Empire 4.4, we are using [PyCQA/isort](https://github.com/PyCQA/isort)
@@ -46,8 +59,12 @@ The more information you provide in a Github issue the easier it will be for us
   * Once you have pre-commit installed, you can run `pre-commit install` to install the pre-commit hooks.
   * Then pre-commit will execute black, isort, and ruff automatically before committing.
 
-## Tests
+### Tests
 
 Please write tests for your code! We use [pytest](https://docs.pytest.org/en/latest/) for testing. Tests are located in the `tests/` directory. To run the tests, run `pytest` from the root directory of the project.
 
-For tests that take >20-30 seconds, please add the `@pytest.mark.slow` decorator to the test function. This will allow us to skip the slow tests when running the tests, unless we explicitly want to run them with `pytest --runslow`.
+For tests that take >20-30 seconds, please add the `@pytest.mark.slow` decorator to the test function. This will allow us to skip the slow tests when running the tests, unless we explicitly want to run them with `pytest --runslow`.
+
+## Upgrading dependencies
+
+Dependencies can be upgraded using [poetry-plugin-up](https://github.com/MousaZeidBaker/poetry-plugin-up).

.github/pull_request_template.md

@@ -0,0 +1,9 @@
+## Describe your changes
+
+## Issue ticket number and link (if there is one)
+
+## Checklist before requesting a review
+- [ ] I have performed a self-review of my code
+- [ ] If it is a core feature, I have added thorough tests.
+- [ ] I have added an entry to `CHANGELOG.md`
+- [ ] I have updated the documentation in `docs/` (if applicable)

docs/README.md

@@ -0,0 +1,56 @@
+# Empire
+
+![](https://user-images.githubusercontent.com/20302208/70022749-1ad2b080-154a-11ea-9d8c-1b42632fd9f9.jpg)
+
+[![Docs](https://img.shields.io/badge/Wiki-Docs-green?style=plastic\&logo=wikipedia)](https://bc-security.gitbook.io/empire-wiki/) [![Twitter URL](https://img.shields.io/twitter/follow/BCSecurity1?style=plastic\&logo=twitter)](https://twitter.com/BCSecurity1) [![YouTube URL](https://img.shields.io/youtube/channel/views/UCIV4xSntF1h1bvFt8SUfzZg?style=plastic\&logo=youtube)](https://www.youtube.com/channel/UCIV4xSntF1h1bvFt8SUfzZg) [![Discord](https://img.shields.io/discord/716165691383873536?style=plastic\&logo=discord)](https://discord.gg/P8PZPyf) [![Donate](https://img.shields.io/badge/Donate-Sponsor-blue?style=plastic\&logo=github)](https://github.com/sponsors/BC-SECURITY) [![Blog](https://img.shields.io/badge/Blog-Read%20me-orange?style=plastic\&logo=wordpress)](https://www.bc-security.org/blog)
+
+Empire is a post-exploitation and adversary emulation framework that is used to aid Red Teams and Penetration Testers. The Empire server is written in Python 3 and is modular to allow operator flexibility. Empire comes built-in with a client that can be used remotely to access the server. There is also a GUI available for remotely accessing the Empire server, [Starkiller](https://github.com/BC-SECURITY/Starkiller).
+
+## Features
+
+* Server/Client Architecture for Multiplayer Support
+* Supports GUI & CLI Clients
+* Fully encrypted communications
+* HTTP/S, Malleable HTTP, OneDrive, Dropbox, and PHP Listeners
+* Massive library (400+) of supported tools in PowerShell, C#, & Python
+* Donut Integration for shellcode generation
+* Modular plugin interface for custom server features
+* Flexible module interface for adding new tools
+* Integrated obfuscation using [ConfuserEx 2](https://github.com/mkaring/ConfuserEx) & [Invoke-Obfuscation](https://github.com/danielbohannon/Invoke-Obfuscation)
+* In-memory .NET assembly execution
+* Customizable Bypasses
+* JA3/S and JARM Evasion
+* MITRE ATT\&CK Integration
+* Integrated Roslyn compiler (Thanks to [Covenant](https://github.com/cobbr/Covenant))
+* Docker, Kali, Ubuntu, and Debian Install Support
+
+## Agents
+
+* PowerShell
+* Python 3
+* C#
+* IronPython 3
+
+## Modules
+
+* [Assembly Execution](https://github.com/BC-SECURITY/Empire/blob/master/empire/server/data/module\_source/code\_execution/Invoke-Assembly.ps1)
+* [BOF Execution](https://github.com/airbus-cert/Invoke-Bof)
+* [Mimikatz](https://github.com/gentilkiwi/mimikatz)
+* [Seatbelt](https://github.com/GhostPack/Seatbelt)
+* [Rubeus](https://github.com/GhostPack/Rubeus)
+* [SharpSploit](https://github.com/cobbr/SharpSploit)
+* [Certify](https://github.com/GhostPack/Certify)
+* [ProcessInjection](https://github.com/3xpl01tc0d3r/ProcessInjection)
+* And Many More
+
+## Sponsors
+
+&#x20;      [<img src="https://user-images.githubusercontent.com/20302208/185246508-56f4f574-5a06-4a2c-ac62-320922588dcf.png" alt="" data-size="original">](https://www.sans.org/cyber-security-courses/red-team-operations-adversary-emulation/)&#x20;
+
+&#x20;     [![](https://user-images.githubusercontent.com/20302208/208271681-235c914b-5359-426e-8a3d-903bbd018847.png)](https://www.cybrary.it/)   &#x20;
+
+## 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 changes as a pull request to the [empire-docs repository](https://github.com/BC-SECURITY/empire-docs).
+
+{% @mailchimp/mailchimpSubscribe %}

docs/SUMMARY.md

@@ -0,0 +1,50 @@
+# Table of contents
+
+* [Empire](README.md)
+* [Quickstart](quickstart/README.md)
+  * [Installation](quickstart/installation/README.md)
+    * [Empire 3 Migration](quickstart/installation/empire-3-migration.md)
+  * [Staging](quickstart/staging.md)
+  * [Configuration](quickstart/configuration/README.md)
+    * [Server](quickstart/configuration/server.md)
+    * [Client](quickstart/configuration/client.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)
+* [Logging](logging/logging.md)
+* [Interfaces](interfaces/README.md)
+  * [Client](interfaces/client/README.md)
+    * [Admin Menu](interfaces/client/admin-menu.md)
+    * [Listener Menu](interfaces/client/listener-menu.md)
+    * [Use Listener Menu](interfaces/client/use-listener-menu.md)
+    * [Use Stager Menu](interfaces/client/use-stager-menu.md)
+    * [Plugin Menu](interfaces/client/plugin-menu.md)
+    * [Use Plugin Menu](interfaces/client/use-plugin-menu.md)
+    * [Agent Menu](interfaces/client/agent-menu.md)
+    * [Interact Menu](interfaces/client/interact-menu.md)
+    * [Credential Menu](interfaces/client/credential-menu.md)
+    * [Use Module Menu](interfaces/client/use-module-menu.md)
+    * [Chat Menu](interfaces/client/chat-menu.md)
+    * [Resource Files](interfaces/client/resource-files.md)
+  * [Starkiller](interfaces/starkiller/README.md)
+    * [Introduction](interfaces/starkiller/introduction.md)
+* [Plugins](plugins/README.md)
+  * [Plugin Development](plugins/plugin-development.md)
+  * [Hooks and Filters](plugins/hooks-and-filters.md)
+* [Bypasses](bypasses.md)
+* [C#](csharp.md)
+* [Module Development](module-development/README.md)
+  * [PowerShell Modules](module-development/powershell-modules.md)
+  * [Python Modules](module-development/python-modules.md)
+  * [C# Modules](module-development/c-modules.md)
+* [Release Notes](release-notes.md)

docs/bypasses.md

@@ -0,0 +1,21 @@
+# Bypasses
+
+Bypasses are stored in yamls found in `/empire/server/bypass/` and uses a similar formatting as modules. Bypasses are currently only available to PowerShell modules and require a minimum version of PowerShell 3. Earlier version of PowerShell did not contain protections that require bypasses.
+
+When Empire first loads, it will wrie the data from the yamls to the database. The bypasses can then be edited via Starkiller or the API with the changes going only to the version stored in the database.
+
+### Example Bypasses YAML
+
+```
+name: ''
+authors:
+  - ''
+description: ''
+comments:
+  - ''
+language: powershell
+min_language_version: '3'
+script: ''
+
+
+```

docs/csharp.md

@@ -0,0 +1,83 @@
+# 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.](csharp.md#quickstart) When prompted for dotnet, type `y`.
+
+As of Empire 4.3, the dotnet SDK is installed by default with the install script and the csharpserver plugin is automatically started up.
+
+## 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:
+
+```
+useplugin csharpserver
+set status start
+execute
+```
+
+![Starting C# Plugin](https://i0.wp.com/www.bc-security.org/wp-content/uploads/2019/05/e4\_csharp\_plugin.png?resize=788%2C269\&ssl=1)
+
+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/`.
+
+![C# module execution](https://user-images.githubusercontent.com/9831420/115481326-3d2da280-a201-11eb-90d3-e00595d76c0a.png)
+
+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.
+
+![Dropdown menu for setting listener options](https://i1.wp.com/www.bc-security.org/wp-content/uploads/2019/05/e4\_uselistener\_options.png?resize=656%2C448\&ssl=1)
+
+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.
+
+![Dropdown menu for available stagers](https://i1.wp.com/www.bc-security.org/wp-content/uploads/2019/05/e4\_stager\_choices.png?resize=608%2C434\&ssl=1)
+
+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.
+
+![Information page for the C# stager](https://i1.wp.com/www.bc-security.org/wp-content/uploads/2019/05/e4\_csharp\_stager\_options.png?resize=1106%2C946\&ssl=1)
+
+![All options available for both PowerShell and C# launchers](https://i2.wp.com/www.bc-security.org/wp-content/uploads/2019/05/e4\_csharp\_stager\_info.png?resize=986%2C232\&ssl=1)
+
+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.
+
+![Message returned to Empire client when generating C# launcher](https://i2.wp.com/www.bc-security.org/wp-content/uploads/2019/05/e4\_csharp\_stager\_compile.png?resize=1170%2C90\&ssl=1)
+
+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.
+
+![Generated stager directory for the Empire client](https://i2.wp.com/www.bc-security.org/wp-content/uploads/2019/05/e4\_csharp\_exe\_location.png?resize=964%2C534\&ssl=1)
+
+## 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.
+
+![Table of active/inactive agents](https://i1.wp.com/www.bc-security.org/wp-content/uploads/2019/05/e4\_csharp\_agents.png?resize=1170%2C195\&ssl=1)
+
+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.
+
+![Dropdown menu of Empire modules](https://i1.wp.com/www.bc-security.org/wp-content/uploads/2019/05/e4\_csharp\_modules.png?resize=1170%2C409\&ssl=1)
+
+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.
+
+![PowerShell module being executed through a C# agent](https://i0.wp.com/www.bc-security.org/wp-content/uploads/2019/05/e4\_csharp\_watson.png?resize=497%2C441\&ssl=1)
+
+![Rubeus being compiled through the compiler and executed](https://i0.wp.com/www.bc-security.org/wp-content/uploads/2021/05/e4\_csharp\_rubeus-edited-1.png?resize=558%2C726\&ssl=1)
+
+![AMSI Bypass module from SharpSploit](https://i1.wp.com/www.bc-security.org/wp-content/uploads/2019/05/e4\_csharp\_amsi\_bypass.png?resize=617%2C432\&ssl=1)
+
+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.
+
+![Interactive shell within an Empire agent](https://i0.wp.com/www.bc-security.org/wp-content/uploads/2019/05/e4\_csharp\_shell.png?resize=496%2C752\&ssl=1)

docs/database/README.md

@@ -0,0 +1,14 @@
+# Database
+
+Beginning in Empire 5.0, MySQL is the default database. Trying to support multi-user setups and expanding our usage of the database started to reach limitations in SQLite. SQLite is still supported, and we run the full test suite against it, but is not recommended.
+
+For database configuration see the [Configuration](../configuration/server.md) section.
+
+## Setup
+The install script will install MySQL if you install on one of the supported operating systems. If you want to switch between MySQL and SQLite, change the `use` property in the `database` section of the configuration file.
+
+There is an environment variable `DATABASE_USE` that can be used to overwrite the `database.use` property in `config.yaml`.
+
+# Docker
+The Docker image still defaults to SQLite. To use MySQL, you can change `config.yaml` or utilize the `DATABASE_USE` enviornment variable. For example `docker run -p 3306:3306 -p 1337:1337 -e DATABASE_USE='mysql' -it bcsecurity/empire:latest`.
+The Docker image does not contain MySQL, so you will need to run a MySQL container or install MySQL on the host machine.

docs/interfaces/README.md

@@ -0,0 +1,2 @@
+# Interfaces
+