Network notebooklets¶

`msticnb.nb.azsent.network.network_flow_summary`
`msticnb.nb.azsent.network.ip_summary`	IP Address Summary notebooklet.

Submodules¶

msticnb.nb.azsent.network.network_flow_summary module¶

msticnb.nb.azsent.network.ip_summary module¶

IP Address Summary notebooklet.

class msticnb.nb.azsent.network.ip_summary.IpAddressSummary(data_providers: Optional[msticnb.data_providers.DataProviders] = None, **kwargs)¶

Bases: msticnb.notebooklet.Notebooklet

IP Address Summary Notebooklet class.

Queries and displays summary information about an IP address, including:

Basic IP address properties
IpAddress entity (and Host entity, if a host could be associated)
WhoIs and Geo-location
Azure activity and network data (optional)
Office activity summary (optional)
Threat intelligence reports
Related alerts and hunting bookmarks

geoip: Get geo location information for IP address.
alerts: Get any alerts listing the IP address.
host_logons: Find any hosts with logons using this IP address as a source.
related_accounts: Find any accounts using this IP address in AAD or host logs.
device_info: Find any devices associated with this IP address.
device_network: Find any devices communicating with this IP address.

bookmarks: Get any hunting bookmarks listing the IP address.
heartbeat: Get the latest heartbeat record for for this IP address.
az_net_if: Get the latest Azure network analytics interface data for this IP address.
vmcomputer: Get the latest VMComputer record for this IP address.
az_netflow: Get netflow information from AzureNetworkAnalytics table.
passive_dns: Force fetching passive DNS data from a TI Provider even if IP is internal.
az_activity: AAD sign-ins and Azure Activity logs.
office_365: Office 365 activity.
common_security: Get records from common security log.
ti: Force get threat intelligence reports even for internal public IPs.

Intialize a new instance of the notebooklet class.

Parameters:	data_providers (DataProviders, Optional) – Optional DataProviders instance to query data. Most classes require this.
Raises:	`MsticnbDataProviderError` – If DataProviders has not been initialized. If required providers are specified by the notebooklet but are not available.

classmethod all_options() → List[str]¶

Return supported options for Notebooklet run function.

Returns:	Supported options.
Return type:	List[str]

browse_alerts() → msticpy.nbtools.nbwidgets.select_alert.SelectAlert¶: Return alert browser/viewer.

browse_ti_results()¶: Display Threat intel results.

check_table_exists(table: str) → bool¶

Check to see if the table exists in the provider.

Parameters:	table (str) – Table name
Returns:	True if the table exists, otherwise False.
Return type:	bool

check_valid_result_data(attrib: str = None, silent: bool = False) → bool¶

Check that the result is valid and attrib contains data.

Parameters:	attrib (str) – Name of the attribute to check, if None this function only checks for a valid _last_result. silent (bool) – If True, suppress output.
Returns:	Returns True if valid data is available, else False.
Return type:	bool

classmethod default_options() → List[str]¶

Return default options for Notebooklet run function.

Returns:	Supported options.
Return type:	List[str]

classmethod description() → str¶

Return description of the Notebooklet.

Returns:	Description
Return type:	str

display_alert_timeline()¶: Display the alert timeline.

classmethod entity_types() → List[str]¶

Entity types supported by the notebooklet.

Returns:	Entity names
Return type:	List[str]

classmethod get_help(fmt='html') → str¶: Return HTML document for class.

get_methods() → Dict[str, Callable[[Any], Any]]¶: Return methods available for this class.

get_pivot_run(get_timespan: Callable[[], msticpy.common.timespan.TimeSpan])¶: Return Pivot-wrappable run function.

get_provider(provider_name: str)¶

Return data provider for the specified name.

Parameters:	provider_name (str) – Name of the provider
Returns:	Provider instance.
Return type:	Any
Raises:	`MsticnbDataProviderError` – If provider is not found.

classmethod get_settings(print_settings=True) → Optional[str]¶

Print or return metadata for class.

Parameters:	print_settings (bool, optional) – Print to standard, by default True or return the str formatted content.
Returns:	If print_settings is True, returns None. If False, returns LF-delimited string of metadata settings.
Return type:	Optional[str]

