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)
    }
  ],
  "errorReason": enum (Code),

  // 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.
errorReason

enum (Code)

Optional. The error reason of the investigation, could be no error.
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,
  "attackDetails": {
    object (AttackDetails)
  }
}
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".
attackDetails

object (AttackDetails)

Optional. Output only. The MITRE ATT&CK details most closely represented by this finding.

Code

The canonical error codes for gRPC APIs.

Sometimes multiple error codes may apply. Services should return the most specific error code that applies. For example, prefer OUT_OF_RANGE over FAILED_PRECONDITION if both codes apply. Similarly prefer NOT_FOUND or ALREADY_EXISTS over FAILED_PRECONDITION.

Enums
OK

Not an error; returned on success.

HTTP Mapping: 200 OK
CANCELLED

The operation was cancelled, typically by the caller.

HTTP Mapping: 499 Client Closed Request
UNKNOWN

Unknown error. For example, this error may be returned when a Status value received from another address space belongs to an error space that is not known in this address space. Also errors raised by APIs that do not return enough error information may be converted to this error.

HTTP Mapping: 500 Internal Server Error
INVALID_ARGUMENT

The client specified an invalid argument. Note that this differs from FAILED_PRECONDITION. INVALID_ARGUMENT indicates arguments that are problematic regardless of the state of the system (e.g., a malformed file name).

HTTP Mapping: 400 Bad Request
DEADLINE_EXCEEDED

The deadline expired before the operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire.

HTTP Mapping: 504 Gateway Timeout
NOT_FOUND

Some requested entity (e.g., file or directory) was not found.

Note to server developers: if a request is denied for an entire class of users, such as gradual feature rollout or undocumented allowlist, NOT_FOUND may be used. If a request is denied for some users within a class of users, such as user-based access control, PERMISSION_DENIED must be used.

HTTP Mapping: 404 Not Found
ALREADY_EXISTS

The entity that a client attempted to create (e.g., file or directory) already exists.

HTTP Mapping: 409 Conflict
PERMISSION_DENIED

The caller does not have permission to execute the specified operation. PERMISSION_DENIED must not be used for rejections caused by exhausting some resource (use RESOURCE_EXHAUSTED instead for those errors). PERMISSION_DENIED must not be used if the caller can not be identified (use UNAUTHENTICATED instead for those errors). This error code does not imply the request is valid or the requested entity exists or satisfies other pre-conditions.

HTTP Mapping: 403 Forbidden
UNAUTHENTICATED

The request does not have valid authentication credentials for the operation.

HTTP Mapping: 401 Unauthorized
RESOURCE_EXHAUSTED

Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space.

HTTP Mapping: 429 Too Many Requests
FAILED_PRECONDITION

The operation was rejected because the system is not in a state required for the operation's execution. For example, the directory to be deleted is non-empty, an rmdir operation is applied to a non-directory, etc.

Service implementors can use the following guidelines to decide between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE: (a) Use UNAVAILABLE if the client can retry just the failing call. (b) Use ABORTED if the client should retry at a higher level. For example, when a client-specified test-and-set fails, indicating the client should restart a read-modify-write sequence. (c) Use FAILED_PRECONDITION if the client should not retry until the system state has been explicitly fixed. For example, if an "rmdir" fails because the directory is non-empty, FAILED_PRECONDITION should be returned since the client should not retry unless the files are deleted from the directory.

HTTP Mapping: 400 Bad Request
ABORTED

The operation was aborted, typically due to a concurrency issue such as a sequencer check failure or transaction abort.

See the guidelines above for deciding between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE.

HTTP Mapping: 409 Conflict
OUT_OF_RANGE

The operation was attempted past the valid range. E.g., seeking or reading past end-of-file.

Unlike INVALID_ARGUMENT, this error indicates a problem that may be fixed if the system state changes. For example, a 32-bit file system will generate INVALID_ARGUMENT if asked to read at an offset that is not in the range [0,2^32-1], but it will generate OUT_OF_RANGE if asked to read from an offset past the current file size.

There is a fair bit of overlap between FAILED_PRECONDITION and OUT_OF_RANGE. We recommend using OUT_OF_RANGE (the more specific error) when it applies so that callers who are iterating through a space can easily look for an OUT_OF_RANGE error to detect when they are done.

HTTP Mapping: 400 Bad Request
UNIMPLEMENTED

The operation is not implemented or is not supported/enabled in this service.

HTTP Mapping: 501 Not Implemented
INTERNAL

Internal errors. This means that some invariants expected by the underlying system have been broken. This error code is reserved for serious errors.

HTTP Mapping: 500 Internal Server Error
UNAVAILABLE

The service is currently unavailable. This is most likely a transient condition, which can be corrected by retrying with a backoff. Note that it is not always safe to retry non-idempotent operations.

See the guidelines above for deciding between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE.

HTTP Mapping: 503 Service Unavailable
DATA_LOSS

Unrecoverable data loss or corruption.

HTTP Mapping: 500 Internal Server Error

Methods

fetchAssociated

 FetchAssociatedInvestigations is used to fetch all the associated resources for each of the given alerts/cases.

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.