Threat Stack API

Download OpenAPI specification:Download

The Threat Stack Rest API provides a way to connect to a Threat Stack Organization and extract key information around security concerns in your environment.

Change Log

Access the API Change Log here.

Authentication

Hawk is a protocol that implements hash message authentication code (HMAC) signing based on the API key provided. Hawk was designed to allow two parties to verify the sender of a message by a signed header in the HTTP request. If there is a body to the request, such as sending data via the API, you can verify the integrity of the body as well.

Get Started using Hawk

To get started with Hawk:

  1. Get necessary environment variables from the Threat Stack platform
  2. Try out a Threat Stack framework implementation to help get started with Authentication
  3. Use the API v2 Endpoints!

Step 1

Before you can use the Threat Stack API v2, you must authenticate using the 3 environment variables:

  • API key
  • Organization ID
  • User ID

You can find the API key and the IDs on the Application Keys tab within the Settings page.

Step 2

Threat Stack has implemented supported HAWK starter clients for Java, NodeJs, and Python for you to use!

You can clone them from the Threat Stack Github repo.

With your credentials from step 1, you should be able to make a test request to our API which will confirm that you have Hawk set up correctly.

Step 3

After you successfully authentication, you can start using the available API endpoints!

Additional Information

If you want more details on our Hawk implementations, you can review one of the following frameworks:

Time Ranges

Some of the API endpoints return data spanning acoss a wide time range. To help refine the responses, you can specify the time ranges by modifying the from and until parameters. Additionally, all date and time parameters follow ISO-8601 standards.

Timestamp Formats

The API uses UTC timestamps:

Date, Time, Date and Time Format Example
Date yyyy-mm-dd 2008-09-15
Combined date and time (hours) yyyy-mm-ddThh 2008-09-15T15
Combined date and time (minutes) yyyy-mm-ddThh:mm 2008-09-15T15:53
Combined date and time (seconds) yyyy-mm-ddThh:mm:ss 2008-09-15T15:53:00

Examples

To return resources created after a specific date, use the from parameter:

https://api.threatstack.com/v2/alerts?from=2017-08-01

To return resources created before a specific date, use the until parameter:

https://api.threatstack.com/v2/alerts?until=2017-02-01

To return resources created within a window of time bounded by specific dates, use the from and until parameters together:

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

Pagination

Overview

The Alert, Agent, and Vulnerabilities endpoints paginate and return up to 100 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.

Example

The token value can be found at the bottom of the response body:

    ],
    "token": "NTk4OGM5MWRmNDUyYWUzZjIzYTk2NWQzLDIwMTctMDgtMDdUMjA6MTA6=="
}

Use this token as an addendum to the query parameter to access the next page:

https://api.threatstack.com/v2/agents?token=NTk4OGM5MWRmNDUyYWUzZjIzYTk2NWQzLDIwMTctMDgtMDdUMjA6MTA6==

NOTE:

Each page of results must display before fetching the next page of results.

Rate Limit

Threat Stack has two types of rate limiting: by organization and by IP address.

Organization Rate Limit

The rate limit for an organization is 200 requests per minute. Specifically this describes the organization-Id rate limit. This results in an HTTP 429 error message. You can send the next request after 1 minute.

Working Within the Rate Limit

The Threat Stack API includes HTTP headers on every API response. These headers help you determine how much of your organization's rate limit budget has been used.

  • x-rate-limit-limit: This parameter displays the maximum number of requests your organization can make in a one minute time window
  • x-rate-limit-remaining: This parameter displays the number of requests you have remaining in the time window.
  • x-rate-limit-reset: If the rate limit triggers, then this parameter displays the number of milliseconds to wait before sending more requests. If the rate limit is not triggered, then this parameter displays 0.

IP Address Rate Limit

If the number of requests from an IP address exceeds 1,000 requests per minute, that results in an HTTP 429 error message and a 15 minute lock out for that IP address.

Agents

The Threat Stack sends event data to the Threat Stack platform for analysis. An Agent is considered online when it is actively connected to the Threat Stack platform and is sending data. An Agent is considered offline if it cannot connect and send messages to the Threat Stack platform.

The Agent sends metadata from the host system that includes the hostname and kernel. That metadata is included in the response from this endpoint. Threat Stack automatically revokes agents if they are offline and have not reported in 1 day.

The Agent endpoints enable you to work with the Agent model.

List Agents

Overview

This method enables you to get a list of all the online or offline Threat Stack agents in your environment.

NOTE:

status is a required query parameter for the /agents endpoint. This endpoint is paginated and returns up to 100 records at a time. See Pagination.

Sample Queries

Find online agents limited to a specific agent type (monitor or investigate):

https://api.threatstack.com/v2/agents?status=online&type=investigate

Find online agents limited to the hostname (example: testing_i-12345):

https://api.threatstack.com/v2/agents?status=online&hostname=testing_i-12345

Find online agents created from 2017-01-01 and until 2017-04-01:

https://api.threatstack.com/v2/agents?status=online&from=2017-01-01&until=2017-04-01

Error Handling Tips

A 400 error code can occur when a required parameter is missing or when you have not correctly specified a valid option for a parameter. You may see this on status (online/offline), type (monitor/investigate), or if the until date is prior to the from date - or the reverse."

Request
query Parameters
status
required
string

Limits the response to the agents that are either online or offline.

Enum: "online" "offline"
from
string <ISO-8601 date and time>

