msticpy.context.vtlookupv3.vtlookupv3 module

VirusTotal v3 API.

class msticpy.context.vtlookupv3.vtlookupv3.ColumnNames(value)

Bases: Enum

Column name enum for DataFrame output.

DETECTIONS = 'detections'
ID = 'id'
RELATIONSHIP_TYPE = 'relationship_type'
SCANS = 'scans'
SOURCE = 'source'
SOURCE_TYPE = 'source_type'
TARGET = 'target'
TARGET_TYPE = 'target_type'
TYPE = 'type'
exception msticpy.context.vtlookupv3.vtlookupv3.MsticpyVTGraphSaveGraphError

Bases: Exception

Could not save VT Graph.

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception msticpy.context.vtlookupv3.vtlookupv3.MsticpyVTNoDataError

Bases: Exception

No data returned from VT API.

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class msticpy.context.vtlookupv3.vtlookupv3.VTEntityType(value)

Bases: Enum

VTEntityType: Enum class for VirusTotal entity types.

DOMAIN = 'domain'
FILE = 'file'
IP_ADDRESS = 'ip_address'
URL = 'url'
class msticpy.context.vtlookupv3.vtlookupv3.VTLookupV3(vt_key: str | None = None, *, force_nestasyncio: bool = False)

Bases: object

VTLookupV3: VirusTotal lookup of IoC reports.

Create a new instance of VTLookupV3 class.

Parameters:

  • vt_key (str, optional) – VirusTotal API key, if not supplied, this is read from user configuration.

  • force_nestasyncio (bool, optional) – To force use of nest_asyncio, by default nest_asyncio is used in Jupyter notebooks, otherwise this defaults to False

create_vt_graph(relationship_dfs: list[DataFrame], name: str, *, private: bool) → str

Create a VirusTotal Graph with a set of Relationship DataFrames.

Parameters:

  • relationship_dfs – List of Relationship DataFrames

  • name – New graph name

  • private – Indicates if the Graph is private or not.

Return type:

Graph ID

Raises:

  • ValueError when private is not indicated. –

  • ValueError when there are no relationship DataFrames –

  • MsticpyVTGraphSaveGraphError when Graph can not be saved –

get_file_behavior(file_id: str | None = None, file_summary: dict[str, Any] | None = None, sandbox: str | None = None) → VTFileBehavior

Return a VTFileBehavior object with file detonation results.

Parameters:

  • file_id (Optional[str], optional) – The ID of the file to look up, by default None

  • file_summary (Optional[dict[str, Any]], optional) – VT file summary object dictionary, by default None

  • sandbox (str, optional) – Name of specific sandbox to retrieve, by default None If None, it will retrieve the behavior summary.

Return type:

VTFileBehavior

get_object(vt_id: str, vt_type: str) → DataFrame

Return the full VT object as a DataFrame.

Parameters:

  • vt_id (str) – The ID of the object

  • vt_type (str) – The type of object to query.

Returns:

Single column DataFrame with attribute names as index and values as data column.

Return type:

pd.DataFrame

Raises:

Notes

This calls the underlying VT get_object API directly and returns all attributes for the object - hence a very wide DataFrame.

iterator(path: str, *path_args: str, params: dict[str, Any] | None = None, cursor: str | None = None, limit: int | None = None, batch_size: int = 0) → vt.Iterator

Return 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.

SOURCE: https://github.com/VirusTotal/vt-py/blob/ 6bf4decb5bbd80bfc60e74ee3caa4c9073cea38c/vt/client.py

Parameters:

  • path (str) – Path to API endpoint returning a collection.

  • path_args (dict) – 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 vt.Iterator

Return type:

vt.Iterator

lookup_ioc(observable: str, vt_type: str, *, all_props: bool = False) → DataFrame

Look up and single IoC observable.

Parameters:

  • observable (str) – The observable value

  • vt_type (str) – The VT entity type

  • all_props (bool, optional) – If True, return all properties, by default False

Return type:

Attributes Pandas DataFrame with the properties of the entity

