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.
Access the API Change Log here.
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.
To get started with Hawk:
Before you can use the Threat Stack API v2, you must authenticate using the 3 environment variables:
You can find the API key and the IDs on the Application Keys tab within the Settings page.
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.
After you successfully authentication, you can start using the available API endpoints!
For more details on our Hawk implementations, review one of the following frameworks:
Some of the API endpoints return data that spans across 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.
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 |
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
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.
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.
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.
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.
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.