× Cookies are disabled! This site requires cookies to be enabled to work properly

If you want to automate tasks with VirusTotal the best option is the Private Mass API , as you can read in the linked documentation, VirusTotal Intelligence advanced searches are exposed in it through the searching for files call. Having said this, in order to access the Private Mass API you must have a private API key, only users that have purchased such a license or users of VirusTotal Intelligence in the unlimited step have such a privilege.

Nonetheless, we want you to make the best use of your VirusTotal Intelligence account and so, we have exposed some VirusTotal Intelligence functionality for programmatic interaction even if you do not have a Private Mass API key. These features are documented below.

Programmatically exporting Hunting rulesets

Malware hunting rulesets can be exported using your personal API key, this can be useful for many users, as often they prefer our online editor for writing rules but would then like to run these locally also.

The URL endpoint to perform an export is as follows:

https://www.virustotal.com/intelligence/hunting/export-ruleset/?ruleset=*&key=<MY_APIKEY>

As you may notice, it includes your API key, make sure you only share this link with trusted third-parties. If you would rather prefer to focus exclusively on a given ruleset, you may do so by speciying its name in the ruleset parameter:

https://www.virustotal.com/intelligence/hunting/export-ruleset/?ruleset=RULESET_NAME&key=<MY_APIKEY>

Retrieving Malware Hunting notifications

Malware Hunting notifications can be accessed programmatically in a number of ways:

  • Configuring email notifications: each ruleset has a settings tab where you can specify email addresses that should receive any notifications for samples that trigger a rule in the ruleset. The email account can then be accessed automatically in order to retrieve these. We do not recommend this approach since it requires far more coding than the following ones.
  • RSS feed: if you go to the notifications tab in Malware Hunting you will observe a RSS link just below the notification filtering input box, this takes you to the RSS feed of your notifications. You can poll this URL at regular intervals in order to retrieve your latest notifications. Shortcut to your RSS feed .
  • JSON feed: if you go to the notifications tab in Malware Hunting you will observe a JSON link just below the notification filtering input box, this takes you to the JSON feed of your notifications. You can poll this URL at regular intervals in order to retrieve your latest notifications. Shortcut to your JSON feed.

Programmatically deleting Hunting notifications

Once users have automatically pulled their Hunting notifications via the JSON or XML interfaces, they often desire to programmatically clear the alerts that have already been processed. This may be achieved through a programmatic interface specifically devoted to this task.

The API endpoint in order to delete one or more Hunting notifications is as follows:

https://www.virustotal.com/intelligence/hunting/delete-notifications/programmatic/?key=<MY_APIKEY>

Please note that the URL embeds your own (public/private) API key and so you should only share the full URL with trusted third parties within your organization.

This endpoint accepts HTTP POST requests with a content type of application/json and whose body should be an array/list of notification ids that should be deleted. Example:

[5278074110738432, 6402641302650880]

You should not embed more than 100 identifiers per HTTP request. So, where can you find these identifiers? When pulling the notifications via the JSON/XML interface, each notification has a field named id, this is the property you should be looking at.

Automating file downloads

Even if you do not have a Private Mass API key that you can use, you can still download files from the VirusTotal storage making use of your VirusTotal Intelligence quota, i.e. programmatic downloads will also deduct quota.

You can download files via the following URL, please note that the URL embeds your own (public/private) API key and so you should only share the full URL with trusted third parties within your organization:

https://www.virustotal.com/intelligence/download/?hash=<file-hash>&apikey=<MY_APIKEY>

You may use either the md5, sha1 or sha256 hash of the file in order to download it.

Automating file searches

Even if you do not have a Private Mass API key that you can use, you can still automate VirusTotal Intelligence searches pretty much in the same way that the searching for files api call works.

In order to do so, you just have to issue an HTTP GET request to the following URL, please note that the URL embeds your own (public/private) API key, you should only share the full URL with trusted third parties within your organization:

https://www.virustotal.com/intelligence/search/programmatic/?query=<your_search>&page=<next_page>&apikey=<MY_APIKEY>

As you can see, the following HTTP GET parameters are expected:

  • query: a VirusTotal Intelligence search string in accordance with the file search documentation .
  • page: the next_page property of the results of a previously issued query to this API. This parameter should not be provided if it is the very first query to the API, i.e. if we are retrieving the first page of results.
  • apikey: the API key associated to a VirusTotal Community account with VirusTotal Intelligence privileges.

The API will return a JSON object with a result property indicating the successfulness of the operation, a next_page property that can be used to set the page HTTP GET parameter of a new query to the API and a hashes property with a list of sha256 hashes of files that match the issued query (at most 25 hashes per API call).

The returned sha256 hashes can then be used to download the corresponding samples making use of the file downloading programmatic interface.

Example use cases

Building a VirusTotal Intelligence batch downloader

Taking into account the last two documented automation cases (file downloading and file searching), it seems quite simple to build a script that will allow you to download from VirusTotal an arbitrary number of files matching a given VirusTotal Intelligence search.

This small utility would execute a user provided query via the searching programmatic interface, paginate over the matching results as many times as required to retrieve the requested number of files, and queue the matches in order to download them via the file downloading programmatic interface.

An example of how the code to do this looks like in python is linked in the batch file downloads section of the file searching documentation.