REST Resource: projects.locations.instances.investigations.investigationSteps

Resource: InvestigationStep

An InvestigationStep is the smallest unit of an Investigation timeline. Each step describes a discrete action (e.g. query, result, or threat intel lookup).

JSON representation 
{
  "name": string,
  "analysisSummary": string,
  "description": string,
  "executionInterval": {
    object (Interval)
  },
  "toolMetadata": [
    {
      object (ToolMetadata)
    }
  ],
  "sourceDataCitations": [
    {
      object (Citation)
    }
  ],
  "sourceMetadata": {
    object (SourceMetadata)
  }
}
Fields
name

string

Output only. The full resource name of the Step. Format: projects/{project}/locations/{location}/instances/{instance}/investigations/{investigation}/investigationSteps/{investigationStep}
analysisSummary

string

Output only. A short summary of the analysis done as a part of this step. E.g. "File hash is malicious."
description

string

Output only. A detailed explanation of the step.
executionInterval

object (Interval)

Output only. Start and end times of the step execution.
toolMetadata[]

object (ToolMetadata)

Output only. Tools used during this step, e.g. "VirusTotal"
sourceDataCitations[]

object (Citation)

Output only. Citations that contributed to the step data
sourceMetadata

object (SourceMetadata)

Output only. The metadata of the source used in the investigation step.

ToolMetadata

ToolMetadata contains metadata about a tool used during an InvestigationStep.

JSON representation 
{
  "displayName": string,
  "resultUri": string,
  "description": string
}
Fields
displayName

string

Output only. The display name of the tool, e.g. "VirusTotal"
resultUri

string

The link to the tool's result page.
description

string

The description of the tool.

Citation

Citation contains metadata about a source of data used to generate an InvestigationStep.

JSON representation 
{
  "referenceText": string,
  "referenceUri": string
}
Fields
referenceText

string

The text of the citation.
referenceUri

string

The link to the citation.

SourceMetadata

SourceMetadata contains metadata about the source of data used during an InvestigationStep.

JSON representation 
{
  "sourceType": enum (SourceType),

  // Union field source_details can be only one of the following:
  "query": {
    object (SourceQuery)
  },
  "threatIntelligence": {
    object (ThreatIntelligence)
  },
  "event": {
    object (SourceEvent)
  },
  "processTree": {
    object (ProcessTree)
  },
  "commandLineAnalysis": {
    object (CommandLineAnalysis)
  }
  // End of list of possible types for union field source_details.
}
Fields
sourceType

enum (SourceType)

Output only. The type of the source. This is used to determine which of the source_details fields is populated.
Union field source_details. The details of the source. source_details can be only one of the following:
query

object (SourceQuery)

Output only. The query used in the source.
threatIntelligence

object (ThreatIntelligence)

Output only. The threat intelligence used in the source.
event

object (SourceEvent)

The event used in the source. Deprecated: Use don't use event .
processTree

object (ProcessTree)

Output only. The process tree used in the source.
commandLineAnalysis

object (CommandLineAnalysis)

Output only. The command line analysis used in the source when Gemini uses command line tool to analyze the alert It'll have a markdown format analysis result.

SourceQuery

Query as a source of investigation step.

JSON representation 
{
  "queryCode": string,
  "timeRange": {
    object (Interval)
  },
  "uniqueResultsCount": integer,
  "totalResultsCount": integer,
  "operation": string
}
Fields
queryCode

string

The code used to execute the query.
timeRange

object (Interval)

The time range that was used in the query execution.
uniqueResultsCount

integer

Output only. The number of unique results returned by the query execution.
totalResultsCount

integer

Output only. The number of total results returned by the query execution.
operation

string

Output only. The name of the operation resource representing the UDM Search operation. This can be passed to StreamSearchOperation to fetch stored results or stream the results of an in-progress operation. Format: projects/{project}/locations/{location}/instances/{instance}/operations/{operation}

ThreatIntelligence

Threat Intelligence as a source of investigation step.

JSON representation 
{
  "evidence": string
}
Fields
evidence

string

Output only. The evidence received in the step execution when using Threat Intelligence. This is a raw string that can be displayed to the user.

SourceEvent

Event data as a source of investigation step.

JSON representation 
{
  "id": [
    string
  ]
}
Fields
id[]

string

IDs of the events.

ProcessTree

Process Tree as a source of investigation step.

JSON representation 
{
  "processTree": string
}
Fields
processTree

string

Output only. ProcessTree is the serialized Depth First Search (DFS) representation of a stored process tree. This is a raw string that can be displayed to the user. Parsing is required to reconstruct the hierarchical process structure.

CommandLineAnalysis

Command Line Analysis as a source of investigation step.

JSON representation 
{
  "analysisResult": string
}
Fields
analysisResult

string

Output only. The command line analysis result in markdown format.

SourceType

The enum to identify the source used in the investigation step. This is used to determine which of the source_details fields is populated.

Enums
SOURCE_TYPE_UNSPECIFIED The source type is unspecified.
SOURCE_TYPE_EVENT The source type is event.
SOURCE_TYPE_THREAT_INTEL The source type is threat intelligence.
SOURCE_TYPE_PROCESS_TREE The source type is a process tree.
SOURCE_TYPE_COMMAND_LINE_ANALYSIS The source type is command line analysis. when Gemini uses command line tool to analyze the alert

Methods

get

 GetInvestigationStep is used to retrieve an investigation step.

list

 ListInvestigationSteps is used to retrieve existing investigation steps for a given investigation.