googleapis/backstory/entity.proto

// Copyright 2026 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package google.backstory;

import "backstory/entity_risk.proto";
import "backstory/udm.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/timestamp.proto";
import "google/type/interval.proto";

option csharp_namespace = "Google.Backstory";
option go_package = "cloud.google.com/go/backstory/backstorypb;backstorypb";
option java_multiple_files = true;
option java_outer_classname = "EntityProto";
option java_package = "com.google.backstory";
option php_namespace = "Google\\Backstory";
option ruby_package = "Google::Backstory";

// Information about the Entity and the product where the entity was created.
message EntityMetadata {
  // Describes the type of entity.
  // An unknown event type.
  enum EntityType {
    // @hide_from_doc
    UNKNOWN_ENTITYTYPE = 0;

    // An asset, such as workstation, laptop, phone, virtual machine, etc.
    ASSET = 1;

    // User.
    USER = 10000;

    // Group.
    GROUP = 10001;

    // Resource.
    RESOURCE = 2;

    // An external IP address.
    IP_ADDRESS = 3;

    // A CIDR block.
    CIDR_BLOCK = 9;

    // A file.
    FILE = 4;

    // A domain.
    DOMAIN_NAME = 5;

    // A url.
    URL = 6;

    // A mutex.
    MUTEX = 7;

    // A metric.
    METRIC = 8;
  }

  // Describes the source of an entity.
  enum SourceType {
    // Default source type
    SOURCE_TYPE_UNSPECIFIED = 0;

    // Entities ingested from customers (e.g. AD_CONTEXT, DLP_CONTEXT)
    ENTITY_CONTEXT = 1;

    // Entities derived from customer data such as prevalence, artifact
    // first/last seen, or asset/user first seen stats.
    DERIVED_CONTEXT = 2;

    // Global contextual entities such as WHOIS or Safe Browsing.
    GLOBAL_CONTEXT = 3;
  }

  // A vendor-specific identifier that uniquely identifies the entity
  // (e.g. a GUID, LDAP, OID, or similar).
  string product_entity_id = 1;

  // GMT timestamp when the entity information was collected by the vendor's
  // local collection infrastructure.
  google.protobuf.Timestamp collected_timestamp = 2;

  // GMT timestamp when the entity described by the product_entity_id was
  // created on the system where data was collected.
  google.protobuf.Timestamp creation_timestamp = 8;

  // Valid existence time range for the version of the entity represented by
  // this entity data.
  google.type.Interval interval = 9;

  // Vendor name of the product that produced the entity information.
  string vendor_name = 3;

  // Product name that produced the entity information.
  string product_name = 4;

  // Vendor feed name for a threat indicator feed.
  string feed = 14;

  // Version of the product that produced the entity information.
  string product_version = 5;

  // Entity type.
  // If an entity has multiple possible types, this specifies the most specific
  // type.
  EntityType entity_type = 6;

  // Human-readable description of the entity.
  string description = 7;

  // Metadata provided by a threat intelligence feed that identified the
  // entity as malicious.
  repeated SecurityResult threat = 10;

  // The source of the entity.
  SourceType source_type = 11;

  // Entity source metadata labels.
  repeated Label source_labels = 12;

  // Metadata field from the event.
  Metadata event_metadata = 13;

  // Structured fields extracted from the log.
  google.protobuf.Struct structured_fields = 15 [deprecated = true];

  // Flattened fields extracted from the log.
  google.protobuf.Struct extracted = 16;

  // Prioritization factors used by ATI curated rules.
  AtiPrioritization ati_prioritization = 17;
}