Raises:

KeyError – Unknown vt_type

Look single IoC observable related items.

Parameters:

  • observable (str) – The observable value

  • vt_type (str) – The VT entity type

  • relationship (str) – Desired relationship

  • limit (int) – Relations limit

Returns:

Any objects with specified relationship to the entity

Return type:

pd.DataFrame

Notes

This method returns full related objects rather than ID links. It is less efficient than looking up ID links only.

See also

lookup_ioc_relationships

return the related IDs.

lookup_ioc_relationships(observable: str, vt_type: str, relationship: str, *, limit: int | None = None, all_props: bool = False) → pd.DataFrame

Look up single IoC observable relationship links.

Parameters:

  • observable (str) – The observable value

  • vt_type (str) – The VT entity type

  • relationship (str) – Desired relationship

  • limit (int) – Relations limit

  • all_props (bool, optional) – If True, return all properties, by default False

Return type:

Relationship Pandas DataFrame with the relationships of the entity

Notes

This method returns relationship links rather than whole objects. That is, it will return the IDs of related items in the specified relationship, if any.

See also

lookup_ioc_related

return the full related objects.

lookup_iocs(observables_df: DataFrame, observable_column: str = 'target', observable_type_column: str = 'target_type', *, all_props: bool = False) → DataFrame

Look up and multiple IoC observables.

Parameters:

  • observables_df (pd.DataFrame) – A Pandas DataFrame, where each row is an observable

  • observable_column – ID column of each observable

  • observable_type_column – Type column of each observable

  • all_props (bool, optional) – If True, return all properties, by default False

Return type:

Attributes Pandas DataFrame with the properties of the entities

lookup_iocs_relationships(observables_df: pd.DataFrame, relationship: str, observable_column: str = 'target', observable_type_column: str = 'target_type', *, limit: int | None = None, all_props: bool = False) → pd.DataFrame

Look up and single IoC observable relationships.

Parameters:

  • observables_df (pd.DataFrame) – A Pandas DataFrame, where each row is an observable

  • relationship (str) – Desired relationship

  • observable_column – ID column of each observable

  • observable_type_column – Type column of each observable.

  • limit (int) – Relations limit

  • all_props (bool, optional) – If True, return all properties, by default False

Return type:

Relationship Pandas DataFrame with the relationships of each observable.

static relationships_to_graph(relationship_dfs: list[DataFrame]) → tuple[list[dict[str, Any]], list[dict[str, Any]]]

Generate nodes and edges from relationships.

Parameters:

relationship_dfs (list[pd.DataFrame]) – List of relationship DataFrames

Returns:

List of nodes (node_id, node_type) List of edges (source_node, target_node, connection_type)

Return type:

Tuple[list[dict[str, Any]], list[dict[str, Any]]]

Raises:

ValueError – If an empty list is supplied.

static render_vt_graph(graph_id: str, width: int = 800, height: int = 600) → None

Display a VTGraph in a Jupyter Notebook.

Parameters:

  • graph_id – Graph ID

  • width – Graph width.

  • height – Graph height

search(query: str, limit: int = 1000) → DataFrame

Return results of a VT search query as a DataFrame.

Parameters:

  • query (str) – Virus Total Intelligence Search string

  • limit (int (default: 1,000)) – Number of intended results

Returns:

Search query results.

Return type:

pd.DataFrame

property supported_vt_types: list[str]

Return list of VirusTotal supported IoC type names.

Returns:

List of VirusTotal supported IoC type names.

Return type:

list[str]

class msticpy.context.vtlookupv3.vtlookupv3.VTObjectProperties(value)

Bases: Enum

Enum for VT Object properties.

ATTRIBUTES = 'attributes'
LAST_ANALYSIS_STATS = 'last_analysis_stats'
MALICIOUS = 'malicious'
RELATIONSHIPS = 'relationship'
msticpy.context.vtlookupv3.vtlookupv3.timestamps_to_utcdate(data: DataFrame) → DataFrame

Replace Unix timestamps in VT data with Py/pandas Timestamp.