google-cloud-chronicle-v1 1.3.0 → 1.4.0

data/proto_docs/backstory/collection.rb

@@ -0,0 +1,371 @@
+# 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
+    # Collection represents a container of objects (such as events, entity
+    # context metadata, detection finding metadata) and state (such as
+    # investigation details).
+    #
+    # An example use case for Collection is to model a detection and investigation
+    # from detection finding metadata to investigative state collected in the
+    # course of the investigation. For more complex investigation and response
+    # workflows a Collection could represent an incident consisting of multiple
+    # child findings or incidents. This can be expanded on to model remediation
+    # elements of a full detection and response workflow.
+    # @!attribute [rw] id
+    #   @return [::String]
+    #     Unique ID for the collection.
+    #     The ID is specific to the type of collection. For example, with rule
+    #     detections this is the detection ID.
+    # @!attribute [rw] type
+    #   @return [::Google::Backstory::Collection::CollectionType]
+    #     What the collection represents.
+    # @!attribute [rw] id_namespace
+    #   @return [::Google::Backstory::Id::Namespace]
+    #     The ID namespace used for the Collection.
+    # @!attribute [rw] created_time
+    #   @return [::Google::Protobuf::Timestamp]
+    #     Time the collection was created.
+    # @!attribute [rw] last_updated_time
+    #   @return [::Google::Protobuf::Timestamp]
+    #     Time the collection was last updated.
+    # @!attribute [rw] time_window
+    #   @return [::Google::Type::Interval]
+    #     Time interval that the collection represents.
+    # @!attribute [rw] collection_elements
+    #   @return [::Array<::Google::Backstory::Element>]
+    #     Constituent elements of the collection. Each element shares an association
+    #     that groups it together and is a component of the overall collection. For
+    #     example, a detection collection may have several constituent elements that
+    #     each share a correlation association that together represent a particular
+    #     pattern or behavior.
+    # @!attribute [rw] detection
+    #   @return [::Array<::Google::Backstory::SecurityResult>]
+    #     Detection metadata for findings that represent detections, can include
+    #     rule details, machine learning model metadata, and indicators implicated
+    #     in the detection (using the .about field).
+    # @!attribute [rw] detection_time
+    #   @return [::Google::Protobuf::Timestamp]
+    #     Timestamp within the time_window related to the time of the
+    #     collection_elements. For Rule Detections, this timestamp is the end of the
+    #     the time_window for multi-event rules or the time of the event for single
+    #     event rules. For late-arriving events that trigger new alerts, the
+    #     detection_time will be the event time of the event.
+    # @!attribute [rw] investigation
+    #   @return [::Google::Backstory::Investigation]
+    #     Consolidated investigation details (categorization, status, etc) typically
+    #     for collections that begin as detection findings and then evolve with
+    #     analyst action and feedback into investigations around the detection
+    #     output.
+    # @!attribute [rw] tags
+    #   @return [::Array<::String>]
+    #     Tags set by UC/DSML/RE for the Finding during creation.
+    # @!attribute [rw] response_platform_info
+    #   @return [::Google::Backstory::ResponsePlatformInfo]
+    #     Alert related info of this same alert in customer's SOAR platform.
+    # @!attribute [rw] case_name
+    #   @return [::String]
+    #     The resource name of the Case that this collection belongs to.
+    #     Example:
+    #     projects/\\{project id}/locations/\\{region}/chronicle/cases/\\{internal_case_id}
+    # @!attribute [rw] soar_alert
+    #   @return [::Boolean]
+    #     A boolean field indicating that the alert is present in SOAR.
+    # @!attribute [rw] soar_alert_metadata
+    #   @return [::Google::Backstory::SoarAlertMetadata]
+    #     Metadata fields of alerts coming from other SIEM systems via SOAR.
+    # @!attribute [rw] data_access_scope
+    #   @return [::String]
+    #     The resource name of the DataAccessScope of this collection.
+    # @!attribute [rw] detection_timing_details
+    #   @return [::Array<::Google::Backstory::Collection::DetectionTimingDetails>]
+    #     Detection timing details for the collection. These details are used to
+    #     determine prossible causes of latency for the detection.
+    #     This field is only set for detections that are generated by rules.
+    # @!attribute [rw] latency_metrics
+    #   @return [::Google::Backstory::LatencyMetrics]
+    #     The latency metrics for the specific detection. These metrics are
+    #     calculated from ALL of the events that contribute to the detection, not
+    #     just the sampled ones.
+    # @!attribute [rw] rule_run_frequency
+    #   @return [::Google::Backstory::Collection::RunFrequency]
+    #     The run frequency of the rule when it generated the detection.
+    # @!attribute [rw] simulated_event_count
+    #   @return [::Integer]
+    #     The total number of simulated events that contributed to this detection.
+    #     Simulated events are realistic threat sequences (Raw Logs or UDM)
+    #     programmatically delivered into the production ingestion pipeline to verify
+    #     the entire detection lifecycle—from identification to action.
+    # @!attribute [rw] simulated_event_names
+    #   @return [::Array<::String>]
+    #     The set of all values from event ingestion_labels where SIMULATED is set as
+    #     the key, for all simulated events that participated in this detection.
+    class Collection
+      include ::Google::Protobuf::MessageExts
+      extend ::Google::Protobuf::MessageExts::ClassMethods
+
+      # The type of the collection which will indicate which other fields are
+      # relevant. For example, detection finding collections will populate the
+      # detection field. Findings that evolve into investigations will populate the
+      # investigation field.
+      module CollectionType
+        # An unspecified collection type.
+        COLLECTION_TYPE_UNSPECIFIED = 0
+
+        # An alert reported in customer telemetry.
+        TELEMETRY_ALERT = 1
+
+        # A finding from the Uppercase team.
+        GCTI_FINDING = 2
+
+        UPPERCASE_ALERT = 2
+
+        # A detection found by applying a rule.
+        RULE_DETECTION = 3
+
+        # An alert generated by Chronicle machine learning models.
+        MACHINE_INTELLIGENCE_ALERT = 4
+
+        # An alert coming from other SIEMs via Chronicle SOAR.
+        SOAR_ALERT = 5
+      end
+
+      # Detection timing details for the collection.
+      module DetectionTimingDetails
+        # Detection timing details are unspecified.
+        DETECTION_TIMING_DETAILS_UNSPECIFIED = 0
+
+        # Detection is generated by a reprocessing run.
+        DETECTION_TIMING_DETAILS_REPROCESSING = 1
+
+        # Detection is generated by a retrohunt run.
+        DETECTION_TIMING_DETAILS_RETROHUNT = 2
+      end
+
+      # Run frequencies used by rule executions.
+      module RunFrequency
+        # Unspecified run frequency.
+        RUN_FREQUENCY_UNSPECIFIED = 0
+
+        # Real-time run frequency.
+        RUN_FREQUENCY_REALTIME = 1
+
+        # Executes once an hour.
+        RUN_FREQUENCY_HOURLY = 2
+
+        # Executes once a day.
+        RUN_FREQUENCY_DAILY = 3
+      end
+    end
+
+    # EntityGraphEnrichment contains the data table name and the enrichment applied
+    # to the entity.
+    # @!attribute [rw] data_table
+    #   @return [::String]
+    #     The name of the data table.
+    # @!attribute [rw] enrichment_type
+    #   @return [::Google::Backstory::EntityGraphEnrichment::EnrichmentType]
+    #     The type of enrichment.
+    # @!attribute [rw] overridden_entity
+    #   @return [::Google::Backstory::Entity]
+    #     The entity which has only the overridden fields populated. Only populated
+    #     if the enrichment type is OVERRIDE.
+    class EntityGraphEnrichment
+      include ::Google::Protobuf::MessageExts
+      extend ::Google::Protobuf::MessageExts::ClassMethods
+
+      # Type of enrichment.
+      module EnrichmentType
+        # Enrichment type is unspecified.
+        ENRICHMENT_TYPE_UNSPECIFIED = 0
+
+        # The data table was appended to the entity graph.
+        APPEND = 1
+
+        # The entity graph was overridden by the data table.
+        OVERRIDE = 2
+      end
+    end
+
+    # DataTableRowInfo captures information about a data table row including the
+    # name of the data table.
+    # @!attribute [rw] data_table
+    #   @return [::String]
+    #     The name of data table.
+    # @!attribute [rw] row
+    #   @return [::Google::Protobuf::Struct]
+    #     Stores the key value pair for a data table row where the key is the name
+    #     of the column for the given value.
+    # @!attribute [rw] row_id
+    #   @return [::String]
+    #     The row id of the data table row.
+    class DataTableRowInfo
+      include ::Google::Protobuf::MessageExts
+      extend ::Google::Protobuf::MessageExts::ClassMethods
+    end
+
+    # LatencyMetrics contains relevant timestamps for measuring latency per event
+    # variable. These metrics are calculated from ALL of the events that contribute
+    # to the detection, not just the sampled ones.
+    # @!attribute [rw] oldest_ingestion_time
+    #   @return [::Google::Protobuf::Timestamp]
+    #     The oldest ingestion timestamp from the events used to create the
+    #     detection.
+    # @!attribute [rw] newest_ingestion_time
+    #   @return [::Google::Protobuf::Timestamp]
+    #     The newest (most recent) ingestion timestamp from the events used to
+    #     create the detection.
+    # @!attribute [rw] oldest_event_time
+    #   @return [::Google::Protobuf::Timestamp]
+    #     The oldest event timestamp from the events used to create the detection.
+    # @!attribute [rw] newest_event_time
+    #   @return [::Google::Protobuf::Timestamp]
+    #     The newest (most recent) event timestamp from the events used to create
+    #     the detection.
+    # @!attribute [rw] ingestion_latency
+    #   @return [::Google::Protobuf::Duration]
+    #     The difference between newest ingestion timestamp and newest event
+    #     timestamp.
+    class LatencyMetrics
+      include ::Google::Protobuf::MessageExts
+      extend ::Google::Protobuf::MessageExts::ClassMethods
+    end
+
+    # Reference to model primatives including event and entity. As support is added
+    # for fast retrieval of objects by identifiers, this will be
+    # expanded to include ID references rather than full object copies.
+    # @!attribute [rw] event
+    #   @return [::Google::Backstory::UDM]
+    #     Only one of event or entity will be populated for a single
+    #     reference.
+    #     Start one-of
+    #     Event being referenced.
+    # @!attribute [rw] entity
+    #   @return [::Google::Backstory::Entity]
+    #     Entity being referenced. In cases where the entity graph is overridden by
+    #     data table, this will represent the original entity.
+    #     End one-of
+    # @!attribute [rw] joined_data_table_rows
+    #   @return [::Array<::Google::Backstory::DataTableRowInfo>]
+    #     The data table rows joined with the event.
+    # @!attribute [rw] graph_enrichment
+    #   @return [::Google::Backstory::EntityGraphEnrichment]
+    #     The entity graph enrichment details. Only set when the reference is an
+    #     Entity which has been overridden by a data table or appended from a data
+    #     table.
+    # @!attribute [rw] id
+    #   @return [::Google::Backstory::Id]
+    #     Id being referenced. This field will also be populated for both event and
+    #     entity with the event id. For detections, only this field will be
+    #     populated.
+    # @!attribute [rw] log_batch_token
+    #   @return [::String]
+    #     The log batch token of the event being referenced. This field is
+    #     used to fetch the raw log associated with the event in some legacy systems.
+    #     This field is only populated for events/entities.
+    class Reference
+      include ::Google::Protobuf::MessageExts
+      extend ::Google::Protobuf::MessageExts::ClassMethods
+    end
+
+    # @!attribute [rw] association
+    #   @return [::Google::Backstory::SecurityResult]
+    #     Metadata that provides the relevant association for the references in the
+    #     element. For a detection, this can be the correlated aspect of the
+    #     references that contributed to the overall detection. For example, may
+    #     include sub-rule condition, machine learning model metadata, and/or
+    #     indicators implicated in this component of the detection
+    #     (using the .about field).
+    # @!attribute [rw] references
+    #   @return [::Array<::Google::Backstory::Reference>]
+    #     References to model primatives including events and entities that share a
+    #     common association.
+    #     Even though a reference can have both UDM and entity, a collection of
+    #     references (of a single element) will only have one type of message in it
+    #     (either UDM / Entity).
+    # @!attribute [rw] label
+    #   @return [::String]
+    #     A name that labels the entire references group.
+    # @!attribute [rw] references_sampled
+    #   @return [::Boolean]
+    #     Copied from the detection event_sample.too_many_event_samples field.
+    #     If true, the number of references will be capped at the sample limit
+    #     (set at rule service).
+    #     This is applicable to both UDM references and Entity references.
+    # @!attribute [rw] latency_metrics
+    #   @return [::Google::Backstory::LatencyMetrics]
+    #     Latency metrics for the specific element. These are
+    #     calculated from all the contributing events or entities for a single event
+    #     variable, not just the sampled ones included in references. This is
+    #     currently only populated for UDM events.
+    class Element
+      include ::Google::Protobuf::MessageExts
+      extend ::Google::Protobuf::MessageExts::ClassMethods
+    end
+
+    # Related info of an Alert in customer's SOAR platform.
+    # @!attribute [rw] alert_id
+    #   @return [::String]
+    #     Id of the alert in SOAR product.
+    # @!attribute [rw] response_platform_type
+    #   @return [::Google::Backstory::ResponsePlatformInfo::ResponsePlatformType]
+    #     Type of SOAR product.
+    class ResponsePlatformInfo
+      include ::Google::Protobuf::MessageExts
+      extend ::Google::Protobuf::MessageExts::ClassMethods
+
+      # Available response platforms.
+      module ResponsePlatformType
+        # Response platform not specified.
+        RESPONSE_PLATFORM_TYPE_UNSPECIFIED = 0
+
+        # Siemplify
+        RESPONSE_PLATFORM_TYPE_SIEMPLIFY = 1
+      end
+    end
+
+    # Metadata fields of alerts coming from other SIEM systems.
+    # @!attribute [rw] alert_id
+    #   @return [::String]
+    #     Alert ID in the source SIEM system.
+    # @!attribute [rw] source_rule
+    #   @return [::String]
+    #     Name of the rule triggering the alert in the source SIEM.
+    # @!attribute [rw] vendor
+    #   @return [::String]
+    #     Name of the vendor.
+    # @!attribute [rw] source_system
+    #   @return [::String]
+    #     Name of the Source SIEM system.
+    # @!attribute [rw] product
+    #   @return [::String]
+    #     Name of the product the alert is coming from.
+    # @!attribute [rw] source_system_ticket_id
+    #   @return [::String]
+    #     Ticket id for the alert in the source system.
+    # @!attribute [rw] source_system_uri
+    #   @return [::String]
+    #     Url to the source SIEM system.
+    class SoarAlertMetadata
+      include ::Google::Protobuf::MessageExts
+      extend ::Google::Protobuf::MessageExts::ClassMethods
+    end
+  end
+end

