REST Resource: projects.locations.instances.cases.caseEvidenceDatas

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 (DataType),
  "sources": [
    {
      object (CaseEvidence)
    }
  ],

  // Union field data can be only one of the following:
  "threatHunt": {
    object (ThreatHunt)
  },
  "detection": {
    object (Collection)
  },
  "alert": {
    object (Collection)
  },
  "event": {
    object (UDM)
  }
  // End of list of possible types for union field data.
}
Fields
name

string

Output only. Identifier. The unique resource name of the CaseEvidenceData. Format: projects/{project}/locations/{location}/instances/{instance}/cases/{case}/ caseEvidenceDatas/{evidence_data}
caseEvidenceDataId

string

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

enum (DataType)

Output only. The category of data stored in this resource. This matches the oneof that reports the data payload.
sources[]

object (CaseEvidence)

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

object (ThreatHunt)

Output only. Detailed findings and investigation steps from a threat hunt.
detection

object (Collection)

Output only. An associated non-alerting detection.
alert

object (Collection)

Output only. An associated alerting detection.
event

object (UDM)

Output only. An associated event.

ThreatHunt

A single execution instance of a threat hunt.

JSON representation 
{
  "subjects": [
    {
      object (HuntSubject)
    }
  ],
  "state": enum (HuntState),
  "interval": {
    object (Interval)
  },
  "createTime": string,
  "completeTime": string,
  "updateTime": string,
  "steps": [
    {
      object (ThreatHuntStep)
    }
  ],

  // Union field result_options can be only one of the following:
  "result": {
    object (SuccessResult)
  },
  "error": {
    object (Status)
  }
  // End of list of possible types for union field result_options.
}
Fields
subjects[]

object (HuntSubject)

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

enum (HuntState)

Output only. The current state of the hunt.
interval

object (Interval)

Required. The time range over which the hunt was run.
createTime

string (Timestamp format)

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

string (Timestamp format)

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

object (ThreatHuntStep)

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

object (SuccessResult)

Output only. Set if the hunt completed successfully.
error

object (Status)

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 (Determination),
  "reasoning": string
}
Fields
score

number

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

enum (Determination)

Output only. High-level determination.
reasoning

string

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 subject can be only one of the following:
  "campaign": {
    object (ThreatCollection)
  },
  "actor": {
    object (IocAssociation)
  },
  "malware": {
    object (IocAssociation)
  },
  "technique": {
    object (Technique)
  },
  "tool": {
    object (Software)
  }
  // End of list of possible types for union field subject.
}
Fields
Union field subject. The resource that the hunt centers on. subject can be only one of the following:
campaign

object (ThreatCollection)

A GTI campaign.
actor

object (IocAssociation)

A GTI threat actor.
malware

object (IocAssociation)

A GTI malware family.
technique

object (Technique)

A MITRE ATT&CK Technique.
tool

object (Software)

A software tool.

HuntState

Enum for the state of a ThreatHunt. New values may be added in the future.

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.
HUNT_STATE_QUEUED Hunt is queued.

ThreatHuntStep

Represents an individual step taken within a ThreatHunt.

JSON representation 
{
  "task": string,
  "startTime": string,
  "endTime": string,
  "stepNumber": integer,

  // Union field step_details can be only one of the following:
  "searchQuery": {
    object (ThreatHuntSearchQuery)
  },
  "threatIntelligence": {
    object (Ioc)
  }
  // End of list of possible types for union field step_details.
}
Fields
task

string

Output only. The hypothesis being investigated in this specific step.
startTime

string (Timestamp format)

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

string (Timestamp format)

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

integer

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

object (ThreatHuntSearchQuery)

Output only. Details of the search query that the agent ran and its results.
threatIntelligence

object (Ioc)

Output only. Details of threat intelligence analyzed in this step.

ThreatHuntSearchQuery

Details of the execution of a search query within a hunt step.

JSON representation 
{
  "query": string,
  "summary": string,
  "events": [
    string
  ],
  "interval": {
    object (Interval)
  },
  "totalRetrievedEventsCount": integer,
  "limitReached": boolean
}
Fields
query

string

Output only. The UDM search query executed.
summary

string

Output only. Summary of the evidence found in this step.
events[]

string

Output only. Resource names of the events that were returned by the query.
interval

object (Interval)

Output only. The time range over which the search query was run.
totalRetrievedEventsCount

integer

Output only. Total count of UDM events retrieved by the search query prior to relevance filtering.
limitReached

boolean

Output only. Indicates if search results reached maximum query limit.

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.

Methods

get

 Gets a case evidence data for a given case.

list

 Lists the case evidence data for a given case.