Method: entityRiskScores.query

Full name: projects.locations.instances.entityRiskScores.query

Queries the instance for EntityRiskScores. The API returns Risk Scores for entities including users and assets.

HTTP request


Path parameters

Parameters
instance

string

Required. The name of the parent resource, which is the SecOps instance this request is sent to. Format: projects/{project}/locations/{location}/instances/{instance}

Query parameters

Parameters
filter

string

Filter expression to be applied to the list of Entity Risk Scores. Timestamps use RFC 3339. Read more here

  • riskWindow: Filter field which represents the time window over which an Entity Risk Score is computed. This could be 24 hours or 7 days. Example:
    filter=riskWindow.start_time >= "2023-08-10T14:20:59.950218416Z" AND riskWindow.end_time <= "2023-08-17T14:20:59.950219626Z"

  • riskScore: Filter by riskScore in the current risk window and time window. Example:
    filter=riskScore<20

  • riskDelta: Filter by riskDelta in the risk window and time window. Example:
    filter=riskDelta>=12 AND riskDelta<=850
    Risk_delta is a percentage representation of change. There are multiple cases of riskDelta calculation:

    1. Previous riskScore was 0 (either truly 0 or non-existent) and current risk score is a non 0 number. This is a 100 percent positive delta.
    2. Previous risk score and current risk score are equal (eg. both 0): delta is 0 since there was no change.
    3. Previous risk score is higher than current score: delta is negative.
    4. Previous risk score is lower than current score: delta is positive.
    5. If riskDelta calculation yields a value > 200%, the delta is instead set to a constant value of 200%.

  • rawRiskScore: Filter by rawRiskScore in the current risk window and time window. Example:
    filter=rawRiskScore<100

  • rawRiskDelta: Filter by rawRiskDelta in the risk window and time window. Example:
    filter=rawRiskDelta>=5 AND rawRiskDelta<=100

  • detectionsCount: Filter by number of detections for the entity in the risk window and time window. Example:
    filter=detectionsCount < 10

  • entity: Filter by details of the entity. Example:
    filter=entity.metadata.entity_type="ASSET"

  • entityIndicator: Filter by entity indicator. The sub fields need to be explicitly requested. Examples:

    • filter=entityIndicator.email: "test@example.com"
    • filter=entityIndicator.hostname="test_hostname"
  Supported entityIndicator subfields:
  - entityIndicator.windows_sid
  - entityIndicator.email
  - entityIndicator.user_name
  - entityIndicator.employee_id
  - entityIndicator.hostname
  - entityIndicator.mac
  - entityIndicator.product_id
  - entityIndicator.asset_ip_address
  - entityIndicator.product_object_id
  - entityIndicator.Namespace
    This can be used in conjunction with an entityIndicator for an
    asset (hostname, mac, productId, assetIpAddress).

  • risk_score_version: Filter results by risk score version. Example:
    filter=risk_score_version = "RISK_SCORE_VERSION_V0_01"

  • lookback_interval: Filter by the lookback interval. Example:
    filter=lookback_interval.start_time >= "2023-08-10T14:20:59.950218416Z" AND lookback_interval.end_time <= "2023-08-17T14:20:59.950219626Z"
orderBy

string

Ordering of Entity Risk Scores. Example: orderBy=detectionsCount
pageSize

integer

The maximum number of Entity Risk Scores to return. The service may return fewer than this value. If unspecified, at most 10000 scores will be returned. The maximum value is 10000; values above 10000 will be coerced to 10000.
pageToken

string

A page token, received from a previous entityRiskScores.query call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to entityRiskScores.query must match the call that provided the page token. If parameters do not match, the request is handled as a new request and the response will not be an accurate representation of the 'next_page' that the client requests for.

Request body

The request body must be empty.

Response body

Response message for Querying Entity Risk Scores.

If successful, the response body contains data with the following structure:

JSON representation 
{
  "entityRiskScores": [
    {
      object (EntityRiskScore)
    }
  ],
  "detectionsCounts": [
    {
      object (DetectionsCount)
    }
  ],
  "nextPageToken": string
}
Fields
entityRiskScores[]

object (EntityRiskScore)

The Risk Scores for a specific time range and filtered criteria.
detectionsCounts[]

object (DetectionsCount)

The detections count for a specific time range and filtered criteria.
nextPageToken

string

A token, which can be sent as pageToken to retrieve the next page. If this field is omitted, there are no subsequent pages.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the instance resource:

  • chronicle.entityRiskScores.queryEntityRiskScores

For more information, see the IAM documentation.

EntityRiskScore

Entity Risk Score

JSON representation 
{
  "entity": {
    object (Entity)
  },
  "riskWindow": {
    object (Interval)
  },
  "riskScore": integer,
  "riskDelta": {
    object (EntityRiskDelta)
  },
  "detectionsCount": integer,
  "firstDetectionTime": string,
  "lastDetectionTime": string,
  "entityIndicator": {
    object (EntityIndicator)
  },
  "rawRiskScore": integer,
  "rawRiskDelta": {
    object (EntityRiskDelta)
  },
  "entityId": string
}
Fields
entity

object (Entity)

Required. Entity for which the Risk Score is computed
riskWindow

object (Interval)

Required. Time window against which the Entity Risk Score is computed, e.g. 24 hours 7 days etc.
riskScore

integer

Normalized Risk Score for the Entity. This value is always between 0-1000
riskDelta

object (EntityRiskDelta)

Represents the change is riskScore for an entity between end of the previous risk window and the end of the current risk window.
detectionsCount

integer

Number of Detections that make up the risk score within the risk window.
firstDetectionTime

string (Timestamp format)

First detection timestamp within the specified risk window. Empty when no detections.

Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
lastDetectionTime

string (Timestamp format)

Last detection timestamp within the specified risk window. Empty when no detections.

Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
entityIndicator

object (EntityIndicator)

Indicator to the entity.
rawRiskScore

integer

Raw Risk Score for the Entity. This value is unbounded.
rawRiskDelta

object (EntityRiskDelta)

Represents the change in rawRiskScore for an entity between end of the previous risk window and the end of the current risk window.
entityId

string

An encoded string of Most Reliable Indicator tuple (value, type, namespace).

EntityRiskDelta

Describes the difference of a risk score between two points in time

JSON representation 
{
  "previousRangeEndTime": string,
  "riskScoreDelta": integer,
  "previousRiskScore": integer,
  "riskScoreNumericDelta": integer
}
Fields
previousRangeEndTime

string (Timestamp format)

End time of the previous riskWindow.

Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
riskScoreDelta

integer

Normalized risk score delta.
previousRiskScore

integer

Normalized risk score from previous risk window
riskScoreNumericDelta

integer

Numeric change in risk score from previous to current risk window

DetectionsCount

Describes the number of detections within a time bucket (e.g., 2h interval).

JSON representation 
{
  "timeBucket": {
    object (Interval)
  },
  "detectionsCount": integer
}
Fields
timeBucket

object (Interval)

Interval representing the time bucket for which we are counting detections.
detectionsCount

integer

Number of Detections that make up the risk score within the risk window.