get_entities_related_to_a_domain

Instructions

Implementation Reference

• gti_mcp/tools/netloc.py:111-174 (handler)

  Handler function for the 'get_entities_related_to_a_domain' tool. Retrieves entities related to a domain via VirusTotal API relationships. Validates relationship_name against DOMAIN_RELATIONSHIPS, then calls utils.fetch_object_relationships and sanitizes the response.

  @server.tool()
  async def get_entities_related_to_a_domain(
      domain: str, relationship_name: str, descriptors_only: bool, ctx: Context, limit: int = 10, api_key: str = None
  ) -> list[dict[str, typing.Any]]:
    """Retrieve entities related to the the given domain.
  
      The following table shows a summary of available relationships for domain objects.
  
      | Relationship                | Description                                                | Return type  |
      | --------------------------- | ---------------------------------------------------------- | ------------ |
      | associations                | Domain's associated objects (reports, campaigns, IoC collections, malware families, software toolkits, vulnerabilities, threat-actors), without filtering by the associated object type.                                                             | Everyone. | List of [reports](ref:report-object), [campaigns](ref:campaign-object), [IoC collections](ref:ioc-collection-object), [malware families](ref:malware-family-object), [software toolkits](ref:software-toolkit-object), [vulnerabilities](ref:vulnerability-object), [threat-actors](ref:threat-actor-object) objecs.| collection |
      | caa_records                 | Records CAA for the domain.                                | domain       |
      | campaigns                   | Campaigns associated to the domain.                        | collection   |
      | cname_records               | Records CNAME for the domain.                              | domain       |
      | collections                 | IoC Collections associated to the domain.                  | collection   |
      | comments                    | Community posted comments about the domain.                | comment      |
      | communicating_files         | Files that communicate with the domain.                    | file         |
      | downloaded_files            | Files downloaded from that domain.                         | file         |
      | graphs                      | Graphs including the domain.                               | graph        |
      | historical_ssl_certificates | SSL certificates associated with the domain.               | ssl-cert     |
      | historical_whois            | WHOIS information for the domain.                          | whois        |
      | immediate_parent            | Domain's immediate parent.                                 | domain       |
      | malware_families            | Malware families associated to the domain.                 | collection   |
      | memory_pattern_parents      | Files having a domain as string on memory during sandbox execution. | file |
      | mx_records                  | Records MX for the domain.                                 | domain       |
      | ns_records                  | Records NS for the domain.                                 | domain       |
      | parent                      | Domain's top parent.                                       | domain       |
      | referrer_files              | Files containing the domain.                               | file         |
      | related_comments            | Community posted comments in the domain's related objects. | comment      |
      | related_reports             | Reports that are directly and indirectly related to the domain. | collection |
      | related_threat_actors       | Threat actors related to the domain.                       | collection   |
      | reports                     | Reports directly associated to the domain.                 | collection   |
      | resolutions                 | DNS resolutions for the domain.                            | resolution   |
      | siblings                    | Domain's sibling domains.                                  | domain       |
      | soa_records                 | Records SOA for the domain.                                | domain       |
      | software_toolkits           | Software and Toolkits associated to the domain.            | collection   |
      | subdomains                  | Domain's subdomains.                                       | domain       |
      | urls                        | URLs having this domain.                                   | url          |
      | user_votes                  | Current user's votes.                                      | vote         |
      | votes                       | Domain's votes.                                            | vote         |
      | vulnerabilities             | Vulnerabilities associated to the domain.                  | collection   |
  
      Args:
        domain (required): Domain to analyse.
        relationship_name (required): Relationship name.
        descriptors_only (required): Bool. Must be True when the target object type is one of file, domain, url, ip_address or collection.
        limit: Limit the number of entities to retrieve. 10 by default.
      Returns:
        List of entities related to the domain.
    """
    if not relationship_name in DOMAIN_RELATIONSHIPS:
      return {
         "error": f"Relationship {relationship_name} does not exist. "
                  f"Available relationships are: {','.join(DOMAIN_RELATIONSHIPS)}"
      }
  
    async with vt_client(ctx) as client:
      res = await utils.fetch_object_relationships(
          client, 
          "domains", domain, 
          relationships=[relationship_name],
          descriptors_only=descriptors_only,
          limit=limit)
    return utils.sanitize_response(res.get(relationship_name, []))

• gti_mcp/tools/netloc.py:22-54 (schema)

  DOMAIN_RELATIONSHIPS list defining all valid relationship names for domain objects, used for validation in the tool handler.

  DOMAIN_RELATIONSHIPS = [
      "associations",
      "caa_records",
      "campaigns",
      "cname_records",
      "collections",
      "comments",
      "communicating_files",
      "downloaded_files",
      "graphs",
      "historical_ssl_certificates",
      "historical_whois",
      "immediate_parent",
      "malware_families",
      "memory_pattern_parents",
      "mx_records",
      "ns_records",
      "parent",
      "referrer_files",
      "related_comments",
      "related_reports",
      "related_threat_actors",
      "reports",
      "resolutions",
      "siblings",
      "soa_records",
      "software_toolkits",
      "subdomains",
      "urls",
      "user_votes",
      "votes",
      "vulnerabilities",
  ]

