VirusTotalAPIFiles

The analysis new files and retrieving information about any file from the VirusTotal database methods are defined in the class.

Methods:

get_file_id(file_path, hash_alg)

Get SHA256, SHA1 or MD5 file identifier.

Arguments:

file_path : Path to the file to be scanned (str).
hash_alg : Necessary identifier (sha256, sha1 or md5). The default value is sha256.

Return value:

The SHA256, SHA1 or MD5 identifier of the file (str).

Exception:

VirusTotalAPIError (File not found): In case the file you want to upload to the server is not found.
VirusTotalAPIError (Permission error): In case do not have access rights to the file.

Usage:

from vtapi3 import VirusTotalAPIFiles, VirusTotalAPIError
    ...
try:
    file_id = VirusTotalAPIFiles.get_file_id('<file path>')
except VirusTotalAPIError as err:
    print(err, err.err_code)
else:
    print(file_id)
    ...

upload(file_path)

Upload and analyse a file.

Arguments:

file_path : Path to the file to be scanned (str).

Return value:

The response from the server as a byte sequence.

Exception:

VirusTotalAPIError (Connection error): In case of server connection errors.
VirusTotalAPIError (Timeout error): If the response timeout from the server is exceeded.
VirusTotalAPIError (File not found): In case the file you want to upload to the server is not found.
VirusTotalAPIError (Permission error): In case do not have access rights to the file.

Usage:

from vtapi3 import VirusTotalAPIFiles, VirusTotalAPIError
   ...
vt_api_files = VirusTotalAPIFiles('<API key>')
try:
    result = vt_api_files.upload('<file path>')
except VirusTotalAPIError as err:
    print(err, err.err_code)
else:
    if vt_api_files.get_last_http_error() == vt_api_files.HTTP_OK:
        result = json.loads(result)
        result = json.dumps(result, sort_keys=False, indent=4)
        print(result)
    else:
        print('HTTP Error [' + str(vt_api_files.get_last_http_error()) +']')
    ...

Note

The total payload size can not exceed 32 MB. For uploading larger files see the get_upload_url() .

Example response:

When _last_http_error = HTTP_OK and after conversion to JSON, the response will look like this:

{
  "data": {
    "type": "analysis",
    "id": "NjY0MjRlOTFjMDIyYTkyNWM0NjU2NWQzYWNlMzFmZmI6MTQ3NTA0ODI3Nw=="
  }
}

get_upload_url()

Get a URL for uploading files larger than 32 MB.

Arguments:

None.

Return value:

The response from the server as a byte sequence.

Exception:

VirusTotalAPIError (Connection error): In case of server connection errors.
VirusTotalAPIError (Timeout error): If the response timeout from the server is exceeded.

Usage:

from vtapi3 import VirusTotalAPIFiles, VirusTotalAPIError
   ...
vt_api_files = VirusTotalAPIFiles('<API key>')
try:
    result = vt_api_files.get_upload_url()
except VirusTotalAPIError as err:
    print(err, err.err_code)
else:
    if vt_api_files.get_last_http_error() == vt_api_files.HTTP_OK:
        result = json.loads(result)
        result = json.dumps(result, sort_keys=False, indent=4)
        print(result)
    else:
        print('HTTP Error [' + str(vt_api_files.get_last_http_error()) +']')
    ...

Example response:

When _last_http_error = HTTP_OK and after conversion to JSON, the response will look like this:

{
  "data": "http://www.virustotal.com/_ah/upload/AMmfu6b-_DXUeFe36Sb3b0F4B8mH9Nb-CHbRoUNVOPwG/"
}

get_report(file_id)

Retrieve information about a file.

Arguments:

fle_id : SHA-256, SHA-1 or MD5 identifying the file (str).

Return value:

The response from the server as a byte sequence.

Exception:

VirusTotalAPIError (Connection error): In case of server connection errors.
VirusTotalAPIError (Timeout error): If the response timeout from the server is exceeded.

Usage:

from vtapi3 import VirusTotalAPIFiles, VirusTotalAPIError
   ...
vt_api_files = VirusTotalAPIFiles('<API key>')
try:
    result = vt_api_files.get_report('<file id>')
except VirusTotalAPIError as err:
    print(err, err.err_code)
else:
    if vt_api_files.get_last_http_error() == vt_api_files.HTTP_OK:
        result = json.loads(result)
        result = json.dumps(result, sort_keys=False, indent=4)
        print(result)
    else:
        print('HTTP Error [' + str(vt_api_files.get_last_http_error()) +']')
    ...

analyse(file_id)

Reanalyse a file already in VirusTotal.

Arguments:

fle_id : SHA-256, SHA-1 or MD5 identifying the file (str).

Return value:

The response from the server as a byte sequence.

Exception:

VirusTotalAPIError (Connection error): In case of server connection errors.
VirusTotalAPIError (Timeout error): If the response timeout from the server is exceeded.

Usage:

from vtapi3 import VirusTotalAPIFiles, VirusTotalAPIError
   ...
vt_api_files = VirusTotalAPIFiles('<API key>')
try:
    result = vt_api_files.analyse('<file id>')
