msticpy.context.vtlookupv3.vtlookup module

Module for VTLookup class.

Wrapper class around Virus Total API. Input can be a single IoC observable or a pandas DataFrame containing multiple observables. Processing requires a Virus Total account and API key and processing performance is limited to the number of requests per minute for the account type that you have. Support IoC Types:

  • Filehash

  • URL

  • DNS Domain

  • IPv4 Address

class msticpy.context.vtlookupv3.vtlookup.DuplicateStatus(is_dup: bool, status: str)

Bases: NamedTuple

Information about vt objects being duplicates.

Create new instance of DuplicateStatus(is_dup, status)

count(value, /)

Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

is_dup: bool

Alias for field number 0

status: str

Alias for field number 1

class msticpy.context.vtlookupv3.vtlookup.VTLookup(vtkey: str, verbosity: int = 1)

Bases: object

VTLookup: VirusTotal lookup of IoC reports.

Main methods are: lookup_iocs() - accepts input of multiple IoCs in a Pandas DataFrame lookup_ioc() - looks up a single IoC observable. supported_ioc_types - a list of valid target types. ioc_vt_type_mapping - a dictionary of mappings to recognized VT Types. Types mapped to None will not be submitted to VT.

For urls a full http request can be submitted, query string and fragments will be dropped before submitting. For files MD5, SHA1 and SHA256 hashes are supported. For IP addresses only dotted IPv4 addresses are supported.

Create a new instance of VTLookup class.

Parameters:

  • vtkey (str) – VirusTotal API key

  • verbosity (int, optional) –

    The level of detail of reporting

    0 = no reporting 1 = minimal reporting (default) 2 = verbose reporting

property ioc_vt_type_mapping: dict[str, str]

Return mapping between internal and VirusTotal IoC type names.

Returns:

Return mapping between internal and VirusTotal IoC type names.

Return type:

Mapping[str, str]

lookup_ioc(observable: str, ioc_type: str, output: str = 'dict') → pd.DataFrame | list[dict]

Look up and single IoC observable.

Parameters:

  • observable (str) – The observable value

  • ioc_type (str) – The IoC Type (see ‘supported_ioc_types’ attribute)

  • output (str, optional) – Output results as a dictionary (or list of dicts) if output is any other value the result will be returned in a Pandas DataFrame (the default is ‘dict’)

Returns:

  • list{dict} (if output == ‘dict’)

  • pd.DataFrame (otherwise)

Raises:

KeyError – Unknown ioc_type

lookup_iocs(data: DataFrame, src_col: str = 'Observable', type_col: str = 'IoCType', src_index_col: str = 'SourceIndex', **kwargs: str) → DataFrame

Retrieve results for IoC observables in the source dataframe.

Parameters:

  • data (pd.DataFrame) – Dataframe containing the observables to search for

  • src_col (str, optional) – The column name that contains the observable data (one item per row) (the default is ‘Observable’)

  • type_col (str, optional) – The column name containing the observable type (the default is ‘IoCType’)

  • src_index_col (str, optional) – The name of the column to use as source index. If not specified this defaults to ‘SourceIndex’. If this (or the supplied value) is not in the source dataframe, the index of the source dataframe will be used. This is retained in the output so that you can join the results back to the original data. (the default is ‘SourceIndex’)

  • kwargs (str) – key/value pairs of additional mappings to supported IoC type names e.g. ipv4=’ipaddress’, url=’httprequest’. This allows you to specify custom mappings when the source data is tagged with different names.

Returns:

Combined results of local pre-processing and VirusTotal Lookups

Return type:

pd.DataFrame

Raises:

KeyError – Unknown ioc_type

Notes

See supported_ioc_types attribute for a list of valid target types. Not all of these types are supported by VirusTotal. See ioc_vt_type_mapping for current mappings. Types mapped to None will not be submitted to VT.

For urls a full http request can be submitted, query string and fragments will be dropped before submitting. Other supported protocols are ftp, telnet, ldap, file For files MD5, SHA1 and SHA256 hashes are supported. For IP addresses only dotted IPv4 addresses are supported.

property supported_ioc_types: list[str]

Return list of supported IoC type internal names.

Returns:

list of supported IoC type internal names.

Return type:

list[str]

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.vtlookup.VTParams(api_type: str, batch_size: int, batch_delimiter: str, http_verb: str, api_var_name: str, headers: dict[str, Any] | None)

Bases: NamedTuple

VirusTotal parameter collection.

Create new instance of VTParams(api_type, batch_size, batch_delimiter, http_verb, api_var_name, headers)

api_type: str

Alias for field number 0

api_var_name: str

Alias for field number 4

batch_delimiter: str

Alias for field number 2

batch_size: int

Alias for field number 1

count(value, /)

Return number of occurrences of value.

headers: dict[str, Any] | None

Alias for field number 5

http_verb: str

Alias for field number 3

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.