Skip to content

API: Commands

This section covers command templates and how to send commands to agents via the API.

List Command Plugins

Retrieve a list of available command plugins:

1
2
GET /api/v1/plugins/commands HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Enable a Command Plugin

Enable a previously disabled command plugin. Disabled plugins have their command templates hidden from agents.

1
2
PUT /api/v1/plugins/commands/{PLUGIN_ID}/enable HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Returns the updated plugin object.

Disable a Command Plugin

Disable a command plugin. Its command templates will no longer be offered to agents until re-enabled.

1
2
PUT /api/v1/plugins/commands/{PLUGIN_ID}/disable HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Returns the updated plugin object.

List Command Templates

Get a list of command templates:

1
2
GET /api/v1/command-templates HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Command Template Details

Fetch details for a specific command template:

1
2
GET /api/v1/command-templates/{COMMAND_TEMPLATE_ID} HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Send a Command to an Agent

Issue a command by specifying the template and configuration. Optionally include an execConf block to control execution context.

JSON request:

1
2
3
4
5
6
7
8
9
POST /api/v1/agents/{AGENT_GUID}/commands HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "template": "{COMMAND_TEMPLATE_ID}",
  "configuration": {COMMAND_CONFIGURATION},
  "execConf": {EXECUTION_CONFIGURATION}
}

Multipart request (when the command configuration uses files):

1
2
3
4
5
6
POST /api/v1/agents/{AGENT_GUID}/commands HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
Content-Type: multipart/form-data

requestBody: {"template": "{COMMAND_TEMPLATE_ID}", "configuration": {COMMAND_CONFIGURATION}, "execConf": {EXECUTION_CONFIGURATION}}
{FILE_FIELD_NAME}: <binary file content>

Use the file field name from the command schema. For example, a schema field shown as @files.executable is sent as a multipart file part named executable.

Examples

Example 1 – Basic Command

Run a simple command, such as "whoami", using the "cmd" template:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
POST /api/v1/agents/{AGENT_GUID}/commands HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "template": "cmd",
  "configuration": {
    "command": "whoami"
  }
}

Example 2 – Spawning a New Process

Spawn a new process with the "spawn" template.

Info

payloadId must reference a payload of type SHELLCODE.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
POST /api/v1/agents/{AGENT_GUID}/commands HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "template": "spawn",
  "configuration": {
    "payloadId": "{PAYLOAD_ID}",
    "encryptedCommunication": true
  },
  "execConf": {
    "execType": "NEW",
    "executable": "C:\\Windows\\System32\\notepad.exe",
    "suspended": false,
    "username": "tuoni",
    "password": "PassW$ord"
  }
}

Retrieve Agent Commands

Get all commands sent to a specific agent:

1
2
GET /api/v1/agents/{AGENT_GUID}/commands HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Retrieve All Commands

List all commands issued across agents:

1
2
GET /api/v1/commands HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Response is a JSON object keyed by command ID, where each value is a CommandResponse (same shape as GET /api/v1/commands/{COMMAND_ID}):

1
2
3
4
{
  "1": { "id": 1, "agentGuid": "...", "template": "...", ... },
  "2": { "id": 2, "agentGuid": "...", "template": "...", ... }
}

Get Command Result

Fetch the result for a specific command:

1
2
GET /api/v1/commands/{COMMAND_ID} HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Send a Command Update

Send new data to an already-running command. Use JSON for commands that only require a configuration update, or multipart form-data when you also need to attach files.

JSON variant:

1
2
3
4
5
6
7
POST /api/v1/commands/{COMMAND_ID}/update HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "configuration": {COMMAND_UPDATE_CONFIGURATION}
}

Multipart variant (when files are required):

1
2
3
4
5
6
POST /api/v1/commands/{COMMAND_ID}/update HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
Content-Type: multipart/form-data

requestBody: {"configuration": {COMMAND_UPDATE_CONFIGURATION}}
file[]: <binary file content>

Download a Command Configuration File

Download a file that was attached to the original command's configuration.

1
2
GET /api/v1/commands/{COMMAND_ID}/configuration/files/{FILE_ID} HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Returns the file as an octet-stream download.

Download a Command Update Configuration File

Download a file attached to a specific command update.

1
2
GET /api/v1/commands/{COMMAND_ID}/updates/{UPDATE_INDEX}/configuration/files/{FILE_ID} HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

UPDATE_INDEX is the zero-based position of the update in the command's update history.

Returns the file as an octet-stream download.

Download a Command Result File

Download a file returned as part of a command's result.

1
2
GET /api/v1/commands/{COMMAND_ID}/files/{FILE_ID} HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Returns the file as an octet-stream download.

Stop command

Sends stop signal to a command identified by ID. If command is not yet sent, then the command will be canceled and never sent.

1
2
PUT /api/v1/commands/{COMMAND_ID}/stop HTTP/1.1
Authorization: Bearer {JWT_TOKEN}