msticpy.context.ip_utils module

ip_utils - IP Address functions.

Contains a series of functions required to manipulate and enrich IP Address data to assist investigations.

Designed to support any data source containing IP address entity.

class msticpy.context.ip_utils.IpWhoisAccessor(pandas_obj)

Bases: object

Pandas api extension for IP Whois lookup.

Instantiate pandas extension class.

lookup(ip_column, **kwargs)

Extract IoCs from either a pandas DataFrame.

Parameters

  • ip_column (str) – Column name of IP Address to look up.

  • asn_col (str, optional) – Name of the output column for ASN description, by default “ASNDescription”

  • whois_col (str, optional) – Name of the output column for full whois data, by default “WhoIsData”

  • show_progress (bool, optional) – Show progress for each query, by default False

Returns

Output DataFrame with results in added columns.

Return type

pd.DataFrame

msticpy.context.ip_utils.convert_to_ip_entities(ip_str: Optional[str] = None, data: Optional[DataFrame] = None, ip_col: Optional[str] = None, geo_lookup: bool = True) → List[IpAddress]

Take in an IP Address string and converts it to an IP Entity.

Parameters

  • ip_str (str) – A string with a single IP Address or multiple addresses delimited by comma or space

  • data (pd.DataFrame) – Use DataFrame as input

  • ip_col (str) – Column containing IP addresses

  • geo_lookup (bool) – If true, do geolocation lookup on IPs, by default, True

Returns

The populated IP entities including address and geo-location

Return type

List

Raises

ValueError – If neither ip_string or data/column provided as input

msticpy.context.ip_utils.create_ip_record(heartbeat_df: DataFrame, az_net_df: Optional[DataFrame] = None) → IpAddress

Generate ip_entity record for provided IP value.

Parameters

  • heartbeat_df (pd.DataFrame) – A dataframe of heartbeat data for the host

  • az_net_df (pd.DataFrame) – Option dataframe of Azure network data for the host

Returns

  • IP – Details of the IP data collected

  • .. deprecated:: 1.4.0 – Will be removed in a version 2.2

msticpy.context.ip_utils.get_ip_type(ip: Optional[str] = None, ip_str: Optional[str] = None) → str

Validate value is an IP address and determine IPType category.

(IPAddress category is e.g. Private/Public/Multicast).

Parameters

  • ip (str) – The string of the IP Address

  • ip_str (str) – The string of the IP Address - alias for ip

Returns

Returns ip type string using ip address module

Return type

str

msticpy.context.ip_utils.get_whois_df(data: DataFrame, ip_column: str, all_columns: bool = False, asn_col: str = 'AsnDescription', whois_col: Optional[str] = None, show_progress: bool = False) → DataFrame

Retrieve Whois ASN information for DataFrame of IP Addresses.

Parameters

  • data (pd.DataFrame) – Input DataFrame

  • ip_column (str) – Column name of IP Address to look up.

  • all_columns – Expand all whois data to columns.

  • asn_col (str, optional) – Name of the output column for ASN description, by default “ASNDescription”. Ignored if all_columns is True.

  • whois_col (str, optional) – Name of the output column for full whois data, by default “WhoIsData” Ignored if all_columns is True.

  • show_progress (bool, optional) – Show progress for each query, by default False

Returns

Output DataFrame with results in added columns.

Return type

pd.DataFrame

msticpy.context.ip_utils.get_whois_info(ip: str = None, show_progress: bool = False, **kwargs) → Tuple[str, dict]

Retrieve whois ASN information for given IP address using IPWhois python package.

Parameters

  • ip (str) – IP Address to look up.

  • ip_str (str) – alias for ip.

  • show_progress (bool, optional) – Show progress for each query, by default False

Returns

Details of the IP data collected

Return type

IP

Notes

This function uses the Python functools lru_cache and will return answers from the cache for previously queried IP addresses.