Thursday, December 13, 2012

, , , ,

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.