REST Resource: projects.locations.instances.entities

Resource: Entity

An Entity provides additional context about an entity in a UDM event (asset, user, etc.). For example, a PROCESS_LAUNCH event describes that user 'abc@example.corp' launched process 'shady.exe'. The event does not include information that user 'abc@example.com' is a recently terminated employee who administers a server storing finance data. Information stored in one or more Entities can add this additional context.

JSON representation 
{
  "name": string,
  "metadata": {
    object (EntityMetadata)
  },
  "entity": {
    object (Noun)
  },
  "additional": {
    object
  },
  "riskScore": {
    object (EntityRisk)
  },
  "metric": {
    object (Metric)
  },
  "relations": [
    {
      object (Relation)
    }
  ]
}
Fields
name

string

The resource name of the entity. Format: projects/{project}/locations/{location}/instances/{instance}/entities/{entity} projects/{project}/locations/{location}/instances/{instance}/analytics/{analytic}/entities/{entity} projects/{project}/locations/{location}/instances/{instance}/watchlists/{watchlist}/entities/{entity}
metadata

object (EntityMetadata)

Entity metadata such as timestamp, product, etc.
entity

object (Noun)

Noun in the UDM event that this entity represents.
additional

object (Struct format)

Important entity data that cannot be adequately represented within the formal sections of the Entity.
riskScore

object (EntityRisk)

Represents the entity risk scores resource
metric

object (Metric)

Metric details of the entity. Used if EntityType is METRIC.
relations[]

object (Relation)

One or more relationships between the entity (a) and other entities, including the relationship type and related entity.

EntityMetadata

Information about the Entity and the product where the entity was created. Next Tag: 17

JSON representation 
{
  "productEntityId": string,
  "collectedTimestamp": string,
  "creationTimestamp": string,
  "interval": {
    object (Interval)
  },
  "vendorName": string,
  "productName": string,
  "feed": string,
  "productVersion": string,
  "entityType": enum (EntityType),
  "description": string,
  "threat": [
    {
      object (SecurityResult)
    }
  ],
  "sourceType": enum (SourceType),
  "sourceLabels": [
    {
      object (Label)
    }
  ],
  "eventMetadata": {
    object (Metadata)
  },
  "structuredFields": {
    object
  },
  "extracted": {
    object
  }
}
Fields
productEntityId

string

A vendor-specific identifier that uniquely identifies the entity (e.g. a GUID, LDAP, OID, or similar).
collectedTimestamp

string (Timestamp format)

GMT timestamp when the entity information was collected by the vendor's local collection infrastructure.

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

string (Timestamp format)

GMT timestamp when the entity described by the productEntityId was created on the system where data was collected.

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

object (Interval)

Valid existence time range for the version of the entity represented by this entity data.
vendorName

string

Vendor name of the product that produced the entity information.
productName

string

Product name that produced the entity information.
feed

string

Vendor feed name for a threat indicator feed.
productVersion

string

Version of the product that produced the entity information.
entityType

enum (EntityType)

Entity type. If an entity has multiple possible types, this specifies the most specific type.
description

string

Human-readable description of the entity.
threat[]

object (SecurityResult)

Metadata provided by a threat intelligence feed that identified the entity as malicious.
sourceType

enum (SourceType)

The source of the entity.
sourceLabels[]

object (Label)

Entity source metadata labels.
eventMetadata

object (Metadata)

Metadata field from the event.
structuredFields
(deprecated)

object (Struct format)

Structured fields extracted from the log.
extracted

object (Struct format)

Flattened fields extracted from the log.

EntityType

Describes the type of entity. An unknown event type.

Enums
UNKNOWN_ENTITYTYPE @hide_from_doc
ASSET An asset, such as workstation, laptop, phone, virtual machine, etc.
USER User.
GROUP Group.
RESOURCE Resource.
IP_ADDRESS An external IP address.
CIDR_BLOCK A CIDR block.
FILE A file.
DOMAIN_NAME A domain.
URL A url.
MUTEX A mutex.
METRIC A metric.

SourceType

Describes the source of an entity.

Enums
SOURCE_TYPE_UNSPECIFIED Default source type
ENTITY_CONTEXT Entities ingested from customers (e.g. AD_CONTEXT, DLP_CONTEXT)
DERIVED_CONTEXT Entities derived from customer data such as prevalence, artifact first/last seen, or asset/user first seen stats.
GLOBAL_CONTEXT Global contextual entities such as WHOIS or Safe Browsing.

Metric

Stores precomputed aggregated analytic data for an entity.

