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

GET https://chronicle.googleapis.com/v1alpha/{instance}/entityRiskScores:query

Path parameters

Parameters
instance

string

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

  • risk_window: 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=risk_window.start_time >= "2023-08-10T14:20:59.950218416Z" AND risk_window.end_time <= "2023-08-17T14:20:59.950219626Z"

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

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

    1. Previous risk_score 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 risk_delta calculation yields a value > 200%, the delta is instead set to a constant value of 200%.

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

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

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

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

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

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

  • 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: order_by=detections_count
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 QueryEntityRiskScores call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to QueryEntityRiskScores 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 
{
  "entity_risk_scores": [
    {
      object (EntityRiskScore)
    }
  ],
  "detections_counts": [
    {
      object (DetectionsCount)
    }
  ],
  "next_page_token": string
}
Fields
entity_risk_scores[]

object (EntityRiskScore)

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

object (DetectionsCount)

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

string

A token, which can be sent as page_token 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)
  },
  "risk_window": {
    object (Interval)
  },
  "risk_score": integer,
  "risk_delta": {
    object (EntityRiskDelta)
  },
  "detections_count": integer,
  "first_detection_time": string,
  "last_detection_time": string,
  "entity_indicator": {
    object (EntityIndicator)
  },
  "raw_risk_score": integer,
  "raw_risk_delta": {
    object (EntityRiskDelta)
  },
  "entity_id": string
}
Fields
entity

object (Entity)

Required. Entity for which the Risk Score is computed
risk_window

object (Interval)

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

integer

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

object (EntityRiskDelta)

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

integer

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

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

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

object (EntityIndicator)

Indicator to the entity.
raw_risk_score

integer

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

object (EntityRiskDelta)

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

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 
{
  "previous_range_end_time": string,
  "risk_score_delta": integer,
  "previous_risk_score": integer,
  "risk_score_numeric_delta": integer
}
Fields
previous_range_end_time

string (Timestamp format)

End time of the previous risk_window.

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

integer

Normalized risk score delta.
previous_risk_score

integer

Normalized risk score from previous risk window
risk_score_numeric_delta

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 
{
  "time_bucket": {
    object (Interval)
  },
  "detections_count": integer
}
Fields
time_bucket

object (Interval)

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

integer

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