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.
Please first review the existing Empire issues to see if the error was resolved with a fix in the development branch or if we chose not to fix the error for some reason.
The more information you provide in a Github issue the easier it will be for us to track down and fix the problem:
- Please provide the version of Empire you are using.
- Please provide the OS and Python versions that you are using.
- Please describe the expected behavior and the encountered error.
- The more detail the better!
- Include any actions taken just prior to the error.
- 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.
- 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 powershell_template.py or 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.
- For more in-depth docs on developing modules, see the Module Development docs
- As of Empire 4.4, we are using 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
- Isort is a Python utility that sorts and formats imports.
- After implementing your changes:
- run
black .
(orpoetry run black .
). - run
isort .
(orpoetry run isort .
).
- run
- The repo is also configured to use pre-commit to automatically format code.
- Once you have pre-commit installed, you can run
pre-commit install
to install the pre-commit hooks. - Then pre-commit will execute black and isort automatically before committing.
- Once you have pre-commit installed, you can run