get https://www.virustotal.com/api/v3/collections
Special privileges required
Reports & Analysis are only available to users with the Google Threat Intelligence (Google TI) Enterprise or Enterprise Plus licenses.
This endpoint allows us to search and filter Google TI Reports effectively. It returns a list of Report objects only when filtering by the parameter collection_type:report.
Searches observations:
- if you don't filter by the
collection_typethis endpoint will return not only Vulnerabilities but other types of objects such as Vulnerabilitie, Threat Actors, Malware families, Software or Toolkits, Campaigns or IoC Collections, matching the rest of the filters. - filers' values are case-insensitive
- several filters can be combined together in a more complex and specific search
- boolean operators can be used in more complex searches:
AND,OR,NOT - quotes are needed for filters' values with spaces:
description:"Phishing campaign" - wildcards (*) can be used for partial matches:
name:Ransom* - date filters formats:
YYYY-MM-DD,YYYY-MM-DDTHH-mm-ss - date relative formats:
60d(for days),10m(for minutes) - date ranges can be specified with
+or-:last_modification_date:7d+,creation_date:2024-01-01-
Allowed filters by object collection_type:report:
collection_type:report:| filters | filter description |
|---|---|
| Open search | Text without modifiers matching against object's name or description |
name | Object's name |
description | Object's description |
creation_date | Object's creation date |
last_modification_date | Object's last modification date |
origin | Object's origin. Available options: Partner for objects curated by trusted partners and security researchers , Crowdsourced for OSINT objects from the community or Google Threat Intelligence for objects curated by our Google TI experts |
owner | Owner's username |
motivation | Motivation behind the malicious activity described in the report |
source_region | Regions from where the malicious activity described in the report is originated |
targeted_region | Region targeted by the malicious activity described in the report |
targeted_industry | Industry targeted by the malicious activity described in the report |
targeted_industry_group | Groups of industries targeted by the malicious activity described in the report |
operating_system | Affected operating system |
malware_role | Report's associated malware role |
software_toolkit | Software or Toolkit's name, associated to the report |
Allowed orders:
order:name+: sorts objects alphabetically by name, ascending+or descending-.order:creation_date-: sorts objects descending-(default) by most recently created objects first, or ascending+by oldest objects first.order:last_modification_date-: sorts objects descending-by most recently modified objects first, or ascending+by firstly modified objects first.order:lookups_trend-: sorts objects ascending+or descending-based on the trend of the daily distinct-user lookups over the IoCs of the object in the last 14 days.order:submissions_trend-: sorts objects ascending+or descending-based on the trend of the daily distinct-user submissions of IoCs of the object in the last 14 days.order:relevance+: sorts objects ascending+or descending-based on the relevance of the object.order:exploitation_state+: sorts objects ascending+or descending-based on the exploitation state of the vulnerability.order:risk_rating+: sorts objects ascending+or descending-based on the risk rating of the vulnerability.
Examples
Get the list of all crowdsourced Reports created from the beginning of 2024 whose name contains the "phishing" word and sort results descending by creation date (FIFO order).
import requests
import urllib
filters = "collection_type:report name:phishing creation_date:2024-01-01+ origin:Crowdsourced"
order = "creation_date-"
url = f"https://www.virustotal.com/api/v3/collections?filter={urllib.parse.quote(filters)}&order={order}"
headers = {"accept": "application/json","x-apikey": <api-key>}
response = requests.get(url, headers=headers)