Client

VT module.

exception vt.APIError(code, message)[source]: Class that encapsules errors returned by the VirusTotal API.

class vt.Client(apikey, agent='unknown', host=None, trust_env=False, timeout=300, proxy=None, headers=None, verify_ssl=True)[source]

Client for interacting with VirusTotal.

Parameters:

apikey (str) – Your VirusTotal API key.
agent (str) – A string that identifies your application.
host (str) – By default https://www.virustotal.com, it can be changed for testing purposes.
trust_env (bool) – Get proxies information from HTTP_PROXY/HTTPS_PROXY environment variables if the parameter is True (False by default).
timeout (int) – A int that determines the number of seconds to wait for a request to timeout (300 by default).
proxy (str) – A string indicating the proxy to use for requests made by the client (None by default).
headers (dict) – Dict of headers defined by the user.
verify_ssl (bool) – Whether to verify the certificate in SSL connections.

close()[source]

Closes the client.

When the client is not needed anymore it must be closed for releasing resources like TCP connections.

Not closing the client after it’s used might show error tracebacks indicating it was not properly closed.

async close_async()[source]: Like close() but returns a coroutine.

delete(path, *path_args)[source]

Sends a DELETE request to a given API endpoint.

Parameters:

path (str) – Path to API endpoint, can contain format placeholders {}.
path_args – A variable number of arguments that are put into any placeholders used in path.

Returns:

An instance of ClientResponse.

async delete_async(path, *path_args)[source]: Like delete() but returns a coroutine.

download_file(file_hash, file)[source]

Downloads a file given its _ (SHA-256, SHA-1 or MD5).

The file identified by the hash will be written to the provided file object. The file object must be opened in write binary mode (‘wb’).

Parameters:

file_hash (str) – File hash.
file (file-like object) – A file object where the downloaded file will be written to.

async download_file_async(file_hash, file)[source]: Like download_file() but returns a coroutine.

download_zip_files(hashes, zipfile, password=None, sleep_time=20)[source]

Creates a bundle zip bundle containing one or multiple files.

The file identified by the hash will be written to the provided file object. The file object must be opened in write binary mode (‘wb’).

Parameters:

hashes – list of file hashes (SHA-256, SHA-1 or MD5).
zipfile – A file object where the downloaded zip file will be written to.
password – optional, a password to protect the zip file.
sleep_time – optional, seconds to sleep between each request.

feed(feed_type, cursor=None)[source]

Returns an iterator for a VirusTotal feed.

This functions returns an iterator that allows to retrieve a continuous stream of files as they are scanned by VirusTotal. See the documentation for the Feed class for more details.

Parameters:

feed_type – One of the supported feed types enumerated in FeedType.
cursor (str) – An optional cursor indicating where to start. This argument can be a string in the format ‘YYYMMDDhhmm’ indicating the date and time of the first package that will be retrieved.

get(path, *path_args, params=None)[source]

Sends a GET request to a given API endpoint.

This is a low-level function that returns a raw HTTP response, no error checking nor response parsing is performed. See get_json(), get_data() and get_object() for higher-level functions.

Parameters:

path (str) – Path to API endpoint, can contain format placeholders {}.
path_args – A variable number of arguments that are put into any placeholders used in path.
params (dict) – Parameters sent in the request.

Returns:

An instance of ClientResponse.

async get_async(path, *path_args, params=None)[source]: Like get() but returns a coroutine.

get_data(path, *path_args, params=None)[source]

Sends a GET request to a given API endpoint and returns response’s data.

Most VirusTotal API responses are JSON-encoded with the following format:

{"data": <response data>}

This function parses the server’s response and return only the data, if the response is not in the expected format an exception is raised. For endpoints where the data is a VirusTotal object you can use get_object() instead.

Parameters:

path (str) – Path to API endpoint, can contain format placeholders {}.
path_args – A variable number of arguments that are put into any placeholders used in path.
params (dict) – Parameters sent in the request.

Returns:

Whatever the server returned in the response’s data field, it may be a dict, list, string or some other Python type, depending on the endpoint called.

async get_data_async(path, *path_args, params=None)[source]: Like get_data() but returns a coroutine.

async get_error_async(response)[source]

Given a ClientResponse returns a APIError

This function checks if the response from the VirusTotal backend was an error and returns the appropriate APIError or None if no error occurred.

Parameters:: response – A ClientResponse instance.
Returns:: An instance of APIError or None.

get_json(path, *path_args, params=None)[source]

Sends a GET request to a given API endpoint and parses the response.

Most VirusTotal API responses are JSON-encoded. This function parses the JSON, check for errors, and return the server response as a dictionary.

Parameters:

path (str) – Path to API endpoint, can contain format placeholders {}.
path_args – A variable number of arguments that are put into any placeholders used in path.
params (dict) – Parameters sent in the request.

Returns:

A dictionary with the backend’s response.

async get_json_async(path, *path_args, params=None)[source]: Like get_json() but returns a coroutine.

get_object(path, *path_args, params=None)[source]

Sends a GET request to a given API endpoint and returns an object.

