Backgroundjob bugfix (#807)

Author: jfmaes

CHANGELOG.md

@@ -14,6 +14,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+-   Added a runtime `Background` option to C# modules, allowing operators to override background/foreground execution at task time
+
+### Fixed
+
+-   Fixed stop-job handlers in PowerShell and Python agents crashing when the target job doesn't exist
+
 ## [6.4.1] - 2026-02-15
 -   Fixed the `docs/quickstart/installation/README.md` file to specify a previously missing reference to Ubuntu
 -   Updated Starkiller to v3.3.0

docs/modules/module-development/README.md

@@ -32,6 +32,34 @@ options:
     strict: true
 ```
 
+## Special Options
+
+Empire reserves certain option names that receive special handling during module execution. These are filtered out of the parameters passed to the module's script and instead control how the task is dispatched or processed.
+
+### Agent
+**Required on all modules.** Identifies which agent should execute the module. This is automatically populated by Empire and should not be included in the module's script logic.
+
+### Background
+Allows the operator to override the module-level `background` field at runtime. When a module defines `background: true` in its YAML metadata, it will run as a background job by default. Adding a `Background` option lets operators choose per-execution whether to run in the foreground or background.
+
+```yaml
+options:
+  - name: Background
+    description: Run as a background job (non-blocking). Can be killed via the jobs/kill_job endpoint.
+    required: false
+    value: 'true'
+    type: bool
+    suggested_values:
+      - 'true'
+      - 'false'
+    strict: true
+```
+
+If the `Background` option is not defined on the module, the module-level `background` field is used as-is.
+
+### OutputFunction
+PowerShell-specific. Controls how module output is formatted. Substituted into the script via the `{{ OUTPUT_FUNCTION }}` placeholder. Defaults to `Out-String`. See [PowerShell Modules](powershell-modules.md) for details.
+
 ## Advanced Options
 
 Empire modules support advanced configuration for dynamic dependencies between options. For example, one option may depend on the value of another option. This is handled using the `depends_on` field.

empire/server/core/module_service.py

@@ -178,9 +178,11 @@ def execute_module(  # noqa: PLR0913 PLR0912 PLR0915
 
         extension = module.output_extension.rjust(5) if module.output_extension else ""
 
+        effective_background = cleaned_options.pop("Background", module.background)
+
         if agent.language in ("ironpython", "python"):
             if module.language == "python":
-                if module.background:
+                if effective_background:
                     module_data.command = "TASK_PYTHON_CMD_JOB"
                 else:
                     command, data = self._handle_save_file_command(
@@ -189,7 +191,7 @@ def execute_module(  # noqa: PLR0913 PLR0912 PLR0915
                     module_data.command = command
                     module_data.data = data
             elif module.language == "powershell":
-                if module.background:
+                if effective_background:
                     module_data.command = "TASK_POWERSHELL_CMD_JOB"
                 else:
                     command, data = self._handle_save_file_command(
@@ -198,7 +200,7 @@ def execute_module(  # noqa: PLR0913 PLR0912 PLR0915
                     module_data.command = command
                     module_data.data = data
             elif module.language in ("csharp", "bof"):
-                if module.background:
+                if effective_background:
                     module_data.command = "TASK_CSHARP_CMD_JOB"
                 else:
                     module_data.command = "TASK_CSHARP_CMD_WAIT"
@@ -209,7 +211,7 @@ def execute_module(  # noqa: PLR0913 PLR0912 PLR0915
 
         elif agent.language == "csharp":
             if module.language in ("csharp", "bof"):
-                if module.background:
+                if effective_background:
                     module_data.command = "TASK_CSHARP_CMD_JOB"
                 else:
                     module_data.command = "TASK_CSHARP_CMD_WAIT"
@@ -222,7 +224,7 @@ def execute_module(  # noqa: PLR0913 PLR0912 PLR0915
 
         elif agent.language == "powershell":
             if module.language == "powershell":
-                if module.background:
+                if effective_background:
                     module_data.command = "TASK_POWERSHELL_CMD_JOB"
                 else:
                     command, data = self._handle_save_file_command(
@@ -231,7 +233,7 @@ def execute_module(  # noqa: PLR0913 PLR0912 PLR0915
                     module_data.command = command
                     module_data.data = data
             elif module.language in ("csharp", "bof"):
-                if module.background:
+                if effective_background:
                     module_data.command = "TASK_CSHARP_CMD_JOB"
                 else:
                     module_data.command = "TASK_CSHARP_CMD_WAIT"
@@ -241,7 +243,7 @@ def execute_module(  # noqa: PLR0913 PLR0912 PLR0915
                 )
         elif agent.language == "go":
             if module.language == "powershell":
-                if module.background:
+                if effective_background:
                     module_data.command = "TASK_POWERSHELL_CMD_JOB"
                 else:
                     command, data = self._handle_save_file_command(
@@ -250,7 +252,7 @@ def execute_module(  # noqa: PLR0913 PLR0912 PLR0915
                     module_data.command = command
                     module_data.data = data
             elif module.language == "csharp":
-                if module.background:
+                if effective_background:
                     module_data.command = "TASK_CSHARP_CMD_JOB"
                 else:
                     module_data.command = "TASK_CSHARP_CMD_WAIT"

empire/server/data/agent/agent.ps1

@@ -1166,17 +1166,23 @@ function Invoke-Empire {
                 $JobResultID = $ResultIDs[$JobName];
 
                 try {
-                    $Results = Stop-AgentJob -JobName $JobName | fl | Out-String;
-                    # send result data if there is any
-                    if($Results -and $($Results.trim() -ne '')) {
-                        Encode-Packet -type $type -data $($Results) -ResultID $JobResultID;
+                    # Check if the job exists
+                    if ($script:tasks.ContainsKey($JobName)) {
+                        $Results = Stop-AgentJob -JobName $JobName | fl | Out-String;
+                        # send result data if there is any
+                        if($Results -and $($Results.trim() -ne '')) {
+                            Encode-Packet -type $type -data $($Results) -ResultID $JobResultID;
+                        }
+                        Encode-Packet -type 51 -data "[+] Job $JobName killed successfully." -ResultID $ResultID;
+                    } else {
+                        # Job doesn't exist - send error message
+                        Encode-Packet -type 0 -data "[!] Job $JobName not found. Available jobs: $($script:tasks.Keys -join ', ')" -ResultID $ResultID;
                     }
-                    Encode-Packet -type 51 -data "Job $JobName killed." -ResultID $JobResultID;
-                    $script:tasks[$ResultID]['status'] = 'completed'
+                    # Note: STOPJOB tasks are not background jobs, so we don't track them in $script:tasks
                 }
                 catch {
-                    Encode-Packet -type 0 -data "[!] Error in stopping job: $JobName" -ResultID $JobResultID;
-                    $script:tasks[$ResultID]['status'] = 'error'
+                    Encode-Packet -type 0 -data "[!] Error in stopping job $JobName : $_" -ResultID $ResultID;
+                    # Note: STOPJOB tasks are not background jobs, so we don't track them in $script:tasks
                 }
             }
 

empire/server/data/agent/agent.py

@@ -561,6 +561,16 @@ def stop_task(self, job_to_kill, result_id):
         Task 51
         """
         try:
+            # Check if the job exists
+            if job_to_kill not in self.tasks:
+                available_jobs = ", ".join(str(k) for k in self.tasks.keys())
+                self.packet_handler.send_message(
+                    self.packet_handler.build_response_packet(
+                        0, "[!] Job %s not found. Available jobs: %s" % (job_to_kill, available_jobs), result_id
+                    )
+                )
+                return
+
             if self.tasks[job_to_kill]['task_thread'].is_alive():
                 self.tasks[job_to_kill]['task_thread'].kill()
                 self.tasks[job_to_kill]['status'] = "stopped"
@@ -578,15 +588,15 @@ def stop_task(self, job_to_kill, result_id):
                     )
                 )
 
-            self.tasks[result_id]["status"] = "completed"
+            # Note: STOPJOB tasks are not background jobs, so we don't track them in self.tasks
 
         except Exception as e:
             self.packet_handler.send_message(
                 self.packet_handler.build_response_packet(
-                    51, "[!] Error stopping job thread: %s" % (e), result_id
+                    0, "[!] Error stopping job thread %s: %s" % (job_to_kill, e), result_id
                 )
             )
-            self.tasks[result_id]["status"] = "error"
+            # Note: STOPJOB tasks are not background jobs, so we don't track them in self.tasks
 
     def dynamic_code_execute_wait_nosave(self, data, result_id):
         """

empire/server/modules/csharp/code_execution/Assembly.yaml

@@ -27,6 +27,16 @@ options:
     description: The command-line parameters to pass to the assembly's EntryPoint.
     required: false
     value: ''
+  - name: Background
+    description: Run as a background job (non-blocking). Can be killed via the jobs/kill_job
+      endpoint.
+    required: false
+    value: 'false'
+    type: bool
+    suggested_values:
+      - 'true'
+      - 'false'
+    strict: true
 csharp:
   UnsafeCompile: false
   CompatibleDotNetVersions:

empire/server/modules/csharp/code_execution/AssemblyReflect.yaml

@@ -36,6 +36,16 @@ options:
     description: The name of the method to execute.
     required: true
     value: ''
+  - name: Background
+    description: Run as a background job (non-blocking). Can be killed via the jobs/kill_job
+      endpoint.
+    required: false
+    value: 'false'
+    type: bool
+    suggested_values:
+      - 'true'
+      - 'false'
+    strict: true
 csharp:
   UnsafeCompile: false
   CompatibleDotNetVersions:

empire/server/modules/csharp/code_execution/RunCoff.yaml

@@ -38,6 +38,16 @@ options:
       [arg2]
     required: false
     value: ''
+  - name: Background
+    description: Run as a background job (non-blocking). Can be killed via the jobs/kill_job
+      endpoint.
+    required: false
+    value: 'true'
+    type: bool
+    suggested_values:
+      - 'true'
+      - 'false'
+    strict: true
 csharp:
   UnsafeCompile: true
   CompatibleDotNetVersions:

empire/server/modules/csharp/credentials/Certify.yaml

@@ -25,6 +25,16 @@ options:
     value: help
     strict: false
     suggested_values: []
+  - name: Background
+    description: Run as a background job (non-blocking). Can be killed via the jobs/kill_job
+      endpoint.
+    required: false
+    value: 'false'
+    type: bool
+    suggested_values:
+      - 'true'
+      - 'false'
+    strict: true
 csharp:
   UnsafeCompile: false
   CompatibleDotNetVersions:

empire/server/modules/csharp/credentials/Rubeus.yaml

@@ -43,6 +43,16 @@ options:
       - changepw
       - hash
       - tgssub
+  - name: Background
+    description: Run as a background job (non-blocking). Can be killed via the jobs/kill_job
+      endpoint.
+    required: false
+    value: 'true'
+    type: bool
+    suggested_values:
+      - 'true'
+      - 'false'
+    strict: true
 csharp:
   UnsafeCompile: true
   CompatibleDotNetVersions: