Alerts

The Threat Stack Agent sends events to the platform and processes them through our rule evaluation engine. If an event matches a rule criteria then Threat Stack creates an Alert. Alerts are stored for a year and can either be active or dismissed.

When an alert has been dismissed the isDismissed property will be true and the alert object will be populated with with the dismissReason and dismissedBy information. Additionally, if the dismissReason is OTHER, than the response will include the dismissedReasonText, which is the text the user entered when they dismissed the alert.

To see the contributing events for an alert, query the using an id from the Get Events For Alert response.

The alert endpoints enable you to work with the Alert and Alert Severity Counts models.

List Alerts

Overview

This method enables you to get a list of all the active or dismissed alerts in your Threat Stack environment. Alert queries to this endpoint have the following required and optional parameters to help you refine your requests.

NOTES:

status is a required query parameter for the /alerts endpoint.

Only queries with the status parameter value of active can use the ruleId and rulesetId parameters to return responses.

This endpoint paginates and returns up to 100 records at a time. See Pagination.

Sample Queries

Find all active alerts:

https://api.threatstack.com/v2/alerts?status=active

Find all dismissed alerts:

https://api.threatstack.com/v2/alerts?status=dismissed

Find active alerts limited to a specific Alert severity (1,2,3):

https://api.threatstack.com/v2/alerts?status=active&severity=1

Find active alerts limited to a specific agentId:

https://api.threatstack.com/v2/alerts?status=active&agentId=[xxxxxxx111111xxxxx22222]

Find an active alert created from 2020-01-01 until 2020-04-01:

https://api.threatstack.com/v2/alerts?status=active&from=2010-01-01&until=2010-01-31

Find active alerts for rulesetId created from 2019-01-01 until 2019-01-31:

https://api.threatstack.com/v2/alerts?status=active&rulesetId=123456789&from=2019-01-01&until=2019-01-31

Find active alerts for ruleId limited to a specific severity:

https://api.threatstack.com/v2/alerts?status=active&ruleId=12345&severity=1

To find contributing events for an alert see Get Events

Error Handling Tips

A 400 error occurs when:

  • a query is missing a required parameter
  • you have not correctly specified a valid option for a parameter
  • you do not have a valid date range. The from parameter needs to be before the until parameter"
Request
query Parameters
status
required
string

Limits the response to alerts that are either active or dismissed.

Enum: "active" "dismissed"
severity
string

Limits the response to the severity level of the alert.

Enum: "1" "2" "3"
until
string <date-time>

Limits the response to alerts created before the selected date.

from
string <date-time>

Limits the response to alerts created after the selected date.

ruleId
string

Limits the response to the unique Threat Stack-generated identifier for the rule that triggered the alert.
Note:Only available as a query parameter if the status parameter value is active.

rulesetId
string

Limits the response to the unique Threat Stack-generated identifier for the ruleset that triggered the alert.
Note:Only available as a query parameter if the status parameter value is active.

agentId
string

Limits the response to the unique Threat Stack-generated identifier for the Agent that triggered the alert.
Note:Only available as a query parameter if the status parameter value is active.

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.

detectionMethods
string

Limits the response to the detection method type. By default, the endpoint will return only rules-based alerts when this parameter is omitted.

Enum: "inference-model" "all" "(blank)"
Responses
200

successful operation

400

Bad parameters

401
403

The user is not allowed to perform this action.

429

Rate limit hit.

500

An internal error has occurred.

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

Get An Alert

Overview

This method enables you to get the details of an Alert by an alertId.

NOTE:

You can only pass one alertId at a time.

Sample Queries

Find details of an Alert by id:

https://api.threatstack.com/v2/alerts/{alertId}

Error Handling Tips

A 404 error message for alertId means that the "Alert Id was not found in the database."

Request
path Parameters
alertId
required
string <uuid>

The id of the alert 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/alerts/{alertId}
Response samples
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "title": "string",
  • "dataSource": "agent",
  • "createdAt": "string",
  • "isDismissed": true,
  • "dismissedAt": "string",
  • "dismissReason": "BUSINESS_OP",
  • "dismissReasonText": "string",
  • "dismissedBy": "string",
  • "severity": 1,
  • "agentId": "bc309ecf-5f66-4057-93c5-6611cc9cb7b2",
  • "hostname": "string",
  • "ruleId": "70af3071-65d9-4ec3-b3cb-5283e8d55dac",
  • "rulesetId": "2f23ed23-d3ba-42fd-898b-b2ccad407a6e",
  • "aggregates": [
    ]
}

