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}

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

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)
  }
}
Fields
product_entity_id

string

collected_timestamp

string (Timestamp format)

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

creation_timestamp

string (Timestamp format)

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

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)

EntityType

Enums
UNKNOWN_ENTITYTYPE
ASSET
USER
GROUP
RESOURCE
IP_ADDRESS
FILE
DOMAIN_NAME
URL
MUTEX
METRIC

SourceType

Enums
SOURCE_TYPE_UNSPECIFIED
ENTITY_CONTEXT
DERIVED_CONTEXT
GLOBAL_CONTEXT

EntityRisk

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,
  "risk_delta": {
    object (RiskDelta)
  },
  "raw_risk_delta": {
    object (RiskDelta)
  }
}
Fields
risk_version

string

risk_window

object (Interval)

DEPRECATED_risk_score
(deprecated)

integer

detections_count

integer

first_detection_time

string (Timestamp format)

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

last_detection_time

string (Timestamp format)

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

risk_score

number

normalized_risk_score

integer

risk_window_size

string (Duration format)

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

risk_delta

object (RiskDelta)

raw_risk_delta

object (RiskDelta)

RiskDelta

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)

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

risk_score_delta

integer

previous_risk_score

integer

risk_score_numeric_delta

integer

Metric

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)

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

last_seen

string (Timestamp format)

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

sum_measure

object (Measure)

total_events

string (int64 format)

metric_name

enum (MetricName)

dimensions[]

enum (Dimension)

export_window

string (int64 format)

Measure

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

number

aggregate_function

enum (AggregateFunction)

AggregateFunction

Enums
AGGREGATE_FUNCTION_UNSPECIFIED
MIN
MAX
COUNT
SUM
AVG
STDDEV

MetricName

Enums
METRIC_NAME_UNSPECIFIED
NETWORK_BYTES_INBOUND
NETWORK_BYTES_OUTBOUND
NETWORK_BYTES_TOTAL
AUTH_ATTEMPTS_SUCCESS
AUTH_ATTEMPTS_FAIL
AUTH_ATTEMPTS_TOTAL
DNS_BYTES_OUTBOUND
NETWORK_FLOWS_INBOUND
NETWORK_FLOWS_OUTBOUND
NETWORK_FLOWS_TOTAL
DNS_QUERIES_SUCCESS
DNS_QUERIES_FAIL
DNS_QUERIES_TOTAL
FILE_EXECUTIONS_SUCCESS
FILE_EXECUTIONS_FAIL
FILE_EXECUTIONS_TOTAL
HTTP_QUERIES_SUCCESS
HTTP_QUERIES_FAIL
HTTP_QUERIES_TOTAL
WORKSPACE_EMAILS_SENT_TOTAL
WORKSPACE_TOTAL_DOWNLOAD_ACTIONS
WORKSPACE_TOTAL_CHANGE_ACTIONS
WORKSPACE_AUTH_ATTEMPTS_TOTAL
WORKSPACE_NETWORK_BYTES_OUTBOUND
WORKSPACE_NETWORK_BYTES_TOTAL
ALERT_EVENT_NAME_COUNT

Dimension

Enums
DIMENSION_UNSPECIFIED
PRINCIPAL_DEVICE
TARGET_USER
TARGET_DEVICE
PRINCIPAL_USER
TARGET_IP
PRINCIPAL_FILE_HASH
PRINCIPAL_COUNTRY
SECURITY_CATEGORY
NETWORK_ASN
CLIENT_CERTIFICATE_HASH
DNS_QUERY_TYPE
DNS_DOMAIN
HTTP_USER_AGENT
EVENT_TYPE
PRODUCT_NAME
PRODUCT_EVENT_TYPE
PARENT_FOLDER_PATH
TARGET_RESOURCE_NAME
PRINCIPAL_APPLICATION
TARGET_APPLICATION
EMAIL_TO_ADDRESS
EMAIL_FROM_ADDRESS
MAIL_ID
PRINCIPAL_IP
SECURITY_ACTION
SECURITY_RULE_ID
TARGET_NETWORK_ORGANIZATION_NAME
PRINCIPAL_NETWORK_ORGANIZATION_NAME
PRINCIPAL_PROCESS_FILE_PATH
PRINCIPAL_PROCESS_FILE_HASH
SECURITY_RESULT_RULE_NAME

Relation

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_type

enum (EntityType)

relationship

enum (Relationship)

direction

enum (Directionality)

uid

string (bytes format)

A base64-encoded string.

entity_label

enum (EntityLabel)

Relationship

Enums
RELATIONSHIP_UNSPECIFIED
OWNS
ADMINISTERS
MEMBER
EXECUTES
DOWNLOADED_FROM
CONTACTS

Directionality

Enums
DIRECTIONALITY_UNSPECIFIED
BIDIRECTIONAL
UNIDIRECTIONAL

EntityLabel

Enums
ENTITY_LABEL_UNSPECIFIED
PRINCIPAL
TARGET
OBSERVER
SRC
NETWORK
SECURITY_RESULT
INTERMEDIARY

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.