The endpoint specified must return an object, not a collection. This means that get_object can be used with endpoints like /files/{file_id} and /urls/{url_id}, which return an individual object but not with /comments, which returns a collection of objects.

Parameters:

path (str) – Path to API endpoint, can contain format placeholders {}.
path_args – A variable number of arguments that are put into any placeholders used in path.
params (dict) – Parameters sent in the request.

Returns:

An instance of Object.

async get_object_async(path, *path_args, params=None)[source]: Like get_object() but returns a coroutine.

iterator(path, *path_args, params=None, cursor=None, limit=None, batch_size=0)[source]

Returns an iterator for the collection specified by the given path.

The endpoint specified by path must return a collection of objects. An example of such an endpoint are /comments and /intelligence/search.

Parameters:

path (str) – Path to API endpoint returning a collection.
path_args – A variable number of arguments that are put into any placeholders used in path.
params (dict) – Additional parameters passed to the endpoint.
cursor (str) – Cursor for resuming the iteration at the point it was left previously. A cursor can be obtained with Iterator.cursor(). This cursor is not the same one returned by the VirusTotal API.
limit (int) – Maximum number of objects that will be returned by the iterator. If a limit is not provided the iterator continues until it reaches the last object in the collection.
batch_size (int) – Maximum number of objects retrieved on each call to the endpoint. If not provided the server will decide how many objects to return.

Returns:

An instance of Iterator.

patch(path, *path_args, data=None, json_data=None)[source]

Sends a PATCH request to a given API endpoint.

This is a low-level function that returns a raw HTTP response, no error checking nor response parsing is performed. See patch_object() for a higher-level function.

Parameters:

path (str) – Path to API endpoint, can contain format placeholders {}.
path_args – A variable number of arguments that are put into any placeholders used in path.
data (A string or bytes) – Data sent in the request body.
json_data (dict) – dict containing data to send in the request body as JSON.

Returns:

An instance of ClientResponse.

async patch_async(path, *path_args, data=None, json_data=None)[source]: Like patch() but returns a coroutine.

patch_object(path, *path_args, obj)[source]

Sends a PATCH request for modifying an object.

This function modifies an object. The endpoint must be one that identifies an object, like /intelligence/hunting_rulesets/{id}.

Parameters:

path (str) – Path to API endpoint, can contain format placeholders {}.
path_args – A variable number of arguments that are put into any placeholders used in path.
obj (Object) – Object that has been modified.

Returns:

An instance of Object representing the same object after the changes has been applied.

async patch_object_async(path, *path_args, obj)[source]: Like patch_object() but returns a coroutine.

post(path, *path_args, data=None, json_data=None)[source]

Sends a POST request to a given API endpoint.

This is a low-level function that returns a raw HTTP response, no error checking nor response parsing is performed. See post_object() for a higher-level function.

Parameters:

path (str) – Path to API endpoint, can contain format placeholders {}.
path_args – A variable number of arguments that are put into any placeholders used in path.
data (A string or bytes) – Data sent in the request body.
json_data (dict) – dict containing data to send in the request body as JSON.

Returns:

An instance of ClientResponse.

async post_async(path, *path_args, data=None, json_data=None)[source]: Like post() but returns a coroutine.

post_object(path, *path_args, obj)[source]

Sends a POST request for creating an object.

This function create a new object. The endpoint must be one that identifies a collection, like /intelligence/hunting_rulesets.

Parameters:

path (str) – Path to API endpoint.
path_args – A variable number of arguments that are put into any placeholders used in path.
obj (Object) – Instance Object with the type expected by the API endpoint.

Returns:

An instance of Object representing the new object.

async post_object_async(path, *path_args, obj)[source]: Like post_object() but returns a coroutine.

scan_file(file, wait_for_completion=False)[source]

Scans a file.

Parameters:

file (File-like object.) – File to be scanned.
wait_for_completion (bool) – If True the function doesn’t return until the analysis has been completed.

Returns:

An instance of Object of analysis type.

async scan_file_async(file, wait_for_completion=False)[source]: Like scan_file() but returns a coroutine.

scan_url(url, wait_for_completion=False)[source]

Scans a URL.

Parameters:

url (str) – The URL to be scanned.
wait_for_completion (bool) – If True the function doesn’t return until the analysis has been completed.

Returns:

An instance of Object of analysis type.

async scan_url_async(url, wait_for_completion=False)[source]: Like scan_url() but returns a coroutine.

class vt.ClientResponse(aiohttp_resp)[source]

Class representing the HTTP responses returned by the client.

This class is just a thing wrapper around aiohttp.ClientResponse that allows using it in both asynchronous and synchronous mode. Instances of this class have all the attributes that you can find in aiohttp.ClientResponse, like version, status, method, url, and so on. Methods in aiohttp.ClientResponse that return a coroutine have two flavors in this class: synchronous and asynchronous. For example, aiohttp.ClientResponse.read() becomes vt.ClientResponse.read_async(), and vt.ClientResponse.read() is the synchronous version of vt.ClientResponse.read_async(). Find more information about attributes and methods in aiohttp.ClientResponse in:

https://aiohttp.readthedocs.io/en/stable/client_reference.html#aiohttp.ClientResponse