Alerts

The Distributed Cloud AIP Agent sends events to the platform and processes them through our rule evaluation engine. If an event matches a rule criteria, then Distributed Cloud 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 Distributed Cloud 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 Distributed Cloud 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 Distributed Cloud 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 Distributed Cloud 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": [{"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": [{"fieldName": "string"
}
]
}
],
"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": [{"fieldName": "string"
}
]
}

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": [{"user": "string",
"agent": [{"agentId": "bc309ecf-5f66-4057-93c5-6611cc9cb7b2",
"hostname": "chef-server.ts.local",
"count": 10
}
],
"topAgents": [{"agentId": "bc309ecf-5f66-4057-93c5-6611cc9cb7b2",
"hostname": "chef-server.ts.local",
"count": 10
}
]
}
],
"userProcesses": [{"user": "string",
"processes": [{"exe": "string",
"count": 0
}
],
"topProcesses": [{"exe": "string",
"count": 0
}
]
}
],
"userActivities": [{"user": "string",
"activityByHour": [{"date": "string",
"count": 0
}
]
}
],
"userSources": [{"user": "string",
"sources": [{"source": "string",
"destination": "string",
"isWan": true,
"count": 0
}
],
"topSources": [{"source": "string",
"destination": "string",
"isWan": true,
"count": 0
}
]
}
],
"cloudtrailSources": [{"identity": "string",
"sources": [{"source": "string",
"count": 0
}
],
"topSources": [{"source": "string",
"count": 0
}
]
}
],
"cloudtrailTasks": [{"identity": "string",
"tasks": [{"eventSource": "string",
"eventName": "string",
"count": 0
}
],
"topTasks": [{"eventSource": "string",
"eventName": "string",
"count": 0
}
]
}
],
"cloudtrailAuthMethods": [{"identity": "string",
"authMethods": [{"eventType": "string",
"authMethod": "string",
"mfaUsed": true
}
],
"topAuthMethods": [{"eventType": "string",
"authMethod": "string",
"mfaUsed": true
}
]
}
],
"digests": [{"alertType": "userAgent",
"indicator": "info",
"digest": "steve has performed the /usr/bin/python action 42 times in the past 30 days",
"template": "{user} has performed the {alertExe} action {count} times in the past 30 days",
"values": [{"user": "root,",
"agentId": "be195f49-c317-11eb-8643-59a651b32d0c",
"hostname": "ip-10-123-12-51.ec2.internal",
"count": 0
}
]
}
]
}

Get Count of Active Alerts by Severity

Overview

This method enables you to get a count of active Distributed Cloud 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

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": [{"severity": 0,
"count": 0
}
]
}

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

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

400

Invalid

401

Unauthorized response

429

Rate limit hit

500

An internal error has occurred

post/alerts/dismiss

Request samples

Payload

application/json

{"ids": ["string"
],
"dismissReason": "BUSINESS_OP",
"dismissReasonText": "string"
}

Response samples

application/json

{"ids": ["string"
],
"dismissReason": "BUSINESS_OP",
"dismissReasonText": "string"
}

➔ Next to Audit Logs