Get recommendations of a Threat Profile

🚧
Public Preview
Threat Profile module is provided as a public preview and is subject to change. Use with caution.

This endpoint returns the list of objects associated to a certain Threat Profile.

Each of these objects has one of the following types types: Threat Actors, Malware Families, Software or Toolkits, Campaigns, IoC Collections, Reports and Vulnerabilities.

We can distinguish between two other types of objects based on how they were associated with the Threat Profile:

Recommended objects are automatically recommended or assigned to a Threat Profile based on our proprietary ML that takes into account the Threat Profile's configured interests such as the targeted industries, target regions, source regions, malware roles and actor motivations to recommend the most relevant threats. These objects are identified by the presence of "source": "SOURCE_RECOMMENDATION" within the "context_attributes" JSON response parameter below.
Added objects are assigned or added by users to a Threat Profile, when users find other relevant threats not automatically recommended by our ML module. These objects are identified by the presence of "source": "SOURCE_DIRECT_FOLLOW" within the "context_attributes" JSON response parameter below.

Example of parameters that will appear next to each threat object (or object descriptor) to inform on how they were associated to the Threat Profile:

"context_attributes":
{
    "source": "SOURCE_RECOMMENDATION",
    "reason":
    {
        "interests": "<_list of dictionaries_> list of the reasons or interests that have been matched to produced the recommendation."
        [
            {
                "type": "<_string_> type of the interest that produced a match. Existing options: 
                    INTEREST_TYPE_TARGETED_INDUSTRY - referes to the Threat Profile's configured targeted industry  
                    INTEREST_TYPE_TARGETED_REGION - referes to the Threat Profile's configured targeted region  
                    INTEREST_TYPE_SOURCE_REGION - referes to the Threat Profile's configured source region 
                    INTEREST_TYPE_MALWARE_ROLE - referes to the Threat Profile's configured malware role 
                    INTEREST_TYPE_ACTOR_MOTIVATION - referes to the Threat Profile's configured Threat Actor motivation.",
                "value": "<_string_> value of the interest that produced a match."
            }
        ]
    },
    "recommendation_relevance": "<_integer_> represents the relevance of the recommendation. The highest relevance goes to 1."
}

"context_attributes":
{
    "source": "SOURCE_DIRECT_FOLLOW"
}

Filters

Available filters for objects associated to a certain Threat Profile:

recommendation_source: to get only recommendations automatically generated by our ML (SOURCE_RECOMMENDATION) or only those specifically added by a user (SOURCE_DIRECT_FOLLOW). Ex: recommendation_source:SOURCE_DIRECT_FOLLOW.
collection_type: to get only objects of a certain type (threat-actor, malware-family, software-toolkit, campaign, collection - for IoC Collections, report, vulnerability). Ex: collection_type:threat-actor, collection_type:collection, collection_type:report.
targeted_region: to filter objects by the region targeted by a threat or malicious activity. The region in ISO 3166 code format. Ex: targeted_region:RU, targeted_region:US, targeted_region:ES.
source_region: to filter objects by the region from which the threats are known to originate. The region in ISO 3166 code format. Ex: source_region:RU, source_region:US, source_region:ES.
targeted_industry: to filter objects by the targeted industry. Ex: targeted_industry:'Online marketplace', targeted_industry:'Oil and Gas', targeted_industry:Arts
targeted_industry_group: to filter objects by the targeted industry group (Aerospace & Defense, Agriculture, Automotive, Chemicals & Materials, Civil Society & Non-Profits, Construction & Engineering, Education, Energy & Utilities, Financial Services, Government, Healthcare, Hospitality, Insurance, Legal & Professional Services, Manufacturing, Media & Entertainment, Multi-sector, Oil & Gas, Other, Pharmaceuticals, Retail, Technology, Telecommunications, Transportation, Unknown). Ex: targeted_industry_group:Manufacturing, targeted_industry_group:'Media & Entertainment'.
origin: to filter objects by the origin or who has created them (partner, crowdsourced, 'Google Threat Intelligence'), and list only those curated by our team or our parteners, or to list crowdsourced objects only. Ex: origin:'Google Threat Intelligence', origin:crowdsourced.
creation_date: to filter objects by their creation date (YYYY-MM-DD+ - from date until now, YYYY-MM-DD- - previous to date, YYYY-MM-DD - exact day). Ex: creation_date:2025-01-15+, creation_date:2025-03-01-, creation_date:2025-04-04.
last_modification_date: to filter objects by their last modification date (YYYY-MM-DD+ - from date until now, YYYY-MM-DD- - previous to date, YYYY-MM-DD - exact day). Ex: last_modification_date:2025-01-15+, last_modification_date:2025-03-01-, last_modification_date:2025-04-04.
description: to filter objects by relevant strings within their descriptions. If you use multiple strings in a sentence, enclose them in quotes. Ex: description:reCAPTCHAs, description:"SHADOWLADDER.IDAT and DEERSTEALER".
motivation: to filter threat actors objects by their motivations (Attack / Destruction, Espionage, Financial Gain, Hacktivism, Influence, Notoriety, Nuisance, Penetration Testing, Surveillance, Opportunistic). Ex: motivation:'Attack / Destruction', motivation:Hacktivism.
capability: to filter malware families objects by their capabilities. Ex: capability:'Constructs mutex', capability:'Delete files', capability:'Hides windows', capability:'Reads memory'.
operating_system: to filter malware families and software or toolkits by their targeted opetrating systems (linux, windows, mac, android, ios, etc). Ex: operating_system:ios, operating_system:android, operating_system:mac.
malware_role: to filter malware families and software or toolkits by their roles (Archiver, ATM Malware, Backdoor - Botnet, Backdoor - Webshell, Backdoor, Bootkit, Builder, Controller, Credential Stealer, Cryptocurrency Miner, Data Miner, Decoder, Disruption Tool, Downloader, Dropper - Memory Only, Dropper, Exploit Builder, Exploit, File Infector, Framework, Installer, Keylogger, Lateral Movement Tool, Launcher, Lightweight Backdoor, Module, Point-of-Sale Malware, Privilege Escalation Tool, Ransomware, Reconnaissance Tool, Remote Control and Administration Tool, Remote Exploitation Tool, Rootkit, Screen Capture Tool, Sniffer, Spambot, Tunneler, Uploader, Utility). Ex: malware_role:'Reconnaissance Tool', malware_role:Ransomware.
merged_actor: to filter large threat actor groups by confirmed threat actors as part of the larger one. Ex: merged_actor:UNC1024.