Notes

Use metadata attribute to retrieve the metadata directly.

classmethod import_cell()¶: Import the text of this module into a new cell.

classmethod keywords() → List[str]¶

Return search keywords for Notebooklet.

Returns:	Keywords
Return type:	List[str]

list_methods() → List[str]¶: Return list of methods with descriptions.

classmethod list_options() → str¶

Return options document for Notebooklet run function.

Returns:	Supported options.
Return type:	List[str]

classmethod match_terms(search_terms: str) → Tuple[bool, int]¶

Search class definition for search_terms.

Parameters:	search_terms (str) – One or more search terms, separated by spaces or commas. Terms can be simple strings or regular expressions.
Returns:	Returns a tuple of bool (True if all terms match) and int (count of matched terms)
Return type:	Tuple[bool, int]

metadata = NBMetadata(name='IpAddressSummary', mod_name='msticnb.nb.azsent.network.ip_summary', description='IP Address Summary notebooklet', default_options=[{'geoip': 'Get geo location information for IP address.'}, {'alerts': 'Get any alerts listing the IP address.'}, {'host_logons': 'Find any hosts with logons using this IP address as a source.'}, {'related_accounts': 'Find any accounts using this IP address in AAD or host logs.'}, {'device_info': 'Find any devices associated with this IP address.'}, {'device_network': 'Find any devices communicating with this IP address.'}], other_options=[{'bookmarks': 'Get any hunting bookmarks listing the IP address.'}, {'heartbeat': 'Get the latest heartbeat record for for this IP address.'}, {'az_net_if': 'Get the latest Azure network analytics interface data for this IP address.'}, {'vmcomputer': 'Get the latest VMComputer record for this IP address.'}, {'az_netflow': 'Get netflow information from AzureNetworkAnalytics table.'}, {'passive_dns': 'Force fetching passive DNS data from a TI Provider even if IP is internal.'}, {'az_activity': 'AAD sign-ins and Azure Activity logs.'}, {'office_365': 'Office 365 activity.'}, {'common_security': 'Get records from common security log.'}, {'ti': 'Force get threat intelligence reports even for internal public IPs.'}], inputs=['value'], entity_types=['ip_address'], keywords=['ip', 'IPAddress', 'network'], req_providers=['AzureSentinel|LocalData', 'tilookup', 'geolitelookup|ipstacklookup'])¶

module_path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/msticnb/checkouts/stable/msticnb/nb/azsent/network/ip_summary.py')¶

classmethod name() → str¶

Return name of the Notebooklet.

Returns:	Name
Return type:	str

netflow_by_direction() → bokeh.plotting.figure.Figure¶: Display netflows grouped by direction.

netflow_by_protocol() → bokeh.plotting.figure.Figure¶: Display netflows grouped by protocol.

netflow_total_by_protocol() → bokeh.plotting.figure.Figure¶: Display netflows grouped by protocol.

classmethod print_options()¶: Print options for Notebooklet run function.

result¶

Return result of the most recent notebooklet run.

Returns:	Notebooklet result class or None if nothing has been run.
Return type:	Optional[NotebookletResult]

run(value: Any = None, data: Optional[pandas.core.frame.DataFrame] = None, timespan: Optional[msticpy.common.timespan.TimeSpan] = None, options: Optional[Iterable[str]] = None, **kwargs) → msticnb.nb.azsent.network.ip_summary.IpSummaryResult¶

Return IP Address activity summary.

Parameters:	value (str) – IP Address - The key for searches data (Optional[pd.DataFrame], optional) – Not supported for this notebooklet. timespan (TimeSpan) – Timespan for queries options (Optional[Iterable[str]], optional) – List of options to use, by default None. A value of None means use default options. Options prefixed with “+” will be added to the default options. To see the list of available options type help(cls) where “cls” is the notebooklet class or an instance of this class.
Returns:	Result object with attributes for each result type.
Return type:	IpSummaryResult
Raises:	`MsticnbMissingParameterError` – If required parameters are missing

classmethod show_help()¶: Display Documentation for class.

silent¶

Get the current instance setting for silent running.

Returns:	Silent running is enabled.
Return type:	Optional[bool]

