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:

The sections below describe the API details.

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-URL>/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-URL>/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"
}'

These APIs are used for fetching anomaly information.

Method: GET

URL: https://<tenant-URL>/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-URL>/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"
    }

Use the Search Anomalies API to search anomalies by source with a time range.

Method: POST

URL: https://<tenant-URL>/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:

Pagination:

Project Fields:

Project fields are an optional query parameter. Use this parameter to choose specific fields. Otherwise, all anomaly fields are returned.

Example:

curl -kv -X POST 'https://<tenant-URL>/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-URL>/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": []
}

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-URL>/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-URL>/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.