Method: instances.summarizeEntity

Full name: projects.locations.instances.summarizeEntity

Returns all entity data over specified time.

HTTP request

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

Path parameters

Parameters
instance

string

Required. The ID of the Instance to summarize entity for. Format: projects/{project}/locations/{location}/instances/{instance}

Query parameters

Parameters
timeRange

object (Interval)

Required. Time range to retrieve the summary for [Inclusive start time, exclusive end time).
pageSize

integer

The maximum number of Entities to return. The service may return fewer than this value. If unspecified, at most 1000 entities will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.
pageToken

string

A page token received from a previous SummarizeEntityRequest call. Provide this to retrieve the subsequent page.
returnPrevalence

boolean

Optional. Request prevelances for the entity.
prevalenceInput

object (FieldAndValue)

Optional. Entity to use in order to compute combined prevalences. return_prevalence needs to be set in order to compute prevalence.
returnAlerts

boolean

Optional. Request alerts for the entity.

Union parameter id.

id can be only one of the following:
entityId

string

ID of the entity.
fieldAndValue

object (FieldAndValue)

Field path or type with value to identify entity.

Request body

The request body must be empty.

Response body

Response message to retrieve summarized data for an entity.

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

JSON representation 
{
  "entities": [
    {
      object (Entity)
    }
  ],
  "alert_counts": [
    {
      object (AlertCountByRule)
    }
  ],
  "has_more_alerts": boolean,
  "timeline": {
    object (Timeline)
  },
  "prevalence_result": [
    {
      object (PrevalenceSnapshot)
    }
  ],
  "tpd_prevalence_result": [
    {
      object (PrevalenceSnapshot)
    }
  ],
  "asset_prevalence_times": [
    string
  ],
  "asset_risk_metadata": [
    {
      object (AssetRiskMetadata)
    }
  ],
  "file_metadata_and_properties": {
    object (MetadataAndProperties)
  },
  "widget_metadata": {
    object (WidgetMetadata)
  },
  "top_level_domain": {
    object (Entity)
  },
  "next_page_token": string
}
Fields
entities[]

object (Entity)

A list of entities.
alert_counts[]

object (AlertCountByRule)

Rule names with alert count for each.
has_more_alerts

boolean

Indicates if there are more alerts than the limit (1000 currently).
timeline

object (Timeline)

Bucketed timeline with alert count.
prevalence_result[]

object (PrevalenceSnapshot)

Timestamp and prevalences for a given entity. If there is no result, that means there are no references to the entity in the customer instance.
tpd_prevalence_result[]

object (PrevalenceSnapshot)

If the entity was a domain with a different top private domain, this will contain statistics for the top private domain.
asset_prevalence_times[]

string (Timestamp format)

Timestamps at which the asset was queried for the entity being summarized.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
asset_risk_metadata[]

object (AssetRiskMetadata)

Vendor defined risk metadata.
file_metadata_and_properties

object (MetadataAndProperties)

File hash metadata and properties.
widget_metadata

object (WidgetMetadata)

Widget metadata for VT widget.
top_level_domain

object (Entity)

Top level domain entity.
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.entities.summarize

For more information, see the IAM documentation.

PrevalenceSnapshot

Prevalence for an artifact at a particular point of time.

JSON representation 
{
  "prevalence_time": string,
  "count": integer
}
Fields
prevalence_time

string (Timestamp format)

The timestamp that the prevalence statistic represents.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
count

integer

The prevalence count for the given entity.

AssetRiskMetadata

Arbitrary Vendor defined risk metadata.

JSON representation 
{
  "source_product": string,
  "upload_time": string,
  "risks": {
    string: string,
    ...
  }
}
Fields
source_product

string

Source product.
upload_time

string (Timestamp format)

The timestamp of the event that uploaded this metadata version.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
risks

map (key: string, value: string)

Map from a risk's name to its description.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

MetadataAndProperties

Metadata and properties subpanel

JSON representation 
{
  "metadata": [
    {
      object (Label)
    }
  ],
  "properties": [
    {
      object (FileHashProperties)
    }
  ],
  "special_descriptions": [
    string
  ],
  "query_state": enum (QueryState)
}
Fields
metadata[]

object (Label)

File hash's metadata include file type and file size information.
properties[]

object (FileHashProperties)

Properties include PE properties (for windows file only) and signer details.
special_descriptions[]

string

Special descriptions for risks of some well-known file types, e.g., micsoroft office documents.
query_state

enum (QueryState)

Output only. File hash query state.

FileHashProperties

File hash properties

JSON representation 
{
  "title": string,
  "properties": [
    {
      object (Label)
    }
  ]
}
Fields
title

string

Title of properties: for example, "PE Properties".
properties[]

object (Label)

Repeated field of properties

QueryState

File hash query state.

Enums
QUERY_STATE_UNSPECIFIED Unspecified state for file hash query.
QUERY_STATE_OK_HAS_RESULT Query is successful and has result.
QUERY_STATE_OK_HAS_NO_RESULT Query is successful but has no result.
QUERY_STATE_ERROR Query is unsuccessful.

WidgetMetadata

Widget metadata.

JSON representation 
{
  "uri": string,
  "detections": integer,
  "total": integer
}
Fields
uri

string

Widget link for the input query.
detections

integer

Number of scanners which flagged this content.
total

integer

Total number of scanners.