// AtiPrioritization contains various fields used to calculate a priority score
// for an entity identified as a threat.
message AtiPrioritization {
  // The confidence score from "GTI verdict" source.
  int32 gti_verdict = 1;

  // The confidence score from "GTI severity" source.
  int32 gti_severity = 2;

  // The confidence score from "GTI threat score" source.
  int32 gti_threat_score = 3;

  // The confidence score from "Mandiant Analyst Intel" source.
  int32 mandiant_analyst_confidence = 4;

  // Timestamp of the latest update for GTI verdict, severity, or threat score.
  google.protobuf.Timestamp gti_update_time = 5;

  // Whether one or more Mandiant incident response customers had this indicator
  // in their environment.
  bool active_ir = 6;

  // The timestamp of the first time an active IR was applied to this entity.
  google.protobuf.Timestamp active_ir_first_tagged_time = 7;

  // Global customer count over the last 30 days
  int64 global_customer_count = 8;

  // Global hit count over the last 30 days
  int64 global_hit_count = 9;

  // Whether the indicator is being used by a maximum of one threat actor.
  bool exclusive = 10;

  // Whether the indicator details are available in open source.
  bool osint = 11;

  // Whether the indicator is a scanner.
  bool scanner = 12;

  // Whether the indicator verdict has passed review.
  bool reviewed = 13;

  // Malware families associated with this indicator.
  repeated SecurityResult.Association attributed_malware = 14;

  // Threat actors associated with this indicator.
  repeated SecurityResult.Association attributed_threat_actors = 15;
}

// 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.
message Entity {
  // Entity metadata such as timestamp, product, etc.
  EntityMetadata metadata = 1;

  // Noun in the UDM event that this entity represents.
  Noun entity = 2;

  // One or more relationships between the entity (a) and other entities,
  // including the relationship type and related entity.
  repeated Relation relations = 4;

  // Important entity data that cannot be adequately represented within
  // the formal sections of the Entity.
  google.protobuf.Struct additional = 3;

  // Stores information related to the entity's risk score.
  optional EntityRisk risk_score = 5;

  // Stores statistical metrics about the entity. Used if metadata.entity_type
  // is METRIC.
  Metric metric = 6;
}

// Defines the relationship between the entity (a) and another entity (b).
message Relation {
  // Type of relationship between the primary entity (a) and related entity (b).
  enum Relationship {
    // Default value
    RELATIONSHIP_UNSPECIFIED = 0;

    // Related entity is owned by the primary entity (e.g. user owns device
    // asset).
    OWNS = 1;

    // Related entity is administered by the primary entity (e.g. user
    // administers a group).
    ADMINISTERS = 2;

    // Primary entity is a member of the related entity (e.g. user is a member
    // of a group).
    MEMBER = 3;

    // Primary entity may have executed the related entity.
    EXECUTES = 4;

    // Primary entity may have been downloaded from the related entity.
    DOWNLOADED_FROM = 5;

    // Primary entity contacts the related entity.
    CONTACTS = 6;
  }

  // Describes the relationship model as directed or undirected.
  enum Directionality {
    // Default value.
    DIRECTIONALITY_UNSPECIFIED = 0;

    // Modeled in both directions. Primary entity (a) to related entity (b) and
    // related entity (b) to primary entity (a).
    BIDIRECTIONAL = 1;

    // Modeled in a single direction. Primary entity (a) to related entity (b).
    UNIDIRECTIONAL = 2;
  }

  // Entity label of the relation.
  enum EntityLabel {
    // Default value.
    ENTITY_LABEL_UNSPECIFIED = 0;

    // The Noun represents a principal type object.
    PRINCIPAL = 1;

    // The Noun represents a target type object.
    TARGET = 2;

    // The Noun represents an observer type object.
    OBSERVER = 3;

    // The Noun represents src type object.
    SRC = 4;

    // The Noun represents a network type object.
    NETWORK = 5;

    // The Noun represents a SecurityResult object.
    SECURITY_RESULT = 6;

    // The Noun represents an intermediary type object.
    INTERMEDIARY = 7;
  }

  // Entity (b) that the primary entity (a) is related to.
  Noun entity = 1;

  // Type of the related entity (b) in this relationship.
  EntityMetadata.EntityType entity_type = 2;

  // Type of relationship.
  Relationship relationship = 3;

  // Directionality of relationship between primary entity (a) and the
  // related entity (b).
  Directionality direction = 4;

  // UID of the relationship.
  bytes uid = 5;

  // Label to identify the Noun of the relation.
  EntityLabel entity_label = 6;
}

