Using the REST API v2 UCI Impact Endpoints
The UCI Impact REST API enables the Netskope platform to ingest 3rd party risk impact as an input to a user's User Confidence Index (UCI) score.
This REST API allows reducing a user's UCI by the specified number based on risk learned from a partner vendor (such as Endpoint Detection and Response, an IdP, or email).
The API parameters allow specifying the user, source, timestamp, score (reduction), and reason to reduce the user's UCI.
In addition, a new alert provides information on anomalies impacting the UCI created in Advanced UEBA using a 3rd party API. Details for the anomalies impacting UCI are shown in the Behavior Analytics Incidents and Behavior Analytics Alerts pages.
The following APIs are enabled by Netskope for UCI Impact:
UCI Impact
Get Anomaly
Search Anomalies
Mark Anomaly as Allowed
The sections below describe the API details.
UCI Impact API
This API is for a third party to provide UCI impact for Netskope to digest. The API returns the anomalyId in response if the request is received. AnomalyId can be used to get anomaly information and revert UCI ingestion if needed. This is an asynchronous API, it will take a few minutes (about 15 minutes) to transform the request to an anomaly and to generate an alert.
Method: POST
URL: https://<tenant>/api/v2/incidents/user/uciimpact
Header:
-H 'Netskope-Api-Token: XXXXXXX'
-H 'Content-Type: application/json'
Parameters:
The current list of parameters are available in Swagger. Navigate to Settings > Tools > REST API v2 > 
to open the Swagger UI tab in your browser.
Example:
curl -kv -X POST 'https://<tenant>/api/v2/incidents/user/uciimpact' \
-H 'Netskope-Api-Token: xxxxx' \
-H 'Content-Type: application/json' \
-d '{
"user": "name@netskope.com",
"score": 50,
"timestamp": 1654823213000,
"source": "Dropbox",
"reason": "login failed too many times"
}'
Get Anomaly API
These APIs are used for fetching anomaly information.
Method: GET
URL: https://<tenant>/api/v2/incidents/anomalies/{anomalyId}
Header:
-H 'Netskope-Api-Token: XXXXXXX'
-H 'Content-Type: application/json'
Parameters:
The current list of parameters are available in Swagger. Navigate to Settings > Tools > REST API v2 > to open the Swagger UI tab in your browser.
Example:
curl -kv -X GET 'https://<tenant>/api/v2/incidents/anomalies/xxxxx \
-H 'Netskope-Api-Token: xxxxx' \
-H 'Content-Type: application/json' \
Response:
{
"anomalyId": "xxxxx",
"user": "blah@sm.com",
"time": 1677618382070,
"score": 20,
"activity": "ActivityForUciImpactAPI",
"eventId": "event_id2",
"anomalyCreatedTime": "2023-02-28T21:06:24Z",
"source": "OKTA",
"reason": "login failed in OKTA"
}Search Anomalies API
Use the Search Anomalies API to search anomalies by source with a time range.
Method: POST
URL: https://<tenant>/api/v2/incidents/anomalies/getanomalies?activity=ActivityForUciImpactAPI&offset=0&limit=1000&fields=field1,field2,field3
Header:
-H 'Netskope-Api-Token: XXXXXXX'
-H 'Content-Type: application/json'
Parameters:
The current list of parameters are available in Swagger. Navigate to Settings > Tools > REST API v2 > to open the Swagger UI tab in your browser.
Filter Options:
There are two kinds of filtering for the payload:
A combination of user, source, startTime, and endTime
By anomaly ID
Only the “equals” condition is supported.
The "startTime" and "endTime" are a pair for the time range. They must be set at the same time. You can only query anomalies that happened within the last 90 days.
If the "startTime" and "endTime" are not set, anomalies in the range (now - 90 days) are returned.
If endTime < (now - 90 days), no anomaly is found.
Otherwise, the anomalies in the range (startTime, endTime) are returned.
Pagination:
offset: The (one-based) offset of the first item in the list to retrieve. Default is 0.
limit: Max number of items to retrieve. Default page size is 1000 and the max page size is 10,000.
Project Fields:
Project fields are an optional query parameter. Use this parameter to choose specific fields. Otherwise, all anomaly fields are returned.
Fields=field1,field2,field3. e.g. fields=anomalyId,user,source,reason,score
Separated by commas
The field name should be in the properties list in the response. 400 is returned if the input field is not in the predefined list.
Example:
curl -kv -X POST 'https://<tenant>/api/v2/incidents/anomalies/getanomalies?activity=ActivityForUciImpactAPI&offset=$offset&limit=$limit&fields=anomalyId,user,source,reason,score' \
-H 'Netskope-Api-Token: xxxxx' \
-H 'Content-Type: application/json' \
-d '{
"filters" :{
"user" : { "equals": ["user1", "user3"] },
"source" : { "equals": ["OKTA", "OKTA2"] },
"startTime": { "equals": 1654823213000 },
"endTime": { "equals": 1654833213000 }
}
}'
or
curl -kv -X POST 'https://<tenant>/api/v2/incidents/anomalies/getanomalies?activity=ActivityForUciImpactAPI&offset=$offset&limit=$limit&fields=anomalyId,user,source,reason,score' \
-H 'Netskope-Api-Token: xxxxx' \
-H 'Content-Type: application/json' \
-d '{
"filters" :{
"anomalyId" : { "equals": ["xxxxx", "xxxxx"] }
}
}'
Response:
{
"totalCount": 5000,
"results": [
{
"anomalyId": "xxxxx",
"user": "blah@sm.com",
"time": 1677618382070,
"score": 20,
"activity": "ActivityForUciImpactAPI",
"eventId": "event_id2",
"anomalyCreatedTime": "2023-02-28T21:06:24Z",
"source": "OKTA2",
"reason": "login failed in OKTA2"
},
{
"anomalyId": "xxxxx",
"user": "hello1@netskope.com",
"time": 1677618382070,
"score": 20,
"activity": "ActivityForUciImpactAPI",
"eventId": "event_id3",
"additionalProps": {
"extra": "must"
},
"anomalyCreatedTime": "2023-02-28T21:06:24Z",
"source": "OKTA3",
"reason": "login failed in OKTA3"
}
]
}
or
{
"totalCount": 0,
"results": []
}Mark Anomaly as Allowed API
Use this API for reverting UCI ingestion if needed. Use in conjunction with the Get Anomaly API to make sure the anomaly has been generated before reverting. The user’s UCI will be added back, and their anomaly status will be marked as allowed, but the alert still appears in SkopeIT.
Method: POST
URL: https://<tenant>/api/v2/incidents/anomalies/{anomalyId}/allow
Header:
-H 'Netskope-Api-Token: XXXXXXX'
-H 'Content-Type: application/json'
Parameters:
The current list of parameters are available in Swagger. Navigate to Settings > Tools > REST API v2 > to open the Swagger UI tab in your browser.
Example:
curl -kv -X POST 'https://<tenant>/api/v2/incidents/anomalies/xxxxx/allow' \
-H 'Netskope-Api-Token: xxxx' \
-H 'Content-Type: application/json' \
-d '{"reason": "not an anomaly"}'
Navigate to Incidents > Behavior Analytics > select the alert to view the following details.
