This guide serves as a follow-up to the Google Threat Intelligence Migration Guide for former Mandiant users. It's designed to help users transition from the Mandiant Advantage API to the Google Threat Intelligence (Google TI) API. Please consider this an additional resource alongside the official API documentation.

Building on that foundation, developers can leverage the comprehensive suite of Google TI API v3 endpoints for building custom integrations. These powerful endpoints provide access to an extensive range of tools, features, and functionalities that mirror those available in the web interface, all accessible under a single, globally used server URL: www.virustotal.com/api/v3/.

In the following sections, we'll cover key aspects of migrating to Google Threat Intelligence. We'll specifically address:

• API authentication methods
• API URL and paths mapping to the Google TI API:
  • Mandiant's Digital Threat Management (DTM)
  • Mandiant's Attack Surface Management (ASM)
  • Mandiant's Threat Intelligence API

Finally we'll take a deep dive into the Threat Intelligence module itself. This section will highlight several key differences and new concepts, and introduce Google TI tools the reader might not be familiar with yet.

🚧

Skipping introductory content

If you'd like to skip the introductory content, you can jump straight to the Threat Intelligence API Endpoints Mapping section here!

API Authentication

Unlike Mandiant, which typically offers both Bearer Token Authentication and Basic Authentication, Google TI primarily uses API keys for authentication. Any endpoints that support additional authentication methods will explicitly indicate it in their specific documentation.

Each Google TI user has its own unique API key, but service accounts were specifically designed for automation tasks. They are not tied to individual users, do not require an email address for creation, and provide API authentication solely via API keys accessible only to group administrators, and only administrators can create them.

API Key

Users can access their individual API key on the platform by navigating to the API key option in either the left navigation menu bar or the top-right User menu:

Administrators can access service accounts' API keys on the platform by navigating to the top-right User menu, selecting My Group option, and then heading to the USERS tab. Within the Service accounts section, they'll find dedicated buttons to view and copy each service account's API key.

API URL & Paths segments mapping

When migrating to Google TI, in addition to the authentication method, the other most critical change is the update to API server URLs and their corresponding paths. While much of the core functionality from Mandiant's modules remains, specifically for ASM and DTM, the access points have been consolidated and streamlined under the Google TI umbrella.

The table below provides a clear mapping of the base URLs and initial path segments from Mandiant's core modules (ASM, DTM, and the Threat Intelligence module) to their equivalents within the new Google TI API.

(*) The next section of this document details the equivalent Threat Intelligence endpoints and highlights other differences and concepts to take into account when migrating.

Digital Threat Monitoring (DTM) &Attack Surface Management (ASM)

When transitioning from Mandiant to Google TI, the core functionality and structure of the Digital Threat Management (DTM) and Attack Surface Management (ASM) APIs largely remain the same. The primary difference lies in their server URLs and the initial segments of their paths as shown in the previous table. Please refer to the Google TI documentation for:

• Digital Threat Monitoring (DTM)
• Attack Surface Management (ASM)

Threat Intelligence API

Before we dive into the Threat Intelligence endpoints, it's helpful to first understand some key Google TI concepts and differences between Mandiant Threat Intelligence API and Google TI API specifically.

Google TI API objects

It's important to note that while Google TI provides all information found in Mandiant API objects (and more), the JSON response objects have different structures. The following list shows the most popular objects and links to their respective documentation, where their JSON structure is defined:

• Indicators of Compromise

  • File
    • Additionally, files can present a Sandbox analysis report represented by the File Behaviour object.
  • URL
  • Domain
  • IP address

• Threat Intelligence objects: note that these objects include the origin attribute which identifies the source of the data for their attributes. Google Threat Intelligence origin refers to objects whose information was checked and validated by the Mandiant analysts, Partner origin refers to the objects coming from our trusted external partners and Crowdsourced origin refers to objects created by the rest of the community.

  • Threat Actor
  • The Mandiant Malware object equivalent in Google TI is conceptually split into two objects: Malware Family and Software and Toolkit
  • Campaign
  • IoC collections: although not present in Mandiant, it plays a crucial role in Google TI through its ability to aggregate, enrich, and distribute indicators of compromise from the community in real time.
  • Report
  • Vulnerability

While these are some of the frequently encountered objects, Google TI offers a more extensive range of object types. For a comprehensive definition of all available objects and their structures, please refer to the API Objects documentation.

