google-cloud-chronicle-v1 1.3.0 → 1.4.0

data/proto_docs/backstory/entity.rb

@@ -0,0 +1,639 @@
+# frozen_string_literal: true
+
+# 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
+#
+#     https://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.
+
+# Auto-generated by gapic-generator-ruby. DO NOT EDIT!
+
+
+module Google
+  module Backstory
+    # Information about the Entity and the product where the entity was created.
+    # @!attribute [rw] product_entity_id
+    #   @return [::String]
+    #     A vendor-specific identifier that uniquely identifies the entity
+    #     (e.g. a GUID, LDAP, OID, or similar).
+    # @!attribute [rw] collected_timestamp
+    #   @return [::Google::Protobuf::Timestamp]
+    #     GMT timestamp when the entity information was collected by the vendor's
+    #     local collection infrastructure.
+    # @!attribute [rw] creation_timestamp
+    #   @return [::Google::Protobuf::Timestamp]
+    #     GMT timestamp when the entity described by the product_entity_id was
+    #     created on the system where data was collected.
+    # @!attribute [rw] interval
+    #   @return [::Google::Type::Interval]
+    #     Valid existence time range for the version of the entity represented by
+    #     this entity data.
+    # @!attribute [rw] vendor_name
+    #   @return [::String]
+    #     Vendor name of the product that produced the entity information.
+    # @!attribute [rw] product_name
+    #   @return [::String]
+    #     Product name that produced the entity information.
+    # @!attribute [rw] feed
+    #   @return [::String]
+    #     Vendor feed name for a threat indicator feed.
+    # @!attribute [rw] product_version
+    #   @return [::String]
+    #     Version of the product that produced the entity information.
+    # @!attribute [rw] entity_type
+    #   @return [::Google::Backstory::EntityMetadata::EntityType]
+    #     Entity type.
+    #     If an entity has multiple possible types, this specifies the most specific
+    #     type.
+    # @!attribute [rw] description
+    #   @return [::String]
+    #     Human-readable description of the entity.
+    # @!attribute [rw] threat
+    #   @return [::Array<::Google::Backstory::SecurityResult>]
+    #     Metadata provided by a threat intelligence feed that identified the
+    #     entity as malicious.
+    # @!attribute [rw] source_type
+    #   @return [::Google::Backstory::EntityMetadata::SourceType]
+    #     The source of the entity.
+    # @!attribute [rw] source_labels
+    #   @return [::Array<::Google::Backstory::Label>]
+    #     Entity source metadata labels.
+    # @!attribute [rw] event_metadata
+    #   @return [::Google::Backstory::Metadata]
+    #     Metadata field from the event.
+    # @!attribute [rw] structured_fields
+    #   @deprecated This field is deprecated and may be removed in the next major version update.
+    #   @return [::Google::Protobuf::Struct]
+    #     Structured fields extracted from the log.
+    # @!attribute [rw] extracted
+    #   @return [::Google::Protobuf::Struct]
+    #     Flattened fields extracted from the log.
+    # @!attribute [rw] ati_prioritization
+    #   @return [::Google::Backstory::AtiPrioritization]
+    #     Prioritization factors used by ATI curated rules.
+    class EntityMetadata
+      include ::Google::Protobuf::MessageExts
+      extend ::Google::Protobuf::MessageExts::ClassMethods
+
+      # Describes the type of entity.
+      # An unknown event type.
+      module EntityType
+        # `@hide_from_doc`
+        UNKNOWN_ENTITYTYPE = 0
+
+        # An asset, such as workstation, laptop, phone, virtual machine, etc.
+        ASSET = 1
+
+        # User.
+        USER = 10_000
+
+        # Group.
+        GROUP = 10_001
+
+        # 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
+      end
+
+      # Describes the source of an entity.
+      module 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
+      end
+    end
+
+    # AtiPrioritization contains various fields used to calculate a priority score
+    # for an entity identified as a threat.
+    # @!attribute [rw] gti_verdict
+    #   @return [::Integer]
+    #     The confidence score from "GTI verdict" source.
+    # @!attribute [rw] gti_severity
+    #   @return [::Integer]
+    #     The confidence score from "GTI severity" source.
+    # @!attribute [rw] gti_threat_score
+    #   @return [::Integer]
+    #     The confidence score from "GTI threat score" source.
+    # @!attribute [rw] mandiant_analyst_confidence
+    #   @return [::Integer]
+    #     The confidence score from "Mandiant Analyst Intel" source.
+    # @!attribute [rw] gti_update_time
+    #   @return [::Google::Protobuf::Timestamp]
+    #     Timestamp of the latest update for GTI verdict, severity, or threat score.
+    # @!attribute [rw] active_ir
+    #   @return [::Boolean]
+    #     Whether one or more Mandiant incident response customers had this indicator
+    #     in their environment.
+    # @!attribute [rw] active_ir_first_tagged_time
+    #   @return [::Google::Protobuf::Timestamp]
+    #     The timestamp of the first time an active IR was applied to this entity.
+    # @!attribute [rw] global_customer_count
+    #   @return [::Integer]
+    #     Global customer count over the last 30 days
+    # @!attribute [rw] global_hit_count
+    #   @return [::Integer]
+    #     Global hit count over the last 30 days
+    # @!attribute [rw] exclusive
+    #   @return [::Boolean]
+    #     Whether the indicator is being used by a maximum of one threat actor.
+    # @!attribute [rw] osint
+    #   @return [::Boolean]
+    #     Whether the indicator details are available in open source.
+    # @!attribute [rw] scanner
+    #   @return [::Boolean]
+    #     Whether the indicator is a scanner.
+    # @!attribute [rw] reviewed
+    #   @return [::Boolean]
+    #     Whether the indicator verdict has passed review.
+    # @!attribute [rw] attributed_malware
+    #   @return [::Array<::Google::Backstory::SecurityResult::Association>]
+    #     Malware families associated with this indicator.
+    # @!attribute [rw] attributed_threat_actors
+    #   @return [::Array<::Google::Backstory::SecurityResult::Association>]
+    #     Threat actors associated with this indicator.
+    class AtiPrioritization
+      include ::Google::Protobuf::MessageExts
+      extend ::Google::Protobuf::MessageExts::ClassMethods
+    end
+
+    # 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.
+    # @!attribute [rw] metadata
+    #   @return [::Google::Backstory::EntityMetadata]
+    #     Entity metadata such as timestamp, product, etc.
+    # @!attribute [rw] entity
+    #   @return [::Google::Backstory::Noun]
+    #     Noun in the UDM event that this entity represents.
+    # @!attribute [rw] relations
+    #   @return [::Array<::Google::Backstory::Relation>]
+    #     One or more relationships between the entity (a) and other entities,
+    #     including the relationship type and related entity.
+    # @!attribute [rw] additional
+    #   @return [::Google::Protobuf::Struct]
+    #     Important entity data that cannot be adequately represented within
+    #     the formal sections of the Entity.
+    # @!attribute [rw] risk_score
+    #   @return [::Google::Backstory::EntityRisk]
+    #     Stores information related to the entity's risk score.
+    # @!attribute [rw] metric
+    #   @return [::Google::Backstory::Metric]
+    #     Stores statistical metrics about the entity. Used if metadata.entity_type
+    #     is METRIC.
+    class Entity
+      include ::Google::Protobuf::MessageExts
+      extend ::Google::Protobuf::MessageExts::ClassMethods
+    end
+
+    # Defines the relationship between the entity (a) and another entity (b).
+    # @!attribute [rw] entity
+    #   @return [::Google::Backstory::Noun]
+    #     Entity (b) that the primary entity (a) is related to.
+    # @!attribute [rw] entity_type
+    #   @return [::Google::Backstory::EntityMetadata::EntityType]
+    #     Type of the related entity (b) in this relationship.
+    # @!attribute [rw] relationship
+    #   @return [::Google::Backstory::Relation::Relationship]
+    #     Type of relationship.
+    # @!attribute [rw] direction
+    #   @return [::Google::Backstory::Relation::Directionality]
+    #     Directionality of relationship between primary entity (a) and the
+    #     related entity (b).
+    # @!attribute [rw] uid
+    #   @return [::String]
+    #     UID of the relationship.
+    # @!attribute [rw] entity_label
+    #   @return [::Google::Backstory::Relation::EntityLabel]
+    #     Label to identify the Noun of the relation.
+    class Relation
+      include ::Google::Protobuf::MessageExts
+      extend ::Google::Protobuf::MessageExts::ClassMethods
+
+      # Type of relationship between the primary entity (a) and related entity (b).
+      module 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
+      end
+
+      # Describes the relationship model as directed or undirected.
+      module 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
+      end
+
+      # Entity label of the relation.
+      module 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
+      end
+    end
+
+    # Stores precomputed aggregated analytic data for an entity.
+    # @!attribute [rw] first_seen
+    #   @return [::Google::Protobuf::Timestamp]
+    #     Timestamp of the first time the entity was seen in the environment.
+    # @!attribute [rw] last_seen
+    #   @return [::Google::Protobuf::Timestamp]
+    #     Time stamp of the last time last time the entity was seen in the
+    #     environment.
+    # @!attribute [rw] sum_measure
+    #   @return [::Google::Backstory::Metric::Measure]
+    #     Sum of all precomputed measures for the given metric.
+    # @!attribute [rw] total_events
+    #   @return [::Integer]
+    #     Total number of events used to calculate the given precomputed metric.
+    # @!attribute [rw] metric_name
+    #   @return [::Google::Backstory::Metric::MetricName]
+    #     Name of the analytic.
+    # @!attribute [rw] dimensions
+    #   @return [::Array<::Google::Backstory::Metric::Dimension>]
+    #     All group by clauses used to calculate the metric.
+    # @!attribute [rw] export_window
+    #   @return [::Integer]
+    #     Export window for which the metric was exported.
+    # @!attribute [rw] display_name
+    #   @return [::String]
+    #     Display name of the custom metric. Google-authored metrics do not have a
+    #     display name.
+    # @!attribute [rw] outcome_variables
+    #   @return [::Array<::Google::Backstory::FindingVariable>]
+    #     List of outcome variables used in the custom metric.
+    # @!attribute [rw] match_variables
+    #   @return [::Array<::Google::Backstory::FindingVariable>]
+    #     List of match variables used in the custom metric.
+    # @!attribute [rw] time_range
+    #   @return [::Google::Type::Interval]
+    #     Time range for which the custom metric was calculated.
+    class Metric
+      include ::Google::Protobuf::MessageExts
+      extend ::Google::Protobuf::MessageExts::ClassMethods
+
+      # Describes the precomputed measure.
+      # @!attribute [rw] value
+      #   @return [::Float]
+      #     Value of the aggregated measure.
+      # @!attribute [rw] aggregate_function
+      #   @return [::Google::Backstory::Metric::AggregateFunction]
+      #     Function used to calculate the aggregated measure.
+      class Measure
+        include ::Google::Protobuf::MessageExts
+        extend ::Google::Protobuf::MessageExts::ClassMethods
+      end
+
+      # Mathematic function used to calculate the value.
+      module 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
+      end
+
+      # The name of the precomputed analytic.
+      module 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
+      end
+
+      # Describes field used as the dimension when grouping data to calculate the
+      # aggregate metric.
+      module 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
+      end
+    end
+  end
+end