Threat Exchange v2.1.0 Plugin

This document explains how to configure the Threat Exchange plugin in the Cloud Exchange platform. With this plugin, you can retrieve malware and malsite alerts from Netskope’s tenant and share File Hash, URL, and Private App (Domain and Hostname) information from third party plugins to Threat Exchange.

Prerequisites

A Netskope Tenant (or multiple, for example, production and development/test instances) that is already configured in Cloud Exchange.
A Secure Web Gateway subscription for URL sharing.
A Threat prevention subscription for malicious file hash sharing.
Connectivity to a Netskope tenant with permission to generate tokens.

CE Version Compatibility

This plugin is compatible with all the CE 5.1.0 and above versions.

Threat Exchange Plugin Support

This plugin is used to fetch the File hashes and URLs (including the types URL, IPv4, hostname, domain, and FQDN) from the Malware and Malsite alerts available on the Netskope tenant. This plugin can share the indicators to File Hash List, URL List, and Private App within Netskope. Consider the maximum size of data that Netskope File Hash List and URL List can hold (8 MB) while configuring the Business Rule.

Fetched indicator types (Malware and Malsite alerts)	SHA256, MD5, Domain, IPv4
Shared indicator types	SHA256, MD5, Domain, IPv4

Mappings

Cloud Exchange Field	Netskope Field
value	Malware local_md5, local_sha256 Malsite url
type	Malware MD5, SHA256 Malsite URL
comments	Malware <Tenant URL> – object For example: https://crest-plugin-support.de.goskope.com – , Malware Name: amtest, Malware Type: hash Malsite <Tenant URL> – malsite_category E.g. https://crest-plugin-support.de.goskope.com – Malicious Site, Phish Site, Bot
firstseen, lastseen	timestamp

Permissions

The required permissions (privilege levels) for the endpoints listed below are available in REST API scopes.

API Details

List of APIs used

API Endpoint	Method	Use Case
/api/v2/events/dataexport/alerts/malware	GET	Pull the Malware alerts from Netskope tenant
/api/v2/events/dataexport/alerts/malsite	GET	Pull the Malsite alerts from Netskope tenant
/api/v1/updateFileHashList	POST	Push the file hashes to Netskope Tenant
/api/v2/policy/urllist	POST	Push the URLs to Netskope Tenant using V2 token
/api/v2/policy/urllist/deploy	POST	Deploy changes to Netskope URL List
/api/v2/steering/apps/private	GET	List Private Apps
/api/v2/infrastructure/publishers	GET	List Publishers for Private Apps
/api/v2/steering/apps/private	POST	Create private app in Netskope

Pull Malware Alerts from your Netskope tenant

API Endpoint: /api/v2/events/dataexport/alerts/malware

Method: GET

Parameters:

Index: <name of iterator index>

operation: <epoch time from where want to fetch the data>

Headers:

Netskope-Api-Token: <Netskope Tenant v2_Token>

Accept: application/json

Content-Type: application/json

Sample API Response:

To access the API Response view, log in to your Netskope tenant and go to the following URL in order to access the Swagger UI.

https://<TENANT_URL>.com/apidocs (or Settings > Tools > REST API v2 > API Documentation).

From there, you will be able to request the API mentioned above and obtain the desired API response.

Pull the Malsite alerts from Netskope tenant

API Endpoint: /api/v2/events/dataexport/alerts/malsite

Method: GET

Parameters:

Index: <name of iterator index>

operation: <epoch time from where want to fetch the data>

Headers:

Netskope-Api-Token: <Netskope Tenant v2_Token>

Accept: application/json

Content-Type: application/json

Sample API Response

To access the API Response view, log in to your Netskope tenant and go to the following URL in order to access the Swagger UI.

https://<TENANT_URL>.com/apidocs (or Settings > Tools > REST API v2 > API Documentation).

From there, you will be able to request the API mentioned above and obtain the desired API response.

Push the file hashes to Netskope Tenant

API Endpoint: /api/v1/updateFileHashList

Method: POST

Parameters:

token: <Netskope Tenant v1 Token>

