Added keylog, error, and complete task statuses (EmpireProject#798)

* Added keylog, error, and complete task statuses * change keylog to continuous * added plugin statuses * added docs for plugin and agent tasks * added docs to summary.md
0xsyr0 · Apr 7, 2024 · bdb941e · bdb941e
1 parent fe80b30
commit bdb941e
Show file tree

Hide file tree

Showing 6 changed files with 69 additions and 0 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -22,6 +22,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 -   Added hook and socket message to receive callback messages for individual agents (@AaronVigal)
 -   Added sacrificial Spawn Process bof (@Cx01N)
 -   Added suggested values to most modules (@Cx01N)
+-   Added continuous, error, and completed tasking statuses (@Cx01N)
+-   Added continuous and error plugin statuses (@Cx01N)
 -   Added Moriary module (@C01N)
 -   Added .NET 4.5 compile option (@C01N)
 

diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -30,10 +30,12 @@
     * [Resource Files](interfaces/client/resource-files.md)
   * [Starkiller](interfaces/starkiller/README.md)
     * [Introduction](interfaces/starkiller/introduction.md)
+    * [Agent Taskings](interfaces/starkiller/agent_tasking.md)
 * [Plugins](plugins/README.md)
   * [Getting Started](plugins/getting-started.md)
   * [Plugin Development](plugins/plugin-development.md)
   * [Hooks and Filters](plugins/hooks-and-filters.md)
+  * [Plugin Taskings](plugins/plugin_tasking.md)
 * [Bypasses](bypasses.md)
 * [C#](csharp.md)
 * [Module Development](module-development/README.md)

diff --git a/docs/interfaces/starkiller/agent_tasking.md b/docs/interfaces/starkiller/agent_tasking.md
@@ -0,0 +1,28 @@
+# Agent Taskings
+
+Agent taskings in Empire are managed through a series of status updates that reflect the lifecycle of a task from creation to completion. These statuses help users understand the current state of tasks assigned to agents. Below are the possible statuses for agent taskings along with descriptions and representative icons.
+
+## Queued
+
+- **Description**: The task is queued for the agent. This status indicates that the task has been created and is waiting to be pulled by the agent.
+- **Icon**: <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="12" height="12"><!--!Font Awesome Free 6.5.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2024 Fonticons, Inc.--><path fill="#ffa200" d="M256 0a256 256 0 1 1 0 512A256 256 0 1 1 256 0zM232 120V256c0 8 4 15.5 10.7 20l96 64c11 7.4 25.9 4.4 33.3-6.7s4.4-25.9-6.7-33.3L280 243.2V120c0-13.3-10.7-24-24-24s-24 10.7-24 24z"/></svg>
+
+## Pulled
+
+- **Description**: The agent has successfully pulled the tasking. This status signifies that the agent has received the task and is either processing it or about to start processing.
+- **Icon**: <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512" width="12" height="12"><!--!Font Awesome Free 6.5.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2024 Fonticons, Inc.--><path fill="#74C0FC" d="M400 480H48c-26.5 0-48-21.5-48-48V80c0-26.5 21.5-48 48-48h352c26.5 0 48 21.5 48 48v352c0 26.5-21.5 48-48 48zm-204.7-98.1l184-184c6.2-6.2 6.2-16.4 0-22.6l-22.6-22.6c-6.2-6.2-16.4-6.2-22.6 0L184 302.7l-70.1-70.1c-6.2-6.2-16.4-6.2-22.6 0l-22.6 22.6c-6.2 6.2-6.2 16.4 0 22.6l104 104c6.2 6.3 16.4 6.3 22.6 0z"/></svg>
+
+## Completed
+
+- **Description**: The task has returned data successfully. This indicates that the agent has finished executing the task and has returned the output.
+- **Icon**: <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="12" height="12"><!--!Font Awesome Free 6.5.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2024 Fonticons, Inc.--><path fill="#47b300" d="M256 512A256 256 0 1 0 256 0a256 256 0 1 0 0 512zM369 209L241 337c-9.4 9.4-24.6 9.4-33.9 0l-64-64c-9.4-9.4-9.4-24.6 0-33.9s24.6-9.4 33.9 0l47 47L335 175c9.4-9.4 24.6-9.4 33.9 0s9.4 24.6 0 33.9z"/></svg>
+
+## Error
+
+- **Description**: If an agent reports an error for a task, it will return an ERROR status. This status allows users to identify tasks that did not execute as expected.
+- **Icon**: <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="12" height="12"><!--!Font Awesome Free 6.5.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2024 Fonticons, Inc.--><path fill="#ff0000" d="M256 512A256 256 0 1 0 256 0a256 256 0 1 0 0 512zM175 175c9.4-9.4 24.6-9.4 33.9 0l47 47 47-47c9.4-9.4 24.6-9.4 33.9 0s9.4 24.6 0 33.9l-47 47 47 47c9.4 9.4 9.4 24.6 0 33.9s-24.6 9.4-33.9 0l-47-47-47 47c-9.4 9.4-24.6 9.4-33.9 0s-9.4-24.6 0-33.9l47-47-47-47c-9.4-9.4-9.4-24.6 0-33.9z"/></svg>)
+
+## Continuous
+
+- **Description**: A special class for modules like keylogging since they are handled differently on the server due to their continuous nature. These tasks do not have a definite end and run continuously until stopped.
+- **Icon**: <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 512" width="12" height="12"><!--!Font Awesome Free 6.5.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2024 Fonticons, Inc.--><path fill="#B197FC" d="M0 241.1C0 161 65 96 145.1 96c38.5 0 75.4 15.3 102.6 42.5L320 210.7l72.2-72.2C419.5 111.3 456.4 96 494.9 96C575 96 640 161 640 241.1v29.7C640 351 575 416 494.9 416c-38.5 0-75.4-15.3-102.6-42.5L320 301.3l-72.2 72.2C220.5 400.7 183.6 416 145.1 416C65 416 0 351 0 270.9V241.1zM274.7 256l-72.2-72.2c-15.2-15.2-35.9-23.8-57.4-23.8C100.3 160 64 196.3 64 241.1v29.7c0 44.8 36.3 81.1 81.1 81.1c21.5 0 42.2-8.5 57.4-23.8L274.7 256zm90.5 0l72.2 72.2c15.2 15.2 35.9 23.8 57.4 23.8c44.8 0 81.1-36.3 81.1-81.1V241.1c0-44.8-36.3-81.1-81.1-81.1c-21.5 0-42.2 8.5-57.4 23.8L365.3 256z"/></svg>
diff --git a/docs/plugins/plugin_tasking.md b/docs/plugins/plugin_tasking.md
@@ -0,0 +1,28 @@
+# Plugin Taskings
+
+Plugin tasks in Empire follow a similar lifecycle to agent taskings, with status updates providing key insights into the progress and outcomes of various plugin operations. Below are the possible statuses for plugin taskings along with descriptions and representative icons.
+
+## Queued
+
+- **Description**: The task is queued for the plugin. This status indicates that the task has been created and is waiting to be pulled by the server.
+- **Icon**: <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="12" height="12"><!--!Font Awesome Free 6.5.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2024 Fonticons, Inc.--><path fill="#ffa200" d="M256 0a256 256 0 1 1 0 512A256 256 0 1 1 256 0zM232 120V256c0 8 4 15.5 10.7 20l96 64c11 7.4 25.9 4.4 33.3-6.7s4.4-25.9-6.7-33.3L280 243.2V120c0-13.3-10.7-24-24-24s-24 10.7-24 24z"/></svg>
+
+## Started
+
+- **Description**: The plugin has successfully pulled and started the tasking. This status signifies that the server has received the task and is either processing it or about to start processing.
+- **Icon**: <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512" width="12" height="12"><!--!Font Awesome Free 6.5.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2024 Fonticons, Inc.--><path fill="#74C0FC" d="M400 480H48c-26.5 0-48-21.5-48-48V80c0-26.5 21.5-48 48-48h352c26.5 0 48 21.5 48 48v352c0 26.5-21.5 48-48 48zm-204.7-98.1l184-184c6.2-6.2 6.2-16.4 0-22.6l-22.6-22.6c-6.2-6.2-16.4-6.2-22.6 0L184 302.7l-70.1-70.1c-6.2-6.2-16.4-6.2-22.6 0l-22.6 22.6c-6.2 6.2-6.2 16.4 0 22.6l104 104c6.2 6.3 16.4 6.3 22.6 0z"/></svg>
+
+## Completed
+
+- **Description**: The task has returned data successfully. This indicates that the plugin has finished executing the task and has returned the output.
+- **Icon**: <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="12" height="12"><!--!Font Awesome Free 6.5.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2024 Fonticons, Inc.--><path fill="#47b300" d="M256 512A256 256 0 1 0 256 0a256 256 0 1 0 0 512zM369 209L241 337c-9.4 9.4-24.6 9.4-33.9 0l-64-64c-9.4-9.4-9.4-24.6 0-33.9s24.6-9.4 33.9 0l47 47L335 175c9.4-9.4 24.6-9.4 33.9 0s9.4 24.6 0 33.9z"/></svg>
+
+## Error
+
+- **Description**: If an plugin reports an error for a task, it will return an ERROR status. This status allows users to identify tasks that did not execute as expected.
+- **Icon**: <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="12" height="12"><!--!Font Awesome Free 6.5.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2024 Fonticons, Inc.--><path fill="#ff0000" d="M256 512A256 256 0 1 0 256 0a256 256 0 1 0 0 512zM175 175c9.4-9.4 24.6-9.4 33.9 0l47 47 47-47c9.4-9.4 24.6-9.4 33.9 0s9.4 24.6 0 33.9l-47 47 47 47c9.4 9.4 9.4 24.6 0 33.9s-24.6 9.4-33.9 0l-47-47-47 47c-9.4 9.4-24.6 9.4-33.9 0s-9.4-24.6 0-33.9l47-47-47-47c-9.4-9.4-9.4-24.6 0-33.9z"/></svg>)
+
+## Continuous
+
+- **Description**: A special class for modules like keylogging since they are handled differently on the server due to their continuous nature. These tasks do not have a definite end and run continuously until stopped.
+- **Icon**: <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 512" width="12" height="12"><!--!Font Awesome Free 6.5.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2024 Fonticons, Inc.--><path fill="#B197FC" d="M0 241.1C0 161 65 96 145.1 96c38.5 0 75.4 15.3 102.6 42.5L320 210.7l72.2-72.2C419.5 111.3 456.4 96 494.9 96C575 96 640 161 640 241.1v29.7C640 351 575 416 494.9 416c-38.5 0-75.4-15.3-102.6-42.5L320 301.3l-72.2 72.2C220.5 400.7 183.6 416 145.1 416C65 416 0 351 0 270.9V241.1zM274.7 256l-72.2-72.2c-15.2-15.2-35.9-23.8-57.4-23.8C100.3 160 64 196.3 64 241.1v29.7c0 44.8 36.3 81.1 81.1 81.1c21.5 0 42.2-8.5 57.4-23.8L274.7 256zm90.5 0l72.2 72.2c15.2 15.2 35.9 23.8 57.4 23.8c44.8 0 81.1-36.3 81.1-81.1V241.1c0-44.8-36.3-81.1-81.1-81.1c-21.5 0-42.2 8.5-57.4 23.8L365.3 256z"/></svg>
diff --git a/empire/server/common/agents.py b/empire/server/common/agents.py
@@ -1339,6 +1339,7 @@ def process_agent_packet(
         ):
             # add keystrokes to database
             if "function Get-Keystrokes" in tasking.input:
+                tasking.status = AgentTaskStatus.continuous
                 key_log_task_id = tasking.id
                 if tasking.output is None:
                     tasking.output = ""
@@ -1355,6 +1356,7 @@ def process_agent_packet(
             else:
                 tasking.original_output = data
                 tasking.output = data
+                tasking.status = AgentTaskStatus.completed
 
                 # Not sure why, but for Python agents these are bytes initially, but
                 # after storing in the database they're strings. So we need to convert
@@ -1375,6 +1377,8 @@ def process_agent_packet(
         #       so this logic is skipped
 
         if response_name == "ERROR":
+            tasking.status = AgentTaskStatus.error
+
             # error code
             message = f"Received error response from {session_id}"
             log.error(message)

diff --git a/empire/server/core/db/models.py b/empire/server/core/db/models.py
@@ -376,6 +376,9 @@ def get_base64_file(self):
 class AgentTaskStatus(str, enum.Enum):
     queued = "queued"
     pulled = "pulled"
+    completed = "completed"
+    error = "error"
+    continuous = "continuous"
 
 
 class AgentTask(Base):
@@ -424,6 +427,8 @@ class PluginTaskStatus(str, enum.Enum):
     queued = "queued"
     started = "started"
     completed = "completed"
+    error = "error"
+    continuous = "continuous"
 
 
 class PluginTask(Base):