Limits the response to the agents created after a given date.

until
string <ISO-8601 date and timeframe>

Limits the response to the agents created before a given date.

type
string

Restricts the response to agents of a single type. If no type is defined, the results display all agent types.

Enum: "monitor" "investigate"
hostname
string

Restricts the response to agents associated with a single hostname.

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.

Responses
200

successful operation

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

Get an Agent

Overview

This method enables you to get the details of an Agent with an agentId.

NOTE:

You can only pass one agentId at a time.

Sample Queries

Find the details of an agent by agentId:

https://api.threatstack.com/v2/agents/{agentId}

Error Handling Tips

A 404 error message for agentId means the Agent Id was not found in the database.

Request
path Parameters
agentId
required
string

The unique id of the agent 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/agents/{agentId}
Response samples
application/json
{
  • "id": "string",
  • "instanceId": "string",
  • "status": "string",
  • "createdAt": "string",
  • "lastReportedAt": "string",
  • "version": "string",
  • "name": "string",
  • "description": "string",
  • "hostname": "string",
  • "ipAddress": [
    ],
  • "tags": [
    ],
  • "agentType": "string",
  • "kernel": "string",
  • "osVersion": "string"
}

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 Threat Stack alerts in your environment. Alert queries to this endpoint require 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 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
  • when you have not correctly specified a valid option for a parameter
  • when 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.

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

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": "string",
  • "title": "string",
  • "dataSource": "agent",
  • "createdAt": "string",
  • "isDismissed": true,
  • "dismissedAt": "string",
  • "dismissReason": "BUSINESS_OP",
  • "dismissReasonText": "string",
  • "dismissedBy": "string",
  • "severity": 1,
  • "agentId": "string",
  • "hostname": "string",
  • "ruleId": "string",
  • "rulesetId": "string",
  • "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/integrations/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

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

Updated on: 2/21/2018

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:

  • when you have not correctly specified a valid option for a query parameter
  • when 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

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
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
}

Audit Logs

Audit Logs

Overview

This method enables you to get audit logs that match selected parameters.

By default, the API will return 30 days of results. This can be changed in one of three ways:

  • By including only a from parameter. The API will return audit logs from the from date to the current date.
  • By including only an until parameter. The API will return audit logs from 30 calendar days before the until date.
  • By including from and until parameters. The API will return audit logs that match the selected timeframe.

If there are more than 50 results in the query, then the API automatically paginates the results. The additional pages can be accessed through a token number that Threat Stack provides.

Note:

If you do not append parameters to this query, then Threat Stack returns all audit logs. The results are paginated.

Sample Queries

Get all audit logs from November 1 to November 5.

https://api.threatstack.com/v2/auditlogs?from=2018-11-01&until=2018-11-05

Note:

Results display in descending order, starting with the most recent date.

Get all audit logs for delete operations.

https://api.threatstack.com/v2/auditlogs?operation=delete

Error Handling Tips

400:

  • Query should have a valid date range. The from parameter needs to be before the until parameter
  • Parameters, with the exception of userID, must be written in lower case or they donot return the expected results. For example, useremail will not return the expected results, while userEmail will return the expected results.
Request
query Parameters
from
string

Limits the response to audit logs created after a given date.
Format: ISO-8601 date and time.

until
string

Limits the response to audit logs created up to 30 calendar days before a given date.
Format: ISO-8601 date and time.

userId
string

Limits the response to audit logs that match a specific user id. This value can be found in Threat Stack > Settings > Application Keys.

userEmail
string

Limits the response to audit logs that match a specific email address used with Threat Stack credentials. This value can be found in Threat Stack > Settings > Users.

result
string

Limits the response to audit logs that match up to two operation results.

Enum: "success" "failure"
operation
string

Limits the response to audit logs that match up to four actions taken on data.

Enum: "create" "read" "update" "delete"
token
string

The Page token of the next set of results to fetch. Responses display paginated results with up to 50 records per page.
If there are more than 50 search results, then you can append &token={token} to the query to access the next 50 results.

Responses
200
400
404
500
get/auditlogs
Response samples
application/json
{
  • "recs": [
    ],
  • "token": "string"
}

Data Portability

List S3 Export Enrollment

Overview

This method enables you to get a list of all AWS S3 export enrollments in your organization.

Sample Queries

Find all the AWS S3 export enrollments in your organization:

https://api.threatstack.com/v2/integrations/s3export
Responses
200
400
401
403
404
500
get/integrations/s3export
Response samples
application/json
{
  • "organization_id": "string",
  • "s3Bucket": "string",
  • "iamRoleArn": "stringstringstringst",
  • "iamRoleArnExternalId": "string",
  • "region": "string",
  • "prefix": "string",
  • "enrolledAt": "string",
  • "enabled": true,
  • "message": "string"
}

Update S3 Export Enrollment

Overview

This method enables you to update an AWS S3 export enrollment in your organization.

Sample Queries

Update an AWS S3 export enrollment in your organization:

https://api.threatstack.com/v2/integrations/s3export
Request
Request Body schema: application/json
s3Bucket
required
string [ 3 .. 63 ] characters

The name of the S3 bucket into which to put raw events. The name can only contain lowercase letters, numbers, and/or dashes. The name must start with a letter or number. The name cannot be formatted as an IP address.

iamRoleArn
required
string [ 20 .. 2048 ] characters

The Role ARN generated at the time of IAM role creation.

iamRoleArnExternalId
required
string [ 0 .. 1224 ] characters

The External ID generated at the time of IAM role creation.

region
required
string

The valid AWS region of your AWS S3 bucket.

prefix
required
string [ 0 .. 64 ] characters

Add a prefix name to put the exported events under a specific prefix in your AWS S3 bucket.

enabled
required
boolean

Flag that shows whether data portability is enabled (true) or disabled (false)

Enum: true false
Responses
200
400
401
403
404
500
put/integrations/s3export
Request samples
application/json
{
  • "s3Bucket": "string",
  • "iamRoleArn": "stringstringstringst",
  • "iamRoleArnExternalId": "string",
  • "region": "string",
  • "prefix": "string",
  • "enabled": true
}
Response samples
application/json:
{
  • "organization_id": "string",
  • "s3Bucket": "string",
  • "iamRoleArn": "stringstringstringst",
  • "iamRoleArnExternalId": "string",
  • "region": "string",
  • "prefix": "string",
  • "enrolledAt": "string",
  • "enabled": true
}

Delete S3 Export Enrollment

Overview

This method enables you to delete an AWS S3 export enrollment in your organization.

Sample Queries

Delete an AWS S3 export enrollment in your organization:

https://api.threatstack.com/v2/integrations/s3export
Request
Request Body schema: application/json
s3Bucket
required
string [ 3 .. 63 ] characters

The name of the S3 bucket to unenroll from the data portability integration.
NOTE: The S3 bucket name must be enrolled in the data portability integration for the delete to work.

Responses
200
400
401
403
404
500
delete/integrations/s3export
Request samples
application/json
{
  • "s3Bucket": "string"
}
Response samples
application/json
{
  • "organization_id": "string",
  • "s3Bucket": "string"
}

Rule Sets & Rules

A Ruleset is comprised of rules which are assigned to an Agent. You can have multiple rule sets assigned to an Agent, such as Threat Stack's Base Rule Set or Threat Intelligence Rule Set.

Threat Stack fires an alert after evaluating incoming events against the rules you created and enabled within your organization. A rule will fire an alert when the window and threshold requirements of the rule are met.

The Rule endpoints enable you to work with the IDS Rule model and the File Rule model. To learn more about creating rules in Threat Stack, see Rule Creation Overview.

List Rulesets

Overview

This method enables you to get a list of all the Rulesets in your environment.

Sample Queries

Find all the Rulesets in your organization:

https://api.threatstack.com/v2/rulesets

Find a Ruleset with a specific agentId (for example: 12345678-9abc-def0-1234-56789abcdef0):

https://api.threatstack.com/v2/rulesets?agentId=12345678-9abc-def0-1234-56789abcdef0

Error Handling Tips

If you see a 400 error, that means the agentId is invalid.

If you see a 404 error code, that means there is no data associated with the query for that agentId.

Request
query Parameters
agentId
string
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/rulesets
Response samples
application/json
{
  • "rulesets": [
    ]
}

Create Ruleset

Overview

This method enables you to create Rule Sets in your environment.

Sample Queries

Create a Ruleset in your organization:

https://api.threatstack.com/v2/rulesets

Error Handling Tips

400: The syntax of the message body is incorrect and the rule set was unable to be created.

404: One of the ruleIds specified in the message body does not exist, so the rule set was unable to be created.

409: The rule set name duplicates an existing rule set name. The rule set was unable to be created.

Request
Request Body schema: application/json
name
required
string [ 1 .. 200 ] characters

The updated name of the Ruleset.

WARNING: The Ruleset name must not duplicate another Ruleset name in the organization.

description
required
string [ 1 .. 300 ] characters

The updated description of the Ruleset.

ruleIds
required
Array of strings

The ruleId for each rule to be copied into the Ruleset.

Responses
200
400
401
404
409
429

Rate limit hit.

500

An internal error has occurred.

post/rulesets
Request samples
application/json
{
  • "name": "string",
  • "description": "string",
  • "ruleIds": [
    ]
}
Response samples
application/json
{
  • "id": "string",
  • "rulesIds": [
    ],
  • "name": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "description": "string"
}

Get a Ruleset

Overview

This method enables you to get the details of a Ruleset by rulesetId.

NOTE:

You can only pass one rulesetId at a time.

Sample Queries

Find a Ruleset by rulesetId:

https://api.threatstack.com/v2/rulesets/{rulesetId}

Error Handling Tips

The 404 error code means that the rulesetId was not found.

Request
path Parameters
rulesetId
required
string

ID of the Ruleset.

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/rulesets/{rulesetId}
Response samples
application/json
{
  • "id": "string",
  • "rulesIds": [
    ],
  • "name": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "description": "string"
}

Update Ruleset

Overview

This method enables you to update Rulesets in your environment.

Sample Queries

Update a Ruleset in your organization:

https://api.threatstack.com/v2/rulesets/{rulesetID}

Error Handling Tips

400: The syntax of the message body is incorrect and the Ruleset did not update.

404: One of the following occurred:

  • The Ruleset was not found.
  • One of the rules in the Ruleset does not exist.

409: The Ruleset name duplicates an existing rule set name.

Request
path Parameters
rulesetId
required
string

ID of the Ruleset.

Request Body schema: application/json
name
required
string [ 1 .. 200 ] characters

The updated name of the rule set.
WARNING: The rule set name must not duplicate another rule set name in the organization.

description
required
string [ 1 .. 300 ] characters

The updated description of the rule set.