data/proto_docs/backstory/data_access.rb

@@ -0,0 +1,59 @@
+# 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
+    # Label used in data access for ingestion.
+    # @!attribute [rw] key
+    #   @return [::String]
+    #     The key.
+    # @!attribute [rw] value
+    #   @return [::String]
+    #     The value.
+    class DataAccessIngestionLabel
+      include ::Google::Protobuf::MessageExts
+      extend ::Google::Protobuf::MessageExts::ClassMethods
+    end
+
+    # Label used in data access.
+    # @!attribute [rw] log_types
+    #   @return [::Array<::String>]
+    #     All the LogType labels.
+    # @!attribute [rw] ingestion_labels
+    #   @deprecated This field is deprecated and may be removed in the next major version update.
+    #   @return [::Array<::String>]
+    #     All the ingestion labels.
+    # @!attribute [rw] namespaces
+    #   @return [::Array<::String>]
+    #     All the namespaces.
+    # @!attribute [rw] custom_labels
+    #   @return [::Array<::String>]
+    #     All the complex labels (UDM search syntax based).
+    # @!attribute [rw] ingestion_kv_labels
+    #   @return [::Array<::Google::Backstory::DataAccessIngestionLabel>]
+    #     All the ingestion labels (key/value pairs).
+    # @!attribute [rw] allow_scoped_access
+    #   @return [::Boolean]
+    #     Are the labels ready for scoped access
+    class DataAccessLabels
+      include ::Google::Protobuf::MessageExts
+      extend ::Google::Protobuf::MessageExts::ClassMethods
+    end
+  end
+end