v6.4.1 into main

.github/install_tests/cst-config-debian.yaml

@@ -5,4 +5,5 @@ commandTests:
   - name: "mysql version"
     command: "mysql"
     args: ["--version"]
-    expectedOutput: ["mysql  Ver 15.*10.*-MariaDB"]
+    expectedOutput: ["mysql  Ver 15.*10.*-MariaDB|mysql from 11.*-MariaDB, client
+        15.*"]

.github/install_tests/cst-config-ubuntu.yaml

@@ -5,4 +5,4 @@ commandTests:
   - name: "mysql version"
     command: "mysql"
     args: ["--version"]
-    expectedOutput: ["mysql  Ver 8.0.*"]
+    expectedOutput: ["mysql  Ver 8\\.[04].*"]

.github/install_tests/docker-compose-install-tests.yml

@@ -35,6 +35,13 @@ services:
         BASE_IMAGE: debian:bookworm
     image: bcsecurity/empire-test-debian12
     <<: *common-platform
+  debian13:
+    build:
+      <<: *common-build
+      args:
+        BASE_IMAGE: debian:trixie
+    image: bcsecurity/empire-test-debian13
+    <<: *common-platform
   kalirolling:
     build:
       <<: *common-build

.github/install_tests/run-all-cst.sh

@@ -5,7 +5,7 @@ set -e
 # or `./run-all-cst.sh debian12` to test a single image
 # or `./run-all-cst.sh` to test all images
 
-all_images=(debian12 debian11 ubuntu2204 ubuntu2404 kalirolling parrotrolling)
+all_images=(debian13 debian12 debian11 ubuntu2204 ubuntu2404 kalirolling parrotrolling)
 
 for image in "${@:-${all_images[@]}}"
 do

.github/workflows/lint-and-test.yml

@@ -102,8 +102,7 @@ jobs:
         with:
           submodules: 'recursive'
           token: ${{ secrets.RELEASE_TOKEN }}
-      - name: Set up SSH (sponsors only)
-        if: ${{ endswith(github.repository, 'Empire-Sponsors') }}
+      - name: Set up SSH
         run: |
           eval "$(ssh-agent -s)"
           echo "SSH_AUTH_SOCK=$SSH_AUTH_SOCK" >> $GITHUB_ENV
@@ -133,7 +132,7 @@ jobs:
       matrix:
         # Because the box runs out of disk space, we can't run all tests on a single docker compose build.
         images:
-          - ['debian11', 'debian12']
+          - ['debian11', 'debian12', 'debian13']
           - ['ubuntu2204', 'ubuntu2404']
           - ['kalirolling'] # 'parrotrolling'
           # Parrot disabled for now because the apt repo is having some slowness issues.
@@ -143,8 +142,7 @@ jobs:
         with:
           submodules: 'recursive'
           depth: 0
-      - name: Set up SSH (sponsors only)
-        if: ${{ endswith(github.repository, 'Empire-Sponsors') }}
+      - name: Set up SSH
         run: |
           eval "$(ssh-agent -s)"
           echo "SSH_AUTH_SOCK=$SSH_AUTH_SOCK" >> $GITHUB_ENV
@@ -159,7 +157,7 @@ jobs:
       # To save CI time, only run these tests when the install script or deps changed
       - name: Get changed files using defaults
         id: changed-files
-        uses: tj-actions/[email protected].0
+        uses: tj-actions/[email protected].1
       - name: Build images
         if: ${{ contains(steps.changed-files.outputs.modified_files, 'setup/install.sh')
           || contains(steps.changed-files.outputs.modified_files, 'poetry.lock')

.github/workflows/release-private-start.yml

@@ -37,7 +37,7 @@ jobs:
       - name: Setup Python
         uses: actions/setup-python@v6
         with:
-          python-version: '3.9'
+          python-version: '3.12'
       - name: Setup poetry
         run: |
           curl -sL https://install.python-poetry.org | python - -y

.github/workflows/release-private-tag.yml

@@ -24,7 +24,7 @@ jobs:
       - name: Setup Python
         uses: actions/setup-python@v6
         with:
-          python-version: '3.9'
+          python-version: '3.12'
       - name: Setup poetry
         run: |
           curl -sL https://install.python-poetry.org | python - -y

.gitignore

@@ -57,3 +57,5 @@ addons/
 __pycache__/
 workspace.xml
 starkiller-dist.tar.gz
+.worktrees/
+config.user.yaml

CHANGELOG.md

@@ -14,12 +14,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [6.4.1] - 2026-02-15
+-   Updated Starkiller to v3.3.0
+
+### Added
+
+-   Added `config.user.yaml` layering support — create a `config.user.yaml` next to `config.yaml` to override specific settings without modifying the base config
+-   Added `auto_install` option to `plugin_marketplace` config for automatic plugin installation during setup
+-   Added `server.socketio` config option to disable Socket.IO (default: `true`)
+-   Added C# spawn module with Powershell and C# executables
+
+### Fixed
+
+-   Fixed Go agent failing to run powershell modules that are too long
+-   Removed StagerURI from http listeners
+-   Fixed HTTP hop listener not getting proper host address
+-   Fixed arguments for bof module netloggedon
+-   Fixed option ComputerName being removed from modules without custom_generate
+-   Fixed missing CompatibleDotNetVersions for ShellcmdRunas and ShellRunAs
+-   Fixed missing CompatibleDotNetVersions for Assembly and AssemblyReflect
+-   Fixed parameter error when running Sharpsploit.Assembly
+
+## [6.4.0] - 2026-01-18
+
+
 ### Added
 
 -   Added Debian 13 support
 -   Added error message if running `ps-empire server` under root without `-f`
--   Added Get-ClipboardHistory PowerShell module to enumerate Windows clipboard history (Windows 10/11) via WinRT APIs
+-   Added `hide_disabled` parameter to `GET /api/v2/modules/` endpoint
+-   Added a health check endpoint at `/healthz`
+-   Added `module_options` to `AgentTask` and `plugin_options` to `PluginTask` for better execution tracking
+-   Added `-c` (compile from source) and `-o` (override) options to `ps-empire`
 -   Added local ticket support to Invoke-PSRemoting module
+-   Added an endpoint to stop background jobs on agents
+-   Added foreground C# tasking support to IronPython agent
+-   Added Get-ClipboardHistory PowerShell module to enumerate Windows clipboard history (Windows 10/11) via WinRT APIs
+
+### Changed
+
+-   Updated the module categeories to be more clear
+-   Updated FastAPI deps to use Annotated types
+-   Changed StratumMiner, Moriarty, and Sharpup to background tasks
+-   Updated empire-compiler to v0.4.3
+
+### Fixed
+
+-   Fixed results not coming back properly for powershell agents on C# background tasks
 
 ## [6.3.0] - 2025-12-11
 -   Updated Starkiller to v3.2.0
@@ -1206,7 +1247,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 -   Updated shellcoderdi to newest version (@Cx01N)
 -   Added a Nim launcher (@Hubbl3)
 
-[Unreleased]: https://github.com/BC-SECURITY/Empire-Sponsors/compare/v6.3.0...HEAD
+[Unreleased]: https://github.com/BC-SECURITY/Empire-Sponsors/compare/v6.4.1...HEAD
+
+[6.4.1]: https://github.com/BC-SECURITY/Empire-Sponsors/compare/v6.4.0...v6.4.1
+
+[6.4.0]: https://github.com/BC-SECURITY/Empire-Sponsors/compare/v6.3.0...v6.4.0
 
 [6.3.0]: https://github.com/BC-SECURITY/Empire-Sponsors/compare/v6.2.1...v6.3.0
 

README.md

@@ -29,7 +29,7 @@ Empire is a post-exploitation and adversary emulation framework that is used to
 - JA3/S and JARM Evasion
 - MITRE ATT&CK Integration
 - Integrated Roslyn compiler (Thanks to [Covenant](https://github.com/cobbr/Covenant))
-- Docker, Kali, ParrotOS, Ubuntu 22.04/24.04, and Debian 11/12 Install Support
+- Docker, Kali, ParrotOS, Ubuntu 22.04/24.04, and Debian 11/12/13 Install Support
 
 ### Agents
 - PowerShell

docs/listeners/http.md

@@ -54,14 +54,13 @@ Empire provides JA3 evasion to help prevent detection by TLS fingerprinting tool
 
 Empire provides additional settings to customize listener behavior:
 
-* CertPath – Path to an SSL certificate for HTTPS listeners.
-* KillDate – The expiration date when the agent will automatically exit (MM/DD/YYYY).
-* WorkingHours – Defines when the agent will operate (09:00-17:00).
-* Cookie – Custom cookie name used for agent communication.
-* StagerURI – The URI for the stager (must use /download/, e.g., /download/stager.php).
-* UserAgent – Defines the user-agent string used for staging requests (default, none, or other).
-* Proxy – Proxy settings for agent communication.
-* ProxyCreds – Proxy credentials (domain\username:password).
+- CertPath – Path to an SSL certificate for HTTPS listeners.
+- KillDate – The expiration date when the agent will automatically exit (MM/DD/YYYY).
+- WorkingHours – Defines when the agent will operate (09:00-17:00).
+- Cookie – Custom cookie name used for agent communication.
+- UserAgent – Defines the user-agent string used for staging requests (default, none, or other).
+- Proxy – Proxy settings for agent communication.
+- ProxyCreds – Proxy credentials (domain\username:password).
 
 ## Default Response Page
 

docs/plugins/README.md

@@ -7,6 +7,28 @@ This allows anyone to build or add community projects to extend Empire functiona
 
 Plugin installation is available through the Starkiller __Plugin Marketplace__.
 
+### Auto-Installing Plugins
+
+Plugins can be automatically installed during `./ps-empire setup` by adding them to the
+`auto_install` list in `config.yaml`. This is useful for Docker builds or automated deployments
+where plugins need to be pre-installed without manual API calls.
+
+```yaml
+plugin_marketplace:
+  registries:
+    - name: BC-SECURITY
+      git_url: https://github.com/BC-SECURITY/Empire-Plugin-Registry.git
+      ref: main
+      file: registry.yaml
+  auto_install:
+    - name: Report Generation Plugin
+      version: '2.0.0'
+      registry: BC-SECURITY
+```
+
+Each entry requires `name`, `version`, and `registry` matching a plugin in the configured registries.
+Plugins that are already installed will be skipped.
+
 ### Additional Dependencies
 
 If a plugin requires additional Python dependencies, the plugin page will show a warning

docs/plugins/development/execution.md

@@ -4,9 +4,10 @@
 The execute function is called when the plugin is executed via the API. The execute function is passed the following arguments:
 
 * command - A dict of the command arguments, already parsed and validated by the core Empire code
-* kwargs - Additional arguments that may be passed in by the core Empire code. Right now there are only two.
+* kwargs - Additional arguments that may be passed in by the core Empire code.
   * user - The user database object for the user that is executing the plugin
   * db - The database session object
+  * plugin_options - A dict of the original options passed to the plugin execution
 
 ### Error Handling
 

docs/plugins/development/plugin-tasks.md

@@ -12,6 +12,7 @@ from empire.server.core.db import models
 def execute(self, command, **kwargs):
     user = kwargs.get('user', None)
     db = kwargs.get('db', None)
+    plugin_options = kwargs.get('plugin_options', None)
 
     input = 'Example plugin execution.'
 
@@ -21,6 +22,7 @@ def execute(self, command, **kwargs):
       input_full=input,
       user_id=user.id,
       status=models.PluginTaskStatus.completed,
+      plugin_options=plugin_options,
     )
 
     db.add(plugin_task)

docs/quickstart/installation/README.md

@@ -5,7 +5,7 @@ We recommend using the installation script or the Docker images to run Empire. A
 The following operating systems have been tested for Empire compatibility.
 
 * 22.04 / 24.04
-* Debian 11 / 12
+* Debian 11 / 12 / 13
 * Kali Linux
 * ParrotOS
 
@@ -28,6 +28,8 @@ When running the ps-empire installation script, you can use the following option
 
 * `-y`: Automatically answer 'Yes' to all prompts during installation. This is useful if you want to install all optional dependencies without being prompted for confirmation.
 * `-f`: Force the installation as root. Normally, Empire does not recommend installing as the root user for security reasons. However, if you need to bypass this restriction, you can use this flag. **Note: Using this option is not recommended unless absolutely necessary.**
+* `-c`: Compile Empire-Compiler from source.
+* `-o`: Override OS check. This flag allows the installation script to proceed even if the detected operating system is not officially supported.
 * `-h`: Displays the help text.
 
 ```
@@ -100,4 +102,33 @@ All image versions can be found at: [https://hub.docker.com/r/bcsecurity/empire/
 
 ## Community-Supported Operating Systems
 
-At this time, we are choosing to only support Kali, ParrotOS, Debian 11/12, and Ubuntu 22.04/24.04 installations, however, we will accept pull requests that fix issues or provide installation scripts specific to other operating systems to this wiki.
+At this time, we are choosing to only support Kali, ParrotOS, Debian 11/12/13, and Ubuntu 22.04/24.04 installations, however, we will accept pull requests that fix issues or provide installation scripts specific to other operating systems to this wiki.
+
+## Common Issues
+
+
+### Issue
+
+```
+Current Python version (3.12.2) is not allowed by the project (>=3.13,<3.14).
+Please change python executable via the "env use" command.
+```
+
+#### Solution
+
+```
+sudo rm -rf .venv
+poetry install
+```
+
+
+### Issue
+
+```
+[*] Updating goenv
+fatal: not a git repository (or any of the parent directories): git
+```
+
+#### Solution
+
+Open a new terminal, the install script should have set `$GOENV_ROOT` in your bashrc or zshrc file.

docs/quickstart/server.md

@@ -4,6 +4,32 @@ The Server configuration is managed via [empire/server/config.yaml](https://gith
 
 Once launched, Empire checks for user write permissions on paths specified in `config.yaml`. If the current user does not have write permissions on these paths, `~/.empire` will be set as fallback parent directory and the configuration file will be updated as well. If `empire-priv.key` and `empire-chain.pem` are not found in \~/.local/share/empire directory, self-signed certs will be generated.
 
+
+## User Config Overrides
+
+To customize settings without modifying `config.yaml`, create a `config.user.yaml` file in the same directory as the base config (e.g. `~/.config/empire/config.user.yaml`). This file only needs to contain the settings you want to override — everything else falls through to the base config.
+
+For example, to override the API port and database type:
+
+```yaml
+api:
+  port: 8443
+database:
+  use: mysql
+  mysql:
+    password: my_secret_password
+```
+
+The config priority order (first wins):
+1. Environment variables (`EMPIRE_*`, e.g. `EMPIRE_API__PORT=8443`)
+2. `.env` file
+3. `config.user.yaml` (user overrides)
+4. `config.yaml` (base defaults)
+
+Nested settings are deep-merged: overriding `database.mysql.password` in `config.user.yaml` does not affect sibling fields like `database.mysql.username`. Lists are replaced entirely rather than appended.
+
+If using `--config /path/to/config.yaml`, Empire looks for `config.user.yaml` in the same directory as the specified config file.
+
 * **suppress-self-cert-warning** - Suppress the http warnings when launching an Empire instance that uses a self-signed cert.
 * **api** - Configure the RESTful API.
 

empire.py

@@ -1,26 +1,56 @@
 #! /usr/bin/env python3
 
+import logging
 import sys
 
 from empire import arguments
+from empire.server.common import empire
 from empire.server.core.config import config_manager
 from empire.server.core.config.data_manager import (
     sync_empire_compiler,
     sync_plugin_registry,
     sync_starkiller,
 )
+from empire.server.core.db import base
+from empire.server.core.db.base import SessionLocal
+from empire.server.core.exceptions import PluginValidationException
+from empire.server.server import run
+
+log = logging.getLogger(__name__)
 
 if __name__ == "__main__":
     args = arguments.args
 
     if args.subparser_name == "server":
-        from empire.server import server
-
-        server.run(args)
+        run(args)
     if args.subparser_name == "setup":
         sync_starkiller(config_manager.empire_config.starkiller)
         sync_empire_compiler(config_manager.empire_config.empire_compiler)
         for registry in config_manager.empire_config.plugin_marketplace.registries:
             sync_plugin_registry(registry)
 
+        auto_install = config_manager.empire_config.plugin_marketplace.auto_install
+        if auto_install:
+            base.startup_db()
+            main = empire.MainMenu(args=args)
+
+            with SessionLocal.begin() as db:
+                for entry in auto_install:
+                    try:
+                        main.pluginregistriesv2.install_plugin(
+                            db, entry.name, entry.version, entry.registry
+                        )
+                        log.info(
+                            f"Auto-install: plugin '{entry.name}' v{entry.version} installed"
+                        )
+                    except PluginValidationException as e:
+                        log.info(f"Auto-install: skipping '{entry.name}': {e}")
+                    except Exception:
+                        log.error(
+                            f"Auto-install: failed to install '{entry.name}'",
+                            exc_info=True,
+                        )
+
+            main.shutdown()
+
     sys.exit(0)