ruleIds
required
Array of strings

The ruleId for each new and existing rule in the rule set.
WARNING: If a rule that belongs in the rule set in Threat Stack is not included in this API rule set, then it will be removed from the rule set, permanently deleted, and irrecoverable from Threat Stack.
IMPORTANT: Alerts previously generated by any rule contained or omitted in this list will continue to exist in the state at which they were created.

Responses
200
400
401
404
409
429
500
put/rulesets/{rulesetId}
Request samples
application/json
{
  • "name": "string",
  • "description": "string",
  • "ruleIds": [
    ]
}
Response samples
application/json
{
  • "id": "string",
  • "rulesIds": [
    ],
  • "name": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "description": "string"
}

Delete Ruleset

Overview

This method enables you to delete a specific Ruleset from your environment.

When you delete a Ruleset, two things occur:

  • The Ruleset permanently deletes from Threat Stack.
  • All rules included in the Ruleset are permanently deleted from Threat Stack

IMPORTANT: Any alerts generated by rule in the deleted Ruleset are not deleted. These alerts continue to list the rule that triggered the alert, even though the Ruleset no longer exists.

Sample Queries

Delete a Ruleset with a specific rulesetID (for example: 00000000-aaaa-0000-aaaa-0000000000):

https://api.threatstack.com/v2/rulesets/00000000-aaaa-0000-aaaa-0000000000

Error Handling Tips

404: The Ruleset set to delete was not found.

Request
path Parameters
rulesetId
required
string

ID of the Ruleset.

Responses
200
400
401
404
429
500
delete/rulesets/{rulesetId}
Response samples
application/json
{
  • "server_ids": [
    ]
}

List Rules for a Ruleset

Overview

This method enables you to get the list of rules assigned to a Ruleset by the rulesetId.

NOTE:

You can only pass one rulesetId at a time.

Sample Queries

Find list of rules by rulesetId:

https://api.threatstack.com/v2/rulesets/{rulesetId}/rules

Error Handling Tips

The 404 error code means that the rulesetId was not found."

Request
path Parameters
rulesetId
required
string

ID of the Ruleset you want to get rules from

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/rulesets/{rulesetId}/rules
Response samples
application/json
{
  • "rules": [
    ]
}

Create Rules

Overview

This method enables you to create a rule for a specific Ruleset.

Sample Queries

Create a rule for a specific ruleset:

https://api.threatstack.com/v2/rulesets/{rulesetId}/rules

Error Handling Tips

  • 400: Invalid value(s) in the rule syntax.
  • 404: The selected Ruleset cannot be found.
  • 409: The rule's name matches an existing rule name for the organization. Rule names must be unique within an organization.
Request
path Parameters
rulesetId
required
string

ID of the Ruleset you want to get rules from

Request Body schema: application/json
One of:
name
required
string [ 1 .. 200 ] characters

Name of the rule.

title
required
string [ 1 .. 200 ] characters

Title of the rule.

type
required
string

Type of the rule.
Note: The allowed values are case insensitive.

Enum: "Host" "CloudTrail" "ThreatIntel"
severityOfAlerts
required
integer

Severity level of alerts the rule will generate.

alertDescription
string [ 0 .. 300 ] characters

Description of the alert the rule will generate.

Array of objects

List of fields to aggregate for the alert the rule will generate. Varies based on rule type.
Note: Alerts fire once per unique aggregate.

filter
required
string

Defines the conditions under which a rule will generate an alert.
IMPORTANT: Filters must pass validation specified by Threat Stack filter query language.

window
required
integer

The time period that must see at least the threshold value of events before the rule will generate an alert.
Format: int32

threshold
required
integer

The minimum number of events matching a rule in the assigning window before the rule will generate an alert.
Format: int32

suppressions
Array of strings

List of alert suppressions for the rule.
IMPORTANT: Suppressions must pass validation specified by Threat Stack filter query language.

enabled
required
boolean

Flag that shows whether the rule is enabled (true) or disabled (false)

Responses
200
400
404
409
429
500
post/rulesets/{rulesetId}/rules
Request samples
application/json
{
  • "name": "string",
  • "title": "string",
  • "type": "Host",
  • "severityOfAlerts": 0,
  • "alertDescription": "string",
  • "aggregateFields": [
    ],
  • "filter": "string",
  • "window": 0,
  • "threshold": 0,
  • "suppressions": [
    ],
  • "enabled": true
}
Response samples
application/json
{
  • "id": "string",
  • "rulesetId": "string",
  • "name": "string",
  • "type": "Host",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "title": "string",
  • "severityOfAlerts": 0,
  • "alertDescription": "string",
  • "aggregateFields": [
    ],
  • "filter": "string",
  • "window": 0,
  • "threshold": 0,
  • "suppressions": [
    ],
  • "enabled": true
}

Get a Rule for a Ruleset

Overview

This method enables you to get the details of a specific rule assigned to a rule set by the rulesetId and ruleId.

NOTE:

You can only pass one rulesetId and one ruleId at a time.

Sample Queries

Find the details of a rule by rulesetId and ruleId:

https://api.threatstack.com/v2/rulesets/{rulesetId}/rules/{ruleId}

Error Handling Tips

The 404 error code means the rulesetId or ruleId was not found.

Request
path Parameters
rulesetId
required
string

ID of the Ruleset.

ruleId
required
string

ID of the rule within a Ruleset.

Responses
200

successful operation

400

Bad parameters

