Skip to content

API: Agents

This section explains how to list, inspect, and update agents via the API.

List Agents

Retrieve all agents, or filter by active/inactive state.

All agents:

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

Active agents only:

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

Inactive agents only:

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

Get Agent Details

Fetch full information for a specific agent.

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

Mark Agent as Inactive

Move a connected agent to the inactive list.

1
2
PUT /api/v1/agents/{AGENT_GUID}/inactive HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Block an Agent

Block an agent from communicating with the server.

1
2
PUT /api/v1/agents/{AGENT_GUID}/block HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Restore an Agent

Remove the blocked state from an agent.

1
2
PUT /api/v1/agents/{AGENT_GUID}/restore HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

List Agent Command Templates

Retrieve command templates that are available for a specific agent.

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

List Agent Commands

Retrieve all commands that have been created for a specific agent, keyed by command ID. Each value follows the same shape as GET /api/v1/commands/{COMMAND_ID}.

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

Response is a JSON object of the form { "<commandId>": { ...CommandResponse }, ... }.

Update Agent

You can add or update metadata and custom properties for an agent or modify other agent aspects.

Update metadata

All fields are optional. Only the fields present in the request body are updated; omitted fields are left unchanged.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
PUT /api/v1/agents/{AGENT_GUID}/metadata HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "username": "exampleUser",
  "proc": "exampleProcess",
  "pid": 2222,
  "workingDir": "C:\\exampleDir",
  "os": "WINDOWS",
  "osMajor": 10,
  "osMinor": 0,
  "ips": "192.168.1.100",
  "hostname": "WORKSTATION01",
  "processArch": "X64",
  "osArch": "X64",
  "ansiCodePage": 1252,
  "integrity": "High",
  "agentType": "myagent",
  "agentVersion": 1,
  "customProperties": {
    "key": "value"
  }
}

Field reference for metadata update

Field Type Description
username string Username running the agent process.
proc string Process name of the agent.
pid integer Process ID.
workingDir string Working directory of the agent process.
os string Operating system. Values: WINDOWS, LINUX, BSD, MAC.
osMajor integer (byte) OS major version number.
osMinor integer (byte) OS minor version number.
ips string IP address(es) of the agent machine.
hostname string Hostname of the agent machine.
processArch string Architecture of the agent process. Values: X86, X64.
osArch string Architecture of the OS. Values: X86, X64.
ansiCodePage integer Windows ANSI code page (Windows only).
integrity string Process integrity level (e.g. System, High, Medium, Low).
agentType string Agent type / codename identifier.
agentVersion integer Agent build version number.
customProperties object Arbitrary key-value pairs attached to the agent. Replaces the existing map.

Clear agent command queue

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

Info

Replace all example values with the actual data for the agent you are updating.