Action: get_tasking

This page describes the format for getting new tasking

Endpoint

All agent messages go to the same endpoint: /api/v1.4/agent_message

Message Request

The contents of the JSON message from the agent to Apfell when requesting tasking is as follows:

Base64( CallbackUUID + JSON(
{
"action": "get_tasking",
"tasking_size": 1, //indicate the maximum number of tasks you want back
//if passing on messages for other agents, include the following
"delegates": [
{"UUID1": agentMessage},
{"UUID2": agentMessage}
]
}
)
)

There are two things to note here:

  • tasking_size - This parameter defaults to one, but allows an agent to request how many tasks it wants to get back at once. If the agent specifies -1 as this value, then Apfell will return all of the tasking it has for that callback.

  • delegates - This parameter is not required, but allows for an agent to forward on messages from other callbacks. This is the peer-to-peer scenario where inner messages are passed externally by the egress point. Each of these messages is a self-contained "Agent Message".

Message Response

Apfell responds with the following message format for get_tasking requests:

Base64( CallbackUUID + JSON(
{
"action": "get_tasking",
"tasks": [
{
"command": "command name",
"parameters": "command param string",
"timestamp": 1578706611.324671, //timestamp provided to help with ordering
"id": "task uuid",
}
],
//if we were passing messages on behalf of other agents
"delegates": [
{"UUID1": agentMessage},
{"UUID2": agentMessage}
]
}
)
)

There are a few things to note here:

  • tasks - This parameter is always a list, but contains between 0 and tasking_size number of entries.

  • parameters - this encapsulates the parameters for the task. If a command has parameters like: {"remote_path": "/users/desktop/test.png", "file_id": "uuid_here"}, then the params field will have that JSON blob as a STRING value (i.e. the command is responsible to parse that out).

  • delegates - This parameter contains any responses for the messages that came through in the first message