Template notebooklet¶

Submodules¶

msticnb.nb.template.nb_template module¶

Template notebooklet.

Notebooklet modules have three main sections:

Result class definition: This defines the attributes and descriptions of the data that you want to return from the notebooklet.
Notebooklet class definition: This is the entry point for running the notebooklet. At minimum it should be a class derived from Notebooklet that implements a run method and returns your result class.
Functions: These do most of the work of the notebooklet and usually the code that is copied from or adapted from the original notebook.

Having the latter section is optional. You can choose to implement this functionality in instance methods of the notebooklet class.

However, there are advantages to keeping these as separate functions outside the class. It means that all the data used in the functions has to be passed around as parameters and return values. This can improve the clarity of the code and reduce errors due to some dependency on some mysterious global state.

If the user of your notebooklet wants to import the module’s code into a notebook to read and possibly adapt it, having standalone functions will make it easier from them understand and work with the code.

class msticnb.nb.template.nb_template.TemplateNB(data_providers: Optional[msticnb.data_providers.DataProviders] = None, **kwargs)¶

Bases: msticnb.notebooklet.Notebooklet

Template Notebooklet class.

Detailed description of things this notebooklet does:

Fetches all events from XYZ
Plots interesting stuff
Returns extended metadata about the thing

Document the options that the Notebooklet takes, if any, Use these control which parts of the notebooklet get run.

all_events: Gets all events about blah
plot_events: Display and summary and timeline of events.

get_metadata: fetches additional metadata about the entity

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='TemplateNB', mod_name='msticnb.nb.template.nb_template', description='Template YAML for Notebooklet', default_options=[{'all_events': 'Gets all events about blah'}, {'plot_events': 'Display and summary and timeline of events.'}], other_options=[{'get_metadata': 'fetches additional metadata about the entity'}], inputs=['value'], entity_types=['host'], keywords=['host', 'computer', 'heartbeat', 'windows', 'account'], req_providers=['AzureSentinel|LocalData', 'tilookup'])¶

module_path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/msticnb/checkouts/stable/msticnb/nb/template/nb_template.py')¶

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.nb.template.nb_template.TemplateResult¶

Return XYZ summary.

Parameters:	value (str) – Host name - The key for searches - e.g. host, account, IPaddress data (Optional[pd.DataFrame], optional) – Alternatively use a DataFrame as input. 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:	TemplateResult
Raises:	`MsticnbMissingParameterError` – If required parameters are missing

run_additional_operation(event_ids: Union[int, Iterable[int], None] = None) → pandas.core.frame.DataFrame¶

Addition method.

Parameters:	event_ids (Optional[Union[int, Iterable[int]]], optional) – Single or interable of event IDs (ints).
Returns:	Results with expanded columns.
Return type:	pd.DataFrame

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.template.nb_template.TemplateResult(description: Optional[str] = None, timespan: Optional[msticpy.common.timespan.TimeSpan] = None, notebooklet: Optional[Notebooklet] = None)¶

Bases: msticnb.notebooklet_result.NotebookletResult

Template Results.

all_events¶

DataFrame of all raw events retrieved.

Type:	pd.DataFrame

plot¶

Bokeh plot figure showing the account events on an interactive timeline.

Type:	bokeh.models.LayoutDOM

additional_info¶

Additional information for my notebooklet.

Type:	dict

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