TruSTAR API

The TruSTAR REST API allows you to easily synchronize the incident report information available in the TruSTAR platform to the monitoring tools and analysis workflows you use in your infrastructure. We suggest using our Python SDK to develop specific integrations for workflow automation. If you have any issues please contact us.

All API access is over HTTPS, and all data is transmitted securely in JSON format.

Current Version

Our current stable version is 1.3, which is accessible at the following base URL:

https://api.trustar.co/api/1.3

Versions 1.0 and 1.1 are no longer officially supported. Although version 1.2 is still maintained, we encourage users to migrate to 1.3.

Authentication

To use the API you must generate an OAuth token using your API key and API secret. You can generate or retrieve your API access key and secret from your account settings page on Station.

To request an OAuth token, send a request to the Authentication endpoint, replacing %api-key% and %api-secret% with your API key and secret retrieved above:

curl -k -v -u %api-key%:%api-secret% -d "grant_type=client_credentials" https://api.trustar.co/oauth/token

This operation generates a security token that can be used to query the public API:

{"access_token":"041c1918-dbe4-47a5-94bf-f13bacf1b0f2","token_type":"bearer","expires_in":599,"scope":"read"}

Note

This token can only be used for up to 10 minutes. Once it has expired, you will need to make this call again to generate a fresh token. If you are programatically accessing the TruSTAR API with a script, the best practice is to refresh the token before every call. If the previous token has not yet expired, then the https://api.trustar.co/oauth/token endpoint will simply return the same token as before, so there is no harm in requesting a fresh token before your current one has expired.

Below is an example API call using the token from above:

curl -k -X GET -H "Authorization: Bearer 041c1918-dbe4-47a5-94bf-f13bacf1b0f2" "https://api.trustar.co/api/1.3/indicators"

Headers

The API accepts 3 headers used to identify the type of client that the user is connecting with:

  • Client-Type: The name of the client being used (Should be either “API” or “Python_SDK”)
  • Client-Version: The version of the client being used (Should be API version or Python SDK version)
  • Client-Metatag: “curl” if executing curl commands from the command-line, “python script” if using the SDK, or integration name (“Splunk”, “ServiceNow”, “Phantom”, “Jira”, etc.)

These headers help us debug problems that users encounter while using the API.

Below is an example of a CURL call using these headers:

curl -k -X GET -H "Authorization: Bearer 041c1918-dbe4-47a5-94bf-f13bacf1b0f2" -H "Client-Type: API" -H "Client-Metatag: curl" "https://api.trustar.co/api/1.3/indicators"

Client-Type will default to API if the header is not found. The Python SDK is written to send PYTHON_SDK for Client-Type and the corresponding version for Client-Version.

Timestamps

  • All timestamps refer to the last updated time of a resource, not to the created time.
  • Time ranges used in queries are always inclusive.
  • All timestamps found in responses are represented in milliseconds since epoch. In version 1.3 of the API, all timestamps in requests are expected to also be in milliseconds since epoch. However, previous versions expected timestamps in requests to be represented in seconds since epoch (even though responses still contained them in milliseconds since epoch). This is an unfortunate result of attempting to maintain backwards compatibility with legacy code. So note that, when using version 1.2 or earlier, if you are using a timestamp from an API response as a parameter in a subsequent request, you will need to first divide it by 1000 in order to convert it to seconds.