JSON representation 
{
  "firstSeen": string,
  "lastSeen": string,
  "sumMeasure": {
    object (Measure)
  },
  "totalEvents": string,
  "metricName": enum (MetricName),
  "dimensions": [
    enum (Dimension)
  ],
  "exportWindow": string
}
Fields
firstSeen

string (Timestamp format)

Timestamp of the first time the entity was seen in the environment.

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

string (Timestamp format)

Time stamp of the last time last time the entity was seen in the environment.

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

object (Measure)

Sum of all precomputed measures for the given metric.
totalEvents

string (int64 format)

Total number of events used to calculate the given precomputed metric.
metricName

enum (MetricName)

Name of the analytic.
dimensions[]

enum (Dimension)

All group by clauses used to calculate the metric.
exportWindow

string (int64 format)

Export window for which the metric was exported.

Measure

Describes the precomputed measure.

JSON representation 
{
  "value": number,
  "aggregateFunction": enum (AggregateFunction)
}
Fields
value

number

Value of the aggregated measure.
aggregateFunction

enum (AggregateFunction)

Function used to calculate the aggregated measure.

AggregateFunction

Mathematic function used to calculate the value.

Enums
AGGREGATE_FUNCTION_UNSPECIFIED Default value.
MIN Minimum.
MAX Maximum.
COUNT Count.
SUM Sum.
AVG Average.
STDDEV Standard Deviation.

MetricName

The name of the precomputed analytic.

Enums
METRIC_NAME_UNSPECIFIED Default
NETWORK_BYTES_INBOUND Total received network bytes.
NETWORK_BYTES_OUTBOUND Total network sent bytes.
NETWORK_BYTES_TOTAL Total network sent bytes and received bytes.
AUTH_ATTEMPTS_SUCCESS Successful authentication attempts.
AUTH_ATTEMPTS_FAIL Failed authentication attempts.
AUTH_ATTEMPTS_TOTAL Total authentication attempts.
DNS_BYTES_OUTBOUND Total number of sent bytes for DNS events.
NETWORK_FLOWS_INBOUND Total number of events having non-null received bytes.
NETWORK_FLOWS_OUTBOUND Total number of events having non-null sent bytes.
NETWORK_FLOWS_TOTAL Total events having non-null sent or received bytes.
DNS_QUERIES_SUCCESS DNS query success count - Number of events with responseCode = 0.
DNS_QUERIES_FAIL Number of events with responseCode != 0.
DNS_QUERIES_TOTAL Total number of DNS queries made.
FILE_EXECUTIONS_SUCCESS Number of successfule file executions.
FILE_EXECUTIONS_FAIL Number of failed file executions.
FILE_EXECUTIONS_TOTAL Total number file executions.
HTTP_QUERIES_SUCCESS Number of successful HTTP queries.
HTTP_QUERIES_FAIL Number of failed HTTP queries.
HTTP_QUERIES_TOTAL Total number of HTTP queries.
WORKSPACE_EMAILS_SENT_TOTAL Total number of emails sent in Google Workspace.
WORKSPACE_TOTAL_DOWNLOAD_ACTIONS Total number of download actions in Google Workspace.
WORKSPACE_TOTAL_CHANGE_ACTIONS Total number of change actions in Google Workspace.
WORKSPACE_AUTH_ATTEMPTS_TOTAL Total number of authentication attempts in Google Workspace.
WORKSPACE_NETWORK_BYTES_OUTBOUND Number of outbound network bytes (total sent) in Google Workspace.
WORKSPACE_NETWORK_BYTES_TOTAL Total number of network bytes (both sent and received) in Google Workspace.
ALERT_EVENT_NAME_COUNT Track number of alerts fired by EDR/SENTINEL/MICROSOFT_GRAPH.
RESOURCE_CREATION_TOTAL Analytic tracking successful resource creations.
RESOURCE_CREATION_SUCCESS Analytic tracking successful resource creations.
RESOURCE_READ_SUCCESS Analytic tracking successful resource reads.
RESOURCE_READ_FAIL Analytic tracking failed resource reads.
RESOURCE_DELETION_SUCCESS Analytic tracking successful resource deletions.
RESOURCE_CREATION_FAIL Analytic tracking failed resource creations.
RESOURCE_DELETION_FAIL Analytic tracking failed resource deletions.
RESOURCE_DELETION_TOTAL Analytic tracking total resource deletions.
RESOURCE_READ_TOTAL Analytic tracking total resource reads.
RESOURCE_WRITTEN_FAIL Analytic tracking failed resource writes.
RESOURCE_WRITTEN_SUCCESS Analytic tracking successful resource writes.
RESOURCE_WRITTEN_TOTAL Analytic tracking total resource writes.
UDM_DATA_PRESENCE_SUMMARY UDM data summary tracking unique values of dimensions.

