Skip to main content

Truss API Guide

Using the API

The Truss API facilitates powerful endpoint query operations to provide access to Truss' security data. The API is designed to be used by developers to retrieve, filter, and analyze data efficiently.

Truss allows organizations to access the security data they need, in a way that is efficient and easy to use.

Truss Search Endpoint

The Truss /product/search endpoint is designed to accommodate most data access needs. This endpoint allows you to retrieve comprehensive slices of security data based on a variety of filter parameters.

curl -X 'POST' \
"https://api.truss-security.com/product/search" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"days": 2
}'

Search by Date

There are several ways to search by date. The following parameters are supported:

  • startdate: Return products uploaded on or after this date.
  • enddate: Return products uploaded on or before this date.
  • days: Return products uploaded since N days ago.

Searches may be time boxed using the startdate and enddate parameters. Different date formats are supported:

  • unix epoch time in milliseconds (e.g., "1717379710282")
  • ISO format (e.g., "2024-06-02")
  • Human readable format (e.g., "March 20, 2024")

For example, the following example will return all security products entered since the specified start date (Sun Jun 2 2024) and before the specified end date (Mon Jun 3 2024).

curl -X 'POST' \
"https://api.truss-security.com/product/search" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"startDate": "2024-06-02",
"endDate": "2024-06-03"
}'

If a days parameter is included the search returns security products entered since that number of days in the past to the current time. This parameter will be used in place of startdate and enddate parameters.

info

When a days parameter is entered, startdate and enddate parameters will be ignored.

curl -X 'POST' \
"https://api.truss-security.com/product/search" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"days": 3
}'

Boolean Search Filters

Boolean search filters can be used to narrow down the results of a query. Boolean search filters contain both the date parameters and the product parameters and are passed directly into the data field of the search request.

The following product parameters support boolean search filters:

  • category: Array of category names (e.g., ["Ransomware", "OSINT"]).
  • source: Array of source names (e.g., ["TOR Project"]).
  • author: Array of author names (e.g., ["MohitK_"]).
  • industry: Array of industry names (e.g., ["Finance"]).
  • region: Array of region names (e.g., ["Europe"]).
  • reference: Array of reference strings (e.g., ["https://threatview.io/"]).
  • tags: Array of tags (e.g., ["C2", "AlphV"]).

'OR' Filtering

When searching for multiple values for a single parameter, the search performs an OR between the strings passed as an array to a single parameter. For example, if the values ["Ransomware", "OSINT"] are passed to the category parameter, the search will return all security products where the category is "Ransomware" OR "OSINT".

'AND' Filtering

If more than one parameter is specified in a search (e.g., category and source), then the search will return those products that satisfy BOTH of the specified parameters. In other words, the search performs an AND between the different parameters.

For example, if ["Ransomeware"] is passed to the category parameter and the ["TOR Project"] is passed to the source parameter, the search will return all security products where the category is "Ransomeware" AND where the source is "TOR Project".

Consider the following filter:

curl -X 'POST' \
"https://api.truss-security.com/product/search" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"days": 3,
"author": ["TOR Project"],
"tags": ["C2", "AlphV"]
}'

Paging

When a product search results in a large number of products, only a subset of the total will be returned by each call to the /product/search endpoint. In these cases, the initial calls will return metadata in the form of a LastEvaluatedKey that can be used to page through the results.

curl -X 'POST' \
"https://api.truss-security.com/product/search" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"days": 2,
"LastEvaluatedKey": {
"GSI1PK": "PROD",
"SK": "VER#0",
"GSI1SK": 1717377712019,
"PK": "PROD#01HKDT164VYRS50ZQ8RJEHHBH0"
}
}'

Last Evaluated Keys

When working with large datasets, the Truss API implements pagination to ensure efficient data retrieval. If your query returns a LastEvaluatedKey in the response, this indicates there are more results available. To retrieve the next set of results, include this key in your subsequent query.

The LastEvaluatedKey acts as a bookmark, telling the API where to resume fetching results. This pagination mechanism ensures optimal performance while allowing you to retrieve complete result sets.

Initial Query Examples

curl -X 'POST' \
"https://api.truss-security.com/product/search" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"startdate": 1733616000000,
"enddate": 1733961599999,
"source": [
"OpenPhish"
]
}' | jq

When using the curl command, the API returns a response containing a LastEvaluatedKey, it will look like this:


  {
    "LastEvaluatedKey": {
      "SK": "VER#0",
      "GSI3PK": "OpenPhish",
      "PK": "PROD#01JEMBFNT12JV97ZT3GVBF2X2J",
      "GSI3SK": 1733702440770
    }
  }

Using LastEvaluatedKey Examples

curl -X 'POST' \
"https://api.truss-security.com/product/search" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"startdate": 1733616000000,
"enddate": 1733961599999,
"source": [
"OpenPhish"
],
"LastEvaluatedKey": {
"SK": "VER#0",
"GSI3PK": "OpenPhish",
"PK": "PROD#01JEMBFNT12JV97ZT3GVBF2X2J",
"GSI3SK": 1733702440770
}
}' | jq

Pro API Tips

Advanced API Techniques

  • Pagination: Handle large result sets efficiently by adding pagination to your client
  • Filter Chaining: Combine multiple filters for precise results
  • Date Formatting: You can use various date formats for flexibility. epoch, day range, or human readable
  • Error Handling: Implement robust error handling through your client to handle errors gracefully

API Best Practices

  • Cache responses when appropriate
  • Implement rate limiting in your client
  • Use proper error handling and retries
  • Your API key is sensitive to your account. Do not share it with anyone.

The Truss API is your tool for accessing and managing security intelligence data. Use these endpoints to retrieve, filter, and analyze data efficiently.