Method: instances.summarizeEntity

Full name: projects.locations.instances.summarizeEntity

Returns all entity data over specified time.

HTTP request


Path parameters

Parameters
instance

string

Required. The name of the parent resource, which is the SecOps instance to summarize an 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. Whether to return prevelance data for the entity.
prevalenceInput

object (FieldAndValue)

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

boolean

Optional. Whether to return alertCounts for the entity.
includeAllUdmEventTypesForFirstLastSeen

boolean

Optional. If true, it includes all types of events we show in UDM Search to calculate the first and last seen time of an entity.
Union parameter id. Identifier options to find the entity snapshots. id can be only one of the following:
entityId

string

ID of the entity indicator to list entity summary snapshots for.
fieldAndValue

object (FieldAndValue)

A set of fields which characterize the entity indicator to return entity summary snapshots for. This can use either an enumerated type or infer the type from a UDM path.

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)
    }
  ],
  "alertCounts": [
    {
      object (AlertCountByRule)
    }
  ],
  "hasMoreAlerts": boolean,
  "timeline": {
    object (Timeline)
  },
  "prevalenceResult": [
    {
      object (PrevalenceSnapshot)
    }
  ],
  "tpdPrevalenceResult": [
    {
      object (PrevalenceSnapshot)
    }
  ],
  "assetPrevalenceTimes": [
    string
  ],
  "assetRiskMetadata": [
    {
      object (AssetRiskMetadata)
    }
  ],
  "fileMetadataAndProperties": {
    object (MetadataAndProperties)
  },
  "widgetMetadata": {
    object (WidgetMetadata)
  },
  "topLevelDomain": {
    object (Entity)
  },
  "nextPageToken": string
}
Fields
entities[]

object (Entity)

A list of entities. Each "entity" is a snapshot of data about the requested entity indicator for a particular time range.
alertCounts[]

object (AlertCountByRule)

Rule display names with an alert count for each rule that has alerts that match the requested entity indicator. This will only be populated if returnAlerts is true in the request.
hasMoreAlerts

boolean

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

object (Timeline)

Data representing the number of alerts associated with the entity indicator within the requested time range, bucketed by time ranges. This will only be populated if returnAlerts is true in the request.
prevalenceResult[]

object (PrevalenceSnapshot)

Prevalence statistics for the requested indicator.
tpdPrevalenceResult[]

object (PrevalenceSnapshot)

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

string (Timestamp format)

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

Uses RFC 3339, where generated output will always be Z-normalized and use 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".
assetRiskMetadata[]

object (AssetRiskMetadata)

Vendor-defined risk metadata for an asset entity. This will only be populated if the requested entity indicator is for an asset entity (internal IP, hostname, MAC, etc.)
fileMetadataAndProperties

object (MetadataAndProperties)

File hash metadata and properties. This data will be only be populated if the requested entity indicator is for a file entity (MD5, SHA1, SHA256 file hash).
widgetMetadata

object (WidgetMetadata)

Widget metadata for the VirusTotal VT Augment widget. This is included for entity indicators that are supported by VirusTotal including file hash (MD5, SHA1, SHA256), IP, and Domain.
topLevelDomain

object (Entity)

Data describing the Top level domain entity for the requested indicator.
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.entities.summarize

For more information, see the IAM documentation.

PrevalenceSnapshot

Prevalence statistics for an artifact at a particular point of time.

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

string (Timestamp format)

The timestamp that the prevalence statistic represents.

Uses RFC 3339, where generated output will always be Z-normalized and use 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".
count

integer

The prevalence count for the indicator at the prevalenceTime.

AssetRiskMetadata

Arbitrary vendor-defined risk metadata about an asset entity.

JSON representation 
{
  "sourceProduct": string,
  "uploadTime": string,
  "risks": {
    string: string,
    ...
  }
}
Fields
sourceProduct

string

Source product that produces the risk metadata for the asset.
uploadTime

string (Timestamp format)

The timestamp of the event that uploaded this metadata version.

Uses RFC 3339, where generated output will always be Z-normalized and use 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".
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

Data about a file hash entity.

JSON representation 
{
  "metadata": [
    {
      object (Label)
    }
  ],
  "properties": [
    {
      object (FileHashProperties)
    }
  ],
  "specialDescriptions": [
    string
  ],
  "queryState": 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.
specialDescriptions[]

string

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

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

VirusTotal widget metadata.

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

string

Widget rendering URL for the VirusTotal VT Augment widget. See https://docs.virustotal.com/reference/widgeturl
detections

integer

Number of scanners which flagged this content.
total

integer

Total number of scanners.