Welcome to virustotal3’s documentation!

virustotal3 core

VirusTotal API v3 Core

Module to interact with the Core part of the API.

class core.Domains(api_key=None, proxies=None)

Class for the Domains endpoints

add_vote(domain, verdict, timeout=None)

Adds a verdict (vote) to a domain. The verdict can be either ‘malicious’ or ‘harmless’.

Parameters:
  • domain (str) – Domain
  • verdict (str) – ‘malicious’ (-1) or ‘harmless’ (+1)
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the submitted vote.

get_relationship(domain, relationship, limit=None, cursor=None, timeout=None)

Retrieve objects related to a domain

Parameters:
  • url (str) – URL identifier
  • relationship (str) –

    Relationship object to retrieve. Can be one of the following: communicating_files, downloaded_files, graphs, referrer_files, resolutions, siblings, subdomains, urls

    For further details, see: https://developers.virustotal.com/v3.0/reference#domains-relationships

  • limit (str, optional) – Limit of results to return
  • cursor (str, optional) – Continuation cursor
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the relationship object.

get_votes(domain, limit=None, cursor=None, timeout=None)

Retrieve votes for a domain

Parameters:
  • domain (str) – Domain
  • limit (int, optional) – Maximum number of rulesets to retrieve
  • cursor (str, optional) – Continuation cursor
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the votes. The votes are located in the ‘value’ key.

info_domain(domain, timeout=None)

Retrieve information about a domain

Parameters:
  • domain (str) – Domain to scan
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the scan results.

class core.Files(api_key=None, proxies=None)

Class for the Files endpoints

add_comment(file_hash, comment, timeout=None)

Add a comment to a file

Parameters:
  • file_hash (str) – File hash (SHA256, MD5, SHA1)
  • data (dict) – Comment to add as dictionary. The package will take care of creating the JSON object.
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the added comment.

add_vote(file_hash, verdict, timeout=None)

Adds a verdict (vote) to a file. The verdict can be either ‘malicious’ or ‘harmless’.

Parameters:
  • file_hash (str) – File hash (SHA256, MD5, SHA1)
  • verdict (str) – ‘malicious’ (-1) or ‘harmless’ (+1)
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the submitted vote.

analyse_file(file_hash, timeout=None)

Re-analyse a file already in VirusTotal.

Parameters:
  • file_hash (str) – File hash to re-analyse
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the analysis ID.

download(file_hash, output_dir='./', timeout=None)

Download a file for a given file hash.

Parameters:
  • file_hash (str) – File hash (SHA256, MD5, SHA1)
  • output_dir (str, optional) – Output directory, current working directory by default.
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

None

get_comments(file_hash, limit=None, cursor=None, timeout=None)

Retrieve comments for a file

Parameters:
  • file_hash (str) – File hash (SHA256, MD5, SHA1)
  • limit (int, optional) – Maximum number of rulesets to retrieve
  • cursor (str, optional) – Continuation cursor
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the comments retrieved.

get_relationship(file_id, relationship, limit=None, cursor=None, timeout=None)

Retrieve an object related to a file

Parameters:
  • file_hash (str) – File hash (SHA256, MD5, SHA1)
  • relationsip (str) –

    Relationship object to retrieve. Can be one of the following:

    analyses, behaviours, bundled_files, carbonblack_children, carbonblack_parents, comments, compressed_parents, comments, contacted_domains, contacted_ips, contacted_urls, email_parents, embedded_domains, embedded_ips, execution_parents, graphs, itw_urls, overlay_parents, pcap_parents, pe_resource_parents, similar_files, submissions, screenshots, votes

  • limit (int, optional) – Maximum number of rulesets to retrieve
  • cursor (str, optional) – Continuation cursor
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict containing the relationship object.

get_votes(file_hash, limit=None, cursor=None, timeout=None)

Retrieve votes for a file

Parameters:
  • file_hash (str) – File hash (SHA256, MD5, SHA1)
  • limit (int, optional) – Maximum number of rulesets to retrieve
  • cursor (str, optional) – Continuation cursor
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the votes. The votes are located in the ‘value’ key.

info_file(file_hash, timeout=None)

Retrieve information on a file

Parameters:
  • file_hash (str) – File hash of the file
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict containing information about the file.

upload(sample, timeout=None)

Upload a file.

The size of the file will be calculated and the endpoint to use will be determined based on the file size.

Parameters:
  • sample (str) – Path to file sample to upload
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the analysis ID

class core.IP(api_key=None, proxies=None)

Class for the IP Addresses endpoints

add_vote(ip, verdict, timeout=None)

Adds a verdict (vote) to a file. The verdict can be either ‘malicious’ or ‘harmless’.

Parameters:
  • ip (str) – IPv4 address
  • verdict (str) – ‘malicious’ (-1) or ‘harmless’ (+1)
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict containing the submitted vote.

get_relationship(ip, relationship, limit=None, cursor=None, timeout=None)

Retrieve information on a user for a given ip identifier.

Parameters:
  • ip (str) – IPv4 address
  • relationship (str) –

    Relationship object to retrieve. Can be one of the following: communicating_files, downloaded_files, graphs, referrer_files, resolutions, siblings, subips, urls

    For further details, see: https://developers.virustotal.com/v3.0/reference#ips-relationships

  • limit (str, optional) – Limit of results to return
  • cursor (str, optional) – Continuation cursor
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the relationship object.

get_votes(ip, limit=None, cursor=None, timeout=None)

Retrieve votes for a given IP address

Parameters:
  • ip (str) – IPv4 address
  • limit (int, optional) – Maximum number of rulesets to retrieve
  • cursor (str, optional) – Continuation cursor
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict containing the votes. The votes are located in the ‘value’ key.

info_ip(ip, timeout=None)

Retrieve information for a given IP address, such as AS owner, country, reputation, etc.

Parameters:
  • ip (str) – IPv4 address
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict containing the scan results.

class core.URL(api_key=None, proxies=None)

Class for the URL endpoints

add_vote(url, verdict, timeout=None)

Add a verdict to a URL

Adds a verdict (vote) to a URL. The verdict can be either ‘malicious’ or ‘harmless’.

Parameters:
  • url (str) – URL identifier
  • verdict (str) – ‘malicious’ (-1) or ‘harmless’ (+1)
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict containing the submitted vote.

get_network_location(url, timeout=None)

Retrieve associated IPs and DNS records, site categories, and WHOIS info for a given URL.

Parameters:
  • url (str) – URL identifier
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the details of a URL, including its latest DNS records and IP addresses.

get_relationship(url, relationship, limit=None, cursor=None, timeout=None)

Retrieve information on an object for a given URL identifier.

Parameters:
  • url (str) – URL identifier
  • relationship (str) – Relationship object to retrieve. Can be one of the following: analyses, downloaded_files, graphs, last_serving_ip_address, redirecting_urls, submissions
  • limit (str, optional) – Limit of results to return
  • cursor (str, optional) – Continuation cursor
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the relationship object.

get_votes(url, limit=None, cursor=None, timeout=None)

Retrieve votes for a URL

Parameters:
  • url (str) – URL identifier
  • limit (int, optional) – Maximum number of rulesets to retrieve
  • cursor (str, optional) – Continuation cursor
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the votes. The votes are located in the ‘value’ key.

info_url(url, timeout=None)

Retrieve information about a URL. If the URL was previously scanned, results will be returned immediately. Otherwise, a URL scan will begin and results might take a few seconds to return.

Parameters:
  • url (str) – URL to scan
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the scan results.

core.get_analysis(api_key, analysis_id, proxies=None, timeout=None)

Retrieve information about an analysis

Parameters:
  • api_key (str) – VirusTotal API key
  • analysis_id (str) – Analysis ID to retrieve
  • proxies (dict, optional) – Dictionary containing proxies
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.

get_analysis

core.get_analysis(api_key, analysis_id, proxies=None, timeout=None)

Retrieve information about an analysis

Parameters:
  • api_key (str) – VirusTotal API key
  • analysis_id (str) – Analysis ID to retrieve
  • proxies (dict, optional) – Dictionary containing proxies
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.

Files

class core.Files(api_key=None, proxies=None)

Class for the Files endpoints

add_comment(file_hash, comment, timeout=None)

Add a comment to a file

Parameters:
  • file_hash (str) – File hash (SHA256, MD5, SHA1)
  • data (dict) – Comment to add as dictionary. The package will take care of creating the JSON object.
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the added comment.

