Agents

The Threat Stack sends event data to the Threat Stack platform for analysis. An Agent is considered online when it is actively connected to the Threat Stack platform and is sending data. An Agent is considered offline if it cannot connect and send messages to the Threat Stack 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. Threat Stack automatically revokes agents if they are offline and have not reported in 1 day.

The Agent endpoints enable you to work with the Agent model.

List Agents

Overview

This method enables you to get a list of all the online or offline Threat Stack 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.

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 2017-01-01 and until 2017-04-01:

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 fetch. Responses display paginated results with up to 100 records per page.

Responses
200

successful operation

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

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.

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

successful operation

400

Bad parameters

401
403

The user is not allowed to perform this action.

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"
}