Dimension

Describes field used as the dimension when grouping data to calculate the aggregate metric.

Enums
DIMENSION_UNSPECIFIED Default
PRINCIPAL_DEVICE Principal Device
TARGET_USER Target User
TARGET_DEVICE Target Device
PRINCIPAL_USER Principal User
TARGET_IP Target IP
PRINCIPAL_FILE_HASH Principal File Hash
PRINCIPAL_COUNTRY Principal Country
SECURITY_CATEGORY Security Category
NETWORK_ASN Network ASN
CLIENT_CERTIFICATE_HASH Client Certificate Hash
DNS_QUERY_TYPE DNS Query Type
DNS_DOMAIN DNS Domain
HTTP_USER_AGENT HTTP User Agent
EVENT_TYPE Event Type
PRODUCT_NAME Product Name
PRODUCT_EVENT_TYPE Product Event Type
PARENT_FOLDER_PATH Parent Folder Path
TARGET_RESOURCE_NAME Target resource Name
PRINCIPAL_APPLICATION Principal Application.
TARGET_APPLICATION Target Application.
EMAIL_TO_ADDRESS Email To Address.
EMAIL_FROM_ADDRESS Email From Address.
MAIL_ID Mail Id.
PRINCIPAL_IP Principal IP.
SECURITY_ACTION Security Action.
SECURITY_RULE_ID Security Rule Id.
TARGET_NETWORK_ORGANIZATION_NAME Target Network Organization name.
PRINCIPAL_NETWORK_ORGANIZATION_NAME Principal Network Organization name.
PRINCIPAL_PROCESS_FILE_PATH Principal Process File Path.
PRINCIPAL_PROCESS_FILE_HASH Principal Process File SHA256 Hash.
SECURITY_RESULT_RULE_NAME Security Result rule name.
TARGET_RESOURCE_LABEL_KEY Target Resource label key.
VENDOR_NAME Vendor name.
TARGET_RESOURCE_TYPE Target Resource type.
TARGET_LOCATION_NAME Target Location name.
LOG_TYPE Log type.

Relation

Defines the relationship between the entity (a) and another entity (b).

JSON representation 
{
  "entity": {
    object (Noun)
  },
  "entityType": enum (EntityType),
  "relationship": enum (Relationship),
  "direction": enum (Directionality),
  "uid": string,
  "entityLabel": enum (EntityLabel)
}
Fields
entity

object (Noun)

Entity (b) that the primary entity (a) is related to.
entityType

enum (EntityType)

Type of the related entity (b) in this relationship.
relationship

enum (Relationship)

Type of relationship.
direction

enum (Directionality)

Directionality of relationship between primary entity (a) and the related entity (b).
uid

string (bytes format)

UID of the relationship.

A base64-encoded string.
entityLabel

enum (EntityLabel)

Label to identify the Noun of the relation.

Relationship

Type of relationship between the primary entity (a) and related entity (b).

Enums
RELATIONSHIP_UNSPECIFIED Default value
OWNS Related entity is owned by the primary entity (e.g. user owns device asset).
ADMINISTERS Related entity is administered by the primary entity (e.g. user administers a group).
MEMBER Primary entity is a member of the related entity (e.g. user is a member of a group).
EXECUTES Primary entity may have executed the related entity.
DOWNLOADED_FROM Primary entity may have been downloaded from the related entity.
CONTACTS Primary entity contacts the related entity.

Directionality

Describes the relationship model as directed or undirected.

Enums
DIRECTIONALITY_UNSPECIFIED Default value.
BIDIRECTIONAL Modeled in both directions. Primary entity (a) to related entity (b) and related entity (b) to primary entity (a).
UNIDIRECTIONAL Modeled in a single direction. Primary entity (a) to related entity (b).

EntityLabel

Entity label of the relation.

Enums
ENTITY_LABEL_UNSPECIFIED Default value.
PRINCIPAL The Noun represents a principal type object.
TARGET The Noun represents a target type object.
OBSERVER The Noun represents an observer type object.
SRC The Noun represents src type object.
NETWORK The Noun represents a network type object.
SECURITY_RESULT The Noun represents a SecurityResult object.
INTERMEDIARY The Noun represents an intermediary type object.

Methods

get

 Gets an entity by name.

import

 ImportEntities import the entities.

modifyEntityRiskScore

 Modify base entity risk score for an entity.

queryEntityRiskScoreModifications

 Query modifications to base entity risk score for an entity.