App Infrastructure Protection (AIP) API

Download OpenAPI specification:Download

NOTE

Threat Stack is transitioning to a new brand: App Infrastructure Protection (AIP). Until this process completes in December 2022, documentation will use "Threat Stack" and "AIP" interchangeably. For more information, see Introduction to AIP.

The AIP Rest API provides a way to connect to a AIP organization and extract key information around security concerns in your environment.

Changelog

View the API Changelog 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 AIP platform
  2. Try out an AIP framework implementation to help get started with Authentication
  3. Use the API v2 endpoints!

Step 1

Before you can use the AIP API v2, you must authenticate using the three 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

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

You can clone them from the AIP GitHub repository.

With your credentials from step 1, you can make a test request to our API that confirms your successful Hawk configuration.

Step 3

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

Additional Information

For more details on our Hawk implementations, review one of the following frameworks:

Time Ranges

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. 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 2022-09-05
Combined date and time (hours) yyyy-mm-ddThh 2022-09-05T15
Combined date and time (minutes) yyyy-mm-ddThh:mm 2022-09-05T15:53
Combined date and time (seconds) yyyy-mm-ddThh:mm:ss 2022-09-05T15: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 is located 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

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