Upgrading from API v2 to v3: What You Need to Know

The VirusTotal API is a versatile and powerful tool that can be utilized in so many ways. Although it is commonly used for threat intelligence enrichment and threat analysis, the potential uses are virtually limitless. The latest version, VirusTotal API v3, is continuously updated with new features to enhance its capabilities with every new release.

With this post we want to help you understand its potential and, in case you are a VT API veteran, help you migrate from API v2 to API v3 to unleash its full potential.

To simplify the process of adopting and migrating to VirusTotal API v3, we have updated the official documentation with a specific section dedicated to this purpose. We also created a GitHub repository with working examples. In the next few weeks we will host a webinar showing you cool use cases you can implement with VT API, so stay tuned!

Why use VT API v3?

The migration guide describes in detail most API v3 benefits, including:

• Endpoints for all VirusTotal products and scanners. VT users can access all of VirusTotal’s tools through a single API, simplifying the integration process.
• User and group management helping administrators to automate managing access and accounts, as well as tracking usage across your team.
• Extra relevant information for file, URL, domain and IP reports. VT API v3 provides additional information for all file, URL, domain and IP reports, including metadata and context.
• REST-based, with predictable, resource-oriented URLs. VirusTotal API v3 uses a RESTful architecture, following a standard set of design principles for building web services with HTTP methods accessed through predictable, resource-oriented URLs, making it easier to use and integrate with other tools.
• MITRE related tactics and techniques seen in file behavior. API v3 provides information on TTPs used by malware samples, as defined by the MITRE ATT&CK framework. This helps understanding the potential impact of a sample and how to respond to any threats.
• More extensive documentation and code examples based on the Python module. V3 has more extensive documentation and code examples which make it easier for users to get started with the API and integrate it into their workflows.

API v2-v3 Migration Guide

Our migration guide outlines the differences between VT API v2 and v3, touching on aspects such as data formats, available integration with other VT products and features, and what are the API Scripts and client libraries available for each one.

It also details the differences between v2 and v3 endpoints, including differences in requests and responses. The table below summarizes endpoint correspondence between v2 and v3:

Description	VT API v2	VT API v3
Submitting samples, getting file reports, and rescanning files
Submit file (<= 32MB)	/file/scan	/files
Submit file(> 32MB)	/file/scan/upload_url and /file/scan	/files/upload_url and /files
Get file report	/file/report (allinfo parameter)	/files/{id}
Rescan file	/file/rescan	/files/{id}/analyse
Getting file behaviour reports and downloading network traffic files
Get file behavior report	/file/behaviour	/files/{id}/behaviours and /file_behaviours/{sandbox_id}/html
Download PCAP	/file/network-traffic	/file_behaviours/{sandbox_id}/pcap
Scanning URLs, getting reports for URLs, domains, and IP addresses
Scan URL	/url/scan	/urls
Get URL report	/url/report	/urls/{id}
Get domain report	/domain/report	/domains/{domain}
Get IP address report	/ip-address/report	/ip_addresses/{ip}
Feeds for enrichment
Get file feed	/file/feed	/feeds/files/{time} and /feeds/files/hourly/{time}
Getting URL feed	/url/feed	/feeds/urls/{time} and /feeds/urls/hourly/{time}
Getting file clusters and downloading files
Get file clusters	/file/clusters	/stats/vhash_clusters
Download file	/file/download	/files/{id}/download
VT Intelligence via API
Advanced search	/file/search (only for files)	/intelligence/search

One more thing

In addition to the examples provided in the GitHub repository, the official API documentation offers additional cool features.

First of all, it provides code examples for every endpoint! The 3 dots button shows a list of available programming languages you can get examples. Select any of them and the code is automatically updated to that language.

Additionally, the ‘Try It!’ button executes the request for you and shows the JSON result in the ‘RESPONSE’ section under the code snippet.

Conclusions

API v2 served VirusTotal users well for many years, but it lacks some features required to any modern professional API. Don’t panic, you can still continue using API v2 if you really have to. We want to make sure you understand the advantages of using v3 and provide you with everything needed to make v2 to v3 transition as smooth as possible.