except VirusTotalAPIError as err:
    print(err, err.err_code)
else:
    if vt_api_files.get_last_http_error() == vt_api_files.HTTP_OK:
        result = json.loads(result)
        result = json.dumps(result, sort_keys=False, indent=4)
        print(result)
    else:
        print('HTTP Error [' + str(vt_api_files.get_last_http_error()) +']')
    ...

Example response:

When _last_http_error = HTTP_OK and after conversion to JSON, the response will look like this:

{
  "data": {
    "type": "analysis",
    "id": "NjY0MjRlOTFjMDIyYTkyNWM0NjU2NWQzYWNlMzFmZmI6MTQ3NTA0ODI3Nw=="
  }
}

get_comments(file_id, limit, cursor)

Retrieve comments for a file.

Arguments:

fle_id : SHA-256, SHA-1 or MD5 identifying the file (str).
limit : Maximum number of comments to retrieve (int). The default value is 10.
cursor : Continuation cursor (str). The default value is ‘’.

Return value:

The response from the server as a byte sequence.

Exception:

VirusTotalAPIError (Connection error): In case of server connection errors.
VirusTotalAPIError (Timeout error): If the response timeout from the server is exceeded.

Usage:

from vtapi3 import VirusTotalAPIFiles, VirusTotalAPIError
   ...
vt_api_files = VirusTotalAPIFiles('<API key>')
try:
    result = vt_api_files.get_comments('<file id>', 5)
except VirusTotalAPIError as err:
    print(err, err.err_code)
else:
    if vt_api_files.get_last_http_error() == vt_api_files.HTTP_OK:
        result = json.loads(result)
        result = json.dumps(result, sort_keys=False, indent=4)
        print(result)
    else:
        print('HTTP Error [' + str(vt_api_files.get_last_http_error()) +']')
    ...

put_comments(file_id, text)

Add a comment to a file.

Arguments:

fle_id : SHA-256, SHA-1 or MD5 identifying the file (str).
text : Text of the comment (str). Any word starting with # in your comment’s text will be considered a tag, and added to the comment’s tag attribute.

Return value:

The response from the server as a byte sequence.

Exception:

VirusTotalAPIError (Connection error): In case of server connection errors.
VirusTotalAPIError (Timeout error): If the response timeout from the server is exceeded.

Usage:

from vtapi3 import VirusTotalAPIFiles, VirusTotalAPIError
   ...
vt_api_files = VirusTotalAPIFiles('<API key>')
try:
    result = vt_api_files.put_comment('<file id>', '<text of the comment>')
except VirusTotalAPIError as err:
    print(err, err.err_code)
else:
    if vt_api_files.get_last_http_error() == vt_api_files.HTTP_OK:
        result = json.loads(result)
        result = json.dumps(result, sort_keys=False, indent=4)
        print(result)
    else:
        print('HTTP Error [' + str(vt_api_files.get_last_http_error()) +']')
    ...

Example response:

When _last_http_error = HTTP_OK and after conversion to JSON, the response will look like this:

{
  "data": {
    "type": "comment",
    "id": "<comment's ID>",
    "links": {
      "self": "https://www.virustotal.com/api/v3/comments/<comment's ID>"
    },
    "attributes": {
      "date": 1521725475,
      "tags": ["ipsum"],
      "html": "Lorem #ipsum dolor sit ...",
      "text": "Lorem #ipsum dolor sit ...",
      "votes": {
        "abuse": 0,
        "negative": 0,
        "positive": 0
      }
    }
  }
}

get_votes(file_id, limit, cursor)

Retrieve votes for a file.

Arguments:

fle_id : SHA-256, SHA-1 or MD5 identifying the file (str).
limit : Maximum number of vites to retrieve (int). The default value is 10.
cursor : Continuation cursor (str). The default value is ‘’.

Return value:

The response from the server as a byte sequence.

Exception:

VirusTotalAPIError (Connection error): In case of server connection errors.
VirusTotalAPIError (Timeout error): If the response timeout from the server is exceeded.

Usage:

from vtapi3 import VirusTotalAPIFiles, VirusTotalAPIError
   ...
vt_api_files = VirusTotalAPIFiles('<API key>')
try:
    result = vt_api_files.get_votes('<file id>', 5)
except VirusTotalAPIError as err:
    print(err, err.err_code)
else:
    if vt_api_files.get_last_http_error() == vt_api_files.HTTP_OK:
        result = json.loads(result)
        result = json.dumps(result, sort_keys=False, indent=4)
        print(result)
    else:
        print('HTTP Error [' + str(vt_api_files.get_last_http_error()) +']')
    ...

put_votes(file_id, malicious)

Add a vote to a file.

Arguments:

fle_id : SHA-256, SHA-1 or MD5 identifying the file (str).
malicious : Determines a malicious (True) or harmless (False) file (bool). The default value is False.

Return value:

The response from the server as a byte sequence.

Exception:

VirusTotalAPIError (Connection error): In case of server connection errors.
VirusTotalAPIError (Timeout error): If the response timeout from the server is exceeded.

