vt-py

The vt-py library is designed to be a lightweight, generic wrapper around the VirusTotal REST API rather than a high-level abstraction that hides it.

Key characteristics include:

• API Parity: The library's API closely mirrors the underlying VirusTotal REST API. You will frequently need to refer to the VirusTotal REST API documentation to identify correct endpoints and object attributes.
• Generic HTTP Methods: It provides generic methods like vt.Client.get and vt.Client.post to interact with endpoints.
• Reduced Boilerplate: While it doesn't abstract away the API structure, it handles low-level details such as setting HTTP headers and serializing/deserializing JSON.
• Resilience: Because it is lightweight and generic, changes to the VirusTotal REST API often do not require a new version of the vt-py client library.

The easiest and recommended method to install the vt-py library is via pip.

$ pip install vt-py

You can install vt-py from source by cloning the GitHub repository or downloading a release tarball, then running pip install . from within the project directory.

# Option 1: Clone from GitHub
$ git clone https://github.com/VirusTotal/vt-py.git
$ cd vt-py
$ pip install .

# Option 2: Use a downloaded tarball
$ tar -zxvf vt-py-X.Y.Z.tar.gz
$ cd vt-py-X.Y.Z
$ pip install .

To use vt-py, import the vt module and instantiate a vt.Client with your API key. It is recommended to use the client as a context manager to ensure it is properly closed at the end of your script, which prevents tracebacks related to unclosed clients.

import vt

# Using a context manager (recommended)
with vt.Client("<apikey>") as client:
    # Your code here
    pass

# Manual initialization
client = vt.Client("<apikey>")
# ... perform tasks ...
client.close()

The ClientResponse class wraps aiohttp.ClientResponse to provide both synchronous and asynchronous methods for reading response data. It also handles chunked transfer encoding automatically.

Available Methods:

• read() / read_async(): Returns response body as bytes.
• json() / json_async(): Returns response body as a dict.
• text() / text_async(): Returns response body as a str.
• content: Returns a StreamReader for streaming the response body.

Note: Methods ending in _async are coroutines and must be awaited.

# Async example
response = await client.get_async('/some/endpoint')
data = await response.json_async()

# Sync example
response = client.get('/some/endpoint')
data = response.json()

To use the examples in a Jupyter environment, you need to install vt-py and nest_asyncio (which allows nested event loops in Jupyter).

!pip install vt-py nest_asyncio

The vt.Client class is the primary entry point for using the vt-py library. It manages the connection to the VirusTotal API and provides methods for making requests. You must provide an API key when initializing the client.

Commonly associated types include:

• Client: The main client instance.
• ClientResponse: Represents the response received from the API.
• APIError: The exception raised when an API request fails.

import vt

client = vt.Client('YOUR_API_KEY')
# Use client to make API calls

The vt.url_id utility function converts a standard URL into a VirusTotal-compatible URL ID. This ID is used when performing lookups or interacting with URL objects via the API, ensuring the URL is properly formatted for VirusTotal's internal identification system.

import vt

url_id = vt.url_id("https://www.google.com")
# Returns the formatted ID used for API requests

To retrieve information about a URL, you must first generate a unique identifier using vt.url_id(). This identifier is then used to construct the API path. You can use Python's string formatting to inject the url_id into the path string.

import vt
client = vt.Client("<apikey>")

# Generate the required URL identifier
url_id = vt.url_id("http://www.virustotal.com")

# Retrieve the URL object
url = client.get_object("/urls/{}", url_id)
# OR using string formatting:
# url = client.get_object("/urls/{}".format(url_id))

print(url.times_submitted)