Sign in to VT Community

What is the VirusTotal email interface?

VirusTotal's email interface lets you upload files via email and receive the scan results in your mailbox. The files are uploaded as email attachments and the results can be received either in plain text or XML.

The files sent via email have a lower priority, therefore, the scan results will not always be sent back immediately.

How do I start?

The requirements are very simple, you just need a valid email account and a file that you wish to analyse.

The sending process is as follows:

1. Create a new message with scan@virustotal.com as the destination address.
2. If you wish to receive the results as plain text, write SCAN in the subject field. If you wish to receive an XML attachment with the results, write SCAN+XML in the subject field.
3. Attach the file to be scanned. Such file must not exceed 20 MB in size. If the attached file is larger, the system will reject it automatically.

If you completed these steps correctly, you will receive an email with the file scan report. The response time will vary depending on the load of the system at the moment in which the file was sent.

What is VirusTotal uploader?

To upload a file to VirusTotal, you can visit the main analysis site, click the Browse button to select a file from your hard drive, and then click the Send file button. You can make this process even easier with the free VirusTotal Uploader utility. After installing it, you can simply right-click any file under 20MB and choose "VirusTotal" from the Send To Windows menu. The scan results will display in your browser as usual.

The latest version 2 of the VirusTotal Uploader utility adds a new program window with some useful extra features, these will be described in the How do I start? section.

How do I start

The first thing you must do is download the program itself, you can do this by clicking on the following link:

VirusTotal Uploader

It is a 140KB Windows installer with the following MD5: 9edab310d6d226164026e555a2daed97. Execute the program and the installation process will begin:

Click on I Agree and then on the Next button:

Now choose the destination folder of the application, i.e. where it will be installed, and click on Install:

Once the setup has ended you can close the installation window. If you selected the option of creating a desktop shortcut you should now see it in your desktop.

Send a file to VirusTotal

With VirusTotal uploader, this task could not be easier, just right-click on the file you wish to upload and select the VirusTotal option from the Send To context menu:

You may also run VirusTotal uploader (by clicking on its desktop shortcut for example) and click on the Select file(s) and upload button:

Even easier, just select the files you want to upload and drag them to VirusTotal Uploader's window.

Note that you can also use VirusTotal uploader from the command-line, you just have to provide one or more files as arguments:

C:\path\to\vt\uploader\VirusTotalUpload2.exe file_to_upload.exe

All of the upload modes are restricted to at most 5 submissions at a time.

Scan running processes

Some malware samples keep running in the system as ordinary processes, it is what the antivirus industry calls active malware. VirusTotal uploader includes a feature to help users in identifying active malware, the Upload process executable button. When clicked, VirusTotal uploader will try to find and read the process' image file and send it to VirusTotal.

Fetch and scan an online file

Another handy option will have VirusTotal fetch and scan an online file without you even having to download it first. Type in the URL, or right-click it and choose "Copy link location" to cut and paste it, and then click the Get and upload button. The file will skip through your computer's memory, but will never be saved to your hard drive (by default). You will get the usual list of results and can then decide whether you want the download.

VirusTotal uploader can also be configured to download the files to a temp folder and remove them later or to store them in a specific location by clicking on the Options button.

Since the vast majority of malware infections start with a web download or e-mail attachment, we believe the Get and upload option can proof itself very useful for users.

What is VT Community?

Fighting malware requires close collaboration. The overwhelming malware production rate, the growing problem of false positives and the everlasting threat of false negatives cannot be counteracted without the determined engagement of all actors involved in end-user system security.

Keeping this in mind, VirusTotal has created VT Community, a space where the antivirus industry and malware reserchers can meet end-users in an effort to make internet a safer place. VT Community allows you to rate and place comments on files and web sites. Comments can be of any nature: disinfection instructions, in-the-wild locations, reverse engineering reports, etc.

Signing up to VT Community also entitles you to a VirusTotal API key which enables you to write simple scripts to automate VirusTotal scans and file/url report searches.

How do I start?

Becoming part of VT Community is very simple, click on the Sign in link at the top left hand corner of any VirusTotal page and a small window will open up. Such window has a Create an account link that will take you directly to the registration form.

You will need to provide a user name that will identify you in the community, a valid email address and a password. Once you have completed the registration form an email with an activation link will be sent to your registration email. After following the activation link you can sign in and start interacting with other users.

Build your profile

The goal of the registration process is simplicity. In order to build further your profile click on the Edit profile option of the My account drop down menu after having signed in.

You can customize your avatar, tell others who you really are, set your status phrase, and much more...

Network of trust

VT Community is based on reputation, there are two ways of increasing your reputation credits. The first one is to build a network of trust. When you visit another user's profile after having signed in you will see an interaction menu:

You can request the user's trust by clicking on the corresponding button. You can also trust the visited user. Trusting someone adds 10% of your reputation credits to his account (without subtracting them from yours).

Additionally, users that trust you and users that you trust will be added to the peering section of your personal profile, having a well-known community user in this list can act as a reputation booster with independence of your amount of credits.

Interact with other users

Each user has a personal wall, all registered users can write on someones wall, you can also write to your own wall (as if it were a simple blog). The idea of VT Community is to share knowledge in order to counteract the bad guys, one of the building blocks to do so are the personal walls.

Having said this, VT Community members can also exchange private messages. Private messages should only be used to discuss confidential or sensible information, for example, requesting someone's email address for further discussion.

Review samples and URLs

At the bottom of each URL or file scan report there is a section devoted to comments. We strongly encourage users to review the samples or URLs they submit, it can be very useful information for other users.

For example, let us assume we are software developers. We have uploaded one of our programs to VirusTotal so as to verify whether any antivirus solution incorrectly detects it. Indeed, one of the engines flags our program as a virus, it is time to comment the file and tell other users that this is a false positive. Of course, we wont forget to provide evidence to defend our claim, this could be done by specifying our product's site and describing the program itself.

Note that comments are not report specific, they are file/url specific, in other words, your comments will not be tied to a given moment in time, future submissions of the same file or URL will show up your reviews.

Reviews allow basic markup following the bbcode syntax. These are the accepted tags:

[b]Some text[/b] -- bold text.
[i]Some text[/i] -- italics style.
[u]Some text[/u] -- underlined text.
[s]Some text[/s] -- place a strike through the enclosed text.
[code]source code/disassembly/etc.[/code] -- preformatted section

Some ideas for the subject of your reviews:

• Description of the propagation/dissemination strategy of a given malware. You may want to include any links from where the sample can be downloaded, even though comments do not allow active links, please replace the http prefix with hxxp when referring to malicious content.
• Disinfection procedure to remove the sample (or even better, the family to which it belongs) from your system.
• Reverse engineering reports of malware samples.
• False positive notifications.

There are obviously many more themes for your reviews, as long as it is helpful for someone it will always be an interesting post.

Address your comments

If you are answering another VT Community member's file or URL comment do not forget to address him your answer, you can do this by using the @user_nick syntax:

@EmilianoMartinez

All addressed comments will appear in the destinatary's inbox references section.

Tag your comments

VT Community allows two types of tags. The "official" tags are those which you can check in the checkbox section of the comment posting form. Within the "official" tags there are two special ones: Malware/Goodware for files and Benign/Malicious for URLs. These two tags are the ones that are taken into account to build the community safety score at the top of a report.

Custom tags are also allowed and can be even more helpful for other users than "official" tags. In order to create a custom tag you just have to preceed the word with a "#" symbol inside the comment:

These are the instructions to remove this family of 
malware from your computer, I hope you find them useful...

[... Instructions ...]

#disinfection #zbot

Users can then search through the comments for specific tags by using VirusTotal's search engine.

Vote other's comments

Below file or URL comments there is always a voting menu where you can tell us whether you found the specific comment useful or not.

Useful comments will help other users to identify interesting reviews to read. Useful comments will also add reputation credits to their authors. On the other hand, comments considered as not useful will not subtract reputation credits from a given user, but they will help to identify misleading reviews.

Visit your inbox regularly

Your inbox shows the comments in which you have been referenced, your private messages and any trust requests you receive. Do not forget to visit it regularly.

What is the VirusTotal API?

The VirusTotal API lets you upload and scan files, submit and scan URLs, access finished scan reports and make automatic comments on URLs or samples without the need of using the HTML website interface. In other words, it allows you to build simple scripts to access the information generated by VirusTotal.

The chosen format for the API is HTTP POST requests with JSON object responses and it is limited to at most 20 requests of any nature in a given 5 minutes time frame. If you run a honeyclient, honeypot or any other automation that is going to provide resources to VirusTotal and not only retrieve reports you are entitled to a special API with a higher request rate quota, ask for it at . The public API is a free service, available for any web site or application that is free to consumers.

The API must not be used in commercial products or services, it can not be used as a substitute for antivirus products and it can not be integrated in any project that may harm the antivirus industry directly or indirectly. Noncompliance of these terms will result in inmediate permanent ban of the infractor individual or organization. Please see the terms of use for more information.

How do I start?

The process could not be easier. Sign up to VT Community (using the sign in box at the top left hand side of the page). Once you have a valid VT Community account, you will find your personal API key in the inbox of your account (sign in and drop down the My account menu). This key is all you need to use VirusTotal's API.

So what can I do with the VirusTotal API?

The following examples show how to perform specific tasks with the API, the examples are coded in Python, but take into account that they work with any coding language, you just need to be able to perform HTTP requests and load JSON objects. Some implementations of the API in other languages can be found at the bottom of this page.

Note that the API response format will always be a dictionary containing at least a result field. If the item you searched for was not present this result will be 0, if you exceeded the public API request rate it will be -2, if the API key provided is incorrect it will be -1, any other case is detailed in the following sections.

Retrieve a file scan report

In order to retrieve a scan report on a given file you must perform an HTTP POST request to the following URL:

https://www.virustotal.com/api/get_file_report.json

With the following two HTTP POST parameters:

• resource: a md5/sha1/sha256 hash will retrieve the most recent report on a given sample. You may also specify a permalink identifier (sha256-timestamp as returned by the file upload API) to access a specific report.
• key: your API key.

Some python code will hopefully illustrate better how this is done:

>>> import simplejson
>>> import urllib
>>> import urllib2
>>> url = "https://www.virustotal.com/api/get_file_report.json"
>>> parameters = {"resource": "99017f6eebbac24f351415dd410d522d",
...               "key": "1fe0ef5feca2f84eb450bc3617f839e317b2a686af4d651a9bada77a522201b0"}
>>> data = urllib.urlencode(parameters)
>>> req = urllib2.Request(url, data)
>>> response = urllib2.urlopen(req)
>>> json = response.read()
>>> print json
{"report": ["2010-04-13 23:28:27", {"nProtect": "", 
                                    "CAT-QuickHeal": "", 
                                    "McAfee": "Generic.dx!rkx", 
                                    "TheHacker": "Trojan/VB.gen", 
                                    "VirusBuster": "", 
                                    "NOD32": "a variant of Win32/Qhost.NTY", 
                                    "F-Prot": "", "Symantec": "", 
                                    "Norman": "", 
                                    "a-squared": "Trojan.Win32.VB!IK", ...}], 
 "permalink": "http://www.virustotal.com/file-scan/report.html?id=a8...",
 "result": 1}
>>> response_dict = simplejson.loads(json)
>>> response_dict.get("report")
['2010-04-13 23:28:27', {'nProtect': '', 'CAT-QuickHeal': '', 
'McAfee': 'Generic.dx!rkx', 'TheHacker': 'Trojan/VB.gen', 
'VirusBuster': '', 'NOD32': 'a variant of Win32/Qhost.NTY', 
'F-Prot': '', 'Symantec': '', 'Norman': '', 'Avast': 'Win32:Malware-gen', 
'eSafe': 'Win32.TRVB.Acgy', 'ClamAV': '', 'Kaspersky': 'Trojan.Win32.VB.acgy', 
'BitDefender': 'Trojan.Generic.3611249', 'Comodo': 'Heur.Suspicious', 
'F-Secure': 'Trojan.Generic.3611249', 'DrWeb': 'Trojan.Hosts.37', 
'AntiVir': 'TR/VB.acgy.1', 'TrendMicro': '', 'McAfee-GW-Edition': 'Trojan.VB.acgy.1', 
'Sophos': '', 'eTrust-Vet': '', 'Authentium': '', 'Jiangmin': '', 
'Antiy-AVL': 'Trojan/Win32.VB', 'a-squared': 'Trojan.Win32.VB!IK', 
'Microsoft': '', 'ViRobot': '', 'Prevx': 'Medium Risk Malware', 
'GData': 'Trojan.Generic.3611249', 'AhnLab-V3': '', 'VBA32': '', 
'Sunbelt': 'Trojan.Win32.Generic!BT', 'PCTools': '', 'Rising': '', 
'Ikarus': 'Trojan.Win32.VB', 'Fortinet': '', 'AVG': 'Generic17.ASTJ', 
'Panda': 'Adware/AccesMembre', 'Avast5': 'Win32:Malware-gen'}]

