msticpy.sectools.vtlookupv3 package

Submodules

msticpy.sectools.vtlookupv3.vt_pivot module

VirusTotal Pivot functions.

class msticpy.sectools.vtlookupv3.vt_pivot.VTAPIScope(value)

Bases: enum.Flag

VT API Type enumeration.

ALL = 3
PRIVATE = 2
PUBLIC = 1
msticpy.sectools.vtlookupv3.vt_pivot.add_pivot_functions(api_scope: Optional[str] = None)

Add VT3 relationship functions as pivot functions.

Parameters

api_scope (Optional[str], optional) – “public” or “private”, by default “public”

msticpy.sectools.vtlookupv3.vtfile_behavior module

VirusTotal File Behavior functions.

class msticpy.sectools.vtlookupv3.vtfile_behavior.SIProcess(process_id: str, name: str, cmd_line: str, parent_id: int = - 1, proc_key: Optional[str] = None, parent_key: Optional[str] = None, path: Optional[str] = None, IsRoot: bool = False, IsLeaf: bool = False, IsBranch: bool = False, children: list = [], time_offset: int = 0)

Bases: object

Data class to hold each process from detonation.

Method generated by attrs for class SIProcess.

IsBranch: bool
IsLeaf: bool
IsRoot: bool
children: list
cmd_line: str
name: str
parent_id: int
parent_key: Optional[str]
path: Optional[str]
proc_key: Optional[str]
process_id: str
time_offset: int
class msticpy.sectools.vtlookupv3.vtfile_behavior.VTFileBehavior(vt_key: Optional[str] = None, file_id: Optional[str] = None, file_summary: Optional[Union[pandas.core.frame.DataFrame, pandas.core.series.Series, Dict[str, Any]]] = None)

Bases: object

VirusTotal File Behavior class.

Initialize the VTFileBehavior class.

Parameters

  • vt_key (str, optional) – VirusTotal API key, by default None

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

  • file_summary (Optional[Union[pd.DataFrame, pd, Series, Dict[str, Any]]], optional) – VT file summary - this can be in one of the following formats: VT object dictionary Pandas DataFrame - first row is assumed to be the file summary Pandas Series by default None

browse() → Optional[ipywidgets.widgets.widget_box.VBox]

Browse the behavior categories.

get_file_behavior(sandbox: Optional[str] = None)

Retrieve the file behavior data.

Parameters

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

property has_behavior_data: bool

Return true if file behavior data available.

property has_evtx: bool

Return True if EVTX data is available (Enterprise only).

property has_memdump: bool

Return True if memory dump data is available (Enterprise only).

property has_pcap: bool

Return True if PCAP data is available (Enterprise only).

classmethod list_sandboxes() → List[str]

Return list of known sandbox types.

property process_tree: Any

Return the process tree plot.

property sandbox_id: str

Return sandbox ID of detonation.

msticpy.sectools.vtlookupv3.vtlookupv3 module

VirusTotal v3 API.

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

Bases: enum.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.sectools.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.sectools.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.sectools.vtlookupv3.vtlookupv3.VTEntityType(value)

Bases: enum.Enum

VTEntityType: Enum class for VirusTotal entity types.

DOMAIN = 'domain'
FILE = 'file'
IP_ADDRESS = 'ip_address'
URL = 'url'
class msticpy.sectools.vtlookupv3.vtlookupv3.VTLookupV3(vt_key: Optional[str] = None)

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.

get_file_behavior(file_id: Optional[str] = None, file_summary: Optional[Dict[str, Any]] = None, sandbox: Optional[str] = None) → msticpy.sectools.vtlookupv3.vtfile_behavior.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) → pandas.core.frame.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.

lookup_ioc(observable: str, vt_type: str, all_props: bool = False) → pandas.core.frame.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: Optional[int] = None, all_props: bool = False) → pandas.core.frame.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: pandas.core.frame.DataFrame, observable_column: str = 'target', observable_type_column: str = 'target_type', all_props: bool = False)

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: pandas.core.frame.DataFrame, relationship: str, observable_column: str = 'target', observable_type_column: str = 'target_type', limit: Optional[int] = None, all_props: bool = False) → pandas.core.frame.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[pandas.core.frame.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)

Display a VTGraph in a Jupyter Notebook.

Parameters

  • graph_id – Graph ID

  • width – Graph width.

  • height – Graph height

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.sectools.vtlookupv3.vtlookupv3.VTObjectProperties(value)

Bases: enum.Enum

Enum for VT Object properties.

ATTRIBUTES = 'attributes'
LAST_ANALYSIS_STATS = 'last_analysis_stats'
MALICIOUS = 'malicious'
RELATIONSHIPS = 'relationship'
msticpy.sectools.vtlookupv3.vtlookupv3.timestamps_to_utcdate(data: pandas.core.frame.DataFrame)

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

msticpy.sectools.vtlookupv3.vtobject_browser module

VirusTotal Object browser.

class msticpy.sectools.vtlookupv3.vtobject_browser.VTObjectBrowser(file_id: Optional[str] = None)

Bases: msticpy.nbtools.nbwidgets.core.IPyDisplayMixin

VirusTotal object attributes browser.

Initialize the VT Browser.

Parameters

file_id (Optional[str], optional) – File ID (Hash) of file to be retrieved and displayed, by default None

display()

Display the interactive widgets.

Module contents

VirusTotal V3 Subpackage.