search_iocs

Instructions

Implementation Reference

• gti_mcp/tools/intelligence.py:28-69 (handler)

  The main handler function for the 'search_iocs' tool. It takes a query string, optional limit, order_by, and api_key parameters. Uses vt_client to query the '/intelligence/search' endpoint via consume_vt_iterator and returns sanitized results.

  async def search_iocs(query: str, ctx: Context, limit: int = 10, order_by: str = "last_submission_date-", api_key: str = None) -> typing.List[typing.Dict[str, typing.Any]]:
    """Search Indicators of Compromise (IOC) in the Google Threat Intelligence platform.
  
    You can search by for different IOC types using the `entity` modifier. Below, the different IOC types and the supported orders:
  
      | Entity type   | Supported orders | Default order |
      | ------------- | ---------------- | ------------- |
      | file          | first_submission_date, last_submission_date, positives, times_submitted, size	    | last_submission_date- |
      | url           | first_submission_date, last_submission_date, positives, times_submitted, status   | last_submission_date- |
      | domain        | creation_date, last_modification_date, last_update_date, positives                | last_modification_date- |
      | ip            | ip, last_modification_date, positives                                             | last_modification_date- |
  
    Note: The `entity` modifier can only be used ONCE per query.
  
    You can find all available modifers at:
      - Files: https://gtidocs.virustotal.com/docs/file-search-modifiers
      - URLs: https://gtidocs.virustotal.com/docs/url-search-modifiers
      - Domains: https://gtidocs.virustotal.com/docs/domain-search-modifiers
      - IP Addresses: https://gtidocs.virustotal.com/docs/ip-address-search-modifiers
  
    With integer modifers, use the `-` and `+` characters to indicate:
      - Greater than: `p:60+`
      - Less than: `p:60-`
      - Equal to: `p:60`
  
    Args
      query (required): Search query to find IOCs.
      limit: Limit the number of IoCs to retrieve. 10 by default.
      order_by: Order the results. "last_submission_date-" by default.
  
    Returns:
      List of Indicators of Compromise (IoCs).
    """
    async with vt_client(ctx, api_key=api_key) as client:
      res = await utils.consume_vt_iterator(
          client,
          "/intelligence/search",
          params={
              "query": query,
              "order": order_by},
          limit=limit)
    return utils.sanitize_response([o.to_dict() for o in res])

• gti_mcp/utils.py:20-26 (helper)

  The consume_vt_iterator helper used by search_iocs to iterate through VT API results up to a given limit.

  async def consume_vt_iterator(
      vt_client: vt.Client, endpoint: str, params: dict | None = None, limit: int = 10):
    """Consumes a vt.Iterator iterator and return the list of objects."""
    res = []
    async for obj in vt_client.iterator(endpoint, params=params, limit=limit):
      res.append(obj)
    return res

• gti_mcp/utils.py:119-138 (helper)

  The sanitize_response helper used by search_iocs to remove empty dicts/lists from the final response.

  def sanitize_response(data: typing.Any) -> typing.Any:
    """Removes empty dictionaries and lists recursively from a response."""
    if isinstance(data, dict):
      sanitized_dict = {}
      for key, value in data.items():
        sanitized_value = sanitize_response(value)
        if sanitized_value is not None:
          sanitized_dict[key] = sanitized_value
      return sanitized_dict
    elif isinstance(data, list):
      sanitized_list = []
      for item in data:
        sanitized_item = sanitize_response(item)
        if sanitized_item is not None:
          sanitized_list.append(sanitized_item)
      return sanitized_list
    elif isinstance(data, str):
      return data if data else None
    else:
      return data

• gti_mcp/server.py:67-70 (registration)

  The FastMCP server initialization (line 67-70) and wildcard import of tools (line 73) that registers search_iocs as a tool via the @server.tool() decorator.

  server = FastMCP(
      "Google Threat Intelligence MCP server",
      dependencies=["vt-py"],
      stateless_http=stateless)

• gti_mcp/tools/__init__.py:14-19 (registration)

  The __init__.py re-exports all tools from intelligence.py, making search_iocs available through the wildcard import in server.py.

  from .collections import *
  from .files import *
  from .intelligence import *
  from .netloc import *
  from .threat_profiles import *
  from .urls import *