Console
    Start free

    MCP Tools Reference: chronicle.googleapis.com

    Tool: get_ioc_match

    Get Indicators of Compromise (IoCs) matches from Chronicle SIEM.

    Retrieves IoCs (e.g., malicious IPs, domains, hashes) from configured threat intelligence feeds that have been observed matching events in Chronicle logs within the specified time window.

    Agent Responsibilities:1. Time Range Calculation:The agent MUST provide the start_time and end_time arguments as ISO 8601 formatted strings (e.g., YYYY-MM-DDTHH:MM:SSZ) to define the search window. 2. Response Parsing:The agent must parse the raw JSON response to extract details from the 'matches' list. Each item in the list represents an IoCDiscoveryInfo object. 3. Data Extraction:From each match, extract relevant fields like 'artifactIndicator', 'sources', 'firstSeenTimestamp', 'lastSeenTimestamp'. 4. Output Formatting:Format the extracted details into a human-readable summary.

    Workflow Integration:- Use this to proactively identify potential threats based on IoC matches within SIEM data, potentially before specific detection rules trigger or cases are created in other systems. - Can provide early warning signs or context during investigations initiated from alerts or intelligence originating from any connected security tool (SIEM, EDR, TI platforms, etc.). - Complements rule-based alerts by showing matches against known bad indicators from threat intelligence feeds integrated with the SIEM.

    Use Cases:- Monitor for recent sightings of known malicious indicators within SIEM logs. - Identify assets that may have interacted with known bad infrastructure or files, based on log evidence. - Supplement investigations by checking if involved entities match known IoCs curated by threat intelligence sources.

    Args: project_id (Optional[str]): Google Cloud project ID. customer_id (Optional[str]): Chronicle customer ID. start_time (str): The start of the time range in ISO 8601 format (e.g., YYYY-MM-DDTHH:MM:SSZ). end_time (str): The end of the time range in ISO 8601 format (e.g., YYYY-MM-DDTHH:MM:SSZ). max_matches (int): Maximum number of IoC matches to return. Defaults to 20. region (Optional[str]): Chronicle region (e.g., "us", "europe").

    Returns: str: The raw JSON response from the API (LegacySearchEnterpriseWideIoCsResponse). The agent is responsible for parsing this and generating the user-facing summary. Returns an error message if retrieval fails.

    Next Steps (using MCP-enabled tools): - Investigate the assets or events associated with the matched IoCs using udm_search . - Use entity lookup tools to get broader context on the matched IoC value (IP, domain, hash). - Use SIEM event search tools to find the specific events in logs that triggered the IoC match. - Check if related cases exist in your case management/SOAR system or create one if the match indicates a significant threat. - Correlate IoC match details with findings from other security tools (EDR, Network, Cloud) via their MCP tools.

    The following sample demonstrate how to use curl to invoke the get_ioc_match MCP tool.

    Curl Request 
      
curl  
--location  
 'https://chronicle.googleapis.com/mcp' 
  
 \ 
--header  
 'content-type: application/json' 
  
 \ 
--header  
 'accept: application/json, text/event-stream' 
  
 \ 
--data  
 '{ 
 "method": "tools/call", 
 "params": { 
 "name": "get_ioc_match", 
 "arguments": { 
 // provide these details according to the tool' 
s  
MCP  
specification  
 } 
  
 } 
,  
 "jsonrpc" 
:  
 "2.0" 
,  
 "id" 
