Agents

Distributed Cloud AIP sends event data to the Distributed Cloud AIP platform for analysis. An Agent is considered online when it is actively connected to the Distributed Cloud AIP platform and is sending data. An Agent is considered offline if it cannot connect and send messages to the Distributed Cloud AIP platform.

The Agent sends metadata from the host system that includes the hostname and kernel. That metadata is included in the response from this endpoint. Distributed Cloud AIP automatically revokes Agents if they are offline and have not reported in 1 day.

List Agents

Overview

This method enables you to get a list of all the online or offline Distributed Cloud AIP Agents in your environment.

NOTE

  • status is a required query parameter for the /agents endpoint.
  • This endpoint is paginated and returns up to 100 records at a time. See Pagination.

NOTE

agentModuleHealth returns UNSUPPORTED for dnsTracer, networkTracer, and processSandbox for Agents that do not support eBPF (2.x and earlier).

Sample Queries

Find online Agents limited to a specific agent type (monitor or investigate):

https://api.threatstack.com/v2/agents?status=online&type=investigate

Find online Agents limited to the hostname (example: testing_i-12345):

https://api.threatstack.com/v2/agents?status=online&hostname=testing_i-12345

Find online Agents created from yyyy-mm-dd and until yyyy-mm-dd:

https://api.threatstack.com/v2/agents?status=online&from=2017-01-01&until=2017-04-01

Error Handling Tips

A 400 error code can occur when a required parameter is missing or when you have not correctly specified a valid option for a parameter. You may see this on status (online/offline), type (monitor/investigate), or if the until date is prior to the from date - or the reverse."

Request
query Parameters
status
required
string

Limits the response to the Agents that are either online or offline

Enum: "online" "offline"
from
string <ISO-8601 date and time>

Limits the response to the Agents created after a given date

until
string <ISO-8601 date and timeframe>

Limits the response to the Agents created before a given date

type
string

Restricts the response to Agents of a single type. If no type is defined, the results display all Agent types

Enum: "monitor" "investigate"
hostname
string

Restricts the response to Agents associated with a single hostname

token
string

This is the Page token of the next set of results to retrieve. Responses display paginated results with up to 100 records per page.

Responses
200

Success

400

Bad parameters

401

Unauthorized response

429

Rate limit hit

500

An internal error has occurred

get/agents
Response samples
application/json
{
  • "agents": [
    ]
}

Get an Agent

Overview

This method enables you to get the details of an Agent with an agentId.

NOTE

You can only pass one agentId at a time.

NOTE

agentModuleHealth returns UNSUPPORTED for dnsTracer, networkTracer, and processSandbox for Agents that do not support eBPF (2.x and earlier).

Sample Queries

Find the details of an Agent by agentId:

https://api.threatstack.com/v2/agents/{agentId}

Error Handling Tips

A 404 error message for agentId means the Agent ID was not found in the database.

Request
path Parameters
agentId
required
string

The unique ID of the Agent to retrieve

Responses
200

Success

401

Unauthorized response

404

The resource was not found

429

Rate limit hit

500

An internal error has occurred

get/agents/{agentId}
Response samples
application/json
{
  • "id": "string",
  • "instanceId": "string",
  • "status": "string",
  • "createdAt": "string",
  • "lastReportedAt": "string",
  • "version": "string",
  • "name": "string",
  • "description": "string",
  • "hostname": "string",
  • "ipAddress": [
    ],
  • "tags": [
    ],
  • "agentType": "string",
  • "kernel": "string",
  • "osVersion": "string",
  • "agentModuleHealth": {
    }
}
➔ Next to Alerts