Risk Exchange v1.0.0 Plugin

This document explains how to configure the Risk Exchange plugin (CREv2) in the Netskope Cloud Exchange platform. With this plugin, you can extract users from UBA alerts and populate user scores from Netskope, and fetch applications from Netskope Tenant. This integration can be used to perform various actions on Netskope, like creating or updating app instances, plus creating or updating CCI tags.

Prerequisites

A Netskope Tenant (or multiple, for example, production and development/test instances) that is already configured in Cloud Exchange.
Connectivity to a Netskope tenant with permission to generate v2 tokens.

CE Version Compatibility

This plugin is compatible with Netskope CE Version 5.1.0 and above.

Risk Exchange Plugin Support

This plugin is used to pull UBA alerts and application events from Netskope Tenant.

Type of data pulled	Application Events, Users and their Risk Scores
Actions	Add user to group, Remove user from group, Update UCI Score, Add Host to Private App, Create or Update App Instance, Tag application, No actions

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/events/alert	GET	To validate v2 token while configuring tenant.
/api/v1/app_instances	GET	Get app instances
/api/v1/app_instances	POST	Create/update app instances
/api/v2/scim/Users	GET	Get users from Netskope tenant
/api/v2/ubadatasvc/user/uci	POST	UBA License Verification
/api/v2/incidents/uba/getuci	POST	Fetch score for user
/api/v2/scim/Groups	GET	Get the available groups for Users
/api/v2/scim/Groups	POST	Create a Group.
/api/v2/scim/Groups/{Groups}	PATCH	Add users in the Group.
/api/v2/scim/Groups/{Group_ID}	PATCH	Remove users from the Group.
/api/v2/services/cci/domain	GET	Find the application domain related details.
/api/v2/services/cci/tags	GET	Find Tags related details for particular applications
/api/v2/services/cci/app	GET	Find application details
/api/v2/incidents/user/uciimpact	GET	Get UCI impact score of user
/api/v2/incidents/user/uciimpact	POST	Update UCI impact score of user
/api/v2/steering/apps/private	GET	Get list of private apps
/api/v2/steering/apps/private	POST	Create private app
/api/v2/steering/apps/private/<app-name>	PATCH	To update private app
/api/v2/services/cci/tags	POST	Create new CCI tag
/api/v2/services/cci/tags/<tagname>	PATCH	To update custom tag
/api/v2/infrastructure/publishers	GET	Get list of publishers

Get users from Netskope Tenant

API Endpoint: /api/v2/scim/Users

Method: GET

Parameters:

appname: <name of application separated by ;>

Headers:

Netskope-Api-Token: <v2_Token>

Accept: application/json

Content-Type: application/json

Sample API Response:

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 1,
    "Resources": [
        {
            "id": "cf2c8dc0-8806-4007-b6cb-c4f5ee139f31",
            "externalId": " ",
            "userName": "",
            "active": true,
            "name": {
                "givenName": null,
                "familyName": null
            },
            "emails": [
                {
                    "type": "work",
                    "value": "",
                    "primary": true
                }
            ]
        },   
     ],
    "itemsPerPage": 6,
    "startIndex": 1
}

UBA License Verification

API Endpoint: /api/v2/ubadatasvc/user/uci

Method: POST

Body:

{
  "user": "abc@gmail.com",
  "fromTime": 0
}

Headers:

Netskope-Api-Token: <v2_Token>

Accept: application/json

Content-Type: application/json

Sample API Response:

{
    "userId": "abc@gmail.com",
    "confidences": []
}

Fetch the Score for a User

API Endpoint: /api/v2/incidents/uba/getuci

Method: POST

Body:

{"users": [""], "fromTime": 0, "capPerUser": 1}

Headers:

Netskope-Api-Token: <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.

Get Available Groups for Users

API Endpoint: /api/v2/scim/Groups

Method: GET

Headers:

Netskope-Api-Token: <v2_Token>

Accept: application/json

Content-Type: application/json

Sample API Response:

{
    "Resources": [
        {
            "displayName": "",
            "externalId": null,
            "id": ""
        },
    ],
    "itemsPerPage": 19,
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "startIndex": 1,
    "totalResults": 19
}

Add Users into a Particular Group

API Endpoint: /api/v2/scim/Groups/{GROUP_ID}

Method: PATCH

Body

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
        {"op": "add", "path": "members", "value": [{"value": ""}]}
    ]
}

