pyvt 0.1a4

pyvt
====

Python 3 implementation of the
`Virustotal <https://www.virustotal.com/>`__ `Private
API <https://www.virustotal.com/en/documentation/private-api/>`__. In
its current form it only implements a subset of the API and is
incomplete.

This module borrows code from, the
`virustotal2 <https://github.com/Phillipmartin/virustotal2>`__ module.
It uses the same rate limiting logic as virustotal2. Additionally it
unifies the output of the API to json format and adds support for bulk
queries.

How To Use
----------

::

import pyvt

api = pyvt.API('~/.virustotal.key')
# Retrieve list of ips
api.retrieve(['173.236.179.77', '66.33.221.102'])

# Retrieve list of urls
api.retrieve(['http://3dtaller.com.ar/',
'http://3dtaller.com.ar/wp-content/themes/theme1392/js/jquery.loader.js',
'http://3dtaller.com.ar/wp-includes/js/swfobject.js',
'http://3dtaller.com.ar/wp-content/themes/theme1392/js/modernizr-2.0.js',
'http://3dtaller.com.ar/wp-content/themes/theme1392/js/custom.js',
'http://3dtaller.com.ar/wp-content/themes/theme1392/js/jquery-1.6.4.min.js'])

# Retrieve domain
api.retrieve('3dtaller.com.ar')

Installiation
-------------

::

pip3 install pyvt --pre

Instantiation
-------------

::

api = pyvt.API('~/.virustotal.key') # The default way of using the
api = pyvt.API('', api_key=<VT API KEY>, limit_per_min=<number>) # Providing other parameters

You can pass limit\_per\_min, which is the number of queries you can
perform per minute. 3000 is the default. You can also alternatively
provide your api\_key as a string parameter.

API
===

Use the method retrieve() to get an existing report from VirusTotal.
This method's first argument can be:

- a single or list of MD5, SHA1 or SHA256 of files
- a single or list of URLs
- a single or list IP addresses
- a single or list of domain names

retrieve() will attempt to auto-detect what you're giving it. If you
want to be explicit, you can use the thing\_type parameter with the
values:

- ip
- domain
- hash
- file
- base64
- url

These values are provided as constants that you can use instead in the
'API\_Constans' class which you can import as follows ::

::

from pyvt import API_Constansts

You can use thee scan() method to scan specific URLs. The scan method
currently only supports URLs and will through an exception if anything
other than a url is given to it.

Here is an example usage of the scan method that blocks until all scan
results are available.

::

response, fail = api.scan(['http://3dtaller.com.ar/',
'http://3dtaller.com.ar/wp-content/themes/theme1392/js/jquery.loader.js',
'http://3dtaller.com.ar/wp-includes/js/swfobject.js',
'http://3dtaller.com.ar/wp-content/themes/theme1392/js/modernizr-2.0.js',
'http://3dtaller.com.ar/wp-content/themes/theme1392/js/custom.js',
'http://3dtaller.com.ar/wp-content/themes/theme1392/js/jquery-1.6.4.min.js'], blocking=True)


Here is another usage example of the scan method that is none blocking.

::

response, fail = api.scan(['http://3dtaller.com.ar/',
'http://3dtaller.com.ar/wp-content/themes/theme1392/js/jquery.loader.js',
'http://3dtaller.com.ar/wp-includes/js/swfobject.js',
'http://3dtaller.com.ar/wp-content/themes/theme1392/js/modernizr-2.0.js',
'http://3dtaller.com.ar/wp-content/themes/theme1392/js/custom.js',
'http://3dtaller.com.ar/wp-content/themes/theme1392/js/jquery-1.6.4.min.js'])

With the non-blocking call you will need to use the 'retrieve' method to
get the results of the scan at a later stage. Note that the 'scan'
method will return a Tuple where the second element is the urls for
which the Virustotal API returned a Failure status response code and the
method will not attempt to submit again.

References
~~~~~~~~~~

`Virustotal Private
API <https://www.virustotal.com/en/documentation/private-api/>`__