add_vote(file_hash, verdict, timeout=None)

Adds a verdict (vote) to a file. The verdict can be either ‘malicious’ or ‘harmless’.

Parameters:
  • file_hash (str) – File hash (SHA256, MD5, SHA1)
  • verdict (str) – ‘malicious’ (-1) or ‘harmless’ (+1)
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the submitted vote.

analyse_file(file_hash, timeout=None)

Re-analyse a file already in VirusTotal.

Parameters:
  • file_hash (str) – File hash to re-analyse
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the analysis ID.

download(file_hash, output_dir='./', timeout=None)

Download a file for a given file hash.

Parameters:
  • file_hash (str) – File hash (SHA256, MD5, SHA1)
  • output_dir (str, optional) – Output directory, current working directory by default.
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

None

get_comments(file_hash, limit=None, cursor=None, timeout=None)

Retrieve comments for a file

Parameters:
  • file_hash (str) – File hash (SHA256, MD5, SHA1)
  • limit (int, optional) – Maximum number of rulesets to retrieve
  • cursor (str, optional) – Continuation cursor
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the comments retrieved.

get_relationship(file_id, relationship, limit=None, cursor=None, timeout=None)

Retrieve an object related to a file

Parameters:
  • file_hash (str) – File hash (SHA256, MD5, SHA1)
  • relationsip (str) –

    Relationship object to retrieve. Can be one of the following:

    analyses, behaviours, bundled_files, carbonblack_children, carbonblack_parents, comments, compressed_parents, comments, contacted_domains, contacted_ips, contacted_urls, email_parents, embedded_domains, embedded_ips, execution_parents, graphs, itw_urls, overlay_parents, pcap_parents, pe_resource_parents, similar_files, submissions, screenshots, votes

  • limit (int, optional) – Maximum number of rulesets to retrieve
  • cursor (str, optional) – Continuation cursor
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict containing the relationship object.

get_votes(file_hash, limit=None, cursor=None, timeout=None)

Retrieve votes for a file

Parameters:
  • file_hash (str) – File hash (SHA256, MD5, SHA1)
  • limit (int, optional) – Maximum number of rulesets to retrieve
  • cursor (str, optional) – Continuation cursor
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the votes. The votes are located in the ‘value’ key.

info_file(file_hash, timeout=None)

Retrieve information on a file

Parameters:
  • file_hash (str) – File hash of the file
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict containing information about the file.

upload(sample, timeout=None)

Upload a file.

The size of the file will be calculated and the endpoint to use will be determined based on the file size.

Parameters:
  • sample (str) – Path to file sample to upload
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the analysis ID

URL

class core.URL(api_key=None, proxies=None)

Class for the URL endpoints

add_vote(url, verdict, timeout=None)

Add a verdict to a URL

Adds a verdict (vote) to a URL. The verdict can be either ‘malicious’ or ‘harmless’.

Parameters:
  • url (str) – URL identifier
  • verdict (str) – ‘malicious’ (-1) or ‘harmless’ (+1)
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict containing the submitted vote.

get_network_location(url, timeout=None)

Retrieve associated IPs and DNS records, site categories, and WHOIS info for a given URL.

Parameters:
  • url (str) – URL identifier
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the details of a URL, including its latest DNS records and IP addresses.

get_relationship(url, relationship, limit=None, cursor=None, timeout=None)

Retrieve information on an object for a given URL identifier.

Parameters:
  • url (str) – URL identifier
  • relationship (str) – Relationship object to retrieve. Can be one of the following: analyses, downloaded_files, graphs, last_serving_ip_address, redirecting_urls, submissions
  • limit (str, optional) – Limit of results to return
  • cursor (str, optional) – Continuation cursor
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the relationship object.

get_votes(url, limit=None, cursor=None, timeout=None)

Retrieve votes for a URL

Parameters:
  • url (str) – URL identifier
  • limit (int, optional) – Maximum number of rulesets to retrieve
  • cursor (str, optional) – Continuation cursor
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the votes. The votes are located in the ‘value’ key.

info_url(url, timeout=None)

Retrieve information about a URL. If the URL was previously scanned, results will be returned immediately. Otherwise, a URL scan will begin and results might take a few seconds to return.

Parameters:
  • url (str) – URL to scan
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the scan results.

Domains

class core.Domains(api_key=None, proxies=None)

Class for the Domains endpoints

add_vote(domain, verdict, timeout=None)

Adds a verdict (vote) to a domain. The verdict can be either ‘malicious’ or ‘harmless’.

Parameters:
  • domain (str) – Domain
  • verdict (str) – ‘malicious’ (-1) or ‘harmless’ (+1)
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the submitted vote.

get_relationship(domain, relationship, limit=None, cursor=None, timeout=None)

Retrieve objects related to a domain

Parameters:
  • url (str) – URL identifier
  • relationship (str) –

    Relationship object to retrieve. Can be one of the following: communicating_files, downloaded_files, graphs, referrer_files, resolutions, siblings, subdomains, urls

    For further details, see: https://developers.virustotal.com/v3.0/reference#domains-relationships

  • limit (str, optional) – Limit of results to return
  • cursor (str, optional) – Continuation cursor
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the relationship object.

get_votes(domain, limit=None, cursor=None, timeout=None)

Retrieve votes for a domain

Parameters:
  • domain (str) – Domain
  • limit (int, optional) – Maximum number of rulesets to retrieve
  • cursor (str, optional) – Continuation cursor
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the votes. The votes are located in the ‘value’ key.

info_domain(domain, timeout=None)

Retrieve information about a domain

Parameters:
  • domain (str) – Domain to scan
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the scan results.

IP

class core.IP(api_key=None, proxies=None)

Class for the IP Addresses endpoints

add_vote(ip, verdict, timeout=None)

Adds a verdict (vote) to a file. The verdict can be either ‘malicious’ or ‘harmless’.

Parameters:
  • ip (str) – IPv4 address
  • verdict (str) – ‘malicious’ (-1) or ‘harmless’ (+1)
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict containing the submitted vote.

get_relationship(ip, relationship, limit=None, cursor=None, timeout=None)

Retrieve information on a user for a given ip identifier.

Parameters:
  • ip (str) – IPv4 address
  • relationship (str) –

    Relationship object to retrieve. Can be one of the following: communicating_files, downloaded_files, graphs, referrer_files, resolutions, siblings, subips, urls

    For further details, see: https://developers.virustotal.com/v3.0/reference#ips-relationships

  • limit (str, optional) – Limit of results to return
  • cursor (str, optional) – Continuation cursor
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the relationship object.

get_votes(ip, limit=None, cursor=None, timeout=None)

Retrieve votes for a given IP address

Parameters:
  • ip (str) – IPv4 address
  • limit (int, optional) – Maximum number of rulesets to retrieve
  • cursor (str, optional) – Continuation cursor
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict containing the votes. The votes are located in the ‘value’ key.

info_ip(ip, timeout=None)

Retrieve information for a given IP address, such as AS owner, country, reputation, etc.

Parameters:
  • ip (str) – IPv4 address
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict containing the scan results.

virustotal3 enterprise

VirusTotal API v3 Enterprise

Module to interact with the Enterprise part of the API.

class enterprise.Accounts(api_key=None, proxies=None)

VT Enterprise Users & Groups

Manage and retrieve information on users and groups.

This part of the API still is under development by VirusTotal.

get_relationship(group_id, relationship, limit=None, cursor=None, timeout=None)

Retrieve information on a user for a given group ID. Currently, the only relationship object supported by the VirusTotal v3 API is graphs.

Parameters:
  • group_id (str) – User ID
  • relationship (str) – Relationship
  • limit (str, optional) – Limit of results to return
  • cursor (str, optional) – Continuation cursor
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the relationship object.

info_group(group_id, timeout=None)

Retrieve information on a group for a given ID

Parameters:
  • group_id (str) – User ID
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the details on the group.

info_user(user_id, timeout=None)

Retrieve information on a user for a given ID

Parameters:
  • user_id (str) – User ID
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the details on the user.

class enterprise.Livehunt(api_key=None, proxies=None)

VT Enterprise Livehunt Endpoints

Livehunt endpoints allowing to manage YARA rules and notifications.

api_key

VirusTotal API key

Type:str
proxies

Dictionary with proxies

Type:dict, optional
create_rulset(data, timeout=None)

