API Reference

graph

vt_graph_api.graph.

This module provides the Python object wrapper for VirusTotal Graph representation.

Documentation:
VT API: https://virustotal.github.io/vt-graph-api/
class vt_graph_api.graph.VTGraph(api_key, name='', private=False, user_editors=None, user_viewers=None, group_editors=None, group_viewers=None, verbose=False)

Bases: object

Python object wrapper for Virustotal Graph representation.

Variables:
  • api_key (str) – VT API Key.
  • graph_id (str) – graph identifier for VT.
  • name (str) – graph title.
  • api_calls (int) – total api calls consumed by graph.
  • private (bool) – whether graph is private or not.
  • user_editors ([str]) – list with users that can edit graph.
  • user_viewers ([str]) – list with users that can see graph.
  • group_editors ([str]) – list with groups that can edit graph.
  • group_viewers ([str]) – list with groups that can see graph.
  • verbose (bool) – if True log will be displayed.
  • nodes (dict) – graph nodes.
  • links (dict) – graph links.
MAX_API_EXPANSION_LIMIT = 40
MAX_CHARACTERS = 100
MAX_PARALLEL_REQUESTS = 1000
MIN_API_EXPANSION_NUMBER = 10
REQUEST_TIMEOUT = 40

Adds a link between source_node and target_node with the given connection_type.

If there’s no connection type supplied, the link will be drawed without relationship node in VirusTotal UI.

Parameters:
  • source_node (str) – source node ID.
  • target_node (str) – target node ID.
  • connection_type (str, optional) – connection type, for example compressed_parent. Defaults to “”.
Raises:
  • NodeNotFoundError – if any of the given nodes are not found.
  • SameNodeError – if the source_node and the target_node are the same.

This call does NOT consume API quota.

Try to find a relationship between the source_node and the target_node.

Adds the needed links between the source_node and the target_node if the target_node could be reached by source_node.

Parameters:
  • source_node (str) – source node ID.
  • target_node (str) – target node ID.
  • max_api_quotas (int, optional) – maximum number of api quotas that could be consumed. Defaults to 100000.
  • max_depth (int, optional) – maximum number of hops between the nodes. Defaults to 3.
  • max_qps (int, optional) – maximum number of requests per second. Defaults to 1000.
  • fetch_info_collected_nodes (bool, optional) – if True, when a new node is added to graph to compute the connection, it will be fetched on VT for information. It consumes api quotas which are not included in max_api_quota. Defaults to True.
Returns:

whether relation has been found.
Return type:

bool
Raises:
  • NodeNotFoundError – if source or target node is not found.
  • SameNodeError – if source_node and target_node are the same.

This call consumes API quota (as much as max_api_quotas value), one for each expansion required to find the relation.

add_node(node_id, node_type, fetch_information=True, fetch_vt_enterprise=True, label='', node_attributes=None, x=0, y=0)

Adds a node with id node_id of node_type type to the graph.

Parameters:
  • node_id (string) – node ID. Example: https://www.virustotal.com for a url.
  • node_type (string) – file, url, ip_address or domain.
  • fetch_information (bool, optional) – whether the script will fetch information for this node in VT. If the node already exist in the graph it will not fetch information for it. Defaults to True.
  • fetch_vt_enterprise (bool, optional) – if True, the graph will search any available information using VT intelligence for the node if there is no normal information for it. Defaults to True.
  • label (str, optional) – label that appears next to the node. Defaults to “”.
  • node_attributes (dict, optional) – if it is set and fetch_information is False, node_attributes will be added to new node with the given node id. Defaults to None.
  • x (int, optional) – X coordinate for Node representation in VT Graph UI.
  • y (int, optional) – Y coordinate for Node representation in VT Graph UI.
Returns:

the node object appended to graph.
Return type:

Node

This call consumes API quota if fetch_information=True. It also consumes API quota if the given node_id is not standard, such as file with id in SHA1 or MD5, URL instead of an VT URL identifier or if the given node_id belongs to an unknown identifier.

add_nodes(node_list, fetch_information=True, fetch_vt_enterprise=True)

