API Source Plugin for Threat Exchange
API Source Plugin for Threat Exchange
The following document explains how to configure the Threat Exchange API Source Plugin for Cloud Exchange. The API Source plugin allows you to integrate virtually any third-party technology invoking an API endpoint to share IoCs, such as hashes and URLs from the third-party to a specific technology, and allow the API Source to read the IoCs managed by Threat Exchange.
To enable the API Source plugin, in Cloud Exchange go to Settings > Plugins , and then search for and select the API Source (CTE) plugin box. Once configured this will enable the API interface to manage the Indicators of Compromise.
Enter these parameters:
- Configuration Name: this parameter is used not only to provide a name for the configuration, but it is also a mandatory parameter that must be provided in the source field of the POST request to the API endpoint used to create an IoC entry (
/api/cte/indicators/). - Aging Criteria: Set the expiration time (in days) for the indicator.
- Override Reputation: Set whether to override the reputation of the indicators received from this configuration. Set 0 to keep the default.
- Enable SSL Verification: Set whether to check the certificate of the SSL connection used to exchange the IoCs.
- Use System Proxy: set this parameter if you have configured a proxy for the Cloud Exchange and you want this plugin to use the same proxy.
 |
When finished, click Save. After saving the configuration, you will see this plugin under the Threat Exchange > Plugin section.
After enabling the plugin, you need to configure an API token. Go to Settings > Users > API Tokens and click Create New Token’:
 |
Enter a Token Description and an expiration time, and then click Create.
After the token is created, you will see it under Settings > Users > API Tokens. Please note that the token is composed of a Client ID (visible) and Client Secret (can be copied using the button). These parameters are needed to authenticate the API call to read or update the IoCs in Cloud Exchange.
As an example, if your use case requires sharing of IoCs from the API Source to a Netskope tenant, you need to specify the Netskope tenant, a business rule, and a sharing configuration.
To specify a Netskope tenant, go to Settings > Netskope Tenant and click Add Tenant.
- Enter these parameters:
- Name: Enter a name for this tenant configuration name.
- Tenant Name: Enter the tenant name (do not include goskope.com).
- V1 API Token: Enter the V1 API token, available from your Netskope tenant under Settings > Tools > Rest API v1.
- V2 API Token (optional): Enter the V2 API token, available from your Netskope tenant under Settings > Tools > Rest API v2. Be sure to provide the proper permission to the token.
- Initial Range (in days): Enter the number of days for which data must be pulled during the initial run.
- Use System Proxy: Set this parameter if you have configured a proxy for the Cloud Exchange and you want this plugin to use the same proxy.
- Click Save.
 |
In Cloud Exchange go to Settings > Plugins and click Netskope v1.0.0.0 (CTE).
- Enter these Basic Information parameters :
- Configuration Name: Enter a name for this plugin.
- Tenant: insert the tenant configuration name that you have defined when you have created the Netskope tenant.
- Aging Criteria: Set an expiration time (in days) for the indicator
- Override Reputation: set this parameter to override the reputation of the indicators received from this configuration. Set 0 to keep the default.
- Click Next and enter the Configuration Parameters:
- Enable Polling: Enable or disable polling data from Netskope.
- Type of Threat Data: Select the data you want to share with this plugin. Possible values are: Malware, URL, or Both.
- Click Save.
After saving the plugin configuration, you will see the configured plugin under Threat Exchange > Plugins.
 |
Before configuring a sharing configuration, you need to define a Business Rule, which decides the criteria to share the IoCs between the two configurations. To do so, go to Threat Exchange > Business Rules and click Create New Rule. For example, the business rule below, called Every Severity, selects the IoCs with all the possible severities.
- Enter a Rule Name.
- Select the rules to use.
- Click Save.
 |
To create a sharing configuration, go to Threat Exchange > Sharing and click Add Sharing Configuration:
- Enter these parameters:
- Source Configuration: Enter a configuration name for the ‘API Source’ plugin you configured previously. Remember that the ‘API Source’ plugin can only push IoCs to a third-party. If you want to read the IoCs from the Threat Exchange, use the corresponding GET method for the
/api/cte/indicators/endpoint below. This means that you cannot insert an API Source as a destination configuration. - Business Rule: Select the Business Rule that you have defined previously and that states which indicators must be shared.
- Destination Configuration: insert the configuration of the Netskope tenant that you have defined previously.
- Target: Define the list where you want to insert the indicators of compromise. It is possible to define a URL list or a hash list. Please do note that the lists must be defined in the Netskope tenant.
Custom URL lists can be defined from Policies > Profiles > Web > URL Lists. A URL list must be inserted into a custom category to be enforced in a policy.
Custom file profiles can be defined from Policies > Profiles > File. A file profile must be inserted into a custom malware profile to be inserted in a policy.
- List Name: Enter the name of the list (URL or file) where you want the indicator to be inserted.
- List Size: Enter a size for the list (default is 8Mb).
- Default URL/File Hash: Enter the default list where the indicator must be inserted when the List Name field is empty.
- Source Configuration: Enter a configuration name for the ‘API Source’ plugin you configured previously. Remember that the ‘API Source’ plugin can only push IoCs to a third-party. If you want to read the IoCs from the Threat Exchange, use the corresponding GET method for the
- Click Save.
If you want to test the API, the documentation is available inside the Cloud Exchange interface at (Help > API Docs): https://<Cloud Exchange IP>/api/docs#/Indicators. In particular,the following endpoints are relevant:
GET /api/cte/indicators/: List the Indicators.
POST /api/cte/indicators/: Insert/update multiple indicators.
PATCH /api/cte/indicators/: Update a single indicator.
GET /api/cte/dashboards/: Get aggregated results from indicators.
DELETE /api/cte/indicators/bulk: Bulk delete indicators.
PATCH /api/cte/indicators/bulk: Bulk update indicators.
GET /api/cte/tags: Get configured tags from tenant
POST /api/cte/tags: Create new tags (globally)
DELETE /api/cte/tags: Delete tags (globally)
In this example an IOC is being pushed using POST to add an URL indicator, www.dubya.com, to an API plugin created and named DW. It has 2 tags associated with it that were already in the tenant – “test_tag” and “test_tag2”. If adding multiple tags, they must each be in their own open and close quotation marks, separated by a comma.
If you wish to POST IoC with tags, you need to create the tags ahead of time, either via the GUI or API.
 |
To update an IoC with new data, use PATCH. In the example below, the IoC has had its reputation increased from 5 to 7.
 |
Note that there are no additional tags added in this example.
Tags can be removed in the GUI or via the API using the remove command issued with a PATCH to endpoint api/cte/indicators/bulk. In the example below, the tag “abc” is removed from indicator “b53f3c0cd32d7f20849850768da6431e5f876b7bfa61db0aa0700b02873393fa“.
 |
