Description

'vt_driver.py' is a small Python utility which rely on the VirusTotal API in order to verify if a file was already identified as malware.

API Key: in order to work this script needs a valid VirusTotal API key, which can be obtained by registering yourself here.

Python 2 vs. 3

Starting from version tagged 0.5, this script is meant to be executed using Python version 3.x. Otherwise use the version tagged as 0.4.

Usage

>>> vt_driver.py -f config_file -s malware_sample

The template config/vt_config_template.cfg can be used as a reference for your own config file.

Available configuration parameters are the following:

• API_KEY: to access the public or private API of VirusTotal a user has to be registered.
• quiet: if 'false' the script will not report any output.
• full_report: if 'true' and 'quiet' is set to 'false' then full report from VirusTotal will be printed.
• hashlib_alg: hashing algorithms (available options are: sha1, sha256 or md5).
• signature_gen: if 'true' a ClamAV compatibile signature archive will be generated.
• persistence: if 'true' the script will keep track of the submitted samples on a SQLite Db.
• name_prefix: a string used as a prefix for the ClamAV signature.

Additional Drivers

The following scripts are available in the scripts/ directory:

vt_ip_driver.py

Checks an IP address against the VirusTotal v3 API.

>>> vt_ip_driver.py -f config_file -i <ip_address>

Uses the same config file template as the main driver. Supports the quiet and full_report parameters.

vt_url_driver.py

Analyzes a URL using the VirusTotal v3 API.

>>> vt_url_driver.py -f config_file -u <url>

Submits the URL for analysis and polls until results are available. Uses the same config file template. Supports the quiet and full_report parameters.

VirusTotal API

The internal behaviour of the script is based on the response code from the VirusTotal API:

• if the item you searched for was not present in VirusTotal's dataset this result will be 0.
• if the requested item is still queued for analysis it will be -2.
• if the item was indeed present and it could be retrieved it will be 1.

Reference: VirusTotal API responses

Public vs Premium VirusTotal API

Note that according to the documentation, there are some explicit limits in using the Public API of VirusTotal:

• The Public API is limited to 4 requests per minute and a total of 500 requests per day.
• The Public API must not be used in commercial products or services.
• The Private API returns more threat data and exposes more endpoints.
• The Private API is governed by an SLA that guarantees readiness of data.

Required Python modules

• Objectpath
• SimpleJSON
• Python-Magic
• VirusTotal API

To install all the required modules:

>>> pip install -r requirements.txt

In order to run a quick test it would be easier to install the vt_driver.py script and its required modules in a virtual environment. Two methods are available:

• If you are using python 2.7.x, it's better to setup a virtual environment through VirtualEnv.
• If you are using python 3.x, the recommended way to setup a virtual environment is through venv.

Samples

• NOTE: The material available at these URLs may be extremely dangerous to your computer and your internal network. These URLs are provided solely to test the scripts against the VirusTotal API entry points. YOU HAVE BEEN WARNED:
  • URLhaus Database
  • Malware Bazaar

References

• VirusTotal: getting started
• VirusTotal API on Pypi.org
• ObjectPath: a NoSQL query language for semi-structured data
• SimpleJSON: simple, fast, extensible JSON encoder/decoder for Python
• Python-Magic: file type identification using libmagic