• gti_mcp/tools/netloc.py:111-174 (registration)

  Tool registration via @server.tool() decorator on the get_entities_related_to_a_domain function, making it discoverable by the MCP server.

  @server.tool()
  async def get_entities_related_to_a_domain(
      domain: str, relationship_name: str, descriptors_only: bool, ctx: Context, limit: int = 10, api_key: str = None
  ) -> list[dict[str, typing.Any]]:
    """Retrieve entities related to the the given domain.
  
      The following table shows a summary of available relationships for domain objects.
  
      | Relationship                | Description                                                | Return type  |
      | --------------------------- | ---------------------------------------------------------- | ------------ |
      | associations                | Domain's associated objects (reports, campaigns, IoC collections, malware families, software toolkits, vulnerabilities, threat-actors), without filtering by the associated object type.                                                             | Everyone. | List of [reports](ref:report-object), [campaigns](ref:campaign-object), [IoC collections](ref:ioc-collection-object), [malware families](ref:malware-family-object), [software toolkits](ref:software-toolkit-object), [vulnerabilities](ref:vulnerability-object), [threat-actors](ref:threat-actor-object) objecs.| collection |
      | caa_records                 | Records CAA for the domain.                                | domain       |
      | campaigns                   | Campaigns associated to the domain.                        | collection   |
      | cname_records               | Records CNAME for the domain.                              | domain       |
      | collections                 | IoC Collections associated to the domain.                  | collection   |
      | comments                    | Community posted comments about the domain.                | comment      |
      | communicating_files         | Files that communicate with the domain.                    | file         |
      | downloaded_files            | Files downloaded from that domain.                         | file         |
      | graphs                      | Graphs including the domain.                               | graph        |
      | historical_ssl_certificates | SSL certificates associated with the domain.               | ssl-cert     |
      | historical_whois            | WHOIS information for the domain.                          | whois        |
      | immediate_parent            | Domain's immediate parent.                                 | domain       |
      | malware_families            | Malware families associated to the domain.                 | collection   |
      | memory_pattern_parents      | Files having a domain as string on memory during sandbox execution. | file |
      | mx_records                  | Records MX for the domain.                                 | domain       |
      | ns_records                  | Records NS for the domain.                                 | domain       |
      | parent                      | Domain's top parent.                                       | domain       |
      | referrer_files              | Files containing the domain.                               | file         |
      | related_comments            | Community posted comments in the domain's related objects. | comment      |
      | related_reports             | Reports that are directly and indirectly related to the domain. | collection |
      | related_threat_actors       | Threat actors related to the domain.                       | collection   |
      | reports                     | Reports directly associated to the domain.                 | collection   |
      | resolutions                 | DNS resolutions for the domain.                            | resolution   |
      | siblings                    | Domain's sibling domains.                                  | domain       |
      | soa_records                 | Records SOA for the domain.                                | domain       |
      | software_toolkits           | Software and Toolkits associated to the domain.            | collection   |
      | subdomains                  | Domain's subdomains.                                       | domain       |
      | urls                        | URLs having this domain.                                   | url          |
      | user_votes                  | Current user's votes.                                      | vote         |
      | votes                       | Domain's votes.                                            | vote         |
      | vulnerabilities             | Vulnerabilities associated to the domain.                  | collection   |
  
      Args:
        domain (required): Domain to analyse.
        relationship_name (required): Relationship name.
        descriptors_only (required): Bool. Must be True when the target object type is one of file, domain, url, ip_address or collection.
        limit: Limit the number of entities to retrieve. 10 by default.
      Returns:
        List of entities related to the domain.
    """
    if not relationship_name in DOMAIN_RELATIONSHIPS:
      return {
         "error": f"Relationship {relationship_name} does not exist. "
                  f"Available relationships are: {','.join(DOMAIN_RELATIONSHIPS)}"
      }
  
    async with vt_client(ctx) as client:
      res = await utils.fetch_object_relationships(
          client, 
          "domains", domain, 
          relationships=[relationship_name],
          descriptors_only=descriptors_only,
          limit=limit)
    return utils.sanitize_response(res.get(relationship_name, []))

• gti_mcp/utils.py:87-116 (helper)

  fetch_object_relationships helper function that fetches relationship descriptors/objects from VirusTotal API using async task groups.

  async def fetch_object_relationships(
      vt_client: vt.Client,
      resource_collection_type: str,
      resource_id: str,
      relationships: typing.List[str],
      params: dict[str, typing.Any] | None = None,
      descriptors_only: bool = True,
      limit: int = 10):
    """Fetches the given relationships descriptors from the given object."""
    rel_futures = {}
    # If true, returns descriptors instead of full objects.
    descriptors = '/relationship' if descriptors_only else ''
    async with asyncio.TaskGroup() as tg:
      for rel_name in relationships:
        rel_futures[rel_name] = tg.create_task(
            consume_vt_iterator(
                vt_client,
                f"/{resource_collection_type}/{resource_id}"
                f"{descriptors}/{rel_name}", params=params, limit=limit))
  
    data = {}
    for name, items in rel_futures.items():
      data[name] = []
      for obj in items.result():
        obj_dict = obj.to_dict()
        if 'aggregations' in obj_dict['attributes']:
          del obj_dict['attributes']['aggregations']
        data[name].append(obj_dict)
  
    return data

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

  consume_vt_iterator helper that consumes a vt.Iterator to paginate through API results.

  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