Headers:

Netskope-Api-Token: <v2_Token>

Accept: application/json

Content-Type: application/json

Sample API Response:

The response will have a status code of 204 and a Content-Type of text/xml.

Remove a User from a Group

API Endpoint: /api/v2/scim/Groups/{GROUP_ID}

Method: PATCH

Body

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
        {
            "op": "remove",
            "path": "members",
            "value": [{"value": ""}]
        }
    ]
}

Headers:

Netskope-Api-Token: <v2_Token>

Accept: application/json

Content-Type: application/json

Sample API Response:

Status: 204

Content-Type: text/xml

The response indicates a successful update of the group with a status code of 204 (No Content).

Find the Application Domain-related Details.

API Endpoint: /api/v2/services/cci/domain

Method: GET

Parameters:

appname: <name of application separated by ;>

Headers:

Netskope-Api-Token: <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.

Find Tags-related Information for Particular Applications

API Endpoint: api/v2/services/cci/tags

Method: GET

Parameters:

apps: <name of apps separated by ;>

Headers:

Netskope-Api-Token: <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.

Find Application Details

API Endpoint: /api/v2/services/cci/app

Method: GET

Parameters:

apps: <name of apps separated by ;>

Headers:

Netskope-Api-Token: <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

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.
Configure the Netskope Tenant plugin.
Configure the Netskope Risk Exchange plugin.
Create a Risk Exchange Business Rule.
Add Actions for the Netskope Risk Exchange plugin.
Validate the Risk Exchange 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.

Configure the Risk Exchange Plugin

