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.