Probably the main advantage is that API v3 is VirusTotal’s standard, and some day in the future we will have to sunset v2. Nevertheless, in v3 we make sure that every service and feature has its corresponding endpoint. That includes many functionalities not available in v2, like user and group management, threat landscape, Graphs or Private Scanning, among others. Moreover, API v3 provides extended data on VT reports for any observable!

We hope the extensive documentation and code examples will help you master API v3 very soon! If you have any suggestions or just want to share feedback, please feel free to reach out here.

Happy hunting!

Read More

VirusTotal API implementation in C programming language

Many users interact programmatically with VirusTotal via its public API, it is an easy HTTP+JSON interface that allows you to easily submit and check files in order to help improve security world-wide. Moreover, many VirusTotal Community volunteers have very kindly implemented the API in a wide variety of programming languages, some of these implementations are documented here, many others exist and we will progressively adding all those that we are made aware of.

This said, there was not any full implementation of the API in the C language, so that any C or C++ program that users might be building could easily interact with VirusTotal, at least we were not aware of any. We have released a VirusTotal interface written in C to our API  on github at https://github.com/VirusTotal/c-vtapi, any C or C++ program should be able to use it. Its goal is to implement all of the public API and private API features in C. The public API features will work for anyone with a free public API key, the private API features will only work for those who have licensed our services and use a private API key.

The recently announced VirusTotal Uploader for OS X internally uses the c-vtapi project. Using C it is a common building block that other programs or languages can interface to.

Suggestions, comments, patches and github pull request for improvements are welcome. Some ideas of improvements:

• Better windows support and testing. We have tested a lot with OS X and linux, the windows scaffolding is there, but is not well tested.
• More example programs or command line utilities that use this C API interface. For example, we know Sebastian Poeplau, being a busy guy, was looking for collaborators that would implement VirusTotal submissions in his awesome Ghost USB project, perhaps this C implementation makes it easier to perform the integration and some volunteers stand up.

Read More

Public API request rate limits and tool development

Our goal is simple: to help keep you safe on the web. For this to happen, among many other technical fireworks, we need to receive as many (hopefully malicious) files as possible that we can eventually share with the antivirus and security industry in order to allow them to improve their products and technologies.

One of the ways we envisioned increased submissions to VirusTotal was through the release of our public API. Many tools and security deployments (honeypots, honeyclients, sandboxes, etc.) are making use of it and we are delighted that they do so. However, very often I see that integration with VirusTotal's API could be simpler.

Many users ignore the fact that public API request rate limits are enforced on (IP address, API key) tuples. What does this mean? Users sharing a same API key with different IP addresses will be subjected to independent request rate counters. Putting it simpler, if you are a tool developer, you might want to create a public API key for your tool and embed it in your application, that way, by default, you would not have to ask the user to create an API key and the whole integration with VirusTotal would be transparent. 

Having said this, it is always wise to have a settings file or tab that allows users to change this default key:

• Some users might be behind some sort of proxy, corporate network aggregator, NATting device, or similar setup that makes them share the same IP address with other users of your tool, these users should be given the option to create their own API key and modify the setting in your tool.
• Some users might just want to use an independent key in order to track their own submissions in their VirusTotal Community profile.
• Some users might simply find the public API request rate limit too low, they might want to speak with VirusTotal about the possibility of getting a private API key, they should be able to embed that independent private API key in your setup.

So, imagine this hypothetical situation: I want to build a tool that whenever a USB storage device is plugged into a given PC it inspects its files, looks for any autorun.inf file and submits to VirusTotal any referenced executables in it. I would create an VirusTotal Community account for my tool and retrieve the corresponding API key, I would hardcode that into my application and make the tool use it by default. This said, I would also have a settings tab in my application that would allow users to change this key for any other key they might register. Of course, I would plan to render the corresponding messages informing a user about the fact they can modify the default key whenever request rate limitations are met because of IP sharing.

Hope this is useful and I would love to see more VirusTotal plugins out there with a more transparent integration such as the one described above. As usual, before doing any kind of integration please look at our Terms of Service and Best practices, tools competing with the antivirus industry or jeopardizing such industry will be immediately banned from the service. VirusTotal is a tool to help antivirus vendors in improving their products, not a means to discredit, harm them in any way or steal their intellectual property, we take this matter very seriously.

Read More