Last updated at Mon, 05 Feb 2024 20:35:21 GMT

VirusTotal is a free online service that allows you to analyze files or URLs in order to identify malware detectable by antivirus engines, and is one of the most popular ones in the community, so we decided to get a piece of that action. As offensive tool developers, we often find ourselves testing the capabilities of different AV products. There are usually two ways to achieve this, of course. You either spend some money and build your own lab, or you spend nothing and just use VirusTotal's API and submit your malware to analyze. Obviously there are plenty of reasons why VirusTotal is useful, but I'll let you explore your own creativity :-) The main purpose of the blog is to explain what we've done to assist your need of automatic malware analysis, and how to use it.

Before you start using these features, note that by default you are using Metasploit's public API key. What does this mean to you? It means as long as you're using the default key, we at Metasploit can see your submission. The data we can see include: The date of the submission, and the web version of the report (which is the same one you have). We don't actually have access to your malware sample. The following screenshot is an example:

If you prefer your own key, you may obtain one free of charge at and sign up for an account. The public API key is limited to 4 requests of any nature per minute, non-commercial purposes, but this should be enough for personal research. If there is a popular demand for supporting the private API, we can jump on that as well. Please feel free to let us know.

We currently offer two different scripts for different scenarios. The standalone version is located under the "tools" directory, which implies this is generally used for some sort of development purposes (but of course, do whatever you want with it). Another one serves as a post module that allows you to check a remote file via a Metasploit payload... that's a little ironic, isn't it?

The Standalone virustotal.rb Utility

The standalone utility will upload your malware sample to VirusTotal, and the service will take care of the rest. If this is an unique malware, it may take several minutes to get a report. My experience is about 5 - 6 minutes. If for some reason the waiting period takes more than an hour, then the script will automatically terminate, but you should still at least have the analysis link to check later manually. If there is already a report for your sample, it should only take a couple of seconds to get it.

It's very easy to get going, obviously you should at least have a malware ready, and then you can simply run the following command:

tools/virustotal.rb -f [PATH TO MALWARE FILE]

The -f option allows you to supply up to 4 files (again, because the API limit), and here's how to do that:

tools/virustotal.rb -f "[FILE_1 FILE_2 FILE_3 FILE_4]"

Like I said earlier, by default there's already a built-in API key, but you can also specify your own::

tools/virustotal.rb -k [API KEY] -f [FILENAME]

Note that after specifying your own key once, you won't have to do it again because that information will be stored in Metasploit's config file at ~/.msf4/config. So that means next time your command will no longer need the -k option:

tools/virustotal.rb -f [FILENAME]

If you prefer to do a quick hash search to grab the report instead of uploading the malware sample, then you can use the -q option. Please note since the -q option doesn't actually upload the malware, not finding a report doesn't necessarily mean the malware is actually undetectable:

tools/virustotal.rb -q -f [FILENAME]

An example of your analysis report should look like this:

The check_malware.rb Post Module

The post module version functions differently than the standalone one. Instead of uploading the sample to VirusTotal, the module will only submit the checksum and grab the report. It also uses the same default API key, and you can set your own.

There are two datastore options in this module: The APIKEY allows you to use your own key. The REMOTEFILE option is the file you wish to check on the target machine. Here's an example of how to use it:

And that's all you need to know about our new features from VirusTotal. If you're new to Metasploit, you can download a copy of it for either Linux or Windows. If you are already a Metasploit user, you should receive these new toys by running the msfupdate command. Enjoy!