This document is intended for a technical audience and provides a detailed description of an External REST integration with the ThreatConnect Platform. The general purpose of an External REST integration is to manipulate data within the ThreatConnect Platform from a third-party application.
Data Directionality: Bi-directional - Data can be retrieved or inserted into the ThreatConnect Platform.
ThreatConnect Technologies:
REST API - Provides an interface into the ThreatConnect Platform.
Execution:
Determined by the third-party application.
Development Environment
This integration is developed completely externally in most instances.
Architecture
NOTE: This approach should not be used to provide a traditional Threat Intelligence Feed. See Integrations - Threat Intelligence Feed Description instead.
We strongly encourage you to consider create a bi-directional integration whenever possible. This means both gathering from and providing data to the ThreatConnect Platform.
The specifics of how this works are best discovered through a conversation with your ThreatConnect Solutions Engineer.
Bi-directional integrations bring additional value to both of our customers by increasing the utility of the integration.
Here are some simple examples of bi-directional capabilities:
Providing threat intelligence data but also collecting false positive reports on that data from the ThreatConnect Platform.
Retrieving Indicator data for display/correlation in your own platform but allowing data manipulation (such as tagging, reporting false positives, or contributing Observations).
With the exception of integrations specifically making use of the Workflow functionality, the REST API v2 endpoints should be used for all calls.
This is not the recommended way to commit large amounts of data into the ThreatConnect Platform. We recommend using Integrations - Threat Intelligence Feed Description architecture for this instead.
Incoming indicator data that inserts multiple records should make use of the Batch Indicator Input File Format v2.
Configuration
The manipulation of data from the ThreatConnect Platform must allow the selection of the data owner(s) to be used.
By default, the organization of the API user calling the API endpoint is used. This is not always the desired behavior and should not be assumed.
It is recommended that you follow either of the two approaches below:
Allow the selection of the owners. The list of owners is available from the owners endpoint. This list can and will change with configuration in the ThreatConnect Platform so you should ensure that you provide an up-to-date selection list including adding or removing owners from your configuration.
Search across all owners when performing operations. This is less-desirable because it reduces flexibility and may require additional configuration within the ThreatConnect Platform to prevent the API user from having access to certain sources.
You should ensure that you take the proper Base URL format as input for your integration. Please see References - ThreatConnect API Base URL and Signatures for specific guidance on how to accept the Base URL and calculate signatures.
Data Mapping
Only potentially malicious indicators should be contributed to the Platform. Whitelist or false-positive data should not be contributed as Indicators within a Developer Partner’s integration.
Only standard indicator types should be used in this integration. You may not implement custom Indicator types of any kind.
NOTE: The Sandbox environment may have custom indicator types configured but these should not be used. Please see the standard indicators in the data model.
A data mapping exercise should take place in order to establish where relevant pieces of inserted information will belong within the ThreatConnect Platform. See this knowledgebase article for the ThreatConnect data model.
Threat Rating and Confidence must be set according to the ThreatConnect best-practices if you are inserting data into the Platform. If the incoming data source does not provide this information, these values must remain configurable and should default to 0.
NOTE: We recommend against putting a blanket confidence or threat rating on all indicators from a source. Instead, provide a configuration parameter for users to configure this behavior only if necessary.
The tag scheme used should only contain the bare words associated with the tag and should not reference the name of the source providing this information.
NOTE: The name of the Owner for the source will provide the appropriate name context.
Providing MITRE ATT&CK information should be done only according to this reference.
When retrieving in-platform indicator data, we recommend using the includeAdditional=true parameter for Indicators and making use of at least the following pieces of information from the JSON response:
data.<indicatortype>.<identifier> - This will change based on the indicatortype you are retrieving. This is typically either summary or the actual name of the data being stored (such as ip for an Address response).
data.<indicatortype>.owner - This will represent the owner of the data with which you are responding as this may make a difference to the use case of the data.
data.<indicatortype>.threatAssessConfidence - This is the overall Confidence generated by the ThreatAssess in-platform analytics based on the 0-100 scale. If you are including the owner’s specific confidence, you may omit this field to avoid confusion.
data.<indicatortype>.threatAssessRating - This is the overall Threat Rating generated by the ThreatAssess in-platform analytics based on the 0-5 scale. If you are including the owner’s specific rating, you may omit this field to avoid confusion.
data.<indicatortype>.threatAssessScore - This is the overall Threat Assess Score generated by the ThreatAssess in-platform analytics based on the 0-1000 scale.
Host and URL type data should be converted into IDNA for insertion into the Platform.
Distribution
This integration will be distributed by the partner using a method appropriate for the partner’s solution.
Getting started with the ThreatConnect REST API is documented here. In particular, you can use the bash script provided in the Hello World section as a test to ensure that your own method for creating the SHA256 HMAC is working as intended by using the same signature in each (including an identical timestamp).
We recommend that you also review this REST API Overview.
It is common that during the design phase of an integration you may desire to perform API testing using one of the many tools available. In selecting a tool to use, ensure that your tool can do a pre-execution calculation of the required SHA256 HMAC for the REST API Authorization header.
You can see an example of how to implement this in Postman here: References - Postman Configuration for API v2.