:  
 1 
 } 
 '

    Input Schema

    Request message for GetIocMatch.

    GetIocMatchRequest

    JSON representation 
     { 
 "projectId" 
 : 
 string 
 , 
 "customerId" 
 : 
 string 
 , 
 "region" 
 : 
 string 
 , 
 "startTime" 
 : 
 string 
 , 
 "endTime" 
 : 
 string 
 , 
 "maxMatches" 
 : 
 integer 
 }
    Fields
    projectId

    string

    Project ID of the customer.
    customerId

    string

    Customer ID of the customer.
    region

    string

    Region of the customer.
    startTime

    string

    Start time of the time range to search for IoC matches.
    endTime

    string

    End time of the time range to search for IoC matches.
    maxMatches

    integer

    Maximum number of matches to return. If not set, the default value is 20.

    Output Schema

    Response containing matched IoCs NEXT TAG: 3

    LegacySearchEnterpriseWideIoCsResponse

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

    object ( IoCDiscoveryInfo )

    IoC Matches returned for the query.
    moreDataAvailable

    boolean

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

    IoCDiscoveryInfo

    JSON representation 
     { 
 "artifactIndicator" 
 : 
 { 
 object (  ArtifactIndicator 
 
) 
 } 
 , 
 "id" 
 : 
 string 
 , 
 "fieldAndValue" 
 : 
 { 
 object (  FieldAndValue 
 
) 
 } 
 , 
 "sources" 
 : 
 [ 
 string 
 ] 
 , 
 "categories" 
 : 
 [ 
 string 
 ] 
 , 
 "confidenceScore" 
 : 
 integer 
 , 
 "confidenceBucket" 
 : 
 string 
 , 
 "assetIndicators" 
 : 
 [ 
 { 
 object (  AssetIndicator 
 
) 
 } 
 ] 
 , 
 "emptyAssetListReasonCode" 
 : 
 enum ( EmptyAssetListReasonCode 
) 
 , 
 "iocIngestTimestamp" 
 : 
 string 
 , 
 "firstSeenTimestamp" 
 : 
 string 
 , 
 "lastSeenTimestamp" 
 : 
 string 
 , 
 "filterProperties" 
 : 
 { 
 object (  FilterProperties 
 
) 
 } 
 , 
 "rawSeverity" 
 : 
 string 
 , 
 "iocState" 
 : 
 enum ( IocState 
) 
 , 
 "priority" 
 : 
 enum ( Priority 
) 
 , 
 "associationIdentifier" 
 : 
 [ 
 { 
 object (  AssociationIdentity 
 
) 
 } 
 ] 
 , 
 "campaigns" 
 : 
 [ 
 string 
 ] 
 , 
 "globalSourceId" 
 : 
 string 
 , 
 "logType" 
 : 
 enum ( LogType 
) 
 , 
 "globalCustomerId" 
 : 
 string 
 , 
 "confidenceScoreBucket" 
 : 
 { 
 object (  IntRange 
 
) 
 } 
 , 
 "ipAndPorts" 
 : 
 { 
 object (  IpAndPorts 
 
) 
 } 
 , 
 "categorization" 
 : 
 string 
 , 
 "domainAndPorts" 
 : 
 { 
 object (  DomainAndPorts 
 
) 
 } 
 , 
 "activeTimerange" 
 : 
 { 
 object (  Interval 
 
) 
 } 
 , 
 "link" 
 : 
 { 
 object (  Link 
 
) 
 } 
 , 
 "feedName" 
 : 
 string 
 , 
 "description" 
 : 
 string 
 , 
 "threatCollectionItems" 
 : 
 [ 
 { 
 object (  ThreatCollectionItem 
 
) 
 } 
 ] 
 }
    Fields
    artifactIndicator

    object ( ArtifactIndicator )

    Artifact that was found in the customer environment.
    id

    string

    Entity ID as a string for pivoting
    fieldAndValue

    object ( FieldAndValue )

    Field path or type with value to identify entity.
    sources[]

    string

    IoC feed sources.
    categories[]

    string

    IoC threat categories.
    confidenceScore

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

    string

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

    object ( AssetIndicator )

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

    enum ( EmptyAssetListReasonCode )

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

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

    string ( Timestamp format)

    Timestamp when the IoC was first seen in the enterprise.

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

    string ( Timestamp format)

    Timestamp when the IoC was last seen in the enterprise.

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

    object ( FilterProperties )

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

    string

    The indicator's raw severity.
    iocState

    enum ( IocState )

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

    enum ( Priority )

    The priority of the ioc match.
    associationIdentifier[]

    object ( AssociationIdentity )

    Associated actors and malware.
    campaigns[]

    string

    List of campaigns this IoC was observed.
    globalSourceId

    string

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

    enum ( LogType )

    The log type of the IoC source.
    globalCustomerId

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

    object ( IntRange )

    Confidence score bucket
    ipAndPorts

    object ( IpAndPorts )

    IP address indicator.
    categorization

    string

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

    object ( DomainAndPorts )

    Domain indicator.
    activeTimerange

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

    object ( Link )

    optional. This will usually be a link to the Feed's definition.
    feedName

    string

    Original feed this indicator originated from.
    description

    string

    Raw description of the IoC.
    threatCollectionItems[]

    object ( ThreatCollectionItem )

    Reference to the threat collection items linked to this IOC match.

    ArtifactIndicator

    JSON representation 
     { 
 // Union field artifact 
can be only one of the following: 
 "domain" 
 : 
 string 
 , 
 "destinationIpAddress" 
 : 
 string 
 , 
 "hashMd5" 
 : 
 string 
 , 
 "hashSha1" 
 : 
 string 
 , 
 "hashSha256" 
 : 
 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.

    FieldAndValue

    JSON representation 
     { 
 "value" 
 : 
 string 
 , 
 "entityNamespace" 
 : 
 string 
 , 
 // Union field type 
can be only one of the following: 
 "fieldPath" 
 : 
 string 
 , 
 "valueType" 
 : 
 enum ( ValueType 
) 
 // End of list of possible types for union field type 
. 
 }
    Fields
    value

    string

    Required. Indicator value that is used to identify or find the entity.

    entityNamespace

    string

    Optional. Entity namespace. Namespace is only applicable to asset entities.

    Union field type .

    type can be only one of the following:

    fieldPath

    string

    A UDM field path which identifies the type of the indicator to be used to find the entity. This path is not used exclusively to "search" for the entity, but rather to identify the type of indicator, which can be inferred from the path.

    valueType

    enum ( ValueType )

    An explicit type of the indicator to be used to find the entity.

    AssetIndicator

    JSON representation 
     { 
 "namespace" 
 : 
 string 
 , 
 "isAnyNamespace" 
 : 
 boolean 
 , 
 "filterNamespace" 
 : 
 boolean 
 , 
 // Union field indicator 
can be only one of the following: 
 "hostname" 
 : 
 string 
 , 
 "assetIpAddress" 
 : 
 string 
 , 
 "mac" 
 : 
 string 
 , 
 "productId" 
 : 
 string 
 // End of list of possible types for union field indicator 
. 
 }
    Fields
    namespace

    string

    The namespace of this asset indicator belongs to. If 'is_any_namespace' is set to true, this field will be ignored.

    isAnyNamespace

    boolean

    False when 'namespace' refers to a valid namespace name related to the asset (both empty and non empty strings are valid namespace name values). True when the asset refers to one or more assets with the given 'indicator' across all namespaces.

    filterNamespace

    boolean

    This field provides clients the option to enable namespace search or not. By default, this field is false and namespace will be ignored.

    Union field indicator . An identifier representing an asset. indicator can be only one of the following:
    hostname

    string

    Hostname of a device or machine.

    assetIpAddress

    string

    IP address of a device or machine.

    mac

    string

    Mac address of a device or machine.

    productId

    string

    The 'product_id' field includes a a product ID type and product ID value, e.g. "CS:1234-5678".

    Timestamp

    JSON representation 
     { 
 "seconds" 
 : 
 string 
 , 
 "nanos" 
 : 
 integer 
 }
    Fields
    seconds

    string ( int64 format)

    Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be between -62135596800 and 253402300799 inclusive (which corresponds to 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z).
    nanos

    integer

    Non-negative fractions of a second at nanosecond resolution. This field is the nanosecond portion of the duration, not an alternative to seconds. Negative second values with fractions must still have non-negative nanos values that count forward in time. Must be between 0 and 999,999,999 inclusive.

    FilterProperties

    JSON representation 
     { 
 "stringProperties" 
 : 
 { 
 string 
 : 
 { 
 object (  StringValues 
 
) 
 } 
 , 
 ... 
 } 
 , 
 "hidden" 
 : 
 boolean 
 }
    Fields
    stringProperties

    map (key: string, value: object ( StringValues ))

    An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" } .
    hidden

    boolean

    StringPropertiesEntry

    JSON representation 
     { 
 "key" 
 : 
 string 
 , 
 "value" 
 : 
 { 
 object (  StringValues 
 
) 
 } 
 }
    Fields
    key

    string

    value

    object ( StringValues )

    StringValues

    JSON representation 
     { 
 "values" 
 : 
 [ 
 { 
 object (  StringValue 
 
) 
 } 
 ] 
 }
    Fields
    values[]

    object ( StringValue )

    StringValue

    JSON representation 
     { 
 "rawValue" 
 : 
 string 
 , 
 "displayValue" 
 : 
 string 
 }
    Fields
    rawValue

    string

    displayValue

    string

    AssociationIdentity

    JSON representation 
     { 
 "name" 
 : 
 string 
 , 
 "regionCode" 
 : 
 { 
 object (  Location 
 
) 
 } 
 , 
 "associationType" 
 : 
 enum ( AssociationType 
) 
 , 
 "associationId" 
 : 
 string 
 }
    Fields
    name

    string

    regionCode

    object ( Location )

    associationType

    enum ( AssociationType )

    associationId

    string

    Location

    JSON representation 
     { 
 "city" 
 : 
 string 
 , 
 "state" 
 : 
 string 
 , 
 "countryOrRegion" 
 : 
 string 
 , 
 "name" 
 : 
 string 
 , 
 "deskName" 
 : 
 string 
 , 
 "floorName" 
 : 
 string 
 , 
 "regionLatitude" 
 : 
 number 
 , 
 "regionLongitude" 
 : 
 number 
 , 
 "regionCoordinates" 
 : 
 { 
 object (  LatLng 
 
) 
 } 
 }
    Fields
    city

    string

    The city.
    state

    string

    The state.
    countryOrRegion

    string

    The country or region.
    name

    string

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

    string

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

    string

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

    number

    Deprecated: use region_coordinates.
    regionLongitude
    (deprecated)

    number

    Deprecated: use region_coordinates.
    regionCoordinates

    object ( LatLng )

    Coordinates for the associated region. See https://cloud.google.com/vision/docs/reference/rest/v1/LatLng for a description of the fields.

    LatLng

    JSON representation 
     { 
 "latitude" 
 : 
 number 
 , 
 "longitude" 
 : 
 number 
 }
    Fields
    latitude

    number

    The latitude in degrees. It must be in the range [-90.0, +90.0].
    longitude

    number

    The longitude in degrees. It must be in the range [-180.0, +180.0].

    IntRange

    JSON representation 
     { 
 "rangeStart" 
 : 
 integer 
 , 
 "rangeEnd" 
 : 
 integer 
 }
    Fields
    rangeStart

    integer

    rangeEnd

    integer

    IpAndPorts

    JSON representation 
     { 
 "ipAddress" 
 : 
 string 
 , 
 "ports" 
 : 
 [ 
 integer 
 ] 
 }
    Fields
    ipAddress

    string ( bytes format)

    A base64-encoded string.
    ports[]

    integer ( uint32 format)

    DomainAndPorts

    JSON representation 
     { 
 "domain" 
 : 
 string 
 , 
 "ports" 
 : 
 [ 
 integer 
 ] 
 }
    Fields
    domain

    string

    ports[]

    integer ( uint32 format)

    Interval

    JSON representation 
     { 
 "startTime" 
 : 
 string 
 , 
 "endTime" 
 : 
 string 
 }
    Fields
    startTime

    string ( Timestamp format)

    Optional. Inclusive start of the interval.

    If specified, a Timestamp matching this interval will have to be the same or after the start.

    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)

    Optional. Exclusive end of the interval.

    If specified, a Timestamp matching this interval will have to be before the end.

    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" .
    JSON representation 
     { 
 "text" 
 : 
 string 
 , 
 "url" 
 : 
 string 
 }
    Fields
    text

    string

    url

    string

    ThreatCollectionItem

    JSON representation 
     { 
 "id" 
 : 
 string 
 , 
 "type" 
 : 
 enum ( ThreatCollectionType 
) 
 , 
 "altNames" 
 : 
 [ 
 string 
 ] 
 }
    Fields
    id

    string

    The ID of the threat collection.
    type

    enum ( ThreatCollectionType )

    The type of threat collection (e.g., "campaign").
    altNames[]

    string

    The name of the threat collection.

    Tool Annotations

    Destructive Hint: ❌ | Idempotent Hint: ✅ | Read Only Hint: ✅ | Open World Hint: ❌
    Create a Mobile Website
    View Site in Mobile | Classic
    Share by: