REST Resource: projects.locations.instances.investigations

Resource: Investigation

An Investigation is a resource that captures analysis details of a particular threat or incident. It includes a final disposition (e.g., true positive, false positive), confidence score, recommended next steps, and a list of InvestigationStep items (timeline events). Investigation is optionally linked to an Alert via alerts.ids.

JSON representation 
{
  "name": string,
  "displayName": string,
  "verdict": enum (Verdict),
  "confidenceScore": number,
  "recommendedNextSteps": [
    string
  ],
  "summary": string,
  "status": enum (InvestigationStatus),
  "timeRange": {
    object (Interval)
  },
  "notebook": string,
  "severity": enum (ProductSeverity),
  "confidence": enum (ProductConfidence),
  "nextSteps": [
    {
      object (InvestigationNextStep)
    }
  ],
  "triggerType": enum (InvestigationTriggerType),
  "experimental": boolean,
  "publishTime": string,
  "updateTime": string,
  "findings": [
    {
      object (Finding)
    }
  ],
  "associations": [
    {
      object (Association)
    }
  ],
  "investigationSteps": [
    {
      object (InvestigationStep)
    }
  ],
  "entities": [
    {
      object (Entity)
    }
  ],

  // Union field subjects can be only one of the following:
  "alerts": {
    object (AssociatedSubjects)
  },
  "cases": {
    object (AssociatedSubjects)
  }
  // End of list of possible types for union field subjects.
}
Fields
name

string

Output only. Identifier. The full resource name of the investigation. Format: projects/{project}/locations/{location}/instances/{instance}/investigations/{investigation}
displayName

string

Required. The user-facing label for the investigation.
verdict

enum (Verdict)

Optional. The final disposition of the investigation.
confidenceScore

number

Optional. The confidence score of the investigation in the range [1..100].
recommendedNextSteps[]
(deprecated)

string

Optional. Recommended next steps, if any. This is a list of strings that can be displayed to the user. Use nextSteps instead.
summary

string

Optional. A short summary or analysis result for this investigation.
status

enum (InvestigationStatus)

Optional. The current status of the investigation.
timeRange

object (Interval)

Output only. The time range of the investigation.
notebook

string

Output only. The resource name of notebook associated with the investigation. Format: projects/{project}/locations/{location}/instances/{instance}/notebooks/{notebook}
severity

enum (ProductSeverity)

The severity of the investigation.
confidence

enum (ProductConfidence)

The level of confidence in the investigation.
nextSteps[]

object (InvestigationNextStep)

Output only. Recommended next steps, if any. This is a list of strings that can be displayed to the user.
triggerType

enum (InvestigationTriggerType)

Output only. The trigger type of the investigation. Not required for manual investigations.
experimental

boolean

Output only. Whether the investigation is experimental.
publishTime

string (Timestamp format)

Output only. Time when investigation was published.

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: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
updateTime

string (Timestamp format)

Output only. Time when investigation 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: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
findings[]

object (Finding)

Output only. Detailed findings from the investigation. An investigation can have multiple findings.
associations[]

object (Association)

Output only. Associations represents different metadata about malware and threat actors associated with an Investigation.
investigationSteps[]

object (InvestigationStep)

Output only. Investigation steps taken by gemini during the investigation.
entities[]

object (Entity)

Output only. A list of network entities associated with the investigation.
Union field subjects. The subjects of the investigation, starting with alerts and cases. subjects can be only one of the following:
alerts

object (AssociatedSubjects)

The list of alerts associated with the investigation.
cases

object (AssociatedSubjects)

The list of cases associated with the investigation.

AssociatedSubjects

AssociatedSubjects is a wrapper for a list of ids.

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

string

Output only. IDs of associated subjects.

Verdict

The final disposition assigned by the agent.

Enums
VERDICT_UNSPECIFIED An unspecified verdict.
TRUE_POSITIVE A categorization of the finding as a "true positive".
FALSE_POSITIVE A categorization of the finding as a "false positive".

InvestigationStatus

Enums
STATUS_UNSPECIFIED The status of the investigation is unspecified.
STATUS_NOT_STARTED The investigation has not started.
STATUS_IN_PROGRESS The investigation is in progress.
STATUS_COMPLETED_SUCCESS The investigation has been completed successfully.
STATUS_COMPLETED_ERROR The investigation has been completed with an error.
STATUS_PENDING The investigation is in pending state.

InvestigationNextStep

InvestigationNextStep contains the recommended next steps for an investigation.

JSON representation 
{
  "title": string,
  "type": enum (Type)
}
Fields
title

string

Output only. The recommended next steps for the investigation.
type

enum (Type)

Output only. The type of the recommended next steps.

Type

The type of the recommended next steps.

Enums
TYPE_UNSPECIFIED The next step type is unknown.
SEARCHABLE The next step type is searchable.
MANUAL The next step type is manual.

InvestigationTriggerType

The trigger type of the investigation.

Enums
INVESTIGATION_TRIGGER_TYPE_UNSPECIFIED The trigger type is unknown.
AGENT_MANUAL The trigger type is agent manual.
AGENT_AUTO The trigger type is agent auto.
MTD_ALERT The trigger type is MTD alert.
MTD_HUNT The trigger type is MTD hunt.

Finding

Findings from the investigation.

JSON representation 
{
  "narrative": string,
  "secopsQueryUri": string,
  "events": [
    string
  ],
  "eventTime": string
}
Fields
narrative

string

Output only. A detailed analysis summary provided by the Mandiant Analyst.
secopsQueryUri

string

Output only. The URI path to the SecOps search page for the events. For example: /search?query=(metadata.id%20%3D%20b%22AAAAABZyPaaD2gq3NK6kPEZBWmEAAAAABgAAAAAAAAA%3D%22)
events[]

string

Output only. The UDM events associated with the findings. Example: events: ["projects/123/locations/us/instances/c17c06a4-7a45-4b1d-aaa9-d8bd5c6cb331/events/event1", "projects/123/locations/us/instances/c17c06a4-7a45-4b1d-aaa9-d8bd5c6cb331/events/event2"]
eventTime

string (Timestamp format)

The timestamp of the first event found in the finding.

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: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".

Methods

get

 GetInvestigation is used to retrieve an investigation.

list

 ListInvestigations is used to retrieve existing investigations for a given instance.

trigger

 Custom method to manually trigger an investigation for a given alert.