Create a Livehunt ruleset

Parameters:
  • data (dict) – Rule to create.
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the created rule.

delete_notification(notification_id, timeout=None)

Delete a notification for a given notification ID

Parameters:
  • notification_id (str) – Notification ID
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

None

delete_notifications(tag, timeout=None)

Delete notifications for a given tag

Parameters:
  • tag (str) – Notification tag
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

None

delete_ruleset(ruleset_id, timeout=None)

Delete ruleset

Delete ruleset for a given ID

Parameters:
  • ruleset_id (str) – Ruleset ID
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

None

get_notification_files(limit=None, cursor=None, timeout=None)

Retrieve file details and context attributes from notifications.

Parameters:
  • limit (int, optional) – Maximum number of rulesets to retrieve
  • cursor (str, optional) – Continuation cursor
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with one or multiple notifications.

get_notifications(notification_id=None, limit=None, fltr=None, cursor=None, timeout=None)

Retrieve a single notification for a given ID or all notifications at once.

Parameters:
  • notification_id (str, optional) – Notification ID required to return a single specific ruleset.
  • limit (int, optional) – Maximum number of rulesets to retrieve
  • fltr (str, optional) – Return the rulesets matching the given criteria only
  • cursor (str, optional) – Continuation cursor
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with one or multiple notifications in JSON format.

get_rulesets(ruleset_id=None, limit=None, fltr=None, order=None, cursor=None, timeout=None)

Retrieve one or multiple rulesets

Retrieve a single ruleset for a given ID or all rulesets at once.

Parameters:
  • ruleset_id (str, optional) – Ruleset ID required to return a single specific ruleset
  • limit (int, optional) – Maximum number of rulesets to retrieve
  • fltr (str, optional) – Return the rulesets matching the given criteria only
  • order (str, optional) – Sort order
  • cursor (str, optional) – Continuation cursor
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with one or multiple rulesets.

update_ruleset(ruleset_id, data, timeout=None)

Update existing ruleset

Update an existing ruleset for a given ID

Parameters:
  • ruleset_id (str) – Ruleset ID
  • data (dict) – Ruleset to update as dictionary. The package will take care of creating the JSON object.
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the updated rule.

class enterprise.Retrohunt(api_key=None, proxies=None)

VirusTotal Retrohunt class

Run Retrohunting jobs.

abort_job(job_id, timeout=None)

Abort a job for a given ID

Parameters:
  • job_id (str) – Job ID
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

None

create_job(data, timeout=None)

Create a new Retrohunt job

Parameters:data (dict) – Rule to create. See example below.
Returns:A dict with the created rule.
delete_job(job_id, timeout=None)

Delete a job for a given ID

Parameters:job_id (str) – Job ID
Returns:None
get_jobs(job_id=None, limit=None, fltr=None, cursor=None, timeout=None)

Retrieve an existing Retrohunt jobs. Returns all jobs if no ID is specified.

Parameters:
  • job_id (str, optional) – Job ID
  • limit (int, optional) – Maximum number of jobs to retrieve
  • fltr (str, optional) – Filter matching specific jobs only
  • cursor (str, optional) – Continuation cursor
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with one of multiple jobs.

get_matching_files(job_id, timeout=None)

Get matching files for a job ID

Parameters:
  • job_id (str) – Job ID
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with matching files

class enterprise.ZipFiles(api_key=None, proxies=None)

Zipping files

Zip and download an individual file or multiple files. Zip files are password protected.

This part of the API still is under development by VirusTotal.

create_zip(data, timeout=None)

Creates a password-protected ZIP file with files from VirusTotal.

Parameters:
Returns:

A dict with the progression and status of the archive compression process, including its ID. Use the info_zip() function to check the status of a Zip file for a given ID.

get_url(zip_id, timeout=None)

Get the download URL of a Zip file for a given ID. Will raise an exception if the file is not yet ready to download. Should be called only after info_zip() returns a ‘finished’ status.

Parameters:
  • zip_id (str) – ID of the zip file
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

URL of the zip file to download

get_zip(zip_id, output_dir, timeout=None)

Download a zip file for a given ID.

Parameters:
  • zip_id (str) – ID of the zip file
  • output_dir (str) – Output directory where the file will be downloaded.
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
info_zip(zip_id, timeout=None)

