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.

msticpy.context.ip_utils.convert_to_ip_entities(ip_str=None, data=None, ip_col=None, *, geo_lookup=True)

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, az_net_df=None)

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

Return type:

IpAddress

msticpy.context.ip_utils.get_asn_details(asns)

Get details about an ASN(s) from its number.

Parameters:

asns (Union[str, List]) – A single ASN or list of ASNs to lookup.

Returns:

Details about the ASN(s) if a single ASN provided, result is a dictionary. If multiple provided, results are returned as a DataFrame.

Return type:

Union[pd.DataFrame, Dict]

msticpy.context.ip_utils.get_asn_from_ip(ip=None, ip_address=None)

Get the ASN that an IP belongs to.

Parameters:

  • ip (Union[str, IpAddress]) – IP address to lookup.

  • ip_address (Union[str, IpAddress]) – IP address to lookup (alias of ip).

Returns:

Details of the ASN that the IP belongs to.

Return type:

dict

msticpy.context.ip_utils.get_asn_from_name(name)

Get a list of ASNs that match a name.

Parameters:

name (str) – The name of the ASN to search for

Returns:

A list of ASNs that match the name.

Return type:

Dict

Raises:
msticpy.context.ip_utils.get_ip_type(ip=None, ip_str=None)

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, ip_column, *, all_columns=True, asn_col='AsnDescription', whois_col='WhoIsData', show_progress=False)

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 (bool) – 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=None, *, show_progress=False, ip_str=None)

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.

Deprecated since version 2.1.0: Replaced with ip_whois function

msticpy.context.ip_utils.ip_whois(ip=None, ip_address=None, *, raw=False, query_rate=0.5, retry_count=5)

Lookup IP Whois information.

Parameters:

  • ip (Union[IpAddress, str, List]) – An IP address or list of IP addresses to lookup.

  • ip_address (Union[IpAddress, str, List]) – An IP address or list of IP addresses to lookup. Alias of ip.

  • raw (bool, optional) – Set True if raw whois result wanted, by default False

  • query_rate (float, optional) – Controls the rate at which queries are made, by default 0.5

  • retry_count (int, optional) – The number of times to retry a query if it fails, default is 5

Returns:

If a single IP Address provided result is a dictionary if multiple provided results are formatted as a dataframe.

Return type:

Union[pd.DataFrame, Dict]

Raises:

ValueError: – If neither ip nor ip_address is supplied.