ThreatML

List Anomalies

Overview

This method enables you to list and filter anomalies for your organization. If you do not add parameters to your query, then Threat Stack returns all anomalies.

By default, anomalies are ordered by time in descending order so you see the most recent anomalies first. If there are more than 20 results in the query, then the API automatically paginates the results. You access the additional pages through a token number that Threat Stack provides.

Sample Queries

List all anomalies:

https://api.threatstack.com/v2/anomalies/process

List all anomalies associated with events that matched at least one rule

https://api.threatstack.com/v2/anomalies/process/?hasRuleMatch=true

Error Handling Tips

The 400 error code means that the request was unable to be fulfilled due to invalid data in the request body. Sample Error messages:

  • The hasRuleMatch parameter should have a valid Boolean value, if one is provided.
  • The agentId parameter should have a valid UUID value, if one is provided.
  • The maxUserScore.gt parameter should have a valid floating point number between 0.0 and 1.0, if one is provided.
  • The orgScore.gt parameter should have a valid floating point number between 0.0 and 1.0, if one is provided.
  • The token parameter should be a valid token that Threat Stack provides, if one is provided.
Request
Request Body schema: application/json
hasRuleMatch
boolean

Limits the response to anomalies associated with events that have matched at least one rule.

user
string

Limits the response to anomalies executed by a specific user.

hostname
string

Limits the response to anomalies executed on an agent with a specific hostname.

agentId
string

Limits the response to anomalies executed on an Agent with a specific Threat Stack-generated identifier.
Format: UUID

maxUserScore.gt
number [ 0 .. 1 ]

Limits the response to anomalies with a maximum user anomaly score greater than a given value.
Format: Float

orgScore.gt
number [ 0 .. 1 ]

Limits the response to anomalies with an organization anomaly score greater than a given value.
Format: Float

token
string

This endpoint returns up to 20 records per query. Use the token value from the response to query for the next page.

When the token value is null in the response, you have reached the end of the results list.

Responses
200
400
401
404
429
500
get/anomalies
Request samples
application/json
{
  • "hasRuleMatch": true,
  • "user": "string",
  • "hostname": "string",
  • "agentId": "string",
  • "maxUserScore.gt": 1,
  • "orgScore.gt": 1,
  • "token": "string"
}
Response samples
application/json
{
  • "anomaly": [
    ],
  • "id": "string",
  • "date": "string",
  • "exe": "string",
  • "orgScore": 1,
  • "trainingDays": 0,
  • "maxUserScore": 1,
  • "numEvents": 0,
  • "numCovered": 0,
  • "numAgents": 0,
  • "firstSeen": "string",
  • "lastSeen": "string",
  • "timesRuleMatched": 0,
  • "completeTrainingDays": 0
}

List Anomalies by Anomaly ID

Overview

This method enables you to get details and additional context for a specific anomaly. Additional context includes:

  • Agent
  • Rule
  • User
  • Frequency (number of occurrences by hour)

NOTES

  • Full Context is returned by default, that could be disabled by setting the verbose parameter to false
  • The Threat Stack anomaly detection system only considers active rules and discards suppressed rules when processing events and associating events with anomalies

Sample Queries

Get details and full context for an anomaly by Id

https://api.threatstack.com/v2/anomalies/process/f0a3a677-b265-4654-af31-1effd5cba063

Get the anomaly details without additional context

https://api.threatstack.com/v2/anomalies/process/f0a3a677-b265-4654-af31-1effd5cba063?verbose=false

Error Handling Tips

The 400 error code means that the request was unable to be fulfilled due to invalid data in the request body.

Sample Error Messages

  • 400: The anomalyId parameter should be a valid UUID.
  • 404: The anomalyId which has been passed in was not found in the database.
Request
path Parameters
anomalyId
required
string

The Threat Stack anomaly system generated identifier of the anomaly to retrieve.
Format: UUID

Request Body schema: application/json
verbose
boolean

Whether or not to return all contextual details for the selected anomaly. By default, the value is true.
True: Return all contextual details
False: Do not return all contextual details

Responses
200
400
401
404
429
500
get/anomalies/{anomalyId}
Request samples
application/json
{
  • "verbose": true
}
Response samples
application/json
{
  • "anomaly": [
    ],
  • "id": "string",
  • "date": "string",
  • "exe": "string",
  • "orgScore": 1,
  • "trainingDays": 0,
  • "maxUserScore": 1,
  • "numEvents": 0,
  • "numCovered": 0,
  • "numAgents": 0,
  • "firstSeen": "string",
  • "lastSeen": "string",
  • "timesRuleMatched": 0,
  • "completeTrainingDays": 0
}