Body:

{
  "name": "<Name of FileHash List>",
  "list": "<MD5 and SHA256 values comma separated>"
}

Sample API Response

To access the API Response view, log in to your Netskope tenant and go to the following URL in order to access the Swagger UI.

https://<TENANT_URL>.com/apidocs (or Settings > Tools > REST API v2 > API Documentation).

From there, you will be able to request the API mentioned above and obtain the desired API response.

Push the URLs to Netskope Tenant using V2 token

API Endpoint: /api/v2/policy/urllist

Method: POST

Headers:

Netskope-Api-Token: <Netskope Tenant v2 Token>

Body:

{
  "name": "<URL List Name>",
  "data": {
    "urls": [<List of URLs comma separated>]],
    "type":"regex"
  }
}

Sample API Response

To access the API Response view, log in to your Netskope tenant and go to the following URL in order to access the Swagger UI.

https://<TENANT_URL>.com/apidocs (or Settings > Tools > REST API v2 > API Documentation).

From there, you will be able to request the API mentioned above and obtain the desired API response.

List the Private apps from Netskope Tenant

API Endpoint: /api/v2/steering/apps/private

Method: POST

Headers:

Netskope-Api-Token: <Netskope Tenant v2 Token>

Sample Response:

To access the API Response view, log in to your Netskope tenant and go to the following URL in order to access the Swagger UI.

https://<TENANT_URL>.com/apidocs (or Settings > Tools > REST API v2 > API Documentation).

From there, you will be able to request the API mentioned above and obtain the desired API response.

List Publishers for Private Apps

API Endpoint: /api/v2/infrastructure/publishers

Method: GET

Headers:

Netskope-Api-Token: <Netskope Tenant v2 Token>

Sample Response:

To access the API Response view, log in to your Netskope tenant and go to the following URL in order to access the Swagger UI.

https://<TENANT_URL>.com/apidocs (or Settings > Tools > REST API v2 > API Documentation).

From there, you will be able to request the API mentioned above and obtain the desired API response.

Push Private Apps to Netskope Tenant

API Endpoint: /api/v2/steering/apps/private

Method: POST

Headers:

Netskope-Api-Token: <Netskope Tenant V2 Token>

Body:

{
  "app_name": "<NAME_OF_PRIVATE_APP>",
  "host": "<hostname with comma seperated>l",
  "protocols": [
    {
      "type": "TCP",
      "port": "443"
    }
  ],
  "tags": [
    {
      "tag_name": "<TAG_NAME<"
    }
  ]
}

Sample Response:

To access the API Response view, log in to your Netskope tenant and go to the following URL in order to access the Swagger UI.

https://<TENANT_URL>.com/apidocs (or Settings > Tools > REST API v2 > API Documentation).

From there, you will be able to request the API mentioned above and obtain the desired API response.

User Agent

The user-agent added in this plugin is in the following format:

Netskope-ce-<ce_version>

For example: Netskope-ce-5.1.0

Workflow

Generate a v1 and v2 token for your Netskope tenant.
Create a File profile and a Malware Detection profile.
Configure a Real-Time Protection policy.
Configure the Threat Exchange plugin.
Enable IoC retraction.
Create a Business Rule.
Set up Sharing using the Source Plugin, Business Rule, Destination Plugin, and Target.
Validate the plugin.

Click play to watch a video.

Generate a v1 Token

In your Netskope tenant, go to Settings > Tools > REST API v1.
Click Generate New Token.
Click Generate.
Click the edit icon located directly beneath the token to adjust the token’s expiration.
By default, the token is generated with no expiry. Choose the expiry duration from the dropdown menu. Select from 30 days, 60 days, 90 days, 180 days, or 365 days.
Click Save.
Copy the token. It will be required when configuring the Netskope tenant in Cloud Exchange.

Generate a v2 Token

