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.df_has_data(data) → bool

Return True if data DataFrame has data.

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, 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=[], 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.

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.
Other Parameters:
 
  • 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
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], attrib: Optional[str] = None, data: Optional[pandas.core.frame.DataFrame] = None, **kwargs) → msticpy.nbtools.nbwidgets.SelectItem

Return simple data view for DataFrame/result attribute.

Parameters:
  • summary_cols (List[str]) – [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

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], attrib: Optional[str] = None, data: Optional[pandas.core.frame.DataFrame] = None, **kwargs) → msticpy.nbtools.nbwidgets.SelectItem

Return simple data view for DataFrame/result attribute.

Parameters:
  • summary_cols (List[str]) – [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