Usage:

from vtapi3 import VirusTotalAPIFiles, VirusTotalAPIError
   ...
vt_api_files = VirusTotalAPIFiles('<API key>')
try:
    result = vt_api_files.put_votes('<file id>', True)
except VirusTotalAPIError as err:
    print(err, err.err_code)
else:
    if vt_api_files.get_last_http_error() == vt_api_files.HTTP_OK:
        result = json.loads(result)
        result = json.dumps(result, sort_keys=False, indent=4)
        print(result)
    else:
        print('HTTP Error [' + str(vt_api_files.get_last_http_error()) +']')
    ...

get_relationship(file_id, relationship, limit, cursor)

Retrieve objects related to a file.

Arguments:

fle_id : SHA-256, SHA-1 or MD5 identifying the file (str).
relationship : Relationship name (str). The default value is /behaviours. For more information, see https://developers.virustotal.com/v3.0/reference#files-relationships.
limit : Maximum number of related objects to retrieve (int). The default value is 10.
cursor : Continuation cursor (str). The default value is ‘’.

Return value:

The response from the server as a byte sequence.

Exception:

VirusTotalAPIError (Connection error): In case of server connection errors.
VirusTotalAPIError (Timeout error): If the response timeout from the server is exceeded.

Usage:

from vtapi3 import VirusTotalAPIFiles, VirusTotalAPIError
   ...
vt_api_files = VirusTotalAPIFiles('<API key>')
try:
    result = vt_api_files.get_relationship('<file id>', 'bundled_files')
except VirusTotalAPIError as err:
    print(err, err.err_code)
else:
    if vt_api_files.get_last_http_error() == vt_api_files.HTTP_OK:
        result = json.loads(result)
        result = json.dumps(result, sort_keys=False, indent=4)
        print(result)
    else:
        print('HTTP Error [' + str(vt_api_files.get_last_http_error()) +']')
    ...

get_behaviours(sandbox_id)

Get the PCAP for the sandbox.

Arguments:

sandbox_id : Identifier obtained using the get_relationship(file_id, relationship, limit, cursor) method with the value of the relationship argument equal to behaviours (str).

Return value:

The response from the server as a byte sequence.

Exception:

VirusTotalAPIError (Connection error): In case of server connection errors.
VirusTotalAPIError (Timeout error): If the response timeout from the server is exceeded.

Usage:

from vtapi3 import VirusTotalAPIFiles, VirusTotalAPIError
   ...
vt_api_files = VirusTotalAPIFiles('<API key>')
try:
    result = vt_api_files.get_relationship('<file id>', 'bundled_files')
except VirusTotalAPIError as err:
    print(err, err.err_code)
else:
    if vt_api_files.get_last_http_error() == vt_api_files.HTTP_OK:
        result = json.loads(result)
        result = json.dumps(result, sort_keys=False, indent=4)
        print(result)
    else:
        print('HTTP Error [' + str(vt_api_files.get_last_http_error()) +']')
    ...

get_download_url(file_id)

Get a download URL for a file (added in version 1.2.0).

Warning

This function is only available for users with special privileges. You need a private key to access the VirusTotal API.

Arguments:

file_id : SHA-256, SHA-1 or MD5 identifying the file (str).

Return value:

The response from the server as a byte sequence.

Exception:

VirusTotalAPIError (Connection error): In case of server connection errors.
VirusTotalAPIError (Timeout error): If the response timeout from the server is exceeded.

Usage:

from vtapi3 import VirusTotalAPIFiles, VirusTotalAPIError
   ...
vt_api_files = VirusTotalAPIFiles('<API key>')
try:
    result = vt_api_files.get_download_url('<file id>')
except VirusTotalAPIError as err:
    print(err, err.err_code)
else:
    if vt_api_files.get_last_http_error() == vt_api_files.HTTP_OK:
        result = json.loads(result)
        result = json.dumps(result, sort_keys=False, indent=4)
        print(result)
    else:
        print('HTTP Error [' + str(vt_api_files.get_last_http_error()) +']')
    ...

get_download(file_id)

Download a file (added in version 1.2.0).

Warning

This function is only available for users with special privileges. You need a private key to access the VirusTotal API.

Arguments:

file_id : SHA-256, SHA-1 or MD5 identifying the file (str).

Return value:

The response from the server as a byte sequence.

Exception:

VirusTotalAPIError (Connection error): In case of server connection errors.
VirusTotalAPIError (Timeout error): If the response timeout from the server is exceeded.

Usage:

from vtapi3 import VirusTotalAPIFiles, VirusTotalAPIError
   ...
vt_api_files = VirusTotalAPIFiles('<API key>')
try:
    result = vt_api_files.get_download('<file id>')
except VirusTotalAPIError as err:
    print(err, err.err_code)
else:
    if vt_api_files.get_last_http_error() == vt_api_files.HTTP_OK:
        result = json.loads(result)
        result = json.dumps(result, sort_keys=False, indent=4)
        print(result)
    else:
        print('HTTP Error [' + str(vt_api_files.get_last_http_error()) +']')
    ...