Examples

Get 10 objects associated to the Threat Profile 332e02da667746f180a9740e94a3ec98.

import requests

profile_id = "332e02da667746f180a9740e94a3ec98"
url = f"https://www.virustotal.com/api/v3/threat_profiles/{profile_id}/recommendations?limit=10"
headers = {"accept": "application/json","x-apikey": <api-key>}

response = requests.get(url, headers=headers)

Get only automatically generated recommendations of the Threat Profile 332e02da667746f180a9740e94a3ec98.

import requests

profile_id = "332e02da667746f180a9740e94a3ec98"
filter = "recommendation_source:SOURCE_RECOMMENDATION"
url = f"https://www.virustotal.com/api/v3/threat_profiles/{profile_id}/recommendations?filter={filter}"
headers = {"accept": "application/json","x-apikey": <api-key>}

response = requests.get(url, headers=headers)

Get only objects added by users to the Threat Profile 332e02da667746f180a9740e94a3ec98.

import requests

profile_id = "332e02da667746f180a9740e94a3ec98"
filter = "recommendation_source:SOURCE_DIRECT_FOLLOW"
url = f"https://www.virustotal.com/api/v3/threat_profiles/{profile_id}/recommendations?filter={filter}"
headers = {"accept": "application/json","x-apikey": <api-key>}

response = requests.get(url, headers=headers)

Get only malware fammilies associated to the Threat Profile 332e02da667746f180a9740e94a3ec98.

import requests

profile_id = "332e02da667746f180a9740e94a3ec98"
filter = "collection_type:malware-family"
url = f"https://www.virustotal.com/api/v3/threat_profiles/{profile_id}/recommendations?filter={filter}"
headers = {"accept": "application/json","x-apikey": <api-key>}

response = requests.get(url, headers=headers)

Get only automatically generated recommendations of threat actors of the Threat Profile 332e02da667746f180a9740e94a3ec98.

import requests

profile_id = "332e02da667746f180a9740e94a3ec98"
filter = "recommendation_source:SOURCE_RECOMMENDATION AND collection_type:threat-actor"
url = f"https://www.virustotal.com/api/v3/threat_profiles/{profile_id}/recommendations?filter={filter}"
headers = {"accept": "application/json","x-apikey": <api-key>}

response = requests.get(url, headers=headers)

Get only vulnerabilities and campaingn associated to the Threat Profile 332e02da667746f180a9740e94a3ec98.

import requests

profile_id = "332e02da667746f180a9740e94a3ec98"
filter = "collection_type:report OR collection_type:vulnerability"
url = f"https://www.virustotal.com/api/v3/threat_profiles/{profile_id}/recommendations?filter={filter}"
headers = {"accept": "application/json","x-apikey": <api-key>}

response = requests.get(url, headers=headers)

🚧Public Preview

Filters

Examples

🚧
Public Preview