- [JSON representation](https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Entity#SCHEMA_REPRESENTATION)
- [EntityMetadata](https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Entity#EntityMetadata)
  - [JSON representation](https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Entity#EntityMetadata.SCHEMA_REPRESENTATION)
- [ThreatIntel](https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Entity#ThreatIntel)
  - [JSON representation](https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Entity#ThreatIntel.SCHEMA_REPRESENTATION)
- [Relation](https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Entity#Relation)
  - [JSON representation](https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Entity#Relation.SCHEMA_REPRESENTATION)
- [Metric](https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Entity#Metric)
  - [JSON representation](https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Entity#Metric.SCHEMA_REPRESENTATION)
- [Measure](https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Entity#Measure)
  - [JSON representation](https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Entity#Measure.SCHEMA_REPRESENTATION)
- [MetricVariable](https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Entity#MetricVariable)
  - [JSON representation](https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Entity#MetricVariable.SCHEMA_REPRESENTATION)

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 (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Entity#EntityMetadata`) }, "entity": { object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Noun`) }, "relations": [ { object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Entity#Relation`) } ], "additional": { object }, "metric": { object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Entity#Metric`) }, "riskScore": { object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/EntityRisk`) } } ``` |

| Fields ||
|---|---|
| `metadata` | ``object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Entity#EntityMetadata`)`` Entity metadata such as timestamp, product, etc. |
| `entity` | ``object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Noun`)`` Noun in the UDM event that this entity represents. |
| `relations[]` | ``object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Entity#Relation`)`` One or more relationships between the entity (a) and other entities, including the relationship type and related entity. |
| `additional` | ``object (`https://protobuf.dev/reference/protobuf/google.protobuf#struct` format)`` Important entity data that cannot be adequately represented within the formal sections of the Entity. |
| `metric` | ``object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Entity#Metric`)`` Stores statistical metrics about the entity. Used if metadata.entity_type is METRIC. |
| `riskScore` | ``object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/EntityRisk`)`` Stores information related to the entity's risk score. |

## EntityMetadata

Information about the Entity and the product where the entity was created.

| JSON representation |
|---|
| ``` { "productEntityId": string, "collectedTimestamp": string, "creationTimestamp": string, "interval": { object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Interval`) }, "vendorName": string, "productName": string, "feed": string, "productVersion": string, "entityType": enum (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/EntityType`), "description": string, "threat": [ { object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/SecurityResult`) } ], "sourceType": enum (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/SourceType`), "sourceLabels": [ { object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Label`) } ], "eventMetadata": { object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Metadata`) }, "structuredFields": { object }, "extracted": { object }, "atiPrioritization": { object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/AtiPrioritization`) }, "threatIntel": { object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Entity#ThreatIntel`) } } ``` |

| Fields ||
|---|---|
| `productEntityId` | `string` A vendor-specific identifier that uniquely identifies the entity (e.g. a GUID, LDAP, OID, or similar). |
| `collectedTimestamp` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#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 (`https://protobuf.dev/reference/protobuf/google.protobuf#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 (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/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 (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/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[] (deprecated)` | ``object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/SecurityResult`)`` > [!WARNING] > This item is deprecated! Deprecated: Usage of this field is discouraged for indicators of compromise. Use the `threatIntel` field instead. Metadata provided by a threat intelligence feed that identified the entity as malicious. |
| `sourceType` | ``enum (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/SourceType`)`` The source of the entity. |
| `sourceLabels[]` | ``object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Label`)`` Entity source metadata labels. |
| `eventMetadata` | ``object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Metadata`)`` Metadata field from the event. |
| `structuredFields (deprecated)` | ``object (`https://protobuf.dev/reference/protobuf/google.protobuf#struct` format)`` > [!WARNING] > This item is deprecated! Structured fields extracted from the log. |
| `extracted` | ``object (`https://protobuf.dev/reference/protobuf/google.protobuf#struct` format)`` Flattened fields extracted from the log. |
| `atiPrioritization (deprecated)` | ``object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/AtiPrioritization`)`` > [!WARNING] > This item is deprecated! Deprecated: Use the `threatIntel` field instead. Prioritization factors used by ATI curated rules. |
| `threatIntel` | ``object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Entity#ThreatIntel`)`` Threat intel metadata for the entity if it is an indicator of compromise. Usage of this field is preferred over usage of the `threat` field. |

## ThreatIntel

ThreatIntel contains threat intel metadata for indicators of compromise.

| JSON representation |
|---|
| ``` { "verdict": enum (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Verdict`), "severity": enum (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Severity`), "threatScore": integer, "updateTime": string, "reviewed": boolean, "soaked": boolean, "stable": boolean, "attributedMalware": [ string ], "attributedThreatActors": [ string ] } ``` |

| Fields ||
|---|---|
| `verdict` | ``enum (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Verdict`)`` Qualitative verdict of the maliciousness of the indicator. |
| `severity` | ``enum (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Severity`)`` Qualitative severity rating of the indicator. |
| `threatScore` | `integer` Quantitative threat score of the indicator. Range is 0-100. |
| `updateTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` When the threat intel was last updated. 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"`. |
| `reviewed` | `boolean` Whether the threat intel has been explicitly reviewed. |
| `soaked` | `boolean` Whether the threat intel has soaked (implicitly reviewed over time). |
| `stable` | `boolean` Whether the threat intel is considered stable. Typically this is true when either `reviewed` or `soaked` is true. |
| `attributedMalware[]` | `string` Names of associated malware families. Examples: "FIRESCALE", "SANDCLOCK" |
| `attributedThreatActors[]` | `string` Names of associated threat actors. Examples: "APT41", "UN3236" |

## Relation

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

| JSON representation |
|---|
| ``` { "entity": { object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Noun`) }, "entityType": enum (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/EntityType`), "relationship": enum (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Relationship`), "direction": enum (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Directionality`), "uid": string, "entityLabel": enum (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/EntityLabel`) } ``` |

| Fields ||
|---|---|
| `entity` | ``object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Noun`)`` Entity (b) that the primary entity (a) is related to. |
| `entityType` | ``enum (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/EntityType`)`` Type of the related entity (b) in this relationship. |
| `relationship` | ``enum (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Relationship`)`` Type of relationship. |
| `direction` | ``enum (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Directionality`)`` Directionality of relationship between primary entity (a) and the related entity (b). |
| `uid` | `string (https://developers.google.com/discovery/v1/type-format format)` UID of the relationship. A base64-encoded string. |
| `entityLabel` | ``enum (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/EntityLabel`)`` Label to identify the Noun of the relation. |

## Metric

Stores precomputed aggregated analytic data for an entity.

| JSON representation |
|---|
| ``` { "firstSeen": string, "lastSeen": string, "sumMeasure": { object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Entity#Measure`) }, "totalEvents": string, "metricName": enum (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/MetricName`), "dimensions": [ enum (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Dimension`) ], "exportWindow": string, "displayName": string, "outcomeVariables": [ { object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Entity#MetricVariable`) } ], "matchVariables": [ { object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Entity#MetricVariable`) } ], "timeRange": { object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Interval`) } } ``` |

| Fields ||
|---|---|
| `firstSeen` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#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 (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` Timestamp of the 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 (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Entity#Measure`)`` Sum of all precomputed measures for the given metric. |
| `totalEvents` | `string (https://developers.google.com/discovery/v1/type-format format)` Total number of events used to calculate the given precomputed metric. |
| `metricName` | ``enum (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/MetricName`)`` Name of the analytic. |
| `dimensions[]` | ``enum (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Dimension`)`` All group by clauses used to calculate the metric. |
| `exportWindow` | `string (https://developers.google.com/discovery/v1/type-format format)` Export window for which the metric was exported. |
| `displayName` | `string` Display name of the custom metric. Google-authored metrics do not have a display name. |
| `outcomeVariables[]` | ``object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Entity#MetricVariable`)`` List of outcome variables used in the custom metric. |
| `matchVariables[]` | ``object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Entity#MetricVariable`)`` List of match variables used in the custom metric. |
| `timeRange` | ``object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Interval`)`` Time range for which the custom metric was calculated. |

## Measure

Describes the precomputed measure.

| JSON representation |
|---|
| ``` { "value": number, "aggregateFunction": enum (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/AggregateFunction`) } ``` |

| Fields ||
|---|---|
| `value` | `number` Value of the aggregated measure. |
| `aggregateFunction` | ``enum (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/AggregateFunction`)`` Function used to calculate the aggregated measure. |

## MetricVariable

A structure that holds the value and associated metadata for a variable used in a metric.

| JSON representation |
|---|
| ``` { "name": string, "sourcePath": string, // Union field `typed_value` can be only one of the following: "boolVal": boolean, "bytesVal": string, "doubleVal": number, "int64Val": string, "uint64Val": string, "stringVal": string, "timestampTime": string, "nullVal": boolean, "boolSeq": { object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/BoolSequence`) }, "bytesSeq": { object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/BytesSequence`) }, "doubleSeq": { object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/DoubleSequence`) }, "int64Seq": { object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Int64Sequence`) }, "uint64Seq": { object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Uint64Sequence`) }, "stringSeq": { object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/StringSequence`) } // End of list of possible types for union field `typed_value`. } ``` |

| Fields ||
|---|---|
| `name` | `string` The name of the variable. |
| `sourcePath` | `string` The UDM field path for the field which this value was derived from. Example: `principal.hostname` |
| Union field `typed_value`. The typed value of the variable. `typed_value` can be only one of the following: ||
| `boolVal` | `boolean` \* |
| `bytesVal` | `string (https://developers.google.com/discovery/v1/type-format format)` \* A base64-encoded string. |
| `doubleVal` | `number` \* |
| `int64Val` | `string (https://developers.google.com/discovery/v1/type-format format)` \* |
| `uint64Val` | `string` The value in uint64 format. |
| `stringVal` | `string` Enum values are returned as strings. |
| `timestampTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` \* 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"`. |
| `nullVal` | `boolean` \* |
| `boolSeq` | ``object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/BoolSequence`)`` \* |
| `bytesSeq` | ``object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/BytesSequence`)`` \* |
| `doubleSeq` | ``object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/DoubleSequence`)`` \* |
| `int64Seq` | ``object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Int64Sequence`)`` \* |
| `uint64Seq` | ``object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Uint64Sequence`)`` \* |
| `stringSeq` | ``object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/StringSequence`)`` \* |