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,
  "source_feed": string,
  "ioc_type": enum (IocType),
  "log_type": string,
  "artifact_indicator": {
    object (IocArtifactIndicator)
  },
  "priority": enum (Priority),
  "display_name": string,
  "ioc_ingestion_time": string,
  "discovery_time": string,
  "last_update_time": string,
  "associations": [
    {
      object (IocAssociation)
    }
  ],
  "verdict_info": [
    {
      object (IocVerdictInfo)
    }
  ],
  "global_customer_id": string,
  "confidence_score": integer,
  "confidence_bucket": enum (ConfidenceBucket),
  "raw_severity": string,
  "campaigns": [
    string
  ]
}
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.
source_feed

string

Original Feed name from where the indicator originated.
ioc_type

enum (IocType)

Immutable. Different types of IOCs.
log_type

string

Ioc LogType. Format: projects/{project}/locations/{location}/instances/{instance}/logTypes/{log_type}
artifact_indicator

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.
display_name

string

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

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.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
discovery_time

string (Timestamp format)

First time the ioc was discovered by provider

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
last_update_time

string (Timestamp format)

Last time the IoC was seen by mandiant

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
associations[]

object (IocAssociation)

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

object (IocVerdictInfo)

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

string (bytes format)

Optional. Global customer id of an IOC

A base64-encoded string.
confidence_score

integer

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.
confidence_bucket

enum (ConfidenceBucket)

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

string

The indicator's raw severity.
campaigns[]

string

List of campaigns this IoC was observed.

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,
  "destination_ip_address": string,
  "hash_md5": string,
  "hash_sha1": string,
  "hash_sha256": 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.
destination_ip_address

string

A destination ip address.
hash_md5

string

A MD5 file hash.
hash_sha1

string

A SHA1 file hash.
hash_sha256

string

A SHA256 file hash.

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

IocAssociation

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

JSON representation 
{
  "id": string,
  "country_code": [
    string
  ],
  "region_code": {
    object (AssociationLocation)
  },
  "type": enum (AssociationType),
  "threat_display_name": string,
  "description": string,
  "alias": [
    {
      object (IocAssociationAlias)
    }
  ],
  "first_reference_time": string,
  "last_reference_time": string,
  "industries_affected": [
    string
  ],
  "associated_actors": [
    {
      object (IocAssociation)
    }
  ]
}
Fields
id

string

Output only. Unique association id generated by mandiant.
country_code[]

string

Country from which the threat actor/ malware is originated.
region_code

object (AssociationLocation)

Name of the country, the threat is originating from.
type

enum (AssociationType)

Signifies the type of association.
threat_display_name

string

Name of the threat actor/malware.
description

string

Human readable description about the association.
alias[]

object (IocAssociationAlias)

Different aliases of the threat actor given by different sources.
first_reference_time

string (Timestamp format)

First time the threat actor was referenced or seen.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
last_reference_time

string (Timestamp format)

Last time the threat actor was referenced or seen.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
industries_affected[]

string

List of industries the threat actor affects.
associated_actors[]

object (IocAssociation)

List of associated threat actors for a malware. Not applicable for threat actors.

AssociationLocation

Information about a location.

JSON representation 
{
  "city": string,
  "state": string,
  "country_or_region": string,
  "location": string,
  "desk": string,
  "floor": string,
  "region_coordinates": {
    object (LatLng)
  }
}
Fields
city

string

Output only. The city.
state

string

The state.
country_or_region

string

The country or region.
location

string

Custom location name (e.g. building or site name like "London Office"). For cloud environments, this is the region (e.g. "us-west2").
desk

string

Desk name or individual location, typically for an employee in an office. (e.g. "IN-BLR-BCPC-11-1121D").
floor

string

Floor name, number or a combination of the two for a building. (e.g. "1-A").
region_coordinates

object (LatLng)

Coordinates for the associated region.

AssociationType

Represents different possible Association types. Can be threat or malware. Used to represent Mandiant threat intelligence.

Enums
ASSOCIATION_TYPE_UNSPECIFIED The default Association Type.
THREAT_ACTOR Association type Threat actor.
MALWARE Association type Malware.

IocAssociationAlias

Association Alias Used to represent Mandiant Threat intel.

JSON representation 
{
  "association_name": string,
  "provider": string
}
Fields
association_name

string

Name of the alias.
provider

string

Name of the provider who gave the association's name.

IocVerdictInfo

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

JSON representation 
{
  "source_count": integer,
  "response_count": integer,
  "neighbour_influence": string,
  "verdict_type": enum (VerdictType),
  "source_provider": string,
  "benign_count": integer,
  "malicious_count": integer,
  "confidence_score": integer,
  "ioc_stats": [
    {
      object (IocStats)
    }
  ],
  "verdict_time": string,
  "verdict_response": enum (VerdictResponse),
  "global_customer_count": integer,
  "global_hits_count": integer,
  "pwn": boolean,
  "category_details": string,
  "pwn_first_tagged_time": string
}
Fields
source_count

integer

Number of sources from which intel was extracted.
response_count

integer

Total response count across all sources.
neighbour_influence

string

Describes the near neighbor influence of the verdict.
verdict_type

enum (VerdictType)

Type of verdict.
source_provider

string

Source provider giving the machine learning verdict.
benign_count

integer

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

integer

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

integer

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

object (IocStats)

List of IocStats from which the verdict was generated.
verdict_time

string (Timestamp format)

Timestamp when the verdict was generated.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
verdict_response

enum (VerdictResponse)

Details about the verdict.
global_customer_count

integer

Global customer count over the last 30 days
global_hits_count

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.
category_details

string

Tags related to the verdict.
pwn_first_tagged_time

string (Timestamp format)

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

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

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 
{
  "ioc_stats_type": enum (IocStatsType),
  "first_level_source": string,
  "second_level_source": string,
  "benign_count": integer,
  "quality": enum (ProductConfidence),
  "malicious_count": integer,
  "response_count": integer,
  "source_count": integer
}
Fields
ioc_stats_type

enum (IocStatsType)

Describes the source of the IoCStat.
first_level_source

string

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

string

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

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.
malicious_count

integer

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

integer

Total number of response from the source.
source_count

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.