Alerts

The AIP Agent sends events to the platform and processes them through our rule evaluation engine. If an event matches a rule criteria, then AIP 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 is true and the alert object populates with with the dismissReason and dismissedBy information. Additionally, if the dismissReason is OTHER, then the response includes the dismissedReasonText, which is the text you enter when dismissing an alert.

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

List Alerts

Overview

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

NOTE

status is a required query parameter for the /alerts endpoint. 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 until :

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

Find active alerts for rulesetId created from until :

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 AIP-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 AIP-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 AIP-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 retrieve. 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

Unauthorized response

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

401

Unauthorized response

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": "OTHER",
  • "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 retrieve 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

401

Unauthorized response

404

The resource was not found

429

Rate limit hit

500

An internal error has occurred

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 AIP 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 yyyy-mm-dd and until yyyy-mm-dd:

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

Error Handling Tips

A 400 error can 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

OK

400

Bad parameters

401

Unauthorized response

429

Rate limit hit

500

An internal error has occurred

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 .. 10 ]
Default: 10

The number of events to retrieve for the given alert

Responses
200

OK

401

Unauthorized response

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"
dismissReasonText
string

Reason the alert was dismissed if reason is OTHER.

Responses
200

OK

400

Invalid

401

Unauthorized response

429

Rate limit hit

500

An internal error has occurred

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