ThreatML

Machine learning predicts future behavior based on previous behavior. As a result, machine learning can identify behavior that falls outside of predicted behavior. Distributed Cloud AIP with ThreatML predicts the future behavior of your infrastructure through two different data models, which collect 30 days of specific information from your infrastructure to create a baseline of normal, predictable behavior. After ThreatML establishes a baseline, it compares your environment's baseline to your current environment and reports any behavior that deviates from the models' predictions as anaomalous.

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 Distributed Cloud AIP 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 Distributed Cloud AIP 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 Distributed Cloud AIP provides, if one is provided.
Request
query Parameters
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 <uuid>

Limits the response to anomalies executed on an Agent with a specific agentId

maxUserScore.gt
number <float> [ 0 .. 1 ]

Limits the response to anomalies with a maximum user anomaly score greater than a given value

orgScore.gt
number <float> [ 0 .. 1 ]

Limits the response to anomalies with an organization anomaly score greater than a given value

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

OK

400

Bad parameters

401

Unauthorized response

404

The resource was not found

429

Rate limit hit

500

An internal error has occurred

get/anomalies
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)

NOTE

  • Full Context is returned by default. To disable this, set the verbose parameter to false
  • The Distributed Cloud AIP 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 Distributed Cloud AIP anomaly system generated identifier of the anomaly to retrieve

Format: UUID

query Parameters
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

OK

400

Bad parameters

401

Unauthorized response

404

The resource was not found

429

Rate limit hit

500

An internal error has occurred

get/anomalies/{anomalyId}
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

OK

400

Bad parameters

401

Unauthorized response

404

The resource was not found

429

Rate limit hit

500

An internal error has occurred

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 Distributed Cloud AIP-generated identifier for the Notification Configuration object

name
string

The name assigned to the Notification Configuration as specified by your Distributed Cloud AIP 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 Distributed Cloud AIP user

Responses
200

OK

400

Bad parameters

401

Unauthorized response

404

The resource was not found

429

Rate limit hit

500

An internal error has occurred

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. Distributed Cloud AIP 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 Distributed Cloud AIP 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 Distributed Cloud AIP user

Responses
200

OK

400

Bad parameters

401

Unauthorized response

406

Resource already exists

429

Rate limit hit

500

An internal error has occurred

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 Distributed Cloud AIP-generated identifier for the Notification Configuration object

Responses
200

OK

400

Bad parameters

401

Unauthorized response

404

The resource was not found

429

Rate limit hit

500

An internal error has occurred

delete/integrations/notification
Request samples
application/json
{
  • "uniqueID": "a1dd802f-555b-4616-ba06-8f3aebecd52a"
}
Response samples
application/json
{
  • "Notification message": "string"
}