Get Context for an Alert

Overview

This method enables you to fetch the context for a particular host or CloudTrail alert. The context helps you answer specific questions about the event that contributed to the alert.
NOTE: You can only request context for one alert ID at a time.

Sample Query

Get the context of a particular host alert:

https://api.threatstack.com/v2/alerts/{alertId}/context

Error Handling Tips

A 404 error message for alertId means that the "Alert Id was not found in the database."

Request
path Parameters
alertId
required
string <uuid>

The id of the alert to retrieve

Responses
200

successful operation

400
404
429
500
get/alerts/{alertId}/context
Response samples
application/json
{
  • "userAgents": [
    ],
  • "userProcesses": [
    ],
  • "userActivities": [
    ],
  • "userSources": [
    ],
  • "cloudtrailSources": [
    ],
  • "cloudtrailTasks": [
    ],
  • "cloudtrailAuthMethods": [
    ],
  • "digests": [
    ]
}

Get Count of Active Alerts by Severity

Overview

This method enables you to get a count of active Threat Stack alerts in your environment for a defined period of time. The maximum request date range is 31 days and the response is grouped by alert severity. If no time parameters are provided, then the default response returns the count for the last 31 days.

NOTE:

This endpoint defaults to the last 31 days without a provided from and until query parameter. The maximum request date range is up to 31 days. This endpoint is not available for dismissed alerts

Sample Queries

Find a count of active alerts created in the last 31 days:

https://api.threatstack.com/v2/alerts/severity-counts

Find a count of active alerts created from 2017-01-01 and until 2017-01-30:

https://api.threatstack.com/v2/alerts/severity-counts?from=2017-01-01&until=2017-01-30

Error Handling Tips

A 400 can error occur when:

  • you have not correctly specified a valid option for a query parameter
  • the time range between from and until is greater than 31 days
  • the date range is invalid. The from parameter needs to be before the until parameter
Request
header Parameters
until
string <ISO-8601 date and time>

Limits the response to alerts created before a given date

from
string <ISO-8601>

Limits the response to alerts created after a given date

detectionMethods
string

Limits the response to the detection method type. By default, the endpoint will return only rules-based alerts when this parameter is omitted.

Enum: "inference-model" "all" "(blank)"
Responses
200
get/alerts/severity-counts
Response samples
application/json
{
  • "severityCounts": [
    ]
}

Get Events for an Alert

Overview

This method enables you to get the events which contributed to an Alert by the alertId.

NOTE:

You can only pass one alertId at a time.

Sample Queries

Find the events which contributed to an alert by alertId:

https://api.threatstack.com/v2/alerts/{alertId}/events

Error Handling Tips

A 404 error message for alertId means that the "Alert Id was not found in the database."

Request
path Parameters
alertId
required
string <uuid>
query Parameters
limit
number [ 1 .. 50 ]
Default: 50

The number of events to retrieve for the given alert.

Responses
200
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/alerts/{alertId}/events
Response samples
application/json
{
  • "events": [
    ]
}

Dismiss Alerts

Overview

This method enables you to dismiss groups of alerts via the API in one of two ways:

  • Specifying a list of alert IDs
  • Specifying query parameters

Note:

This endpoint accepts two different styles of json body. You dismiss alerts in batches of no more than seven days.

Sample Requests

Dismiss a group of alerts by alert ID:

https://api.threatstack.com/v2/alerts/dismiss

Dismiss a group of alerts by query parameters:

https://api.threatstack.com/v2/alerts/dismiss

Error Handling Tips

400: Invalid syntax:

  • Error message for invalid format
  • Error message for an invalid value type
  • Error message for body not including one of severity, ruleId, or agentId
  • Error message for body date range. The from parameter must be before the until parameter."
Request
Request Body schema: application/json
One of:
ids
required
Array of strings [ 1 .. 512 ] items

A list of valid alertIds.

dismissReason
required
string
Default: ""

The reason the alert was dismissed.

Enum: "BUSINESS_OP" "COMPANY_POLICY" "MAINTENANCE" "NONE" "AUTO_DISMISS" "OTHER"
dissmissReasonText
string

Reason the alert was dismissed if reason is OTHER.

Responses
200
400
401
403

The user is not allowed to perform this action.

429

Rate limit hit.

500

An internal error has occurred.

post/alerts/dismiss
Request samples
application/json
{
  • "ids": [
    ],
  • "dismissReason": "BUSINESS_OP",
  • "dissmissReasonText": "string"
}
Response samples
application/json
{
  • "message": 0
}