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
  },
  "risk_score": {
    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.
risk_score

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 
{
  "product_entity_id": string,
  "collected_timestamp": string,
  "creation_timestamp": string,
  "interval": {
    object (Interval)
  },
  "vendor_name": string,
  "product_name": string,
  "feed": string,
  "product_version": string,
  "entity_type": enum (EntityType),
  "description": string,
  "threat": [
    {
      object (SecurityResult)
    }
  ],
  "source_type": enum (SourceType),
  "source_labels": [
    {
      object (Label)
    }
  ],
  "event_metadata": {
    object (Metadata)
  },
  "structured_fields": {
    object
  },
  "extracted": {
    object
  }
}
Fields
product_entity_id

string

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

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

string (Timestamp format)

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

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

object (Interval)

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

string

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

string

Product name that produced the entity information.
feed

string

Vendor feed name for a threat indicator feed.
product_version

string

Version of the product that produced the entity information.
entity_type

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.
source_type

enum (SourceType)

The source of the entity.
source_labels[]

object (Label)

Entity source metadata labels.
event_metadata

object (Metadata)

Metadata field from the event.
structured_fields
(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.
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.

EntityRisk

Stores information related to the risk score of an entity.

JSON representation 
{
  "risk_version": string,
  "risk_window": {
    object (Interval)
  },
  "DEPRECATED_risk_score": integer,
  "detections_count": integer,
  "first_detection_time": string,
  "last_detection_time": string,
  "risk_score": number,
  "normalized_risk_score": integer,
  "risk_window_size": string,
  "last_reset_time": string,
  "detail_uri": string,
  "risk_delta": {
    object (RiskDelta)
  },
  "raw_risk_delta": {
    object (RiskDelta)
  }
}
Fields
risk_version

string

Version of the risk score calculation algorithm.
risk_window

object (Interval)

Time window used when computing the risk score for an entity, for example 24 hours or 7 days.
DEPRECATED_risk_score
(deprecated)

integer

Deprecated risk score.
detections_count

integer

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

string (Timestamp format)

Timestamp of the first detection within the specified time window. This field is empty when there are 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)

Timestamp of the last detection within the specified time window. This field is empty when there are 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".
risk_score

number

Raw risk score for the entity.
normalized_risk_score

integer

Normalized risk score for the entity. This value is between 0-1000.
risk_window_size

string (Duration format)

Risk window duration for the Entity.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".
last_reset_time

string (Timestamp format)

Timestamp for UEBA risk score reset based deduplication. Used specifically for risk based meta rules.

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

string

Link to the Google Security Operations UI with information about the entity risk score. If the SecOps instance has multiple frontend paths configured, this will be a relative path that can be used to construct the full URL.
risk_delta

object (RiskDelta)

Represents the change in risk score for an entity between the end of the previous time window and the end of the current time window.
raw_risk_delta

object (RiskDelta)

Represents the change in raw risk score for an entity between the end of the previous time window and the end of the current time window.

RiskDelta

Describes the difference in 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 time 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

Difference in the normalized risk score from the previous recorded value.
previous_risk_score

integer

Risk score from previous risk window
risk_score_numeric_delta

integer

Numeric change between current and previous risk score

Metric

Stores precomputed aggregated analytic data for an entity.

JSON representation 
{
  "first_seen": string,
  "last_seen": string,
  "sum_measure": {
    object (Measure)
  },
  "total_events": string,
  "metric_name": enum (MetricName),
  "dimensions": [
    enum (Dimension)
  ],
  "export_window": string
}
Fields
first_seen

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 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_seen

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

object (Measure)

Sum of all precomputed measures for the given metric.
total_events

string (int64 format)

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

enum (MetricName)

Name of the analytic.
dimensions[]

enum (Dimension)

All group by clauses used to calculate the metric.
export_window

string (int64 format)

Export window for which the metric was exported.

Measure

Describes the precomputed measure.

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

number

Value of the aggregated measure.
aggregate_function

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 response_code = 0.
DNS_QUERIES_FAIL Number of events with response_code != 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 First-time analytic tracking successful resource creations.
RESOURCE_CREATION_SUCCESS Volume-based analytic tracking successful resource creations.
RESOURCE_READ_SUCCESS Volume-based analytic tracking successful resource reads.
RESOURCE_READ_FAIL Volume-based analytic tracking failed resource reads.
RESOURCE_DELETION_SUCCESS Volume-based analytic tracking successful resource deletions.

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.

Relation

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

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

object (Noun)

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

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.
entity_label

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.