Merge branch 'BC-SECURITY:main' into master

.dockerignore

@@ -1,6 +1,7 @@
 # Git
-.git
+**.git
 .gitignore
+.github
 
 # CI
 .codeclimate.yml

.github/CONTRIBUTING.md

@@ -17,14 +17,48 @@ 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.
 
+## Documentation
 
-## Submitting Modules
+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.
 
-* Submit pull requests to the [dev branch](https://github.com/powershellempire/Empire/tree/dev). After testing, changes will be merged to master.
-* Base modules on the template at [./modules/template.py](https://github.com/PowerShellEmpire/Empire/blob/dev/lib/modules/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).
+
+## 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.
+
+
+### 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).
-* Use [approved PowerShell verbs](https://technet.microsoft.com/en-us/library/ms714428(v=vs.85).aspx) for any functions.
-* PowerShell Version 2 compatibility is **STRONGLY** preferred. 
-* TEST YOUR MODULE! Be sure to run it from an Empire agent before submitting a pull to ensure everything is working correctly.
-* For additional guidelines for your PowerShell code itself, check out the [PowerSploit style guide](https://github.com/PowerShellMafia/PowerSploit/blob/master/README.md).
+* Use [approved PowerShell verbs](https://docs.microsoft.com/en-us/powershell/scripting/developer/cmdlet/approved-verbs-for-windows-powershell-commands?view=powershell-7.1) 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](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
+
+* We are using [psf/black](https://github.com/psf/black) for code formatting.
+* We are using [charliermarsh/ruff](https://github.com/charliermarsh/ruff) for linting.
+* After implementing your changes:
+    1. run `ruff . --fix` (or `poetry run ruff . --fix`).
+    2. run `black .` (or `poetry run black .`).
+* The repo is also configured to use [pre-commit](https://pre-commit.com/) 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 ruff automatically before committing.
+
+### 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`.
+
+## Upgrading dependencies
+Dependencies can be upgraded using [poetry-plugin-up](https://github.com/MousaZeidBaker/poetry-plugin-up).

.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -0,0 +1,72 @@
+name: 🐞 Bug
+description: File a bug/issue
+title: "[BUG] <title>"
+labels: ["bug"]
+body:
+- type: checkboxes
+  attributes:
+    label: Is there an existing issue for this?
+    description: Please search to see if an issue already exists for the bug you encountered.
+    options:
+    - label: I have searched the existing issues
+      required: true
+- type: input
+  attributes:
+    label: Empire Version
+    description: What version of Empire are you using?
+  validations:
+    required: true
+- type: input
+  attributes:
+    label: Python Version
+    description: What version of Python are you using?
+  validations:
+    required: true
+- type: input
+  attributes:
+    label: Operating System
+    description: What operating system are you using?
+  validations:
+    required: true
+- type: dropdown
+  attributes:
+    label: Database
+    description: What database are you using?
+    options:
+      - SQLite
+      - MySQL
+      - MariaDB
+  validations:
+    required: true
+- type: textarea
+  attributes:
+    label: Current Behavior
+    description: A concise description of what you're experiencing.
+  validations:
+    required: true
+- type: textarea
+  attributes:
+    label: Expected Behavior
+    description: A concise description of what you expected to happen.
+  validations:
+    required: true
+- type: textarea
+  attributes:
+    label: Steps To Reproduce
+    description: Steps to reproduce the behavior.
+    placeholder: |
+      1. In this environment...
+      1. With this config...
+      1. Run '...'
+      1. See error...
+  validations:
+    required: true
+- type: textarea
+  attributes:
+    label: Anything else?
+    description: |
+      Links? References? Anything that will give us more context about the issue you are encountering!
+
+      Tip: You can attach images or log files by clicking this area to highlight it and then dragging files in.
+  validations:
+    required: false

.github/ISSUE_TEMPLATE/feature_request.yaml

@@ -0,0 +1,29 @@
+name: 🚀 Feature Request
+description: File a bug/issue
+title: "[FEATURE REQUEST] <title>"
+labels: ["enhancement"]
+body:
+- type: textarea
+  attributes:
+    label: Description
+    description: A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+  validations:
+    required: true
+- type: textarea
+  attributes:
+    label: Solution
+    description: A clear and concise description of what you want to happen.
+  validations:
+    required: true
+- type: textarea
+  attributes:
+    label: Alternatives
+    description: A clear and concise description of any alternative solutions or features you've considered.
+  validations:
+    required: false
+- type: textarea
+  attributes:
+    label: Additional Context
+    description: Add any other context or screenshots about the feature request here.
+  validations:
+    required: false

.github/actions/clean-merge/action.yml

@@ -0,0 +1,50 @@
+name: 'Clean Merge'
+description: 'Merge a branch into another branch without creating a merge commit. Fail if the merge would create merge conflicts.'
+inputs:
+  from-branch:
+    description: 'The branch to merge from'
+    required: true
+  to-branch:
+    description: 'The branch to merge to'
+    required: true
+  push-repo:
+    description: 'The remote to push to'
+    required: true
+runs:
+  using: "composite"
+  steps:
+    - name: Checkout ${{ inputs.to-branch }}
+      shell: bash
+      run: |
+        git checkout ${{ inputs.to-branch }}
+
+        # reset submodules https://gist.github.com/nicktoumpelis/11214362
+        git clean -xfd
+        git submodule foreach --recursive git clean -xfd
+        git reset --hard
+        git submodule foreach --recursive git reset --hard
+        git submodule update --init --recursive
+    - name: Merge ${{ inputs.from-branch }} branch to ${{ inputs.to-branch }}
+      shell: '/bin/bash {0}'
+      run: |
+        git merge --no-edit ${{ inputs.from-branch }}
+        if [ $? -ne 0 ]; then
+          echo "Merge failed. Aborting. This is likely caused by a conflict and the merge must be done manually."
+          exit 1
+        fi
+
+        git diff ${{ inputs.push-repo }}/${{ inputs.to-branch }} --exit-code --quiet
+        if [ $? -eq 0 ]; then
+          echo "No changes needed to merge."
+          echo "MERGE_STATUS=NO_CHANGES" >> $GITHUB_ENV
+        else
+          echo "Changes needed to merge."
+          echo "MERGE_STATUS=CHANGES" >> $GITHUB_ENV
+        fi
+        exit 0
+    - name: Push ${{ inputs.to-branch }} to GitHub
+      if: ${{ env.MERGE_STATUS == 'CHANGES' }}
+      shell: bash
+      run: |
+        git push ${{ inputs.push-repo }} ${{ inputs.to-branch }}
+        echo "MERGE_STATUS=NO_CHANGES" >> $GITHUB_ENV

.github/actions/update-starkiller/action.yml

@@ -0,0 +1,41 @@
+name: 'Update Starkiller'
+description: 'Updates the config.yaml to the specified version and commits the change.'
+inputs:
+  starkiller-version:
+    description: 'The starkiller ref to use'
+    required: true
+  app-version:
+    description: 'The changelog section to update'
+    required: true
+  repo:
+    description: "The starkiller repo to use. If not set, doesn't update the field."
+    required: false
+  changelog-path:
+    description: "The changelog path"
+    default: CHANGELOG.md
+runs:
+  using: "composite"
+  steps:
+    # This is technically only needed for the first time we update the public repo, as a bootstrap.
+    # After that, the submodule is already initialized to the right repo.
+    - name: Update config.yaml repo
+      if: ${{ inputs.repo }}
+      shell: bash
+      run: |
+        sed -i "s|repo:.*|repo: ${{ inputs.repo }}|" empire/server/config.yaml
+    - name: Update config.yaml ref
+      shell: bash
+      # this depends on there not being any other keys in the config named ref
+      # if there are, this will break. We could be safer to load/dump the yaml,
+      # but would lose the comments.
+      run: |
+        sed -i "s/ref: .*/ref: ${{ inputs.starkiller-version }}/" empire/server/config.yaml
+    - name: Update changelog
+      shell: bash
+      run: |
+        sed -i '/## \[${{ inputs.app-version }}\]/a -   Updated Starkiller to ${{ inputs.starkiller-version }}' ${{ inputs.changelog-path }}
+    - name: Commit changes
+      shell: bash
+      run: |
+        git add -A
+        git commit --message "Update starkiller version to ${{ inputs.starkiller-version }}"