Entity

An Entity provides additional context about an item in a UDM event. 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
{
  "metadata": {
    object (EntityMetadata)
  },
  "entity": {
    object (Noun)
  },
  "relations": [
    {
      object (Relation)
    }
  ],
  "additional": {
    object
  },
  "metric": {
    object (Metric)
  },
  "risk_score": {
    object (EntityRisk)
  }
}
Fields
metadata

object (EntityMetadata)

Entity metadata such as timestamp, product, etc.

entity

object (Noun)

Noun in the UDM event that this entity represents.

relations[]

object (Relation)

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

additional

object (Struct format)

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

metric

object (Metric)

Stores statistical metrics about the entity. Used if metadata.entity_type is METRIC.

risk_score

object (EntityRisk)

Stores information related to the entity's risk score.

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.

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.

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.