Adds the node_list to the graph concurrently.

Parameters:
  • node_list ([dict]) – a list of dictionaries with the following keys {node_id, node_type, label, attributes, x_position, y_position}.
  • fetch_information (bool, optional) – whether the script will fetch information for the nodes that will be added in VT. Defaults to True.
  • fetch_vt_enterprise (bool, optional) – if True, the graph will search any available information using VT intelligence for the node if there is no normal information for it. Defaults to True.
Returns:

the list with the added nodes.
Return type:

[Node]
static clone_graph(graph_id, api_key, name='', private=False, user_editors=None, user_viewers=None, group_editors=None, group_viewers=None)

Clone VirusTotal Graph and make it yours according the given parameters.

Parameters:
  • graph_id (str) – VirusTotal Graph ID.
  • api_key (str) – VT API Key
  • name (str, optional) – graph title. Defaults to “”.
  • private (bool, optional) – true for private graphs. You need to have Private Graph premium feature enabled in your subscription. Defaults to False.
  • user_editors ([str], optional) – usernames that can edit the graph. Defaults to None.
  • user_viewers ([str], optional) – usernames that can view the graph. Defaults to None.
  • group_editors ([str], optional) – groups that can edit the graph. Defaults to None.
  • group_viewers ([str], optional) – groups that can view the graph. Defaults to None.
Raises:

vt_graph_api.errors.LoadError – whether the given graph_id cannot be found or JSON does not have the correct structure.
Returns:

the cloned graph.
Return type:

VTGraph
connect_with_graph(source_node, max_api_quotas=100000, max_depth=3, max_qps=1000, fetch_info_collected_nodes=True)

Try to connect the source_node with the current graph nodes.

Parameters:
  • source_node (Node) – source_node ID.
  • max_api_quotas (int, optional) – maximum number of api quotas that could be consumed. Defaults to 100000.
  • max_depth (int, optional) – maximum number of hops between the nodes. Defaults to 3.
  • max_qps (int, optional) – maximum number requests per second. Defaults to 1000.
  • fetch_info_collected_nodes (bool, optional) – if True, when a new node is added to graph to compute the connection, it will be fetched on VT for information. It consumes api quotas which are not included in max_api_quota. Defaults to True.
Raises:

NodeNotFoundError – if the node source is not found.
Returns:

whether at least one relationship has been found.
Return type:

bool

This call consumes API quota (as much as max_api_quotas value), one for each expansion required to find the relationships.

Deletes the link between source_node and target_node with the given connection_type.

Parameters:
  • source_node (str) – source node ID.
  • target_node (str) – target node ID.
  • connection_type (str) – connection type, for example compressed_parent.
Raises:
  • NodeNotFoundError – if any of the given nodes are not found.
  • SameNodeError – if the source_node and the target_node are the same.
  • LinkNotFoundError – if the given link does not exists in the graph.

Deletes all the links which contains the given node_id.

Parameters:node_id (str) – the node which are in the links that will be deleted from the graph.
Raises:NodeNotFoundError – if the given node_id is not found.
delete_node(node_id)

Deletes the node with the given node_id from the graph.

Parameters:node_id (str) – node ID.
Raises:NodeNotFoundError – if there is no node with the given node_id in the graph.

This call does NOT consume API quota.

expand(node_id, expansion, max_nodes_per_relationship=40)

Expands the given node with the given expansion.

Parameters:
  • node_id (str) – identifier of the node. See the top level documentation to understand IDs.
  • expansion (str) – expansion name. For example: compressed_parents for nodes of type file.
  • max_nodes_per_relationship (int, optional) – max number of nodes that will be expanded per relationship. Minimum value will be MIN_API_EXPANSION_NUMBER. Defaults to 40.
Raises:
  • NodeNotFoundError – if the node is not found.
  • NodeNotSupportedExpansionError – if the node cannot be expanded with the given expansion.
Returns:

a list with the nodes resulted by the expansion of the given node

with the given relationship.
Return type:

[Node]

This call consumes API quota.