In your Netskope tenant, go to Settings > Tools > REST API v2.
Click New Token.
Enter a Tenant Name.
Enter an Expire time. Select from Day(s), Hour(s), Week(s), Year(s).
Click Add Endpoint, select the desired endpoints listed above in List of APIs Used, and enable the Read privilege. For more details, go to REST API Scopes.
Click Save.
Copy the Token. It will be required when configuring the Netskope Tenant plugin in Cloud Exchange. Go here to configure the Netskope Tenant plugin.

Create a File Profile

In your Netskope tenant, go to Policies > Profiles > File and click New File Profile.
Select File Hash, and in the dropdown, select SHA256.
Enter a temporary value in the text field. Netskope does not support proceeding without having a value in this field, and we recommend using as a string of 64 characters that consist of the character f, this will have a very low possibility of matching a valid file format. For example, ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff.
Click Next.
Enter a Profile name and description. Do not use spaces in your profile name; use underscores instead for spaces.
Click Save.
To use this profile in a policy, click Apply Changes on the top right of the screen.

Create a Malware Detection Profile

In your Netskope tenant, go to Policies > Threat Protection > Malware Detection Profile and click New Malware Detection Profile.
Click Next.
For this example, create this list as a block list (click through Allow options). Netskope does support inclusion of both allow and block lists in the Malware Detection profiles.Click Next.
Select the File Profile that you created previously.
Click Next.
Enter a name for the Malware Detection profile.
Click Save Malware Detection Profile.
To use this profile in a policy, click Apply Changes on the top right of the Screen.

Create Real-Time Protection Policy

In your Netskope tenant, go to Policies > Real-time Protection. The policy configuration is just an example. Modify as appropriate for your organization.
Click New Policy and then select Cloud App Access.
For Source, leave the default as User = Any.
Click Category.
The window expands to allow you to search for and select the option All Categories.
Click outside of this list to close the search dialog.
For Activities & Constraints, click Edit.
Select Upload and Download.
Click Save.
For Profile & Action, click the Add Profile dropdown and select Threat Protection Profile.
Click in the new Threat Protection Profile box, and it will open up a list of available profiles.
Choose the Threat Profile you created previously.
Adjust the Action: Alert to reflect Action: Block for each of the Severity options.
For Set Policy, enter a descriptive Policy Name.
Click Save in the top right of the screen.
Select the To the top option when it is presented.
To publish this policy into the tenant, click Apply Changes on the top right of the Screen.

Configure the Threat Exchange Plugin

In Cloud Exchange, go to Settings > General and enable the Threat Exchange module.
In Settings, go to Plugins.
Search for and select the Netskope Threat Exchange plugin box.
Enter the Basic Information:
- Configuration Name: Enter a unique configuration name.
- Tenant: Choose the desired tenant from the dropdown menu. The primary tenant is automatically selected by default.
- Aging Criteria: Specify the criteria for aging the indicator, with the default expiration set at 90 days.
- Override Reputation: Assign a value [1-10] to override the reputation received from this configuration; leave it blank for the default setting.
- Tags Aggregate Strategy: Choose whether to append new tags to existing IoC(s) or overwrite them. This configuration parameter determines how tags are stored for indicators pulled for this configuration.
Click Next and enter the values for the Configuration Parameters:
- Enable Polling: Allows data polling from Netskope.
- Types of Threat Data to Pull: Selected indicator types will be extracted from Netskope malware alerts and stored on Threat Exchange.
- Initial Range (in days): Initial range for threat data to be pulled.
- Enable Tagging: The unshared tag indicators can be tagged using this feature.
Click Save.

Enable IoC Retraction

To enable IoC retraction from Cloud Exchange:

Go to Settings > Threat Exchange.
Enable IoC(s) Retraction and select a Retraction Interval.
Click Save.

Create a Business Rule for Threat IoCs

In Threat Exchange, go to Threat IoCs.
Click Apply Filter to a create filter for the business rule, like the one shown at the top of this next image.
Enter a Rule Name.
Click Save.

Add a Sharing Configuration

In order to add Sharing configuration, a third-party Threat Exchange plugin, like Threat Connect, has to be configured before proceeding. You need both a source and destination plugin (configurations) to add a Sharing configuration.

Add to a URL List