As you can see, the report field of the response is a list with the date of the file scan as its first member and a dictionary of antivirus:result key:value pairs. Whenever a file is not detected by a given antivirus the result is an empty string.

Send and scan a file

The VirusTotal API also allows you to send files. Before performing your submissions we encourage you to retrieve the latest report on the files, if it is recent enough you might want to save time and bandwidth by making use of it.

To send a file you must perform an HTTP POST request to the following URL:

https://www.virustotal.com/api/scan_file.json

This API call expects multipart/form-data parameters, the string part of the the call should have the following parameter:

• key: your API key.

The file part of the call should contain the name of the submitted file and the file itself. We strongly encourage you to send the file with the name with which it was found in the wild since this is very rich metadata for the VirusTotal database. The API acts like a form with a file input field named file.

Some python code will hopefully illustrate better how this is done. Since urllib2 cannot (at least up to python 2.5) send files using POST and multipart/form-data encoding we will use this snippet to help us, let us call it postfile.py. Note that this script was written to work with HTTP connections, API URLs are HTTPS (although you can use traditional HTTP if you desire), so take into account that you should modify the line h = httplib.HTTP(host) to h = httplib.HTTPS(host) in such snippet if your are going to make queries over SSL.

>>> import postfile
>>> host = "www.virustotal.com"
>>> selector = "https://www.virustotal.com/api/scan_file.json"
>>> fields = [("key", "1fe0ef5feca2f84eb450bc3617f839e317b2a686af4d651a9bada77a522201b0")]
>>> file_to_send = open("test.txt", "rb").read()
>>> files = [("file", "test.txt", file_to_send)]
>>> json = postfile.post_multipart(host, selector, fields, files)
>>> print json
{"scan_id": "cd1384c10baa2d5b96f397b986e2a1fc9535d2ef0e185a113fc610eca1c6fb0e-1271623480", 
 "result": 1}

The scan_id field of the JSON object lets us query the report later on making use of the file report retrieval API previously mentioned. Keep in mind that files sent using the API have the lowest scanning priority, depending on VirusTotal's load, it may take several hours before the file is scanned, so query the report at regular intervals until the result shows up and do not keep sending the file once and over again.

Having said this, you might prefer to use Bryce Boe's (@bboe) python snippet for uploading samples to VirusTotal, he has taken care of branching the behaviour depending on whether it is an SSL request, the script can be found in his blog.

Retrieve a URL scan report

In order to retrieve a scan report on a given URL you must perform an HTTP POST request to the following URL:

https://www.virustotal.com/api/get_url_report.json

With the following HTTP POST parameters:

• resource: a URL will retrieve the most recent report on the given URL. You may also specify a permalink identifier (md5-timestamp as returned by the URL submission API) to access a specific report.
• scan (optional): this is an optional parameter that when set to "1" will automatically submit the URL for analysis if no report is found for it in VirusTotal's database. In this case the result will contain a scan_id field that can be used to query the analysis report later on.
• key: your API key.

Some python code will hopefully illustrate better how this is done:

>>> import simplejson
>>> import urllib
>>> import urllib2
>>> url = "https://www.virustotal.com/api/get_url_report.json"
>>> parameters = {"resource": "http://www.google.com",
...               "key": "1fe0ef5feca2f84eb450bc3617f839e317b2a686af4d651a9bada77a522201b0"}
>>> data = urllib.urlencode(parameters)
>>> req = urllib2.Request(url, data)
>>> response = urllib2.urlopen(req)
>>> json = response.read()
>>> print json
{"report": ["2010-04-17 19:13:22", {"Firefox": "Clean site", 
                                    "Opera": "Clean site",
                                    "Google Safebrowsing": "Clean site",
                                    "Phishtank": "Clean site",
                                    "TRUSTe": "Clean site",
                                    "Smartscreen": "Clean site"}], 
 "result": 1, 
"file-report":"9920da8178df4c521f8cd8754c2fc67fd41fd0b098b2c8a41b290179a158b713-1271611297"}
>>> response_dict = simplejson.loads(json)
>>> response_dict.get("report")[1].get("Firefox")
'Clean site'
>>> parameters = {"resource": "http://www.google.com",
...               "key": "1fe0ef5feca2f84eb450bc3617f839e317b2a686af4d651a9bada77a522201b0",
                  "scan": 1}