401
404

The Resource was not found.

429

Rate limit hit.

500

An internal error has occurred.

get/rulesets/{rulesetId}/rules/{ruleId}
Response samples
application/json
{
  • "name": "string",
  • "title": "string",
  • "type": "File",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "severityOfAlerts": 0,
  • "alertDescription": "string",
  • "aggregateFields": [
    ],
  • "filter": "string",
  • "window": 0,
  • "threshold": 0,
  • "suppressions": [
    ],
  • "enabled": true,
  • "fileIntegrityPaths": [
    ],
  • "ignoreFiles": [
    ],
  • "eventsToMonitor": [
    ]
}

Update Rule

Overview

This method enables you to update a rule.

NOTE:

You cannot update the rule's type with this method.

Sample Queries

Update a rule in a specific Rule Set:

https://api.threatstack.com/v2/rulesets/{rulesetId}/rules/{ruleId}

Error Handling Tips

  • 400: Invalid value(s) in the rule syntax.
  • 404: One of the following situations occurred: The selected Rule Set cannot be found; The rule cannot be found.
  • 409: The rule's type cannot be updated with this method.
Request
path Parameters
rulesetId
required
string

ID of the Ruleset.

ruleId
required
string

ID of the rule within a Ruleset.

Request Body schema: application/json
One of:
name
required
string [ 1 .. 200 ] characters

Name of the rule.

title
required
string [ 1 .. 200 ] characters

Title of the rule.

type
required
string

Type of the rule.
Note: The allowed values are case insensitive.

Enum: "Host" "CloudTrail" "ThreatIntel"
severityOfAlerts
required
integer

Severity level of alerts the rule will generate.

alertDescription
string [ 0 .. 300 ] characters

Description of the alert the rule will generate.

Array of objects

List of fields to aggregate for the alert the rule will generate. Varies based on rule type.
Note: Alerts fire once per unique aggregate.

filter
required
string

Defines the conditions under which a rule will generate an alert.
IMPORTANT: Filters must pass validation specified by Threat Stack filter query language.

window
required
integer

The time period that must see at least the threshold value of events before the rule will generate an alert.
Format: int32

threshold
required
integer

The minimum number of events matching a rule in the assigning window before the rule will generate an alert.
Format: int32

suppressions
Array of strings

List of alert suppressions for the rule.
IMPORTANT: Suppressions must pass validation specified by Threat Stack filter query language.

enabled
required
boolean

Flag that shows whether the rule is enabled (true) or disabled (false)

Responses
200
400
404
409
429
500
put/rulesets/{rulesetId}/rules/{ruleId}
Request samples
application/json
{
  • "name": "string",
  • "title": "string",
  • "type": "Host",
  • "severityOfAlerts": 0,
  • "alertDescription": "string",
  • "aggregateFields": [
    ],
  • "filter": "string",
  • "window": 0,
  • "threshold": 0,
  • "suppressions": [
    ],
  • "enabled": true
}
Response samples
application/json
{
  • "id": "string",
  • "rulesetId": "string",
  • "name": "string",
  • "type": "Host",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "title": "string",
  • "severityOfAlerts": 0,
  • "alertDescription": "string",
  • "aggregateFields": [
    ],
  • "filter": "string",
  • "window": 0,
  • "threshold": 0,
  • "suppressions": [
    ],
  • "enabled": true
}

Delete Rule

Overview

This method enables you to delete a rule from a specific Rule Set.

Sample Queries

Delete a rule from a specific Rule Set

https://api.threatstack.com/v2/rulesets/{rulesetId}/rules/{ruleId}

Errors Handling Tips

404: One of the following situations occurred: The selected Rule Set cannot be found; The rule cannot be found.

Request
path Parameters
rulesetId
required
string

ID of the Ruleset.

ruleId
required
string

ID of the rule within a Ruleset.

Responses
200

The rule was successfully deleted.

404
429
500
delete/rulesets/{rulesetId}/rules/{ruleId}
Response samples
application/json
{
  • "error": "string"
}

List Active Agents for Ruleset

Overview

This method enables you to get the list of Threat Stack Agents to which a specific Ruleset has been assigned.

NOTE:

This endpoint returns only active Agents. You can only pass one rulesetId at a time.

Sample Queries

Find the list of Threat Stack Agents assigned to a specific Ruleset:

https://api.threatstack.com/v2/rulesets/{rulesetId}/agents

Error Handling Tips

The 404 error code means rulesetId was not found.

Request
path Parameters
rulesetId
required
string
Responses
200
get/rulesets/{rulesetId}/agents
Response samples
application/json
{
  • "agents": [
    ]
}

Get Tags for a Rule

Overview

This method enables you to get a list of AWS EC2 tags for a specific rule.

Notes:

You can only pass one ruleId at a time.
You cannot get tags for AWS CloudTrail rules.

Sample Request

Find tags by ruleId

https://api.threatstack.com/v2/rules/{ruleId}/tags

Error Handling Tips

404: No tags found for the selected ruleId.

Request
path Parameters
ruleID
required
string
Responses
200
400
404
409
429

Rate limit hit.

500

An internal error has occurred.

get/rules/{ruleID}/tags
Response samples
application/json
{
  • "inclusion": [
    ],
  • "exclusion": [
    ]
}

Set Tags for a Rule

Overview

This method enables you to set inclusion and exclusion AWS EC2 tags for a specific rule.

Notes:

You can only pass one ruleId at a time.
You cannot set tags for an AWS CloudTrail rule.

Sample Request

Set tags by ruleId

https://api.threatstack.com/v2/rules/{ruleId}/tags

Error Handling Tips

404: No tags found for the selected ruleId.

Request
path Parameters
ruleID
required
string
Request Body schema: application/json
Array of objects

The AWS EC2 tags on the server associated with the Threat Stack Agent. Any Threat Stack Agent associated with that server will have this rule applied to it.

Array of objects

The AWS EC2 tags on the server associated with the Threat Stack Agent. Any Threat Stack Agent associated with that server will not have this rule applied to it.

Responses
200
400
404
409
429

Rate limit hit.

500

An internal error has occurred.

post/rules/{ruleID}/tags
Request samples
application/json
{
  • "inclusion": [
    ],
  • "exclusion": [
    ]
}
Response samples
application/json
{
  • "inclusion": [
    ],
  • "exclusion": [
    ]
}

Update Rule Suppressions

Overview

This method enables you to update a rule's suppression list.

Sample Queries

Update a rule suppression list in your organization:

https://api.threatstack.com/v2/rules/{ruleID}/suppressions

Error Handling Tips

400: The syntax of the message body is incorrect and the rule did not update. There are three possible messages:

  • Error message for an invalid value where invalid1 and invalid2 are strings coming from the suppression body that do not fit an accepted format.
  • Error message for an invalid key. Status code 400
  • Error message for an invalid value type. Status code 400
Request
path Parameters
ruleId
required
string
Request Body schema: application/json
suppressions
required
Array of strings

Each string references a suppression that will be attributed to the rule.
NOTE: Individual suppressions for the rule are separated by commas.

Responses
200
400
404
409
429
500
put/rules/{ruleId}/suppressions
Request samples
application/json
{
  • "suppressions": [
    ]
}
Response samples
application/json
{
  • "name": "string",
  • "title": "string",
  • "type": "Host",
  • "severityOfAlerts": 0,
  • "alertDescription": "string",
  • "aggregateFields": [
    ],
  • "filter": "string",
  • "window": 0,
  • "threshold": 0,
  • "suppressions": [
    ],
  • "enabled": true
}

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"
}

EC2 Instances

When EC2 Sync with Threat Stack is enabled, we continually scan for any instance creation or termination so the Threat Stack platform will reflect the current state of your infrastructure. Threat Stack utilizes a “read-only” access role, scoped to EC2 and permissions are within your control.

The EC2 instance endpoint provides visibility into which EC2 instances are monitored by Threat Stack. The List EC2 Endpoints endpoint enables you to work with the EC2 Instance model.

List AWS EC2 Instances

Overview

This method enables you to get a list of all the EC2 instances in your environment.

NOTES:

The response defaults to show both monitored and non-monitored EC2 instances. The EC2 endpoint paginates query results based on the request.

  • If the request uses the verbose model, then results paginate after 100 responses return.
  • If the request uses the standard model, then results paginate after 10,000 responses return.

Sample Queries

Find all the EC2 instances in your organization:

https://api.threatstack.com/v2/aws/ec2

Find all monitored EC2 instances in your organization:

https://api.threatstack.com/v2/aws/ec2?monitored=true

Find all the non-monitored EC2 instances in your organization:

https://api.threatstack.com/v2/aws/ec2?monitored=false

Find all monitored AWS EC2 instances in your organization and return Threat Stack Agent information about them:

https://api.threatstack.com/v2/aws/ec2?monitored=true&verbose=true

Error Handling Tips

The 400 error code means that you did not correctly specify a valid option for a parameter. You may hit this on monitored which, if provided, must be true or false.

Request
query Parameters
monitored
boolean

Limits the response of EC2 servers to those that are monitored by Threat Stack Agents (true), or those that are not (false).

verbose
boolean

Whether to return results that include Threat Stack Agent information (true) or not (false)

Responses
200
get/aws/ec2
Response samples
application/json
{
  • "servers": [
    ],
  • "token": "string"
}

CVE Vulnerabilities

Threat Stack utilizes data from a wide variety of sources, including the packages installed on your individual servers to show you potentially vulnerable software. The vulnerabilities endpoint enables you to interact with your vulnerability data.

List Vulnerabilities

Overview

The method enables you to list all vulnerabilities found across the infrastructure in your Threat Stack organization.

NOTE:

The response defaults to display the active and suppressed vulnerabilities

This endpoint is paginated and returns up to 100 records at a time. See #docTextSection:zR4WHD8nqEMdNENHa.

Sample Queries

Find all CVE's:

https://api.threatstack.com/v2/vulnerabilities

Find all of the active CVEs:

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

Find all of the active CVEs which hasSecurityNotices available:

https://api.threatstack.com/v2/vulnerabilities?status=active&hasSecurityNotices=true

Find all of the active CVEs which have a severity of medium:

https://api.threatstack.com/v2/vulnerabilities?status=active&severity=medium

Find all of the CVEs for a specific agentId:

https://api.threatstack.com/v2/vulnerabilities?agentId=<foo>

Error Handling Tips

A 400 or 404 error code mean:

400: A required parameter is missing or the parameter is not valid. You may hit this when using severity or active.

404: Invalid agentId.

404: No packages have been collected from the agent.

404: No vulnerability assesment is available for the agent.

Request
query Parameters
status
string

Limit the response to CVEs that are either active or suppressed.

