- Resource: CaseEvidenceData
- ThreatHunt
- SuccessResult
- Determination
- HuntSubject
- HuntState
- ThreatHuntStep
- ThreatHuntSearchQuery
- Collection
- CollectionType
- Element
- Reference
- DataTableRowInfo
- EntityGraphEnrichment
- EnrichmentType
- LatencyMetrics
- ResponsePlatformInfo
- ResponsePlatformType
- Feedback
- UserType
- SoarAlertMetadata
- DetectionTimingDetails
- RunFrequency
- DataType
- CaseEvidence
- EvidenceType
- Methods
Resource: CaseEvidenceData
Represents arbitrary data (like threat hunts or alerts) attached to a specific security case, either directly (for example, via AttachCaseEvidence or indirectly (for example, events that belong to a detection that was attached as evidence)
| JSON representation |
|---|
{ "name": string, "caseEvidenceDataId": string, "evidenceType": enum ( |
| Fields | |
|---|---|
name |
Output only. Identifier. The unique resource name of the CaseEvidenceData. Format: projects/{project}/locations/{location}/instances/{instance}/cases/{case}/ caseEvidenceDatas/{evidence_data} |
caseEvidenceDataId |
Output only. The system-generated unique key for this evidence data entry. This is used as the final segment of the resource name and repeated here for convenience. |
evidenceType |
Output only. The category of data stored in this resource. This matches the |
sources[] |
Output only. Information about the origin of the CaseEvidenceData. Each CaseEvidenceData resource will have at least one source, which represents when and how it was attached to the Case. |
Union field data. The evidence data payload associated with the Case. data can be only one of the following: |
|
threatHunt |
Output only. Detailed findings and investigation steps from a threat hunt. |
detection |
Output only. An associated non-alerting detection. |
alert |
Output only. An associated alerting detection. |
event |
Output only. An associated event. |
ThreatHunt
A single execution instance of a threat hunt.
| JSON representation |
|---|
{ "subjects": [ { object ( |
| Fields | |
|---|---|
subjects[] |
Required. The subjects under investigation in this hunt. Although repeated to support potential future hunts on more than one subject, currently this will only have a single subject. |
state |
Output only. The current state of the hunt. |
interval |
Required. The time range over which the hunt was run. |
createTime |
Output only. Timestamp when the hunt was initiated. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: |
completeTime |
Output only. Timestamp when the hunt concluded. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: |
updateTime |
Output only. Timestamp when the hunt was last updated. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: |
steps[] |
Output only. The steps that the agent took to hunt for the subject. |
Union field result_options. The hunt result is either a success or an error. result_options can be only one of the following: |
|
result |
Output only. Set if the hunt completed successfully. |
error |
Output only. Error details which will be set if the hunt resulted in an error. |
SuccessResult
Details for a successful hunt result.
| JSON representation |
|---|
{
"score": number,
"determination": enum ( |
| Fields | |
|---|---|
score |
Output only. The weight of evidence found in making the determination. The value ranges from 1 (no evidence) to 4 (a lot of strong evidence). |
determination |
Output only. High-level determination. |
reasoning |
Output only. Supporting reasoning for the determination. |
Determination
Whether the threat may be present in the environment
| Enums | |
|---|---|
DETERMINATION_UNSPECIFIED |
An unknown determination. |
TRUE |
The threat may be present. |
FALSE |
The threat is likely not present. |
HuntSubject
Represents the subject of a threat hunt.
| JSON representation |
|---|
{ // Union field |
| Fields | |
|---|---|
Union field subject. The resource that the hunt centers on. subject can be only one of the following: |
|
campaign |
A GTI campaign. |
actor |
A GTI threat actor. |
malware |
A GTI malware family. |
technique |
A MITRE ATT&CK Technique. |
tool |
A software tool. |
HuntState
Enum for the state of a ThreatHunt.
| Enums | |
|---|---|
HUNT_STATE_UNSPECIFIED |
Default value. |
HUNT_STATE_NOT_STARTED |
Hunt has not started yet. |
HUNT_STATE_RUNNING |
Hunt is currently running. |
HUNT_STATE_SUCCEEDED |
Hunt completed successfully. |
HUNT_STATE_FAILED |
Hunt completed with an error. |
ThreatHuntStep
Represents an individual step taken within a ThreatHunt.
| JSON representation |
|---|
{ "task": string, "startTime": string, "endTime": string, "stepNumber": integer, // Union field |
| Fields | |
|---|---|
task |
Output only. The hypothesis being investigated in this specific step. |
startTime |
Output only. Timestamp when the step started. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: |
endTime |
Output only. Timestamp when the step finished. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: |
stepNumber |
Output only. Incremental integer representing the step number. |
Union field step_details. The details of the action performed in this step. step_details can be only one of the following: |
|
searchQuery |
Output only. Details of the search query that the agent ran and its results. |
ThreatHuntSearchQuery
Details of the execution of a search query within a hunt step.
| JSON representation |
|---|
{
"query": string,
"summary": string,
"events": [
string
],
"interval": {
object ( |
| Fields | |
|---|---|
query |
Output only. The UDM search query executed. |
summary |
Output only. Summary of the evidence found in this step. |
events[] |
Output only. Resource names of the events that were returned by the query. |
interval |
Output only. The time range over which the search query was run. |
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: 25
| JSON representation |
|---|
{ "id": string, "type": enum ( |
| Fields | |
|---|---|
id |
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 |
What the collection represents. |
idNamespace |
The ID namespace used for the Collection. |
createdTime |
Time the collection was created. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: |
lastUpdatedTime |
Time the collection was last updated. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: |
timeWindow |
Time interval that the collection represents. |
collectionElements[] |
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[] |
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 |
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 use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: |
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[] |
Tags set by UC/DSML/RE for the Finding during creation. |
responsePlatformInfo |
Alert related info of this same alert in customer's SOAR platform. |
caseName |
The resource name of the Case that this collection belongs to. Example: projects/{project id}/locations/{region}/chronicle/cases/{internal_case_id} |
feedbackSummary |
The current primary analyst feedback. This does not include the history of feedback given, which may be supplied in |
feedbackHistory[] |
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 |
A boolean field indicating that the alert is present in SOAR. |
soarAlertMetadata |
Metadata fields of alerts coming from other SIEM systems via SOAR. |
dataAccessScope |
The resource name of the DataAccessScope of this 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. |
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. |
ruleRunFrequency |
The run frequency of the rule when it generated the detection. |
simulatedEventCount |
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. |
simulatedEventNames[] |
The set of all values from event ingestionLabels where SIMULATED is set as the key, for all simulated events that participated in this detection. |
CollectionType
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.
| Enums | |
|---|---|
COLLECTION_TYPE_UNSPECIFIED |
An unspecified collection type. |
TELEMETRY_ALERT |
An alert reported in customer telemetry. |
GCTI_FINDING |
A finding from the Uppercase team. |
UPPERCASE_ALERT |
|
RULE_DETECTION |
A detection found by applying a rule. |
MACHINE_INTELLIGENCE_ALERT |
An alert generated by Chronicle machine learning models. |
SOAR_ALERT |
An alert coming from other SIEMs via Chronicle SOAR. |
Element
NEXT TAG: 6
| JSON representation |
|---|
{ "association": { object ( |
| Fields | |
|---|---|
association |
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[] |
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 |
A name that labels the entire references group. |
referencesSampled |
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. |
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. |
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 ( |
| Fields | |
|---|---|
event |
Only one of event or entity will be populated for a single reference. Start one-of Event being referenced. |
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[] |
The data table rows joined with the event. |
graphEnrichment |
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 |
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. |
logBatchToken |
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. |
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 |
The name of data table. |
row |
Stores the key value pair for a data table row where the key is the name of the column for the given value. |
rowId |
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 ( |
| Fields | |
|---|---|
dataTable |
The name of the data table. |
enrichmentType |
The type of enrichment. |
overriddenEntity |
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. |
LatencyMetrics
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. NEXT TAG: 6
| JSON representation |
|---|
{ "oldestIngestionTime": string, "newestIngestionTime": string, "oldestEventTime": string, "newestEventTime": string, "ingestionLatency": string } |
| Fields | |
|---|---|
oldestIngestionTime |
The oldest ingestion timestamp from the events used to create the detection. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: |
newestIngestionTime |
The newest (most recent) ingestion timestamp from the events used to create the detection. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: |
oldestEventTime |
The oldest event timestamp from the events used to create the detection. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: |
newestEventTime |
The newest (most recent) event timestamp from the events used to create the detection. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: |
ingestionLatency |
The difference between newest ingestion timestamp and newest event timestamp. A duration in seconds with up to nine fractional digits, ending with ' |
ResponsePlatformInfo
Related info of an Alert in customer's SOAR platform.
| JSON representation |
|---|
{
"alertId": string,
"responsePlatformType": enum ( |
| Fields | |
|---|---|
alertId |
Id of the alert in SOAR product. |
responsePlatformType |
Type of SOAR product. |
ResponsePlatformType
Available response platforms.
| Enums | |
|---|---|
RESPONSE_PLATFORM_TYPE_UNSPECIFIED |
Response platform not specified. |
RESPONSE_PLATFORM_TYPE_SIEMPLIFY |
Siemplify |
Feedback
| JSON representation |
|---|
{ "idpUserId": string, "createdTime": string, "verdict": enum ( |
| Fields | |
|---|---|
idpUserId |
Required. |
createdTime |
Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: |
verdict |
|
reputation |
|
confidenceScore |
|
riskScore |
|
disregarded |
|
severity |
|
comment |
Optional. |
status |
Optional. |
priority |
Optional. |
rootCause |
Optional. |
reason |
Optional. |
severityDisplay |
Optional. |
priorityDisplay |
Optional. |
triageAgentInvestigationId |
Optional. |
userType |
|
UserType
| Enums | |
|---|---|
USER_TYPE_UNSPECIFIED |
|
ANALYST |
|
TRIAGE_AGENT |
|
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 |
Alert ID in the source SIEM system. |
sourceRule |
Name of the rule triggering the alert in the source SIEM. |
vendor |
Name of the vendor. |
sourceSystem |
Name of the Source SIEM system. |
product |
Name of the product the alert is coming from. |
sourceSystemTicketId |
Ticket id for the alert in the source system. |
sourceSystemUri |
Url to the source SIEM system. |
DetectionTimingDetails
Detection timing details for the collection.
| Enums | |
|---|---|
DETECTION_TIMING_DETAILS_UNSPECIFIED |
Detection timing details are unspecified. |
DETECTION_TIMING_DETAILS_REPROCESSING |
Detection is generated by a reprocessing run. |
DETECTION_TIMING_DETAILS_RETROHUNT |
Detection is generated by a retrohunt run. |
RunFrequency
Run frequencies used by rule executions.
| Enums | |
|---|---|
RUN_FREQUENCY_UNSPECIFIED |
Unspecified run frequency. |
RUN_FREQUENCY_REALTIME |
Real-time run frequency. |
RUN_FREQUENCY_HOURLY |
Executes once an hour. |
RUN_FREQUENCY_DAILY |
Executes once a day. |
DataType
The classification of the evidence data (e.g., ALERT, EVENT, THREAT_HUNT).
| Enums | |
|---|---|
DATA_TYPE_UNSPECIFIED |
Unspecified evidence type. |
THREAT_HUNT |
Represents a multi-stage threat hunt. |
EVENT |
Represents a specific UDM event. |
ALERT |
Represents a security alert. |
DETECTION |
Represents a detection. |
CaseEvidence
Represents a piece of evidence associated with a Chronicle case. Evidence can be of various types, such as alerts, detections, or events.
| JSON representation |
|---|
{ "evidenceType": enum ( |
| Fields | |
|---|---|
evidenceType |
Output only. The type of evidence. |
evidenceId |
Output only. The unique identifier of the evidence. |
attachTime |
Output only. The timestamp when the evidence was attached to the Case. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: |
attacher |
Output only. The user who attached the evidence to the Case. |
sourceEvidenceId |
Output only. The ID of the evidence that this evidence was extracted from. |
sourceEvidenceType |
Output only. The type of evidence that this evidence was extracted from. |
sourceEvidenceKey |
Output only. The key of the evidence that this evidence was extracted from. |
soarEvidenceId |
Output only. The ID of the evidence in SOAR. |
EvidenceType
Describes the type of evidence a case evidence is. Note: This enum is not frozen and new values are likely to be added in the future.
| Enums | |
|---|---|
EVIDENCE_TYPE_UNSPECIFIED |
The evidence type is unspecified. |
EVIDENCE_TYPE_ALERT |
The evidence type is alert. |
EVIDENCE_TYPE_EVENT |
The evidence type is event. |
EVIDENCE_TYPE_DETECTION |
The evidence type is detection. |
EVIDENCE_TYPE_ENTITY |
The evidence type is entity. |
EVIDENCE_TYPE_RULE_MATCH_ENTITY |
The evidence type is rule match entity. |
EVIDENCE_TYPE_RULE_OUTCOME_ENTITY |
The evidence type is rule outcome entity. |
EVIDENCE_TYPE_UDM_PRINCIPAL_ENTITY |
The evidence type is UDM entity principal. |
EVIDENCE_TYPE_UDM_TARGET_ENTITY |
The evidence type is UDM entity target. |
EVIDENCE_TYPE_UDM_ABOUT_ENTITY |
The evidence type is UDM entity about. |
EVIDENCE_TYPE_THREAT_HUNT |
The evidence type is threat hunt. |
Methods |
|
|---|---|
|
Gets a case evidence data for a given case. |
|
Lists the case evidence data for a given case. |