+++ title = "Creating a New Task" chapter = false weight = 25 +++ ## Creating a New Task Tasks fall under two categories: script only tasks, and atomic tasks. ## Script Only Tasks Script only tasks orchestrate one or more tasks that are already built-in to Apollo. For example, think about a `psexec` command. This command would first want to perform an `upload` to a target, then issue an `sc` command to create a new service, then another `sc` command to start the service. All you should need to do is add a new python file under `Payload_Type/apollo/mythic/agent_functions/` named `mycommand.py`. This file should be of the format: ``` // import statements here class MyCommandArguments(TaskArguments): def __init__(self, command_line, **kwargs): super().__init__(command_line, **kwargs) self.args = [ ... ] async def parse_arguments(self): ... class MyCommandCommand(CommandBase): cmd = "my_command" attributes=CommandAttributes( dependencies=["execute_pe"] ) ... other attributes ... async def create_tasking(self, task: MythicTask) -> MythicTask: return task async def process_response(self, response: AgentResponse): pass ``` Of note, if your command requires one or more dependencies to be loaded into the agent, you should specify them in the list of `dependencies` that are defined under `MyCommandCommand["attributes"]`. To perform task delegation, see Mythic documentation, or other examples of script only commands in Apollo, such as `pth`, `dcsync`, `mimikatz`, and otherwise. ## Atomic Tasks Atomic tasks are defined as new tasks to be added in the core of the agent. These types of tasks have no dependencies and are discrete taskings in and of themselves. New atomic tasks should be created under the `Tasks` project of the Apollo solution, as `my_command.cs`. This new file should contain a class, `public class my_command`, that inherits from the `Tasking` base class. ### Tasking Base Class The `Tasking` base class that all tasks inherit from have the following special variables: 1. `IAgent _agent` - Dependency resolver. 2. `Task _data` - A .NET representation of the task data sent from Mythic 3. `JsonSerializer _jsonSerializer` - An object that can serialize .NET objects to JSON strings and deserialize JSON strings to .NET objects. Lastly, all tasks that inherit this class will use the `CreateTaskResponse` function, which is defined as the following: ``` public virtual TaskResponse CreateTaskResponse( object userOutput, // What the user will see bool completed, // If the task is finished executing string status = "completed", // Status of task execution. IEnumerable messages = null // List of additional IMythicMessages ) ``` These `TaskResponse` objects are what are added to the queue via the `ITaskManager.AddTaskResponseToQueue` function, which ultimately sends data from the executing task back to Mythic (discussed later). What you should know, as a user, is that: 1. `userOutput` is what is sent in the `user_output` field of a task to Mythic. 2. `messages` is a list of additional typed messages Mythic can interpret and feed into various parts of it's UI. The `messages` variable is a list of `IMythicMessage` types, which can be one of the following: - `CommandInformation` - Information about loaded commands - `EdgeNode` - Updating the P2P nodes this agent knows about or is connected to - `FileBrowser` - Updating data in Mythic's file browser - `Credential` - Adding new credentials to the Mythic store - `RemovedFileInformation` - Tracking file deletions in Mythic - `Artifact` - Artifacts from task execution. Includes process creation events, logons, file deletions, etc. - `UploadMessage` - A special message type telling Mythic you're retrieving a file from it. - `DownloadMessage` - A special message type telling Mythic you're pushing a data to the Mythic server - `ProcessInformation` - Updates information in Mythic's process browser - `KeylogInformation` - Information about a user's keypresses. ### Example `my_command.cs` File ``` #define COMMAND_NAME_UPPER #if DEBUG #define MY_COMMAND #endif #if MY_COMMAND using System; using System.Collections.Generic; using System.Linq; using System.Text; using ApolloInterop.Classes; using ApolloInterop.Interfaces; using ApolloInterop.Structs.MythicStructs; using System.Runtime.Serialization; using ApolloInterop.Serializers; using System.Threading; using System.IO; namespace Tasks { public class my_command : Tasking { [DataContract] public struct MyCommandParameters { [DataMember(Name = "param_name")] public string ParamName; } public my_command(IAgent agent, Task task) : base(agent, task) { /* * Initiliaze any variables that'll be required for task execution, such as * getting function pointers to Win32 APIs through agent.GetApi().GetLibraryFunction, * asynchronous tasks that push data to Mythic if output streaming is required, * etc. */ } public override void Start() { MyCommandParameters parameters = _jsonSerializer.Deserialize(_data.Parameters); TaskResponse resp; /* * Do the main bulk of work of the function here. When you want to submit data to Mythic, * create a new TaskResponse, and add it to the response queue. */ _agent.GetTaskManager().AddTaskResponseToQueue(CreateTaskResponse( $"This is the data I want to display to the user", true // Whether or not the task has completed)); } } } #endif ``` ### IAgent Interface The IAgent interface is a dependency leveraged heavily throughout the agent. More reading on the interface can be done in the "Available Interfaces" documentation (may or may not be complete at the time of writing). You can use this interface to perform the following: 1. Get the agent's `IFileManager` interface, responsible for storing, fetching, and sending files to Mythic. 2. Get the agent's `IProcessManager` interface, responsible for creating new child processes. 3. Get the agent's `IInjectionManager` interface, responsible for injecting shellcode into processes. 4. Get the agent's `ITaskManager` interface, responsible for loading commands, dispatching new tasks, and adding output from tasks to the sending queue. This is by no means an exhaustive list of interfaces `IAgent` presents nor is it meant as a full list of the capabilities of each of the aforementioned interfaces. The following are just what's most frequently used during Task development. ### IFileManager Interface The IFileManager interface is used by tasking to perform the following. 1. Get a file from Mythic by its file ID. The result of this operation will yield the file from Mythic in the `fileBytes` variable shown below: ``` _agent.GetFileManager().GetFile( _cancellation.Token, _data.ID fileId, out byte[] fileBytes ) ``` 2. Send a file to Mythic via the `PutFile` call: ``` _agent.GetFileManager().PutFile( _cancellationToken.Token, _data.ID, fileBytes, // The file you're sending to Mythic filePath, // Where the file originated out string mythicFileId, // The file ID Mythic assigned to your file false, // Whether or not this file is a screenshot parameters.Hostname // The host where this file was found ) ``` 3. Retrieve a file from the agent's cache. Some tasks use the file cache to fetch files required for execution, as it reduces latency from task issuance to task execution. Some examples are: - `execute_assembly` - Fetches assemblies previously registered via `register_file` from the file cache to execute in a sacrifical process - `powershell` - Fetches the currently loaded PowerShell script from the file cache. ``` _agent.GetFileManager().GetFileFromStore( fileName, out byte[] fileBytes) ``` ### IProcessManager The IProcessManager interface is responsible for: - Spawning new child processes - Setting the parent process ID of child processes (`ppid`) - Blocking non-Microsoft DLL's from being loaded into the process (`block_dlls`) - Setting the default process to spawn used in fork and run tasks (`spawnto_*`) - Retrieving default application startup arguments. #### Spawning a Child Process Spawning a new child process can be done via: ``` _agent.GetProcessManager().NewProcess( string lpApplication, string lpArguments, bool startSuspended = false, ) ``` This returns a new `Process` object (defined in `ApolloInterop`) which is distinct from the traditional `System.Diagnostics.Process` object. You can subscribe to this process's stdout and stderr by adding an event handler to the `Process` object's `OutputDataReceived` and `ErrorDataReceived`. Once you have your event handlers configured, you can issue `Process.Start()` to start process execution, and similarily, `WaitForExit` if you wish to wait for the process to exit. Should you need to inject shellcode into a process, the `Process.Inject` method will inject arbitrary shellcode into the process using the currently defined injection method in the `IInjectionManager` implementation in use. ### IInjectionManager This interface is responsible for retrieving the loaded injection techniques, changing which technique is in use for post-ex jobs, as well as giving callers the ability to inject into arbitrary processes. Namely, `IInjectionManager.CreateInstance` will allow the caller to create an instance of injection to a target process, then a separate call to `InjectionTechnique.Inject` will inject the shellcode. ### ITaskManager The `ITaskManager` interface is what Tasks will most heavily interface with. Notably, this interface will push output from tasks up to Mythic for the user to see, load new taskings, cancel running tasks, and otherwise. As a Task developer, you'll mostly look to use `ITaskManager.AddTaskResponseToQueue`, which adds a new `TaskResponse` message to be sent to Mythic. These `TaskResponse` objects should be created via the `Tasking` base class's `Tasking.CreateTaskResponse`, which populates the requisite fields.