Method: legacy.legacySearchEnterpriseWideIoCs

Full name: projects.locations.instances.legacy.legacySearchEnterpriseWideIoCs

RPC for listing IoC matches against ingested events.

HTTP request

GET https://chronicle.googleapis.com/v1alpha/{instance}/legacy:legacySearchEnterpriseWideIoCs

Path parameters

Parameters
instance

string

Required. Chronicle instance this request is sent to. Format: projects/{project}/locations/{location}/instances/{instance}

Query parameters

Parameters
timestampRange

object (Interval)

Required. Time range [start, end) in which matched to be queried. UI/FE is expected to pass in NOW as end.
maxMatchesToReturn

integer

Required. How many matches to return, maximum. All matches will be sorted by default by most recently seen IoC ingestion time OR first seen in enterprise time and the most recent items returned as shown in the mocks. If we need to support other sorting schemes, we can add another field later.
addMandiantAttributes

boolean

Required. Indicates if mandiant attributes should be added to the ioc response.

Union parameter id.

id can be only one of the following:
entityId

string

ID of the entity.
fieldAndValue

object (FieldAndValue)

Field path or type with value to identify entity.

Request body

The request body must be empty.

Response body

Response containing matched IoCs NEXT TAG: 3

If successful, the response body contains data with the following structure:

JSON representation 
{
  "matches": [
    {
      object (IoCDiscoveryInfo)
    }
  ],
  "more_data_available": boolean
}
Fields
matches[]

object (IoCDiscoveryInfo)

IoC Matches returned for the query.
more_data_available

boolean

Indicates that more data was available but not sent due to more hits than max_matches_to_return.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the instance resource:

  • chronicle.legacies.legacySearchEnterpriseWideIoCs

For more information, see the IAM documentation.

IoCDiscoveryInfo

Information about an IoC match. NEXT TAG: 31

JSON representation 
{
  "artifact_indicator": {
    object (ArtifactIndicator)
  },
  "id": string,
  "sources": [
    string
  ],
  "categories": [
    string
  ],
  "confidence_score": integer,
  "confidence_bucket": string,
  "asset_indicators": [
    {
      object (AssetIndicator)
    }
  ],
  "empty_asset_list_reason_code": enum (EmptyAssetListReasonCode),
  "ioc_ingest_timestamp": string,
  "first_seen_timestamp": string,
  "last_seen_timestamp": string,
  "filter_properties": {
    object (FilterProperties)
  },
  "raw_severity": string,
  "ioc_state": enum (IocState),
  "priority": enum (Priority),
  "association_identifier": [
    {
      object (AssociationIdentity)
    }
  ],
  "campaigns": [
    string
  ],
  "global_source_id": string,
  "log_type": enum (LogType),
  "global_customer_id": string,
  "confidence_score_bucket": {
    object (IntRange)
  },
  "ip_and_ports": {
    object (IpAndPorts)
  },
  "categorization": string,
  "domain_and_ports": {
    object (DomainAndPorts)
  },
  "active_timerange": {
    object (Interval)
  },
  "link": {
    object (Link)
  },
  "feed_name": string,
  "description": string
}
Fields
artifact_indicator

object (ArtifactIndicator)

Artifact that was found in the customer environment.
id

string

Entity ID as a string for pivoting
sources[]

string

IoC feed sources.
categories[]

string

IoC threat categories.
confidence_score

integer

IoC confidence score. It is not a repeated field because it is used for V2 feeds, where sources and categories are restricted to a cardnality of 1 as well.
confidence_bucket

string

IoC confidence score, bucketed into e.g. low/medium/high.
asset_indicators[]

object (AssetIndicator)

We will limit the number of assets to the first N (e.g., N=20) found.
empty_asset_list_reason_code

enum (EmptyAssetListReasonCode)

When asset_indicators is empty, this field should be set.
ioc_ingest_timestamp

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".
first_seen_timestamp

string (Timestamp format)

Timestamp when the IoC was first seen in the enterprise.

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_seen_timestamp

string (Timestamp format)

Timestamp when the IoC was last seen in the enterprise.

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".
filter_properties

object (FilterProperties)

Properties of this match, used for filtering in the client.
raw_severity

string

The indicator's raw severity.
ioc_state

enum (IocState)

The current state of IoC. default state is MATCHED.
priority

enum (Priority)

The priority of the ioc match.
association_identifier[]

object (AssociationIdentity)

Associated actors and malware.
campaigns[]

string

List of campaigns this IoC was observed.
global_source_id

string

Global source ID this IoC is part of. This would only be populated if the indicator is coming from a global source.
log_type

enum (LogType)

The log type of the IoC source.
global_customer_id

string (bytes format)

Global source ID this IoC is part of. This would only be populated if the indicator is coming from a global source.

A base64-encoded string.
confidence_score_bucket

object (IntRange)

Confidence score bucket
ip_and_ports

object (IpAndPorts)

IP address indicator.
categorization

string

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

object (DomainAndPorts)

Domain indicator.
active_timerange

object (Interval)

The time range in which this indicator has been "active". The start or end time (or both) may be empty, indicating an open-ended time interval.
feed_name

string

Original feed this indicator originated from.
description

string

Raw description of the IoC.

EmptyAssetListReasonCode

Enums
UNSPECIFIED_CODE
CONTAIN_HIGH_VOLUME_ASSETS_ONLY
CALCULATION_TIME_OUT

IocState

Enums
IOC_STATE_UNSPECIFIED
STATUS_MATCHED
STATUS_REVIEWED
STATUS_MUTED

Priority

Enums
PRIORITY_UNSPECIFIED
LOW
MEDIUM
HIGH
ACTIVE_BREACH

AssociationIdentity

JSON representation 
{
  "name": string,
  "region_code": {
    object (Location)
  },
  "association_type": enum (AssociationType),
  "association_id": string
}
Fields
name

string
region_code

object (Location)
association_type

enum (AssociationType)
association_id

string