expand_n_level(level=1, max_nodes_per_relationship=40, max_nodes=10000)

Expands all the nodes in the graph level levels.

For example:

If your graph has three nodes, and you apply a expand_n_level(1). It will expand the three nodes with all the known expansions for those nodes.

If you select 2 levels of expansions. After the first expansion is applied to the three nodes, the new discovered nodes will be expanded as well.

Parameters:
  • level (int, optional) – number of layers down the graph that will be expanded. Defaults to 1.
  • max_nodes_per_relationship – (int, optional): max number of nodes that will be expanded per relationship. Defaults to 40.
  • max_nodes (int, optional) – max number of nodes that will be added to the graph. The expansion will stop as soon as any expansion result adds more than this limit to the graph. Defaults to 10000.
Returns:

a list with the nodes resulted by the expansion of each graph

node in all his known relationships.
Return type:

[Node]

This call consumes API quota, one for each node expansion.

expand_one_level(node_id, max_nodes_per_relationship=40)

Expands all relationship that we know in VirusTotal for the give node.

Parameters:
  • node_id (str) – node ID.
  • max_nodes_per_relationship (int, optional) – max number of nodes that will be expanded per relationship. Defaults to None.
Raises:

NodeNotFoundError – if the node is not found.

It consumes API quota, one for each expansion available for the node.

Returns:
a list with the nodes resulted by te expansion of the given node
in all his known relationships.
Return type:[Node]
get_api_calls()

Get api counter in thread safe mode.

get_iframe_code()

Return VirusTotal UI iframe for the graph.

Requires that save_graph was called.

Raises:vt_graph_api.errors.SaveGraphError – if save_graph was not called.
Returns:VirusTotal UI iframe.
Return type:str

Return VirusTotal UI link for the graph.

Requires that save_graph was called.

Raises:vt_graph_api.errors.SaveGraphError – if save_graph was not called.
Returns:VirusTotal UI link.
Return type:str
has_node(node_id)

Check if the graph contains the node with the given node_id.

Parameters:node_id (str) – node ID.
Returns:whether the graph contains the node with the given node_id.
Return type:bool

This call consumes API quota if the given node_id is not a standard VT id.

static is_editor(vt_user, graph_id, api_key)

Check if the given vt_user can edit the graph with the given graph_id.

Parameters:
  • vt_user (str) – VirusTotal user/group name.
  • graph_id (str) – VirusTotal Graph ID.
  • api_key (str) – VirusTotal Api key.
Returns:

whether the given vt_user can edit the graph.
Return type:

bool
static is_viewer(vt_user, graph_id, api_key)

Check if the given vt_user can view the graph with the given graph_id.

Parameters:
  • vt_user (str) – VirusTotal user/group name.
  • graph_id (str) – VirusTotal Graph ID.
  • api_key (str) – VirusTotal Api key.
Returns:

whether the given vt_user can view the graph.
Return type:

bool
static load_graph(graph_id, api_key)

Load the graph using the given VirusTotal graph id.

Parameters:
  • graph_id (str) – VirusTotal Graph ID.
  • api_key (str) – VirusTotal API key.
Raises:
Returns:

the imported graph.
Return type:

VTGraph
save_graph()

Saves the graph into VirusTotal Graph database.

At this point if the Graph is set to public it will be searchable in VirusTotal UI.

Raises:
  • CollaboratorNotFoundError – if any of the collaborators is not found in VirusTotal user and group database.
  • SaveGraphError – if something went bad when saving the graph.

This call not consume API quota.

node

vt_graph_api.node.

This module provides the Python object wrapper for VTGraph node representation.

class vt_graph_api.node.Node(node_id, node_type, x=0, y=0)

Bases: object

Python object wraper for the VT Graph Node representation.

Variables:
  • node_id (str) – node identifier.
  • node_type (str) – node type, must be one of the SUPPORTED_NODE_TYPES.
  • pretty_id (str) – node identifier without dots.
  • x (int, optional) – X coordinate for Node representation in VT Graph GUI.
  • y (int, optional) – Y coordinate for Node representation in VT Graph GUI.
  • expansions_available ([str]) – available expansions for the node.
  • attributes (dict) – VirusTotal attribute dict.
  • label (str) – node name.
  • children (dict) – dict with the children for each expansion type.
  • relationship_ids (dict) – dict with the relationship id for each expansion type.