// Stores precomputed aggregated analytic data for an entity.
message Metric {
  // Mathematic function used to calculate the value.
  enum AggregateFunction {
    // Default value.
    AGGREGATE_FUNCTION_UNSPECIFIED = 0;

    // Minimum.
    MIN = 1;

    // Maximum.
    MAX = 2;

    // Count.
    COUNT = 3;

    // Sum.
    SUM = 4;

    // Average.
    AVG = 5;

    // Standard Deviation.
    STDDEV = 6;
  }

  // Describes the precomputed measure.
  message Measure {
    // Value of the aggregated measure.
    double value = 1;

    // Function used to calculate the aggregated measure.
    AggregateFunction aggregate_function = 2;
  }

  // The name of the precomputed analytic.
  enum MetricName {
    // Default
    METRIC_NAME_UNSPECIFIED = 0;

    // Total received network bytes.
    NETWORK_BYTES_INBOUND = 1;

    // Total network sent bytes.
    NETWORK_BYTES_OUTBOUND = 2;

    // Total network sent bytes and received bytes.
    NETWORK_BYTES_TOTAL = 3;

    // Successful authentication attempts.
    AUTH_ATTEMPTS_SUCCESS = 4;

    // Failed authentication attempts.
    AUTH_ATTEMPTS_FAIL = 5;

    // Total authentication attempts.
    AUTH_ATTEMPTS_TOTAL = 6;

    // Total number of sent bytes for DNS events.
    DNS_BYTES_OUTBOUND = 7;

    // Total number of events having non-null received bytes.
    NETWORK_FLOWS_INBOUND = 8;

    // Total number of events having non-null sent bytes.
    NETWORK_FLOWS_OUTBOUND = 9;

    // Total events having non-null sent or received bytes.
    NETWORK_FLOWS_TOTAL = 10;

    // DNS query success count - Number of events with response_code = 0.
    DNS_QUERIES_SUCCESS = 11;

    // Number of events with response_code != 0.
    DNS_QUERIES_FAIL = 12;

    // Total number of DNS queries made.
    DNS_QUERIES_TOTAL = 13;

    // Number of successfule file executions.
    FILE_EXECUTIONS_SUCCESS = 14;

    // Number of failed file executions.
    FILE_EXECUTIONS_FAIL = 15;

    // Total number file executions.
    FILE_EXECUTIONS_TOTAL = 16;

    // Number of successful HTTP queries.
    HTTP_QUERIES_SUCCESS = 17;

    // Number of failed HTTP queries.
    HTTP_QUERIES_FAIL = 18;

    // Total number of HTTP queries.
    HTTP_QUERIES_TOTAL = 19;

    // Total number of emails sent in Google Workspace.
    WORKSPACE_EMAILS_SENT_TOTAL = 20;

    // Total number of download actions in Google Workspace.
    WORKSPACE_TOTAL_DOWNLOAD_ACTIONS = 21;

    // Total number of change actions in Google Workspace.
    WORKSPACE_TOTAL_CHANGE_ACTIONS = 22;

    // Total number of authentication attempts in Google Workspace.
    WORKSPACE_AUTH_ATTEMPTS_TOTAL = 23;

    // Number of outbound network bytes (total sent) in Google Workspace.
    WORKSPACE_NETWORK_BYTES_OUTBOUND = 24;

    // Total number of network bytes (both sent and received) in Google
    // Workspace.
    WORKSPACE_NETWORK_BYTES_TOTAL = 25;

    // Track number of alerts fired by EDR/SENTINEL/MICROSOFT_GRAPH.
    ALERT_EVENT_NAME_COUNT = 26;

    // Analytic tracking successful resource creations.
    RESOURCE_CREATION_TOTAL = 27;

    // Analytic tracking successful resource creations.
    RESOURCE_CREATION_SUCCESS = 28;

    // Analytic tracking successful resource reads.
    RESOURCE_READ_SUCCESS = 29;

    // Analytic tracking failed resource reads.
    RESOURCE_READ_FAIL = 30;

    // Analytic tracking successful resource deletions.
    RESOURCE_DELETION_SUCCESS = 31;

    // Analytic tracking failed resource creations.
    RESOURCE_CREATION_FAIL = 32;

    // Analytic tracking failed resource deletions.
    RESOURCE_DELETION_FAIL = 33;

    // Analytic tracking total resource deletions.
    RESOURCE_DELETION_TOTAL = 34;

    // Analytic tracking total resource reads.
    RESOURCE_READ_TOTAL = 35;

    // Analytic tracking failed resource writes.
    RESOURCE_WRITTEN_FAIL = 36;

    // Analytic tracking successful resource writes.
    RESOURCE_WRITTEN_SUCCESS = 37;

    // Analytic tracking total resource writes.
    RESOURCE_WRITTEN_TOTAL = 38;

    // UDM data summary tracking unique values of dimensions.
    UDM_DATA_PRESENCE_SUMMARY = 39;
  }

  // Describes field used as the dimension when grouping data to calculate the
  // aggregate metric.
  enum Dimension {
    // Default
    DIMENSION_UNSPECIFIED = 0;

    // Principal Device
    PRINCIPAL_DEVICE = 1;

    // Target User
    TARGET_USER = 2;

    // Target Device
    TARGET_DEVICE = 3;

    // Principal User
    PRINCIPAL_USER = 4;

    // Target IP
    TARGET_IP = 5;

    // Principal File Hash
    PRINCIPAL_FILE_HASH = 6;

    // Principal Country
    PRINCIPAL_COUNTRY = 7;

    // Security Category
    SECURITY_CATEGORY = 8;

    // Network ASN
    NETWORK_ASN = 9;

    // Client Certificate Hash
    CLIENT_CERTIFICATE_HASH = 10;

    // DNS Query Type
    DNS_QUERY_TYPE = 11;

    // DNS Domain
    DNS_DOMAIN = 12;

    // HTTP User Agent
    HTTP_USER_AGENT = 13;

    // Event Type
    EVENT_TYPE = 14;

    // Product Name
    PRODUCT_NAME = 15;

    // Product Event Type
    PRODUCT_EVENT_TYPE = 16;

    // Parent Folder Path
    PARENT_FOLDER_PATH = 17;

    // Target resource Name
    TARGET_RESOURCE_NAME = 18;

    // Principal Application.
    PRINCIPAL_APPLICATION = 19;

    // Target Application.
    TARGET_APPLICATION = 20;

    // Email To Address.
    EMAIL_TO_ADDRESS = 21;

    // Email From Address.
    EMAIL_FROM_ADDRESS = 22;

    // Mail Id.
    MAIL_ID = 23;

    // Principal IP.
    PRINCIPAL_IP = 24;

    // Security Action.
    SECURITY_ACTION = 25;

    // Security Rule Id.
    SECURITY_RULE_ID = 28;

    // Target Network Organization name.
    TARGET_NETWORK_ORGANIZATION_NAME = 29;

    // Principal Network Organization name.
    PRINCIPAL_NETWORK_ORGANIZATION_NAME = 30;

    // Principal Process File Path.
    PRINCIPAL_PROCESS_FILE_PATH = 31;

    // Principal Process File SHA256 Hash.
    PRINCIPAL_PROCESS_FILE_HASH = 32;

    // Security Result rule name.
    SECURITY_RESULT_RULE_NAME = 33;

    // Target Resource label key.
    TARGET_RESOURCE_LABEL_KEY = 34;

    // Vendor name.
    VENDOR_NAME = 35;

    // Target Resource type.
    TARGET_RESOURCE_TYPE = 36;

    // Target Location name.
    TARGET_LOCATION_NAME = 37;

    // Log type.
    LOG_TYPE = 38;

    // Target Hostname.
    TARGET_HOSTNAME = 39;
  }

  // Timestamp of the first time the entity was seen in the environment.
  google.protobuf.Timestamp first_seen = 1;

  // Time stamp of the last time last time the entity was seen in the
  // environment.
  google.protobuf.Timestamp last_seen = 2;

  // Sum of all precomputed measures for the given metric.
  Measure sum_measure = 3;

  // Total number of events used to calculate the given precomputed metric.
  int64 total_events = 4;

  // Name of the analytic.
  MetricName metric_name = 5;

  // All group by clauses used to calculate the metric.
  repeated Dimension dimensions = 6;

  // Export window for which the metric was exported.
  int64 export_window = 7;

  // Display name of the custom metric. Google-authored metrics do not have a
  // display name.
  string display_name = 8;

  // List of outcome variables used in the custom metric.
  repeated FindingVariable outcome_variables = 9;

  // List of match variables used in the custom metric.
  repeated FindingVariable match_variables = 10;

  // Time range for which the custom metric was calculated.
  google.type.Interval time_range = 11;
}