>>> data = urllib.urlencode(parameters)
>>> req = urllib2.Request(url, data)
>>> response = urllib2.urlopen(req)
>>> json = response.read()
>>> print json
{"scan_id": "4fb49478f1857a41ec1708a397f71206-1288247724", "result": 0}

As you can see, the report field of the response is a list with the date of the URL scan as its first member and a dictionary of scantool:result key:value pairs. The URL is downloaded and sent to the antivirus scanning engine of VirusTotal, the report id of the file scan is presented in the file-report key of the JSON object.

Submit and scan a URL

URLs can also be submitted for scanning. Once again, before performing your submission we encourage you to retrieve the latest report on the URL, if it is recent enough you might want to save time and bandwidth by making use of it.

To submit a URL you must perform an HTTP POST request to the following URL:

https://www.virustotal.com/api/scan_url.json

This API call expects the following HTTP POST parameters:

• url: The URL that should be scanned.
• key: your API key.

Some python code will hopefully illustrate better how this is done:

>>> import simplejson
>>> import urllib
>>> import urllib2
>>> url = "https://www.virustotal.com/api/scan_url.json"
>>> parameters = {"url": "http://www.virustotal.com",
...               "key": "1fe0ef5feca2f84eb450bc3617f839e317b2a686af4d651a9bada77a522201b0"}
>>> data = urllib.urlencode(parameters)
>>> req = urllib2.Request(url, data)
>>> response = urllib2.urlopen(req)
>>> json = response.read()
>>> print json
{"scan_id": "7f911bbcf618f052ac6b9928600d2820-1271621154", "result": 1}

The scan_id parameter of the JSON object can then be used to query for the scan report making use of the URL scan report retrieval API described in the previous section. Keep in mind that URLs sent using the API have the lowest scanning priority, depending on VirusTotal's load, it may take several hours before the URL is scanned, so query the report at regular intervals until the result shows up and do not keep submitting the URL once and over again.

Make comments on files and URLs

The initial idea of VT Community was that users should be able to make comments on files and URLs, the comments may be malware analyses, false positive flags, disinfection instructions, etc.

Imagine you have some automatic setup that can produce interesting results related to a given sample or URL that you submit to VirusTotal for antivirus characterization, you might want to give visibility to your setup by automatically reviewing samples and URLs with the output of your automation.

In order to do so you can make use of VirusTotal's API by performing an HTTP POST request to the following URL:

https://www.virustotal.com/api/make_comment.json

You must provide the following HTTP POST parameters to the call:

• file or url: either a md5/sha1/sha256 hash of the file you want to review or the URL itself that you want to comment on.
• comment: the actual review, you can tag it using the "#" twitter-like syntax (e.g. #disinfection #zbot) and reference users using the "@" syntax (e.g. @EmilianoMartinez).
• tags: this parameter is optional. It should be a semi-colon separated list of standard file or URL tags. The standard file tags are: goodware, malware, spamattachmentorlink, p2pdownload, impropagating, networkworm, drivebydownload. The standard URL tags are: malicious, benign, malwaredownload, phishingsite, browserexploit, spamlink.
• key: your API key.

Some python code will hopefully illustrate better how this is done:

>>> import simplejson
>>> import urllib
>>> import urllib2
>>> url = "https://www.virustotal.com/api/make_comment.json"
>>> parameters = {"file": "99017f6eebbac24f351415dd410d522d",
...               "comment": "How to disinfect you from this file... #disinfect #zbot",
...               "tags": "malware;drivebydownload",
...               "key": "1fe0ef5feca2f84eb450bc3617f839e317b2a686af4d651a9bada77a522201b0"}
>>> data = urllib.urlencode(parameters)
>>> req = urllib2.Request(url, data)
>>> response = urllib2.urlopen(req)
>>> json = response.read()
>>> print json
{"result": 1}

If the comment was successfully posted the result will be 1.

Scripts for using the API

Several VT Community users have made scripts for using the API in different languages, VirusTotal is not responsible for these code snippets, having said this, many of you may find them useful. If you want to see your snippet here just ping VirusTotalTeam.

• Rubi implementation thanks to @HoneyWhales.
• File upload in python thanks to @bboe.
• Perl implementation thanks to @santeri.
• PHP implementation thanks to @omg.
• Java implementation thanks to @sneak.
• Python API client thanks to @Lobe.
• Python batch application for working with VirusTotal's API thanks to @paul_edelman.