NODE_EXPANSIONS = {'domain': ['inmediate_parent', 'parent', 'communicating_files', 'downloaded_files', 'referrer_files', 'resolutions', 'siblings', 'subdomains', 'urls'], 'file': ['bundled_files', 'carbonblack_children', 'carbonblack_parents', 'compressed_parents', 'contacted_domains', 'contacted_ips', 'contacted_urls', 'email_parents', 'embedded_domains', 'embedded_urls', 'embedded_ips', 'execution_parents', 'itw_domains', 'itw_urls', 'overlay_parents', 'pcap_parents', 'pe_resource_parents', 'similar_files'], 'ip_address': ['communicating_files', 'downloaded_files', 'referrer_files', 'resolutions', 'urls'], 'url': ['downloaded_files', 'last_serving_ip_address', 'network_location', 'redirecting_urls']}
SUPPORTED_NODE_TYPES = ('file', 'url', 'domain', 'ip_address')
add_attributes(attributes)

Adds the attributes if the node doesn’t have it yet.

Parameters:attributes (dict) – VirusTotal attribute dict.
add_child(node_id, expansion)

Add child to Node in the given expansion.

Parameters:
  • node_id (str) – child node id.
  • expansion (str) – expansion for the given node_id.
add_label(label)

Adds a label to the node.

Parameters:label (str) – value of the label.
delete_child(node_id, expansion)

Delete child from Node in the given expansion.

Parameters:
  • node_id (str) – child node id.
  • expansion (str) – expansion for the given node_id.
get_detections()

Get the node detections from attributes.

Returns:the number of detections.
Return type:int
static is_domain(node_id)

Check if node_id belongs to domain name.

Parameters:node_id (str) – node ID.
Returns:wether node_id belongs to a domain name.
Return type:bool
static is_ipv4(node_id)

Check if node_id belongs to ipv4.

Parameters:node_id (str) – node ID.
Returns:wether node_id belongs to a ipv4.
Return type:bool
static is_md5(node_id)

Check if node_id belongs to md5 hash.

Parameters:node_id (str) – node ID.
Returns:wether node_id belongs to a md5 hash.
Return type:bool
static is_sha1(node_id)

Check if node_id belongs to sha1 hash.

Parameters:node_id (str) – node ID.
Returns:wether node_id belongs to a sha1 hash.
Return type:bool
static is_sha256(node_id)

Check if node_id belongs to a sha256 hash.

Parameters:node_id (str) – node ID.
Returns:wether node_id belongs to a sha256 hash.
Return type:bool
static is_url(node_id)

Check if node_id belongs to url.

Parameters:node_id (str) – node ID.
Returns:whether node_id belongs to a url
Return type:bool
reset_relationship_ids()

Reset relationship_ids.

errors

vt_graph_api.errors.

This modules provides all errors that could be raised by the methods in vt_graph_api package.

exception vt_graph_api.errors.CollaboratorNotFoundError

Bases: exceptions.Exception

exception vt_graph_api.errors.InvalidJSONError

Bases: exceptions.Exception

exception vt_graph_api.errors.LinkNotFoundError

Bases: exceptions.Exception

exception vt_graph_api.errors.LoadError

Bases: exceptions.Exception

exception vt_graph_api.errors.MaximumConnectionRetriesError

Bases: exceptions.Exception

exception vt_graph_api.errors.NodeNotFoundError

Bases: exceptions.Exception

exception vt_graph_api.errors.NodeNotSupportedExpansionError

Bases: exceptions.Exception

exception vt_graph_api.errors.NodeNotSupportedTypeError

Bases: exceptions.Exception

exception vt_graph_api.errors.SameNodeError

Bases: exceptions.Exception

exception vt_graph_api.errors.SaveGraphError

Bases: exceptions.Exception