Enum: "active" "suppressed"
severity
string

Severity of the CVEs to return

Enum: "high" "medium" "low"
agentId
string

The id of the agent to limit the result set to

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.

hasSecurityNotices
boolean

Include vulnerabilities with security notices (true), or include vulnerabilities with and without security notices (false).

Responses
200

successful operation

400

Bad parameters

401

Missing auth credentials

429

Rate limit hit

500

Something went wrong

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

List Affected Servers by CVE

Overview

This method enables you to get the list of servers affected by a CVE number.

NOTE:

You can only pass one CVE number at a time.

Sample Queries

Find all of the servers affected by a CVE:

https://api.threatstack.com/v2/vulnerabilities/{CVE}/servers

To find related information about a server that is returned in the affected list, use #endpoint:K3ahcQo6A629apLW7 endpoint to lookup the agentId details.

Error Handling Tips

The 404 error code means that the CVE was not found in the database.

Request
path Parameters
cve
required
string
Responses
200
get/vulnerabilities/{cve}/servers
Response samples
application/json
{
  • "servers": [
    ]
}

List Vulnerabilities by Package

Overview

This method enables you to get the list of CVE's found across the infrastructure in you Threat Stack organization, for a specific software package.

NOTE:

You can only pass one package (without a version) at a time

The repsonse defaults to show both active and suppressed vulnerabilities

Sample Queries

Find all CVEs for a package, example sudo:

https://api.threatstack.com/v2/vulnerabilities/package/sudo

To get the list of active CVEs for a package:

https://api.threatstack.com/v2/vulnerabilities/package/{package}?status=active

Error Handling Tips

The 400 error code means a required parameter is missing or is not correctly specified as a valid option for a parameter.

Request
path Parameters
rootPackageName
required
string
query Parameters
status
string

Limit the response to CVEs that are either active or suppressed.

Enum: "active" "suppressed"
Responses
200

successful operation

400

Bad parameters

401

Missing auth credentials

429

Rate limit hit

500

Something went wrong

get/vulnerabilities/package/{rootPackageName}
Response samples
application/json
{
  • "cves": [
    ]
}

List Suppressions with details

Overview

This method enables you to get the list of current CVE suppressions with suppression reason details for your organization.

Sample Queries

Find the list of current CVE suppressions with details:

https://api.threatstack.com/v2/vulnerabilities/suppressions

Error Handling Tips

The 400 error code means a required parameter is missing or is incorrectly specified and not a valid option for the parameter. You may hit this on an active query.

Responses
200

successful operation

400

Bad parameters

401

Missing auth credentials

429

Rate limit hit

500

Something went wrong

get/vulnerabilities/suppressions
Response samples
application/json
{
  • "suppressions": [
    ]
}

List all suppressed vulnerabilities by package

Overview

This method enables you to list all of the suppressed CVEs for a specific package.

NOTE: The list does not show the version of the suppressed CVEs.

Other Related Endpoints:

To view all CVE suppressions and reasonings, use this endpoint #endpoint:zuBjDgw86x5adaX8n.

To view all of the active, unsuppressed CVEs for a package, use this endpoint #endpoint:9tc3iNQqAfjoyM6S4.

Request
path Parameters
rootPackageName
required
string
Responses
200

successful operation

400

Bad parameters

401

Missing auth credentials

429

Rate limit hit

500

Something went wrong

get/vulnerabilities/package/{rootPackageName}/suppressed
Response samples
application/json
{
  • "cves": [
    ]
}

List all suppressed vulnerabilities

Overview

The method enables you to list all of the suppressed CVEs in your Threat Stack Organization.

The list will return all suppressed CVEs.

Learn more about Threat Stack and vulnerability suppression:

If you suppress a vulnerability, then the vulnerability for that package version is no longer assessed during a Vulnerability Assessment scan. It will display on a suppressed vulnerabilities list, and will not be listed as an active vulnerability. See the Suppressing Vulnerabilites FAQ article for more information.

Available Queries

Here are the queries available for this endpoint.

Filter for a Specific Server

To view CVES for a particular server you can use one of the following query params:

  • agentId - The id of the agent
  • hostname - the name of the host

You may only use one of these options per query. If multiple are used, the api will return a Bad Request.

Filter for a Specific Suppressed Vulnerability Severity

To view suppressed CVEs of a specific severity, use the severity query parameter. You can filter for high, medium, or low severities within Theat Stack. For example, to view all low severity, suppressed CVEs:

https://api.threatstack.com/v2/vulnerabilities/suppressed?severity=low

To view all active, unsuppressed CVEs use this endpoint #endpoint:W7t3LDLPHQG9tT4Ni.

Request
query Parameters
severity
string

Severity of the CVEs to return

agentId
string

The id of the agent to limit the result set to

hostname
string

The hostname of the server to limit the result set to

Responses
200
get/vulnerabilities/suppressed
Response samples
application/json
{
  • "cves": [
    ],
  • "token": "string"
}

Reports

List All Generated Reports

Overview

This method enables you to fetch the full list of reports available for download in your organization. If your organization has more than 360 reports available, then the results will paginate.

Sample Query

Get the full list of reports available for download:

https://api.threatstack.com/v2/reports/generated-reports

Error Handling Tips

A 400 error code can occure when the list of all generated reports could not be returned due to bad request data. An example message could be, "Field is required but was not supplied" operationId: generated-reports

Request
query Parameters
token
string

