Using the REST API v2 UCI Impact Endpoints

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.

UEBA_UCI_Details.jpg

The following APIs are enabled by Netskope for UCI Impact:

  • UCI Impact
  • Get Anomaly
  • Search Anomalies
  • Mark Anomaly as Allowed
  • UCI Reset Rule

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

Get Anomaly API

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"
    }

Search Anomalies API

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:

  • There are two kinds of filtering for the payload:
  1. A combination of user, source, startTime, and endTime
  2. 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-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": []
}

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

Mark_Anomaly_as_Allowed.jpg
Share this Doc

Using the REST API v2 UCI Impact Endpoints

Or copy link

In this topic ...