Core modules and classes¶

Submodules¶

`msticnb.class_doc`	Functions to create documentation from notebooklets classes.
`msticnb.common`	Common definitions and classes.
`msticnb.data_providers`	Data Providers class and init function.
`msticnb.nb_browser`	Jupyter Browser for Notebooklets.
`msticnb.notebooklet`	Notebooklet base classes.
`msticnb.options`	Notebooklets global options.
`msticnb.read_modules`	read_modules - handles reading notebooklets modules.

msticnb.class_doc module¶

Functions to create documentation from notebooklets classes.

msticnb.class_doc.get_class_doc(doc_cls: type, fmt: str = 'html') → str¶

Create HTML documentation for the notebooklet class.

Parameters:	doc_cls (type) – The class to document fmt (str) – Format = “html” or “md”, by default “html”
Returns:	HTML documentation for the class
Return type:	str
Raises:	`TypeError` – If the class is not a subclass of Notebooklet.

msticnb.common module¶

Common definitions and classes.

exception msticnb.common.MsticnbDataProviderError¶

Bases: msticnb.common.MsticnbError

DataProvider Error.

args¶

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception msticnb.common.MsticnbError¶

Bases: Exception

Generic exception class for Notebooklets.

args¶

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception msticnb.common.MsticnbMissingParameterError(*args)¶

Bases: msticnb.common.MsticnbError

Parameter Error.

Exception for missing parameter.

Parameters:	args (str) – First arg is the name or names of the parameters.

args¶

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class msticnb.common.NBContainer¶

Bases: object

Container for Notebooklet classes.

iter_classes() → Iterable[Tuple[str, Any]]¶: Return iterator through all notebooklet classes.

msticnb.common.add_result(result: Any, attr_name: Union[str, List[str]])¶

Decorate func to add return value(s) to result.

Parameters:	result (Any) – Object that will have result attributes set. attr_name (str or List[str]) – Name of return attribute to set on result
Returns:	Wrapped function
Return type:	Callable[args, *kwargs]

msticnb.common.check_mp_version(required_version: str) → bool¶: Returns true if the installed version is >= required_version.

msticnb.common.df_has_data(data) → bool¶: Return True if data DataFrame has data.

msticnb.common.mp_version()¶: Return currently-loaded msticpy version.

msticnb.common.nb_data_wait(source: str)¶

Print Getting data message.

Parameters:	source (str) – The data source.

msticnb.common.nb_debug(*args)¶: Print debug args.

msticnb.common.nb_display(*args, **kwargs)¶: Ipython display function wrapper.

msticnb.common.nb_markdown(*args, **kwargs)¶: Display Markdown/HTML text.

msticnb.common.nb_print(*args, **kwargs)¶

Print output but suppress if “silent”.

Parameters:	mssg (Any) – The item/message to show

msticnb.common.nb_warn(*args, **kwargs)¶: Display Markdown/HTML warning text.

msticnb.common.set_text(title: Optional[str] = None, hd_level: int = 2, text: Optional[str] = None, md: bool = False, docs: Dict[str, Any] = None, key: str = None)¶

Decorate function to print title/text before execution.

Parameters:	title (Optional[str], optional) – Title text to print, by default None hd_level (int) – Heading level (1-4), by default 2 text (Optional[str], optional) – Text to print, by default None md (bool, optional) – Treat text as markdown, by default False docs (Dict[str, Any]) – Dictionary of cell documentation indexed by key key (str) – Item to use from docs dictionary.
Returns:	Wrapped function
Return type:	Callable[args, *kwargs]

msticnb.common.show_bokeh(plot)¶: Display bokeh plot, resetting output.

msticnb.data_providers module¶

Data Providers class and init function.

class msticnb.data_providers.ProviderDefn(prov_class, connect_reqd, get_config)¶

Bases: tuple

Create new instance of ProviderDefn(prov_class, connect_reqd, get_config)

connect_reqd¶: Alias for field number 1

count()¶: Return number of occurrences of value.

get_config¶: Alias for field number 2

index()¶

Return first index of value.

Raises ValueError if the value is not present.

prov_class¶: Alias for field number 0

class msticnb.data_providers.SingletonDecorator(wrapped_cls)¶

Bases: object

Singleton decorator class.

Notes

Using this decorator on a class enforces the following behavior: - First instantiation of class will work as normal - Subsequent attempts with the same set/values of kwargs

will just return the original class

Instantiation of the class with a different set of kwargs will instantiate a new class.
The class method current() will always return the last instance of the class.

Instantiate the class wrapper.

current()¶: Return the current instance of the wrapped class.

msticnb.data_providers.init(query_provider: str = 'AzureSentinel', providers: Optional[List[str]] = None, **kwargs)¶

Instantiate an instance of DataProviders.

Parameters:

query_provider (str, optional) – DataEnvironment name of the primary query provider. By default, “AzureSentinel”. You can add addtional query providers by including them in the providers list.
providers (Optional[List[str]], optional) – A list of provider names, by default None

Other Parameters:

kwargs – You can pass parameters to individual providers using the following notation: ProviderName_param_name=”param_value” Where `ProviderName is the name of the data provider, param_name is the parameter name expected by the provider and param_value is the value to assign to param_name. param_value can be any type.

Depending on the provider, these parameters (with the prefix stripped) are sent to either the constructor or connect method.

Notes

To see a list of currently supported providers call: DataProviders.list_providers()

msticnb.nb_browser module¶

Jupyter Browser for Notebooklets.

class msticnb.nb_browser.NBBrowser¶

Bases: object

Interactive browser/viewer for Notebooklets.

Initialize and Display Notebooklet Browser.

display()¶: Display the widget.

msticnb.nb_metadata module¶

Notebooklet base classes.

class msticnb.nb_metadata.NBMetadata(name: str = 'Unnamed', mod_name: str = '', description: str = '', default_options: List[Union[str, Dict[KT, VT]]] = NOTHING, other_options: List[Union[str, Dict[KT, VT]]] = NOTHING, inputs: List[str] = ['value'], entity_types: List[str] = NOTHING, keywords: List[str] = NOTHING, req_providers: List[str] = NOTHING)¶

Bases: object

Notebooklet metadata class.

Method generated by attrs for class NBMetadata.

all_options¶: Return combination of default and other options.

get_options(option_set: str = 'all') → List[Tuple[str, Optional[str]]]¶

Return list of options and descriptions.

Parameters:	option_set (str, optional) – The subset of options to return, by default “all” Other values are “default” and “other”
Returns:	A list of tuples of option name and description.
Return type:	List[Tuple[str, Optional[str]]]

options_doc¶: Return list of options and documentation.

search_terms¶: Return set of search terms for the object.

msticnb.nb_metadata.read_mod_metadata(mod_path: str, module_name) → Tuple[msticnb.nb_metadata.NBMetadata, Dict[str, Any]]¶

Read notebooklet metadata from yaml file.

Parameters:	mod_path (str) – The fully-qualified (dotted) module name module_name (str) – The full module name.
Returns:	A tuple of the metadata class and the documentation dictionary
Return type:	Tuple[NBMetadata, Dict[str, Any]]

msticnb.nb_metadata.update_class_doc(cls_doc: str, cls_metadata: msticnb.nb_metadata.NBMetadata)¶: Append the options documentation to the cls_doc.

msticnb.notebooklet module¶

Notebooklet base classes.

class msticnb.notebooklet.Notebooklet(data_providers: Optional[msticnb.data_providers.DataProviders] = None, **kwargs)¶

Bases: abc.ABC

Base class for Notebooklets.

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]

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

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='Notebooklet', mod_name='', description='Base class', default_options=[], other_options=[], inputs=['value'], entity_types=[], keywords=[], req_providers=[])¶

module_path = ''¶

classmethod name() → str¶

Return name of the Notebooklet.

Returns:	Name
Return type:	str

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.notebooklet_result.NotebookletResult¶

Notebooklet abstract base class.

Other Parameters:
Parameters:	value (Any, optional) – value to process, by default None data (Optional[pd.DataFrame], optional) – Input data to process, by default None timespan (Optional[TimeSpan, Any], optional) – Timespan over which operations such as queries will be performed, by default None. This can be a TimeStamp object or another object that has valid start, end, or period attributes. 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. Options prefixed with “-” will be removed from 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.
	start (Union[datetime, datelike-string]) – Alternative to specifying timespan parameter. end (Union[datetime, datelike-string]) – Alternative to specifying timespan parameter.
Returns:	Result class from the notebooklet
Return type:	NotebookletResult

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]

msticnb.notebooklet_result module¶

Notebooklet Result base classes.

class msticnb.notebooklet_result.NotebookletResult(description: Optional[str] = None, timespan: Optional[msticpy.common.timespan.TimeSpan] = None, notebooklet: Optional[Any] = None)¶

Bases: msticnb.data_viewers.DFViewer

Base result class.

Create new Notebooklet 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[Notebooklet], 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.

msticnb.options module¶

Notebooklets global options.

Available options are: [name, type (default value), description]

verbose: bool (True) - Show progress messages.
debug: bool (False) - Turn on debug output.
show_sample_results: bool (True) - Display sample of results as they are produced.
silent: bool (False) - Execute notebooklets with no output.

msticnb.options.current()¶: Show current settings.

msticnb.options.get_opt(option: str) → Any¶

Get the named option.

Parameters:	option (str) – Option name.
Returns:	Option value
Return type:	Any
Raises:	`KeyError` – An invalid option name was supplied.

msticnb.options.set_opt(option: str, value: Any)¶

Set the named option.

Parameters:	option (str) – Option name. value (Any) – Option value.
Raises:	`KeyError` – An invalid option name was supplied. `TypeError` – Option value was not the correct type.

msticnb.options.show()¶: Show help for options.

msticnb.read_modules module¶

read_modules - handles reading notebooklets modules.

class msticnb.read_modules.FindResult(full_match, match_count, name, nb_class)¶

Bases: tuple

Create new instance of FindResult(full_match, match_count, name, nb_class)

count()¶: Return number of occurrences of value.

full_match¶: Alias for field number 0

index()¶

Return first index of value.

Raises ValueError if the value is not present.

match_count¶: Alias for field number 1

name¶: Alias for field number 2

nb_class¶: Alias for field number 3

msticnb.read_modules.discover_modules(nb_path: Union[str, Iterable[str]] = None) → msticnb.common.NBContainer¶

Discover notebooks modules.

Parameters:	nb_path (Union[str, Iterable[str]], optional) – Additional path to search for notebooklets, by default None
Returns:	Container of notebooklets. This is structured as a tree mirroring the source folder names.
Return type:	NBContainer

msticnb.read_modules.find(keywords: str, full_match=True) → List[Tuple[str, msticnb.notebooklet.Notebooklet]]¶

Search for Notebooklets matching key words.

Parameters:	keywords (str) – Space or comma-separated words to search for. Terms can be regular expressions. full_match (bool) – If True only return full matches, default is True. If False it will return partial matches.
Returns:	List of matches sorted by closest match
Return type:	List[Tuple[str, Notebooklet]]

Notes

Search terms are treated as regular expressions, so any regular expression reserved characters will be treated as part of the regex pattern.

msticnb.dataviewers module¶

Data viewers mixin classes.

class msticnb.data_viewers.DFViewer¶

Bases: object

Mixin class for NotebookletResult.

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