This is the page token of the next set of results to fetch. Responses display paginated with 360 records per page

Responses
200

successful operation

400
429
500
get/reports/generated-reports
Response samples
application/json
{
  • "id": "string",
  • "categoryId": "337f5e5d-288b-40d5-be14-901cc3acacc0",
  • "orgId": "string",
  • "startTime": "2019-08-24T14:15:22Z",
  • "endTime": "2019-08-24T14:15:22Z",
  • "reportType": "insight",
  • "pdfStatus": "not_applicable",
  • "csvStatus": "not_applicable",
  • "jsonStatus": "not_applicable",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "scheduleId": "string",
  • "token": "string"
}

Get a Report by Report ID

Overview

This method enables you to fetch a single generated report using the report's ID

Sample Query

Get a specific generated report:

https://api.threatstack.com/v2/reports/generated-reports/{reportId}

operationId: generated-reports_reportId

Request
path Parameters
reportId
required
string

The Threat Stack-generated unique identifier (ID) for the report

Responses
200
400
429
500
get/reports/generated-reports/{reportId}
Response samples
application/json
{
  • "id": "string",
  • "categoryId": "string",
  • "orgId": "string",
  • "startTime": "2019-08-24T14:15:22Z",
  • "endTime": "2019-08-24T14:15:22Z",
  • "reportType": "insight",
  • "pdfStatus": "not_applicable",
  • "csvStatus": "not_applicable",
  • "jsonStatus": "not_applicable",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "scheduleId": "string",
  • "token": "string"
}

Delete a Report by Report ID

Overview

This method enables you to delete a single generated report using the report’s ID.

Samply Query

https://api.threatstack.com/v2/reports/generated-reports/{reportId}

Error Handling Tips

400

  • Report with id {reportId} not found
  • Failed to delete report with id {reportId}

operationId: generated-reports_reportId

Request
path Parameters
reportId
required
string

The Threat Stack-generated unique identifier (ID) for the report

Responses
200
400
429
500
delete/reports/generated-reports/{reportId}
Response samples
application/json
{
  • "error": "string"
}

Generate a Report

Overview

This method enables you to generate a report using data from a specified time period.

Sample Query

Generate a report for the past seven days:

https://api.threatstack.com/v2/reports/generate-report?from=2021-12-01&until=2021-12-07

operationId: POST_generate-reports

Request
query Parameters
categoryId
required
string

The identifier (UUID) of the category in which the report belongs

reportType
required
string

The type of report generated

Value: "compliance"
from
required
string <date>

The date and time at which to start gathering data for the report.

until
required
string <date>

The date and time at which to stop gathering data for the report.

Responses
200

successful operation

400
429
500
post/reports/generate-report
Response samples
application/json
{
  • "id": "string",
  • "categoryId": "string",
  • "orgId": "string",
  • "startTime": "2019-08-24T14:15:22Z",
  • "endTime": "2019-08-24T14:15:22Z",
  • "reportType": "compliance",
  • "pdfStatus": "not_applicable",
  • "csvStatus": "not_applicable",
  • "jsonStatus": "not_applicable",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "scheduleId": "string",
  • "token": "string"
}

Get a List of Schedules for Report Generation

Overview

This method enables you to fetch the full list of report generation schedules available for your organization.

Sample Query

Get a list of report generation schedules:

https://api.threatstack.com/v2/reports/scheduled-reports
Responses
200

successful operation

400
429
500
get/reports/scheduled-reports
Response samples
application/json
{
  • "scheduleId": "string",
  • "orgId": "string",
  • "reportType": "compliance",
  • "cadence": "daily",
  • "categoryComplianceId": "string"
}

Create a Schedule for Report Generation

Overview

This method enables you to create a report generation schedule for your organization.

Sample Query

Create a report generation schedule:

https://api.threatstack.com/v2/reports/scheduled-reports
Request
query Parameters
reportType
required
string

The type of report generated

Value: "compliance"
cadence
required
string

The frequency of report generation

Enum: "daily" "weekly"
complianceCategoryId
required
string

The identifier (UUID) of the compliance category in which the report belongs

Responses
200

successful operation

400
429
500
post/reports/scheduled-reports
Response samples
application/json
{
  • "scheduleId": "string",
  • "orgId": "string",
  • "reportType": "insight",
  • "cadence": "daily",
  • "categoryComplianceId": "string"
}

Get a Single Report Generation Scedule

Overview

This method enables you to fetch the information for a single report generation schedule.

Sample Query

Get a specific report generation schedule:

https://api.threatstack.com/v2/reports/scheduled-reports/{scheduleId}
Request
path Parameters
scheduleId
required
string

The Threat Stack-generated unique identifier (ID) for the schedule

Responses
200

successful operation

400
429
500
get/reports/scheduled-reports/{scheduleId}
Response samples
application/json
{
  • "scheduleId": "string",
  • "orgId": "string",
  • "reportType": "insight",
  • "cadence": "daily",
  • "categoryComplianceId": "string"
}

Delete a Single Report Generation Schedule

Overview

This method enables you to delete a single report generation schedule.

Sample Query

Delete a specific generated report:

https://api.threatstack.com/v2/reports/scheduled-reports/{scheduleId}
Request
path Parameters
scheduleId
required
string

The Threat Stack-generated unique identifier (ID) for the schedule

Responses
200

successful operation

400
429
500
delete/reports/scheduled-reports/{scheduleId}
Response samples
application/json
{
  • "error": "string"
}