REST Resource: projects.locations.instances.iocs

Resource: Ioc

Represents an Ioc (Indicator of Compromise) which is flagged as suscpicious by customer's security infrastructure or by IoC partners of Google. Each Ioc comes from a single source feed so there can be multiple Iocs with same Ioc value.

JSON representation 
{
  "name": string,
  "categorization": string,
  "description": string,
  "sourceFeed": string,
  "iocType": enum (IocType),
  "logType": string,
  "artifactIndicator": {
    object (IocArtifactIndicator)
  },
  "priority": enum (Priority),
  "displayName": string,
  "iocIngestionTime": string,
  "discoveryTime": string,
  "lastUpdateTime": string,
  "associations": [
    {
      object (IocAssociation)
    }
  ],
  "verdictInfo": [
    {
      object (IocVerdictInfo)
    }
  ],
  "globalCustomerId": string,
  "confidenceScore": string,
  "confidenceBucket": enum (ConfidenceBucket),
  "rawSeverity": string,
  "campaigns": [
    string
  ],
  "gtiThreatScore": integer
}
Fields
name

string

Identifier. The resource name of this IndicatorOfCompromise (Ioc).
categorization

string

The category/type of this indicator. Ex: "Spyware", "Bitcoin_Related", etc.
description

string

Raw description of the IoC.
sourceFeed

string

Original Feed name from where the indicator originated.
iocType

enum (IocType)

Immutable. Different types of IOCs.
logType

string

Ioc LogType. Format: projects/{project}/locations/{location}/instances/{instance}/logTypes/{logType}
artifactIndicator

object (IocArtifactIndicator)

Optional. An indicator to an artifact. An artifact is an identifier like a website domain, file hash, or IP address that is used to identify a malicious website, file, or computer system that might be contacted or used by a device in customer's environment.
priority

enum (Priority)

Optional. Priority of an IoC. Priority is determined from GCTI rules based on the indicator and ingested event.
displayName

string

Immutable. Value of an IOC which can be either a domain, ip address or file hash (MD5, SHA1, SHA256).
iocIngestionTime

string (Timestamp format)

Timestamp when the IoC was first received from ANY feed. This is the earliest timestamp of receipt by Malachite, given that the artifact might have been sent in multiple feeds at different times.

Uses RFC 3339, where generated output will always be Z-normalized and uses 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".
discoveryTime

string (Timestamp format)

First time the ioc was discovered by provider

Uses RFC 3339, where generated output will always be Z-normalized and uses 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".
lastUpdateTime

string (Timestamp format)

Last time the IoC was seen by mandiant

Uses RFC 3339, where generated output will always be Z-normalized and uses 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".
associations[]

object (IocAssociation)

Associations represents different metadata about malware and threat actors involved with an IoC.
verdictInfo[]

object (IocVerdictInfo)

Verdict information about the IoC from the provider. Describes the threat verdict provided by human analysts and machine learning models.
globalCustomerId

string (bytes format)

Optional. Global customer id of an IOC

A base64-encoded string.
confidenceScore

string

IoC confidence score. Raw confidence level from the IoC source, higher score means more confidence. If there is no confidence score in the raw data, this will not be set.
confidenceBucket

enum (ConfidenceBucket)

IoC confidence score, bucketed into e.g. low/medium/high.
rawSeverity

string

The indicator's raw severity.
campaigns[]

string

List of campaigns this IoC was observed.
gtiThreatScore

integer

Output only. Google Threat Intelligence threat score of the IoC.

IocType

Different Types of IoCs currently supported.

Enums
IOC_TYPE_UNSPECIFIED Ioc type is unspecified
DOMAIN Ioc Type is Domain
IP Ioc Type is IP
FILE_HASH Ioc Type is FILE_HASH
URL Ioc Type is URL
USER_EMAIL Ioc Type is USER_EMAIL
MUTEX Ioc Type is MUTEX
FILE_HASH_MD5 Ioc Type is FILE_HASH_MD5
FILE_HASH_SHA1 Ioc Type is FILE_HASH_SHA1
FILE_HASH_SHA256 Ioc Type is FILE_HASH_SHA256
IOC_TYPE_RESOURCE Ioc Type is RESOURCE

IocArtifactIndicator

An indicator to identify an artifact. Artifact indicator can be one of domain name, destination ip address, md5 hash, sha1 hash, or sha256 hash.

JSON representation 
{

  // Union field artifact can be only one of the following:
  "domain": string,
  "destinationIpAddress": string,
  "hashMd5": string,
  "hashSha1": string,
  "hashSha256": string,
  "url": string
  // End of list of possible types for union field artifact.
}
Fields
Union field artifact. An artifact. artifact can be only one of the following:
domain

string

A domain name.
destinationIpAddress

string

A destination ip address.
hashMd5

string

A MD5 file hash.
hashSha1

string

A SHA1 file hash.
hashSha256

string

A SHA256 file hash.
url

string

A URL.

Priority

Priority of an IoC

Enums
PRIORITY_UNSPECIFIED The default value of the priority
LOW Low Priority Ioc match
MEDIUM Medium Priority Ioc match
HIGH High Priority Ioc match
ACTIVE_BREACH Ioc match priority is ACTIVE BREACH