Go to Threat Exchange > Sharing and click Add Sharing Configuration.
Select how to share the indicators.
- Select the Source Plugin.
- Select the Business Rule.
- Select the Destination Plugin.
- Select the Target Add to File Hash List.
- Choose the list name from the dropdown menu if you wish to add the URL to a list that has already been created.
  OR
  Create New List by giving the name to the field “Create New List”.Choose the format in which you’d like the URL to be stored within the list: Exact OR Regex.
- List Size [Maximum Size of the Limit is 8MB]
- Default URL
Click Save.

Add to a File Hash List

Go to Threat Exchange > Sharing and click Add Sharing Configuration.
Select how to share the indicators.
- Select the Source Plugin.
- Select the Business Rule.
- Select the Destination Plugin.
- Select the Target Add to File Hash List.
- Provide the name of the file hash list on Netskope.
- List Size [Maximum Size of the Limit is 8MB]
Click Save.

Add to a Private App

Go to Threat Exchange > Sharing and click Add Sharing Configuration.
Select how to share the indicators.
- Select the Source Plugin.
- Select the Business Rule.
- Select the Destination Plugin.
- Select the Target Add to File Hash List.
- Choose the Private App Name from the dropdown menu if you wish to add the domain/hostname to already created app.
  OR
  Create New Private App.
  1. Select Protocol
  2. Provide the comma separated TCP and UDP ports (For the selected protocol).
  3. Select the Publisher
  4. Use Publisher DNS or Not
  5. Default Host
Choose the Private App Name from the dropdown menu if you wish to add the domain/hostname to already created app.
OR

Create New Private App
1. Select Protocol(s).
2. Provide the comma separated TCP and UDP ports (For the selected protocols).
3. Select the Publisher.
4. Choose to use Publisher DNS or not.
5. Enter the Default Host.
Click Save.

Validate the Threat Exchange Plugin

Validate the Pull

To validate the pulling of Alert from Netskope, go to the Logging in Cloud Exchange and search for the pulled logs.

Validate the Stored Indicator

To validate the stored indicator in the Netskope.

Go to Threat Exchange > Threat IoCs.
Add a filter to search the indicator.

Validate Alerts are Present in your Tenant

In your Netskope, tenant go to Skope IT.
Click Alerts, click Add Filter and select Alert Type > Malsite and Malware, and then click Apply. Select an option from the Last x Days dropdown in the top-right corner.

Validate the Push

To validate the plugin workflow in Netskope Cloud Exchange.

Go to Logging and search for pushed indicator with the filter message contains pushed.
The pushed logs will be filtered.

Validate the Push on the Netskope Tenant

To ensure the push of indicators on the Netskope tenant from the third-party plugin.

For Malsite Alerts

In your Netskope tenant, go to Policies.
Click Web > URL Lists.
Click on the List Name on which the URL is stored.
The List is shown here.

For Malware Alerts

In your Netskope tenant, go to Policies.
Click Web > File.
Click File Name > File Hash on which the MD5 and SHA256 File Hash is stored.

For Domain and Host Alerts

Go to Settings.
Click Security Cloud Platform > App Definition > Private App.
Click the application name where the hostname and domain details are shared.

Troubleshooting the Log Shipper Plugin

Receiving Error While Configuring the Netskope Threat Exchange

Getting the error: The Netskope tenant API V2 token does not have necessary permissions configured. Refer to the list of endpoints for which the token is missing permission. **

Cause: The provided V2 token does not have the minimum required permissions to configure the tenant in CE.

What to do:

Go to Logging and look for warning log similar to the following pattern:
TENANT Netskope Tenant (Required) [Netskope Tenant]: For Netskope Tenant, received 403 error for following endpoint(s)
Expand the log and get the list of endpoints for which permissions are missing
Now update the v2 token permissions and add the permission for the above endpoint list from Netskope Dashboard.

Limitations

An error will be thrown if the same File Hash list will be shared to Netskope Tenant from CE. If a File Hash list contains same list of file hashes that were pushed previously, and CE tries to push it again, then the API will throw error as shown below:

Threat Exchange v2.1.0 Plugin