Google TI Relationships endpoints

Most objects in the documentation include a Relationships section. Values in this section can be used, along with the specific object id, to retrieve additional related or associated objects as documented here:

• /api/v3/{collection name}/{object id}?relationships={relationship} - returns one relationship objects' descriptors, which include only the most relevant attributes of the related objects such as their type, id and links to retrieve the complete objects.
• /api/v3/{collection name}/{object id}?relationships={relationship1},{relationship2} - returns several relationships objects' descriptors , which include only the most relevant attributes of the related objects such as their type, id and links to retrieve the complete objects.
• /api/v3/{collection name}/{object id}/{relationship} - returns one relationship complete objects, not only their descriptors.

{collection name} can be one of the following: files, urls, domains, ip_addresses, domains, ip_addresses or collections for all Threat Intelligence objects such as Threat Actors, Campaigns, Reports, Vulnerabilities, etc.

Additional observations

• Pagination: Mandiant does pagination through the next field of the JSON response, while Google TI does it via links -> next field.

• Indicators of Compromise: here are the differences in how indicator types are named in their respective JSON responses

• Set of objects: while Mandiant's API separates different object types into distinct JSON response fields (threat-actors, campaigns, malware, vulnerability, objects for reports, and indicators), Google TI is consistent and simplifies this by grouping all objects under a single data field. The specific object type is then identified by the type attribute for indicators or the collection_type attribute for other Threat Intelligence objects.

• HTTP POST method: In Google TI the POST method is reserved to send data to the platform, such as creating new IoC Collections, building Threat Graphs, adding community comments to objects cards and more. All requests for retrieving information from our databases require the GET method.
• Object identifiers: in Google TI, Threat Intelligence objects (including Actors, Malware, Tools, Campaigns, IoC Collections, Vulnerabilities, and Reports) and IoCs are consistently identified in API JSON responses by the id attribute. Same id values are displayed on the browser URL when opening any object card or IoC report.

(*) While SHA256 is the primary identifier for files, MD5 and SHA1 hashes can also be used for unique identification. Please note that files integrated from Mandiant without provided binary content can only be searched using their MD5 hash, not SHA256.

• GTI score: endpoints that can provide the Google TI assessment of an object require the x-tool header to do so. This header must specify the tool or service that will be consuming our data. Without this header, the GTI score will not be returned.

headers = {
   "accept": "application/json",
   "x-apikey": "your API key",
   "X-tool":"SIEM custom integration"
}

Threat Intelligence API endpoints mapping

New Google TI API Functionalities

In addition to the endpoints mapped in the previous section, Google TI offers other analysis and threat intelligence-related endpoints, including:

• Threat Profiles: Google TI provides access to the Threat Profile tool via API, to be able to programmatically manage them and retrieve recommendations on the most relevant threats. This includes insights into Threat Actors, Campaigns, Malware & Tools, IoC Collections, Vulnerabilities, and Reports prioritized by our machine learning (ML) module based on specific criteria, such as targeted industries, target regions, source regions, malware roles, and actor motivations. Refer to the API documentation section here.
• Categorized Threat Lists: Google TI includes API data streams that provide curated and categorized Indicators of Compromise (IoCs). While these feeds are pre-filtered by certain criteria and categories, they also include additional filters for an extra layer of user customization. For more details, refer to the API documentation section here.
• Private Scanning: Google TI provides for programmatically scanning files and analyzing URLs within a completely private environment. This way users can run investigations without sharing files, their scanning reports, or URL analysis reports with the broader Google TI community, avoiding exposing sensitive information. Refer to our API documentation section for more information here.
• YARA Livehunt: Google TI allows to programmatically create and manage Livehunt rulesets with YARA language to be notified any time a new IoC submitted to our open database matches the defined criteria (searching in the future). Go to our documentation section here.
• YARA Retrohunt: Running Retrohunt jobs to check our current database (searching in the past) for files matching YARA rules criteria defined by the user, can be done programmatically via our API endpoints whose documentation can be checked here.
• IoC Stream: Our API endpoints allow for programmatic control over the centralized notification hub. This means users can manage notifications for IoCs detected by Livehunt and Retrohunt jobs, and those related to Threat Profiles and Threat Intelligence objects they're following. Documentation is available here.