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: str | None = None, data: DataFrame | None = None, ip_col: str | None = 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: DataFrame | None = 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_asn_details(asns: str | List) DataFrame | Dict
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: str | IpAddress | None = None, ip_address: str | IpAddress | None = None) Dict
Get the ASN that an IP belongs to.
- msticpy.context.ip_utils.get_asn_from_name(name: str) Dict
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:
MsticpyConnectionError – If the list of all ASNs cannot be retrieved.
MsticpyException – If no matches found.
- msticpy.context.ip_utils.get_ip_type(ip: str | None = None, ip_str: str | None = 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 = True, asn_col: str = 'AsnDescription', whois_col: str | None = 'WhoIsData', 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.
Deprecated since version 2.1.0: Replaced with ip_whois function
- msticpy.context.ip_utils.ip_whois(ip: IpAddress | str | List | Series | None = None, ip_address: IpAddress | str | List | Series | None = None, raw=False, query_rate: float = 0.5, retry_count: int = 5) DataFrame | Tuple
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.