class msticnb.nb.azsent.network.ip_summary.IpSummaryResult(description: Optional[str] = None, timespan: Optional[msticpy.common.timespan.TimeSpan] = None, notebooklet: Optional[Notebooklet] = None)¶

Bases: msticnb.notebooklet_result.NotebookletResult

IPSummary Results.

ip_str¶

The input IP address as a string.

Type:	str

ip_address¶

Ip Address Python object

Type:	Optional[Union[IPv4Address, IPv6Address]]

ip_entity¶

IpAddress entity

Type:	IpAddress

ip_origin¶

“External” or “Internal”

Type:	str

host_entities¶

Host entity or entities associated with IP Address

Type:	Host

ip_type¶

IP address type - “Public”, “Private”, etc.

Type:	str

geoip¶

Geo location information as a dictionary.

Type:	Optional[Dict[str, Any]]

location¶

Location entity context object.

Type:	Optional[GeoLocation]

whois¶

WhoIs information for IP Address

Type:	pd.DataFrame

whois_nets¶

List of networks definitions from WhoIs data

Type:	pd.DataFrame

heartbeat¶

Heartbeat record for IP Address or host

Type:	pd.DataFrame

az_network_if¶

Azure NSG analytics interface record, if available

Type:	pd.DataFrame

vmcomputer¶

VMComputer latest record

Type:	pd.DataFrame

az_network_flows¶

Azure NSG flows for IP, if available

Type:	pd.DataFrame

az_network_flows_timeline¶

Azure NSG flows timeline, if data is available

Type:	Figure

aad_signins¶

AAD signin activity

Type:	pd.DataFrame = None

azure_activity¶

Azure Activity log entries

Type:	pd.DataFrame = None

azure_activity_summary¶

Azure Activity (AAD and Az Activity) summarized view

Type:	pd.DataFrame = None

office_activity¶

Office 365 activity

Type:	pd.DataFrame = None

common_security¶

Common Security Log entries for source IP

Type:	pd.DataFrame

related_bookmarks¶

Bookmarks related to IP Address

Type:	pd.DataFrame

alert_timeline¶

Timeline plot of alerts

Type:	Figure

ti_results¶

Threat intel lookup results

Type:	pd.DataFrame

passive_dns¶

Passive DNS lookup results

Type:	pd.DataFrame

self.host_logons¶

Hosts with logons from this IP Address

Type:	pd.DataFrame

self.related_accounts¶

Accounts with activity related to this IP Address

Type:	pd.DataFrame

self.associated_hosts¶

Hosts using this IP Address

Type:	pd.DataFrame

self.device_info¶

Device info of hosts using this IP Address

Type:	pd.DataFrame

self.network_connections¶

Network connections to/from this IP on other devices

Type:	pd.DataFrame = None

Create new IPSummaryResult result instance.

Parameters:	description (Optional[str], optional) – Result description, by default None timespan (Optional[TimeSpan], optional) – TimeSpan for the results, by default None notebooklet (Optional[, optional) – Originating notebooklet, by default None

data_properties(empty: bool = False) → List[str]¶: Return list of attributes with populated data.

prop_doc(name) → Tuple[str, str]¶: Get the property documentation for the property.

properties¶: Return names of all properties.

view_events(summary_cols: List[str] = None, attrib: Optional[str] = None, data: Optional[pandas.core.frame.DataFrame] = None, **kwargs) → msticpy.nbtools.nbwidgets.select_item.SelectItem¶

Return simple data view for DataFrame/result attribute.

Parameters:	summary_cols (List[str], optional) – [description] attrib (Optional[str], optional) – [description], by default None data (Optional[pd.DataFrame], optional) – [description], by default None kwargs – Additional keyword arguments passed to the SelectItem widget.
Returns:	Browser for events in DataFrame.
Return type:	SelectItem
Raises:	`AttributeError` – Attribute name not in results class. `TypeError` – Input data or attribute is not a DataFrame `MsticnbMissingParameterError` – One of data or attrib parameters must be supplied `KeyError` – Summary column name specified that isn’t in the DataFrame

vis_properties() → List[str]¶: Return list of properties with visualizations.