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

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.

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"

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

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

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

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

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

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.

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

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

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

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.