Ticket Orchestrator v2.0.0 Plugin
Ticket Orchestrator v2.0.0 Plugin
This document explains how to configure the Ticket Orchestrator plugin in the Cloud Exchange platform. With this plugin, you can store the alerts and events pulled from the Netskope tenant in Cloud Exchange, and update the incidents back to the Netskope tenant.
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 CE 5.1.0 and above versions.
Ticket Orchestrator Plugin Support
This plugin is used to pull alerts and events data from Netskope tenant and store them in CE.
| Alert Types | Yes: DLP, Malware, Policy, Compromised Credential, Malsite, Quarantine, Remediation, Security Assessment, Watchlist, CTEP, UBA |
| Event Types | Yes: Incident, Endpoint |
Mappings
Mapping for Alerts page
| Netskope API Fields | Netskope CE Fields |
|---|---|
| _id | id |
| alert_name | alertName |
| alert_type | alertType |
| app | app |
| appcategory | appCategory |
| type | type |
| user | user |
| timestamp | time |
| raw_fields | rawData |
Mapping for Events page
| Netskope API Fields | Netskope CE Fields |
|---|---|
| _id | id |
| evnet_type | eventType |
| user | user |
| timestamp | time |
| raw_fields | rawData |
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/compromisedcredential | GET | Pull the data from Netskope tenant |
| /api/v2/events/dataexport/alerts/dlp | GET | Pull the data from Netskope tenant |
| /api/v2/events/dataexport/alerts/malware | GET | Pull the data from Netskope tenant |
| /api/v2/events/dataexport/alerts/remediation | GET | Pull the data from Netskope tenant |
| /api/v2/events/dataexport/alerts/securityassessment | GET | Pull the data from Netskope tenant |
| /api/v2/events/dataexport/alerts/ctep | GET | Pull the data from Netskope tenant |
| /api/v2/events/dataexport/alerts/malsite | GET | Pull the data from Netskope tenant |
| /api/v2/events/dataexport/alerts/policy | GET | Pull the data from Netskope tenant |
| /api/v2/events/dataexport/alerts/quarantine | GET | Pull the data from Netskope tenant |
| /api/v2/events/dataexport/alerts/uba | GET | Pull the data from Netskope tenant |
| /api/v2/events/dataexport/alerts/watchlist | GET | Pull the data from Netskope tenant |
| /api/v2/events/dataexport/events/endpoint | GET | Pull the data from Netskope tenant |
| /api/v2/events/dataexport/events/incident | GET | Pull the data from Netskope tenant |
| /api/v2/incidents/update | PATCH | To update incidents back to Netskope |
Pull the data from Netskope Tenant
Here is an example from one of the above mentioned APIs. To access the API Response for other APIs, you can use the Swagger API in your Netskope tenant (Settings > Tools > REST API v2 > API Documentation).
API Endpoint: /api/v2/events/dataexport/alerts/dlp
Method: GET
Parameters:
Index: <name of iterator index>
operation: <epoch time from where want to fetch the data>
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.0.1
Workflow
- Generate a v2 token for your Netskope tenant.
- Configure the Ticket Orchestrator plugin.
- Configure a third-party plugin.
- Configure a Queue with a third-party plugin (like ServiceNow).
- Validate the plugin.
Click play to watch a video.
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 API Details, 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 Ticket Orchestrator Plugin
- In Cloud Exchange, go to Settings and enable the Ticket Orchestrator Module.
- In Settings, go to Plugins.
- Search for and select the Netskope Ticket Orchestrator plugin box.
- Enter the Basic Information:
- Configuration Name: Enter a unique configuration name.
- Tenant: Select the configured Tenant from dropdown.
- Sharing Sync Intervals: Select how often to sync sharing.
- Update Incidents back to the Netskope Tenant: Enable to update incidents on your Netskope tenant.
- Click Next and enter the Configuration Parameters:
- Alert Types: Types of alerts to be pulled.
- Initial Range for Alerts (in days): Initial range for alerts data to be pulled.
- Event Types: Types of events to be pulled.
- Initial Range for Events (in hours): Initial range for events data to be pulled.
- Alert/Event Query: Only the alerts/events matching this filter query will be stored and considered for ticket creation. If kept blank all the Alerts and Events will be considered for ticket creation.
- Click Next and configure the details for updating Incidents.
- Click Save.
Create a Business Rule for Ticket Orchestrator
- Go to Ticket Orchestrator > Business Rule and click Create New Rule.
- Enter the Rule name and create a filter query.
- Click Save.
Add a Queue for Ticket Orchestrator
In order to add a Queue, a third-party Ticket Orchestrator plugin, like ServiceNow, has to be configured before proceeding. You need a third-party source plugin (configuration) to create a Queue configuration.
- Go to Ticket Orchestrator > Queues and click Add Queue Configuration.
- Enter the Queue information:
- Business Rule: Select a business rule from the dropdown.
- Configuration: Select your third-party plugin from the dropdown.
- Queues: Search for and select Incident Management.
- Map Fields: Review the target and deduplication mappings.
- Click Save.
Tickets
After the tickets for Netskope Incidents are created on the third-party plugin, like ServiceNow, update the ticket on there, and wait for the ticket to be synced in CE. After the ticket is synced in CE on the next execution of Incident update task, the same incident will be updated on Netskope as well.
All the tickets created will be displayed in the Tickets Page.
Validate the Ticket Orchestrator Plugin
Validate Alerts are Present in your Netskope Tenant
- In your Netskope tenant, go to Skope IT.
- Go to Alerts > Filters and select an option from the Last x Days dropdown in the top-right corner
Validate Incidents Events are Present in your Tenant
- In your Netskope tenant, go to Skope IT.
- Go to Incidents > DLP and select an option from the Last x Days dropdown in the top-right corner
Validate Endpoint Events are Present in your Tenant
- In your Netskope tenant, go to Skope IT.
- Go to Skope IT > Endpoint Events and select an option from the Last x Days dropdown in the top-right corner.
Validate the Pull
To validate the pulling of Alerts from the Netskope tenant and getting stored in the Netskope CE, go to Ticket Orchestrator > Alerts. 
To validate the pulling of Events from the Netskope tenant and getting stored in the Netskope CE, go to Ticket Orchestrator > Events.
Validate the Ticket Creation
Go to the Ticket Orchestrator > Tickets and check for the created tickets.
Validate the Incident is updated on Netskope from CE
Incident update works only when the user has enabled “Update Incidents back to the Netskope Tenant” for this plugin and will happen at the configured sync interval. When the ticket is updated on third party platform (eg. service now) CE will sync the updated status (at third party plugin sync interval) and after that it will initiate the incident update on Netskope tenant.
- Go to the Ticket Orchestrator > Tickets and check for the created tickets.
- Expand the incident type and check for Incident Sync Status.
Validate the Incident is Updated on Netskope
- Go to Incidents > DLP and select the Incident which was updated from CE.
- Click Check Object History.
- Verify the updated incident from the history.
Troubleshooting the Ticket Orchestrator Plugin
Receiving Error While Configuring the Netskope Ticket Orchestrator
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 a 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.
Receiving error while updating the incidents’ status
Getting the error: Error occurred while updating the incidents’ status to Netskope Tenant for batch No. x. 
Cause: The provided V2 token does not have the minimum required permissions to update the incidents’ status back to the Netskope Tenant.
What to do:
- Go to Logging and look for the error message regarding the Netskope CTO plugin.
- Expand the log and get the information regarding the error.
- Provide the /api/v2/incidents/update read and write permissions to the v2 token.