IocVerdictInfo

Describes the threat verdict provided by human analysts and machine learning models. These fields are used to model Mandiant sources.

JSON representation 
{
  "sourceCount": integer,
  "responseCount": integer,
  "neighbourInfluence": string,
  "verdictType": enum (VerdictType),
  "sourceProvider": string,
  "benignCount": integer,
  "maliciousCount": integer,
  "confidenceScore": integer,
  "iocStats": [
    {
      object (IocStats)
    }
  ],
  "verdictTime": string,
  "verdictResponse": enum (VerdictResponse),
  "globalCustomerCount": integer,
  "globalHitsCount": integer,
  "pwn": boolean,
  "categoryDetails": string,
  "pwnFirstTaggedTime": string
}
Fields
sourceCount

integer

Number of sources from which intel was extracted.
responseCount

integer

Total response count across all sources.
neighbourInfluence

string

Describes the near neighbor influence of the verdict.
verdictType

enum (VerdictType)

Type of verdict.
sourceProvider

string

Source provider giving the machine learning verdict.
benignCount

integer

Count of responses where this IoC was marked as benign.
maliciousCount

integer

Count of responses where this IoC was marked as malicious.
confidenceScore

integer

Confidence score of the verdict. Range of Confidence Score is 0-100.
iocStats[]

object (IocStats)

List of IocStats from which the verdict was generated.
verdictTime

string (Timestamp format)

Timestamp when the verdict was generated.

Uses RFC 3339, where generated output will always be Z-normalized and uses 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".
verdictResponse

enum (VerdictResponse)

Details about the verdict.
globalCustomerCount

integer

Global customer count over the last 30 days
globalHitsCount

integer

Global hit count over the last 30 days.
pwn

boolean

Whether one or more Mandiant incident response customers had this indicator in their environment.
categoryDetails

string

Tags related to the verdict.
pwnFirstTaggedTime

string (Timestamp format)

The timestamp of the first time a pwn was associated to this entity.

Uses RFC 3339, where generated output will always be Z-normalized and uses 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".

VerdictType

Category of the verdict.

Enums
VERDICT_TYPE_UNSPECIFIED Verdict category not specified.
PROVIDER_ML_VERDICT MLVerdict result provided from threat providers, like Mandiant. These fields are used to model Mandiant sources.
ANALYST_VERDICT Verdict provided by the human analyst. These fields are used to model Mandiant sources.

IocStats

Information about the threat intel source. These fields are used to model Mandiant sources.

JSON representation 
{
  "iocStatsType": enum (IocStatsType),
  "firstLevelSource": string,
  "secondLevelSource": string,
  "benignCount": integer,
  "quality": enum (ProductConfidence),
  "maliciousCount": integer,
  "responseCount": integer,
  "sourceCount": integer
}
Fields
iocStatsType

enum (IocStatsType)

Describes the source of the IoCStat.
firstLevelSource

string

Name of first level IoC source, for example Mandiant or a third-party.
secondLevelSource

string

Name of the second-level IoC source, for example Crowdsourced Threat Analysis or Knowledge Graph.
benignCount

integer

Count of responses where the IoC was identified as benign.
quality

enum (ProductConfidence)

Level of confidence in the IoC mapping extracted from the source.
maliciousCount

integer

Count of responses where the IoC was identified as malicious.
responseCount

integer

Total number of response from the source.
sourceCount

integer

Number of sources from which information was extracted.

IocStatsType

Type of IoCStat based on source.

Enums
UNSPECIFIED_IOC_STATS_TYPE IoCStat source is unidentified.
MANDIANT_SOURCES IoCStat is from a Mandiant Source.
THIRD_PARTY_SOURCES IoCStat is from a third-party source.
THREAT_INTELLIGENCE_IOC_STATS IoCStat is from a threat intelligence feed.

ProductConfidence

A level of confidence in the result.

Enums
PRODUCT_CONFIDENCE_UNSPECIFIED The default confidence level.
LOW_CONFIDENCE Low confidence.
MEDIUM_CONFIDENCE Medium confidence.
HIGH_CONFIDENCE High confidence.

VerdictResponse

Represents different verdict types. Used to represent Mandiant threat intelligence.

Enums
VERDICT_RESPONSE_UNSPECIFIED The default verdict response type.
MALICIOUS VerdictResponse resulted a threat as malicious.
BENIGN VerdictResponse resulted a threat as benign.

ConfidenceBucket

An indicator for locating one or multiple assets with matching property. The indicator can be hostname, ip address or mac address.

Enums
CONFIDENCE_BUCKET_UNSPECIFIED Confidence score not specified
LOW_CONFIDENCE Confidence score is low
MEDIUM_CONFIDENCE Confidence score is medium
HIGH_CONFIDENCE Confidence score is high

Methods

batchGet

 Gets a batch (list) of iocs given a list of names and a parent.

findFirstAndLastSeen

 FindFirstAndLastSeen for an Ioc.

get

 Get an Ioc.

getIocState

 Gets the status of an ioc

searchCuratedDetectionsForIoc

 Search curated detections for an Ioc.

updateIocState

 Update an Ioc state.