Check the status of a Zip file for a given ID.

Parameters:
  • zip_id (str) – ID of the zip file
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the status of the zip file creation. When the value of the ‘status’ key is set to ‘finished’, the file is ready for download. Other status are: ‘starting’, ‘creating’, ‘timeout’, ‘error-starting’, ‘error-creating’.

enterprise.file_feed(api_key, time, timeout=None)

Get a file feed batch for a given date, by the minute.

From the official documentation: “Time 201912010802 will return the batch corresponding to December 1st, 2019 08:02 UTC. You can download batches up to 7 days old, and the most recent batch has always a 60 minutes lag with respect with to the current time.”

Parameters:
  • api_key (str) – VirusTotal key
  • time (str) – YYYYMMDDhhmm
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

each line is a json string for one report

Return type:

StringIO

enterprise.search(api_key, query, order=None, limit=None, cursor=None, descriptors_only=None, proxies=None, timeout=None)

Search for files and return the file details.

Parameters:
  • api_key (str) – VirusTotal API key
  • query (str) – Search query
  • order (str, optional) – Sort order. Can be one of the following: size, positives, last_submission_date, first_submission_date, times_submitted. Can be followed by a + or -. Default is ‘last_submission_date-‘
  • limit (int, optional) – Maximum number of results to retrieve
  • cursor (str, optional) – Continuation cursor
  • descriptors_only (bool, optional) – Return file descriptor only instead of all details
  • proxies (dict, optional) – Dictionary with proxies
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the results from the search.

enterprise.url_feed(api_key, time, timeout=None)

Get a URL feed batch for a given date, by the minute.

From the official documentation: “Time 201912010802 will return the batch corresponding to December 1st, 2019 08:02 UTC. You can download batches up to 7 days old, and the most recent batch has always a 60 minutes lag with respect with to the current time.”

Parameters:
  • api_key (str) – VirusTotal key
  • time (str) – YYYYMMDDhhmm
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

each line is a json string for one report

Return type:

StringIO

file_feed

enterprise.file_feed(api_key, time, timeout=None)

Get a file feed batch for a given date, by the minute.

From the official documentation: “Time 201912010802 will return the batch corresponding to December 1st, 2019 08:02 UTC. You can download batches up to 7 days old, and the most recent batch has always a 60 minutes lag with respect with to the current time.”

Parameters:
  • api_key (str) – VirusTotal key
  • time (str) – YYYYMMDDhhmm
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

each line is a json string for one report

Return type:

StringIO

Livehunt

class enterprise.Livehunt(api_key=None, proxies=None)

VT Enterprise Livehunt Endpoints

Livehunt endpoints allowing to manage YARA rules and notifications.

api_key

VirusTotal API key

Type:str
proxies

Dictionary with proxies

Type:dict, optional
create_rulset(data, timeout=None)

Create a Livehunt ruleset

Parameters:
  • data (dict) – Rule to create.
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the created rule.

delete_notification(notification_id, timeout=None)

Delete a notification for a given notification ID

Parameters:
  • notification_id (str) – Notification ID
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

None

delete_notifications(tag, timeout=None)

Delete notifications for a given tag

Parameters:
  • tag (str) – Notification tag
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

None

delete_ruleset(ruleset_id, timeout=None)

Delete ruleset

Delete ruleset for a given ID

Parameters:
  • ruleset_id (str) – Ruleset ID
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

None

get_notification_files(limit=None, cursor=None, timeout=None)

Retrieve file details and context attributes from notifications.

Parameters:
  • limit (int, optional) – Maximum number of rulesets to retrieve
  • cursor (str, optional) – Continuation cursor
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with one or multiple notifications.

get_notifications(notification_id=None, limit=None, fltr=None, cursor=None, timeout=None)

Retrieve a single notification for a given ID or all notifications at once.

Parameters:
  • notification_id (str, optional) – Notification ID required to return a single specific ruleset.
  • limit (int, optional) – Maximum number of rulesets to retrieve
  • fltr (str, optional) – Return the rulesets matching the given criteria only
  • cursor (str, optional) – Continuation cursor
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with one or multiple notifications in JSON format.

get_rulesets(ruleset_id=None, limit=None, fltr=None, order=None, cursor=None, timeout=None)