In Cloud Exchange, go to Settings and enable the Risk Exchange module.
In Settings, go to Plugins.
Search for and select the Netskope Risk Exchange plugin box.
Enter a configuration name, and select the configured Tenant plugin from the dropdown.
Click Next and enter the values for the Configuration Parameters.
- Initial Range for Events (in hours).
- Initial Range for Alerts (in days).
Configure Entity Sources for Users and Application.
- If you want to pull users then configure entity source for Users.
- If you want to pull applications then configure entity source for Users.
Configure Entity source for Users (previously known as User Risk Exchange).
Select Users from the Entity dropdown, or click Add New Entity to create new entity.
Map the plugin fields for users entity with Risk Exchange fields (like map email string field of plugin with Email string field of Users entity. Note : Data type of the field will be enclosed in “()”.
Click Add to map multiple fields, (like map ubaScore Number field).
Click Add Field to add a new Number field in the Users entity.
Add a Field Label, select a Data Type, Enable or Disable Unique restriction for this new field being added, and then select Aggregate Strategy. When finished, click Save.
Similarly configure Entity sources for Applications (previously known as Application Risk Exchange), and do Field mappings for plugin and Risk Exchange fields.
Click Save.

Create a Business Rule for Risk Exchange

Go to Risk Exchange and click Business Rules.
Click Create New Rule.
Enter a Rule name and select the entity for which you want to create this rule. Create a filter rule and click Save (like If you want to identify the users having Uba score less than 100).
Click Save.
You can see what your users’ scores are by going to Records in the Risk Exchange left panel and selecting Users entity.

Add Actions for Risk Exchange

All of the actions are one of two types:

Source: This type represents the field of the Entity (like Users, Application, Devices Entity). This type can have dynamic values for each record of the entity.
Static: This type represents the static value for a particular action.

To configure actions:

Go to Risk Exchange > Actions.
Click Add Action Configuration.
From the Business Rule dropdown, select the Business rule you created.
From the Configuration dropdown, select your Risk Exchange plugin.
From the Actions dropdown, select one of these actions:
- Add user to group: When selected, users are added to that group.
- Remove user from group: When selected, users are removed from that group.
- Update UCI score: When selected, users score will be reduced per the Score (Reduction) field.
- Add host to Private App: When triggered, a host will be added configured private app.
- Create or Update App Instance: When selected, app instances will be created or updated per the configuration.
- Tag application: When selected, an application will be tagged as per the configuration.
- No action: This does not perform any actions on users.
Enable the Generate Alert toggle. Enabling the Generate Alert toggle ensures that new alerts are added in the Ticket Orchestrator module whenever this action executed.
if you wish to perform an action during the Maintenance Window, enable the Perform action during Maintenance Window toggle. The Action will be performed during the Maintenance Window; otherwise, it will be performed instantly.
Disable the Require Approval toggle. Disabling this toggle will trigger the action automatically without any manual intervention. If the toggle is enabled, each action will require manual approval from the CE user.
Click Save.

Add a User to a Group

Whenever this action is triggered, users are added to that group.

Click play to watch a video.

Go to Risk Exchange > Actions.
Click Add Action Configuration.
Enter these values:
- Business Rule: Select a Business Rule.
- Configuration: Netskope Risk Exchange configuration.
- Actions: Add user to group.
- User Email: Select a source field for Email from the entity
- Group: Select Static as the group type, and select an existing group, or select Create new group.
- Group name: Select Static as group name type and enter a Group name for the new group to be created.
- Generate Alert: Enable the Generate Alert toggle. This ensures that new alerts are added in the CTO module whenever this action is taken
- Perform action during Maintenance Window: Actions will be performed during the maintenance window.
- Require Approval: If enabled all the actions will require user approval from the records page.
Click Save.
Click Sync.
Add Time Period and Click on the Fetch button and number of records on which action will be taken when you click on Sync button.

Remove a User from a Group

Whenever this action is triggered, remove users from the group.

Click play to watch a video.

Go to Risk Exchange > Actions.
Click Add Action Configuration.
Enter these values:
- Business Rule: Select a Business Rule.
- Configuration: Netskope Risk Exchange configuration.
- Actions: Remove user from group.
- Hosts: Select source field for Email from the entity
- Group: Select Static as group type and select an existing group.
- Generate Alert: Click on the Generate Alert switch to enable it. This would ensure that new alerts are added in the CTO module whenever this action is taken
- Perform action during Maintenance Window: Actions will be performed during the maintenance window
- Require Approval: If enabled all the actions will require user approval from the records page.
Click on Save.
Click on Sync.
Add Time Period and Click on the Fetch button and number of records on which action will be taken when you click on Sync button.

Update UCI Score

Whenever this action is triggered, the user’s score will be updated.

Click play to watch a video.

Go to Risk Exchange > Actions.
Click Add Action Configuration.
Enter these values:
- Business Rule: Select a Business Rule.
- Configuration: Netskope Risk Exchange configuration.
- Actions: Update UCI Score.
- User Email: Select source field for Email from the entity
- Source (Reduction): Select source or static as type and select field for score reduction or enter static value to reduce the score by that field or the static value.
- Source: Name of the source reporting this action
- Reason: Reason for the score change.
- Generate Alert: Click on the Generate Alert switch to enable it. This would ensure that new alerts are added in the CTO module whenever this action is taken
- Perform action during Maintenance Window: Actions will be performed during the maintenance window
- Require Approval: If enabled all the actions will require user approval from the records page.
Click on Save.
Click on Sync.
Add Time Period and Click on the Fetch button and number of records on which action will be taken when you click on Sync button.

Add a Host to a Private App

Whenever this action is triggered, host will be added to private app.

Click play to watch a video.

Go to Risk Exchange > Actions.
Click Add Action Configuration.
Enter these values:
- Business Rule: Select a Business Rule.
- Configuration: Netskope Risk Exchange configuration.
- Actions: Add Host to Private App.
- Host: Host address to append to the private app.
- Tags: Tags to set for the private app. These tags will overwrite existing tags available on your tenant.
- Private App Name: Select a private app.
- Create New Private App: Create private app with given name. (Only enter if you have selected ‘Create new private app’ in Private App Name.)
- Protocol: Protocol.
- TCP Ports: Comma-separated ports for the TCP protocol.(Only enter if you have selected ‘TCP’ in Protocol.)
- UDP Ports: Comma-separated ports for the UDP protocol.(Only enter if you have selected ‘UDP’ in Protocol.)
- Publisher: Select publishers.
- Use Publisher DNS: Use publishers DNS.
- Default Host: The default Host to be used when the private app is empty.
- Generate Alert: Click on the Generate Alert switch to enable it. This would ensure that new alerts are added in the CTO module whenever this action is taken
- Perform action during Maintenance Window: Actions will be performed during the maintenance window
- Require Approval: If enabled all the actions will require user approval from the records page.
Click on Save.
Click on Sync.
Add a Time Period and click Fetch and number of records on which action will be taken when you click Sync.

Create or Update an App Instance

Whenever this action is triggered, app instance will be created or updated.

Click play to watch a video.

Go to Risk Exchange > Actions.
Click Add Action Configuration.
Enter these values:
- Business Rule: Select a Business Rule.
- Configuration: Netskope Risk Exchange configuration.
- Actions: Create or Update App Instance.
- Instance ID: For AWS, use the account ID. For Azure, use the Subscription. For GCP, use the Project. The `app + instance_id` combo must be new.
- Instance Name: Used to change instance name, and must be unique. Name should be unique within `app + instance_id` or `app + instance_name`.
- Application Name: Name of the application.
- Tag: Tags to add.
- Generate Alert: Click on the Generate Alert switch to enable it. This would ensure that new alerts are added in the CTO module whenever this action is taken
- Perform action during Maintenance Window: Actions will be performed during the maintenance window
- Require Approval: If enabled all the actions will require user approval from the records page.
Click on Save.
Click on Sync.
Add Time Period and click on the Fetch button and number of records on which action will be taken when you click on Sync button.

Tag Application

Whenever this action is triggered, an app instance will be created or updated.

Click play to watch a video.

Go to Risk Exchange > Actions.
Click Add Action Configuration.
Enter these values:
- Business Rule: Select a Business Rule.
- Configuration: Netskope Risk Exchange configuration.
- Actions: Tag application.
- Tags: Comma separated tag values.
- Application Names: Comma separated application names. 100 is the max allowed input size.
- Application Name: Name of the application.
- Application Ids: Comma separated application ids. 100 is the max allowed input size.
- Generate Alert: Click on the Generate Alert switch to enable it. This would ensure that new alerts are added in the CTO module whenever this action is taken
- Perform action during Maintenance Window: Actions will be performed during the maintenance window
- Require Approval: If enabled all the actions will require user approval from the records page.
Click on Save
Click on Sync
Add Time Period and Click on the Fetch button and number of records on which action will be taken when you click on Sync button.

No Actions

This action has no impact on users.

Go to Risk Exchange > Actions.
Click Add Action Configuration.
Enter these values:
- Business Rule: Select a Business Rule.
- Configuration: Netskope Risk Exchange configuration.
- Actions: no actions.
- Generate Alert: Click on the Generate Alert switch to enable it. This would ensure that new alerts are added in the CTO module whenever this action is taken.
- Perform action during Maintenance Window: Actions will be performed during the maintenance window
- Require Approval: If enabled all the actions will require user approval from the records page.
Click Save.
Click Sync.
Add Time Period and Click on the Fetch button and number of IoCs will be shared when you click on Sync button.

View Performed Actions in your Netskope Tenant

Add a User to a Group

Go to Settings > Security Cloud Platform > Groups.
Select the group name that you selected while adding an action configuration, and then select View Details.

Remove a User from a Group

Go to Settings > Security Cloud Platform > Groups.
Select the group name that you selected while adding an action configuration for remove from group action, and then select View Details.

Update UCI Score

Go to Incidents > Behavior Analytics and select the user for which the score has been updated.

Add Host to a Private App

Go to Settings > Security Cloud Platform > App Definition > Private Apps.
Select the Private app name that you configured while adding an action configuration to add a host to private app and check for hosts.

Create or Update an App Instance

Go to Policies > App Instance, to view updated app instances on this page.

Tag Application

Go to Skope IT > Applications and select the application for which tag has been added.
Go to the About section of an Application to check for the tags.

Validate the Risk Exchange Plugin

Validate UBA Alerts are Present in your Tenant

In your Netskope tenant, go to Skope IT.
Click Users and click on a User Name.
For UBA Alerts, go to Skope IT > Alerts > Add Filter > Inside Alert Type, and select Uba, and then click Apply.

Validate in Risk Exchange

To verify the Users pulled from Netskope, go to Risk Exchange > Records and select the Entity that is configured in the User section of Netskope Risk Exchange plugin.

Pulling of Users

To validate the pulling of UBA Alerts from your Netskope tenant, go to the Logging in Netskope CE. Search for the pulled logs.

Pulling of Applications

To validate the pulling of UBA Alerts from your Netskope tenant, go to the Logging in Netskope CE and search for the pulled logs.

Troubleshooting the Risk Exchange Plugin

Receiving Error While Configuring the Netskope Risk 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.
Update the v2 token permissions and add the permission for the above endpoint list from Netskope Dashboard.

Risk Exchange v1.0.0 Plugin