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
ormd5
). The default value issha256
.
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 isFalse
.
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 therelationship
argument equal tobehaviours
(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()) +']')
...