Retrieve one or multiple rulesets

Retrieve a single ruleset for a given ID or all rulesets at once.

Parameters:
  • ruleset_id (str, optional) – Ruleset ID required to return a single specific ruleset
  • limit (int, optional) – Maximum number of rulesets to retrieve
  • fltr (str, optional) – Return the rulesets matching the given criteria only
  • order (str, optional) – Sort order
  • cursor (str, optional) – Continuation cursor
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with one or multiple rulesets.

update_ruleset(ruleset_id, data, timeout=None)

Update existing ruleset

Update an existing ruleset for a given ID

Parameters:
  • ruleset_id (str) – Ruleset ID
  • data (dict) – Ruleset to update as dictionary. The package will take care of creating the JSON object.
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the updated rule.

Retrohunt

class enterprise.Retrohunt(api_key=None, proxies=None)

VirusTotal Retrohunt class

Run Retrohunting jobs.

abort_job(job_id, timeout=None)

Abort a job for a given ID

Parameters:
  • job_id (str) – Job ID
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

None

create_job(data, timeout=None)

Create a new Retrohunt job

Parameters:data (dict) – Rule to create. See example below.
Returns:A dict with the created rule.
delete_job(job_id, timeout=None)

Delete a job for a given ID

Parameters:job_id (str) – Job ID
Returns:None
get_jobs(job_id=None, limit=None, fltr=None, cursor=None, timeout=None)

Retrieve an existing Retrohunt jobs. Returns all jobs if no ID is specified.

Parameters:
  • job_id (str, optional) – Job ID
  • limit (int, optional) – Maximum number of jobs to retrieve
  • fltr (str, optional) – Filter matching specific jobs only
  • cursor (str, optional) – Continuation cursor
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with one of multiple jobs.

get_matching_files(job_id, timeout=None)

Get matching files for a job ID

Parameters:
  • job_id (str) – Job ID
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with matching files

Accounts

class enterprise.Accounts(api_key=None, proxies=None)

VT Enterprise Users & Groups

Manage and retrieve information on users and groups.

This part of the API still is under development by VirusTotal.

get_relationship(group_id, relationship, limit=None, cursor=None, timeout=None)

Retrieve information on a user for a given group ID. Currently, the only relationship object supported by the VirusTotal v3 API is graphs.

Parameters:
  • group_id (str) – User ID
  • relationship (str) – Relationship
  • limit (str, optional) – Limit of results to return
  • cursor (str, optional) – Continuation cursor
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the relationship object.

info_group(group_id, timeout=None)

Retrieve information on a group for a given ID

Parameters:
  • group_id (str) – User ID
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the details on the group.

info_user(user_id, timeout=None)

Retrieve information on a user for a given ID

Parameters:
  • user_id (str) – User ID
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the details on the user.

ZipFiles

class enterprise.ZipFiles(api_key=None, proxies=None)

Zipping files

Zip and download an individual file or multiple files. Zip files are password protected.

This part of the API still is under development by VirusTotal.

create_zip(data, timeout=None)

Creates a password-protected ZIP file with files from VirusTotal.

Parameters:
Returns:

A dict with the progression and status of the archive compression process, including its ID. Use the info_zip() function to check the status of a Zip file for a given ID.

get_url(zip_id, timeout=None)

Get the download URL of a Zip file for a given ID. Will raise an exception if the file is not yet ready to download. Should be called only after info_zip() returns a ‘finished’ status.

Parameters:
  • zip_id (str) – ID of the zip file
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

URL of the zip file to download

get_zip(zip_id, output_dir, timeout=None)

Download a zip file for a given ID.

Parameters:
  • zip_id (str) – ID of the zip file
  • output_dir (str) – Output directory where the file will be downloaded.
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
info_zip(zip_id, timeout=None)

Check the status of a Zip file for a given ID.

Parameters:
  • zip_id (str) – ID of the zip file
  • timeout (float, optional) – The amount of time in seconds the request should wait before timing out.
Returns:

A dict with the status of the zip file creation. When the value of the ‘status’ key is set to ‘finished’, the file is ready for download. Other status are: ‘starting’, ‘creating’, ‘timeout’, ‘error-starting’, ‘error-creating’.

Indices and tables