List Notification Configuration

Overview

This method enables you to view the Notification Configuration in your organization.

Sample Queries

View the Notification Configuration in your organization

https://api.threatstack.com/v2/integrations/notification
Responses
200
400
401
404
429
500
get/integrations/notification
Response samples
application/json
{
  • "uniqueID": "a1dd802f-555b-4616-ba06-8f3aebecd52a",
  • "domain": "threatML",
  • "name": "string",
  • "url": "string",
  • "enrolledAt": "2019-08-24T14:15:22Z",
  • "enabled": true,
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "description": "string"
}

Update Notification Configuration

Overview

This method enables you to update an existing Notification Configuration for threatML in your organization.

Sample Queries

Update an existing Notification Configuration in your organization

https://api.threatstack.com/v2/integrations/notification

Error Handling Tips

400:

  • The url parameter should be valid.
  • The uniqueID parameter should be a valid UUID.

404: Could not find Notification Configuration that matched the uniqueID parameter value.

Request
Request Body schema: application/json
uniqueID
required
string <uuid>

The unique Threat Stack-generated identifier for the Notification Configuration object.

name
string

The name assigned to the Notification Configuration, as specified by your Threat Stack user.

url
string

The URL associated with the Slack channel where notifications are to be sent.

enabled
boolean

Flag that shows whether the Notification Configuration is enabled (true) or disabled (false).
Default: True

description
string [ 0 .. 300 ] characters

The description assigned to the Notification Configuration, as specified by your Threat Stack user.

Responses
200
400
401
404
429
500
put/integrations/notification
Request samples
application/json
{
  • "uniqueID": "a1dd802f-555b-4616-ba06-8f3aebecd52a",
  • "name": "string",
  • "url": "string",
  • "enabled": true,
  • "description": "string"
}
Response samples
application/json
{
  • "uniqueID": "a1dd802f-555b-4616-ba06-8f3aebecd52a",
  • "domain": "threatML",
  • "name": "string",
  • "url": "string",
  • "enrolledAt": "2019-08-24T14:15:22Z",
  • "enabled": true,
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "description": "string"
}

Add Notification Configuration

Overview

This method enables you to add a new Notification Configuration for ThreatML to your organization. Threat Stack supports a single ThreatML Notification Configuration per organization.

Sample Queries

Add a new Notification Configuration to your organization

https://api.threatstack.com/v2/integrations/notification

Error Handling Tips

400: The url parameter should contain a valid domain value. The only supported value is “threatML”."

Request
Request Body schema: application/json
domain
required
string

The domain of the Notification Configuration.

Value: "threatML"
name
string

The name assigned to the Notification Configuration, as specified by your Threat Stack user.

url
required
string

The URL associated with the Slack channel where notifications are to be sent.

enabled
boolean

Flag that shows whether the Notification Configuration is enabled (true) or disabled (false).
Default: True

description
string [ 0 .. 300 ] characters

The description assigned to the Notification Configuration, as specified by your Threat Stack user.

Responses
200
400
401
406
429
500
post/integrations/notification
Request samples
application/json
{
  • "domain": "threatML",
  • "name": "string",
  • "url": "string",
  • "enabled": true,
  • "description": "string"
}
Response samples
application/json
{
  • "uniqueID": "a1dd802f-555b-4616-ba06-8f3aebecd52a",
  • "domain": "threatML",
  • "name": "string",
  • "url": "string",
  • "enrolledAt": "2019-08-24T14:15:22Z",
  • "enabled": true,
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "description": "string"
}

Delete Notification Configuration

Overview

This method enables you to delete an existing Notification Configuration for threatML in your organization.

Sample Queries

Delete an existing Notification Configuration in your organization:

https://api.threatstack.com/v2/integrations/notification

Error Handling Tips

400: The uniqueID parameter should be a valid UUID. 404: Could not find Notification Configuration that matched the uniqueID parameter value.

Request
Request Body schema: application/json
uniqueID
required
string <uuid>

The unique Threat Stack-generated identifier for the Notification Configuration object.

Responses
200
400
401
404
429
500
delete/integrations/notification
Request samples
application/json
{
  • "uniqueID": "a1dd802f-555b-4616-ba06-8f3aebecd52a"
}
Response samples
application/json
{
  • "Notification message": "string"
}