Collection

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.

NEXT TAG: 20

JSON representation
{
  "id": string,
  "type": enum (CollectionType),
  "idNamespace": enum (Namespace),
  "createdTime": string,
  "lastUpdatedTime": string,
  "timeWindow": {
    object (Interval)
  },
  "collectionElements": [
    {
      object (Element)
    }
  ],
  "detection": [
    {
      object (SecurityResult)
    }
  ],
  "detectionTime": string,
  "investigation": {
    object (Investigation)
  },
  "tags": [
    string
  ],
  "responsePlatformInfo": {
    object (ResponsePlatformInfo)
  },
  "caseName": string,
  "feedbackSummary": {
    object (Feedback)
  },
  "feedbackHistory": [
    {
      object (Feedback)
    }
  ],
  "soarAlert": boolean,
  "soarAlertMetadata": {
    object (SoarAlertMetadata)
  },
  "dataAccessScope": string
}
Fields
id

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.

type

enum (CollectionType)

What the collection represents.

idNamespace

enum (Namespace)

The ID namespace used for the Collection.

createdTime

string (Timestamp format)

Time the collection was created.

Uses RFC 3339, where generated output will always be Z-normalized and uses 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".

lastUpdatedTime

string (Timestamp format)

Time the collection was last updated.

Uses RFC 3339, where generated output will always be Z-normalized and uses 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".

timeWindow

object (Interval)

Time interval that the collection represents.

collectionElements[]

object (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.

detection[]

object (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).

detectionTime

string (Timestamp format)

Timestamp within the timeWindow related to the time of the collectionElements. For Rule Detections, this timestamp is the end of the the timeWindow for multi-event rules or the time of the event for single event rules. For late-arriving events that trigger new alerts, the detectionTime will be the event time of the event.

Uses RFC 3339, where generated output will always be Z-normalized and uses 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".

investigation

object (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.

tags[]

string

Tags set by UC/DSML/RE for the Finding during creation.

responsePlatformInfo

object (ResponsePlatformInfo)

Alert related info of this same alert in customer's SOAR platform.

caseName

string

The resource name of the Case that this collection belongs to. Example: projects/{project id}/locations/{region}/chronicle/cases/{internal_case_id}

feedbackSummary

object (Feedback)

The current primary analyst feedback. This does not include the history of feedback given, which may be supplied in feedback.

feedbackHistory[]

object (Feedback)

The history of feedback submitted by analysts for this finding, in descending order by timestamp. This field is limited to the most recent 1000 feedback events. The primary feedback will also be included in this list.

soarAlert

boolean

A boolean field indicating that the alert is present in SOAR.

soarAlertMetadata

object (SoarAlertMetadata)

Metadata fields of alerts coming from other SIEM systems via SOAR.

dataAccessScope

string

The resource name of the DataAccessScope of this collection.

Element

NEXT TAG: 5

JSON representation
{
  "association": {
    object (SecurityResult)
  },
  "references": [
    {
      object (Reference)
    }
  ],
  "label": string,
  "referencesSampled": boolean
}
Fields
association

object (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).

references[]

object (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).

label

string

A name that labels the entire references group.

referencesSampled

boolean

Copied from the detection eventSample.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.

Reference

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.

JSON representation
{
  "event": {
    object (UDM)
  },
  "entity": {
    object (Entity)
  },
  "joinedDataTableRows": [
    {
      object (DataTableRowInfo)
    }
  ],
  "graphEnrichment": {
    object (EntityGraphEnrichment)
  },
  "id": {
    object (Id)
  }
}
Fields
event

object (UDM)

Only one of event or entity will be populated for a single reference. Start one-of Event being referenced.

entity

object (Entity)

Entity being referenced. In cases where the entity graph is overridden by data table, this will represent the original entity. End one-of

joinedDataTableRows[]

object (DataTableRowInfo)

The data table rows joined with the event.

graphEnrichment

object (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.

id

object (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.

DataTableRowInfo

DataTableRowInfo captures information about a data table row including the name of the data table.

JSON representation
{
  "dataTable": string,
  "row": {
    object
  },
  "rowId": string
}
Fields
dataTable

string

The name of data table.

row

object (Struct format)

Stores the key value pair for a data table row where the key is the name of the column for the given value.

rowId

string

The row id of the data table row.

EntityGraphEnrichment

EntityGraphEnrichment contains the data table name and the enrichment applied to the entity.

JSON representation
{
  "dataTable": string,
  "enrichmentType": enum (EnrichmentType),
  "overriddenEntity": {
    object (Entity)
  }
}
Fields
dataTable

string

The name of the data table.

enrichmentType

enum (EnrichmentType)

The type of enrichment.

overriddenEntity

object (Entity)

The entity which has only the overridden fields populated. Only populated if the enrichment type is OVERRIDE.

EnrichmentType

Type of enrichment.

Enums
ENRICHMENT_TYPE_UNSPECIFIED Enrichment type is unspecified.
APPEND The data table was appended to the entity graph.
OVERRIDE The entity graph was overridden by the data table.

SoarAlertMetadata

Metadata fields of alerts coming from other SIEM systems.

JSON representation
{
  "alertId": string,
  "sourceRule": string,
  "vendor": string,
  "sourceSystem": string,
  "product": string,
  "sourceSystemTicketId": string,
  "sourceSystemUri": string
}
Fields
alertId

string

Alert ID in the source SIEM system.

sourceRule

string

Name of the rule triggering the alert in the source SIEM.

vendor

string

Name of the vendor.

sourceSystem

string

Name of the Source SIEM system.

product

string

Name of the product the alert is coming from.

sourceSystemTicketId

string

Ticket id for the alert in the source system.

sourceSystemUri

string

Url to the source SIEM system.