msticpy.config package

msticpy.config.mp_config_file module

Msticpy Config class.

class msticpy.config.mp_config_file.MpConfigFile(file: Optional[str] = None, settings: Optional[Dict[str, Any]] = None)

Bases: msticpy.config.comp_edit.CompEditStatusMixin, msticpy.config.comp_edit.CompEditDisplayMixin

MSTICPy Configuration management class.

Use the functions from the commandline or display in a Jupter notebook to use interactive version.

Create an instance of the MSTICPy Configuration helper class.

Parameters
  • file (Optional[str], optional) – config file to load, by default None

  • settings (Optional[Dict[str, Any]], optional) – setting dict to load, by default None

static border_layout(width='95%')

Return border widget layout.

browse_for_file(show: bool = True)

Open the browser to browser/search fr a file.

clear_status()

Clear the status text.

property current_file

Return currently loaded file path.

load_default()

Load default settings specified by MSTICPYCONFIG env var.

load_from_file(file: str)

Load settings from file.

map_json_to_mp_ws()

Map config.json settings to MSTICPy settings.

static no_border_layout(width='95%')

Return no-border widget layout.

static refresh_mp_config()

Refresh global MSTICPy settings from config file.

save_to_file(file: str, backup: bool = True)

Save current configuration to file.

Parameters
  • file (str) – The file path to save to.

  • backup (bool, optional) – Create a backup file, if overwriting existing file, by default True

set_status(status, timeout: float = 3.0)

Set the status text.

show_kv_secrets(show: bool = True)

Show secrets from currently configured Key Vault.

status = Label(value='', layout=Layout(width='99%'))
testing = False
validate_settings(show: bool = True)

Run the validator against currently loaded settings.

view_settings(show: bool = True)

View the current settings as text.

msticpy.config.mp_config_edit module

Module docstring.

class msticpy.config.mp_config_edit.MpConfigEdit(settings: Optional[Union[Dict[str, Any], msticpy.config.mp_config_file.MpConfigFile, str]] = None, conf_filepath: Optional[str] = None)

Bases: msticpy.config.comp_edit.CompEditDisplayMixin

Msticpy Configuration helper class.

Initialize instance of MpConfigEdit.

Parameters
  • settings (Optional[Union[Dict[str, Any], MpConfigFile, str]], optional) –

    settings can be one of the following:

    • A dict of msticpyconfig settings

    • An instance of MpConfigFile with loaded settings

    • A file path to a msticpyconfig.yaml

    If None, the settings will be read from the default (via MSTICPYCONFIG variable)

  • conf_filepath (str) – If settings are passed as MPConfigFile instance or a dict, this parameter will override the file path used to save the settings. If settings is a file path, this parameter is ignored.

static border_layout(width='95%')

Return border widget layout.

property controls

Return a list of current tab names and controls.

property current_config_file

Return the currently loaded configuration file path.

static no_border_layout(width='95%')

Return no-border widget layout.

set_tab(tab_name: Optional[str], index: int = 0)

Programatically set the tab by name or index.

property tab_names

Return a list of current tabs.

msticpy.config.mp_config_control module

MP Config Control Class.

class msticpy.config.mp_config_control.MpConfigControls(mp_config_def: Dict[str, Any], mp_config: Optional[Dict[str, Any]] = None)

Bases: object

Msticpy configuration and settings database.

Return an instance of MpConfigControls.

Parameters
  • mp_config_def (Dict[str, Any]) – Msticpy config setting definitions.

  • mp_config (Optional[Dict[str, Any]], optional) – Msticpy Settings dictionary, by default None

del_control(path: str)

Delete the control stored at path.

del_value(path: str, keep_ctrl: bool = False)

Delete setting item at path.

get_control(path: str) Any

Return the control stored at path.

get_defn(path: str) Union[Dict[str, Any], Tuple[str, Any]]

Return the setting definition at path.

get_value(path: str) Any

Return setting value at path.

populate_ctrl_values(path: str)

Populate control at path from settings at path.

rename_path(old_path: str, new_path: str)

Rename a setting from old_path to new_path.

save_ctrl_values(path: str)

Save the values in the control at path to settings.

set_control(path: str, control)

Set the control stored at path.

set_value(path: str, value: Any)

Set setting value at path to value.

validate_all_settings(show_all: bool = False) List[msticpy.config.mp_config_control.ValidtnResult]

Validate settings against definitions.

Parameters

show_all (bool, optional) – Show success validations as well as failures, by default False

Returns

List of validation results: bool - True == valid status - validation result description

Return type

List[ValidtnResult]

validate_setting(path: str, defn_path: Optional[str] = None, show_all: bool = False) List[msticpy.config.mp_config_control.ValidtnResult]

Validate settings against definitions for a specific path.

Parameters
  • path (str) – The setting path

  • defn_path (Optional[str], optional) – The definition path, by default None Unless, specified this is the same as the setting path

  • show_all (bool, optional) – Return successful as well as failed validation results , by default False

Returns

List of validation results: bool - True == valid status - validation result description

Return type

List[ValidtnResult]

class msticpy.config.mp_config_control.ValidtnResult(result, status)

Bases: tuple

Create new instance of ValidtnResult(result, status)

count(value, /)

Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

property result

Alias for field number 0

property status

Alias for field number 1

msticpy.config.mp_config_control.get_mpconfig_definitions() Dict[str, Any]

Return the current msticpyconfig definition dictionary.

Returns

msticpyconfig definition dictionary

Return type

Dict[str, Any]

Raises

ValueError: – Could not load definitions from resources/mpconfig_defaults.yaml

msticpy.config.ce_common module

Component edit utility functions.

msticpy.config.ce_common.dict_to_txt(dict_val: Union[str, Dict[str, Any]]) str

Return string as “key:val; key2:val2” pairs from dict_val.

Parameters

dict_val (Union[str, Dict[str, Any]]) – Dict of key/val pairs or string of single key/value

Returns

str formatted as “key:val; key2:val2”

Return type

str

msticpy.config.ce_common.get_def_tenant_id(sub_id: str) Optional[str]

Get the tenant ID for a subscription.

Parameters

sub_id (str) – Subscription ID

Returns

TenantID or None if it could not be found.

Return type

Optional[str]

Notes

This function returns the tenant ID that owns the subscription. This may not be the correct ID to use if you are using delegated authorization via Azure Lighthouse.

msticpy.config.ce_common.get_defn_or_default(defn: Union[Tuple[str, Any], Any]) Tuple[str, Dict]

Return the type and options (or a default) for the setting definition.

Parameters

defn (Optional[Tuple[str, dict]]) – Setting definition. Returns a default of “str”, {} if no definition is passed.

Returns

Tuple of setting type and options.

Return type

Tuple[str, Dict]

msticpy.config.ce_common.get_or_create_mpc_section(mp_controls: MpConfigControls, section: str, subkey: Optional[str] = None) Any

Return (and create if it doesn’t exist) a settings section.

Parameters
  • mp_controls (MpConfigControls) – The MP Config database.

  • section (str) – The section name (top level settings item)

  • subkey (Optional[str], optional) – Optional subkey to create, by default None

Returns

The settings at that section[subkey] location.

Return type

Any

msticpy.config.ce_common.get_wgt_ctrl(setting_path: str, var_name: str, mp_controls: MpConfigControls, wgt_style: Optional[Dict[str, Any]] = None) ipywidgets.widgets.widget.Widget

Return widget appropriate to value type of var_name.

Parameters
  • setting_path (str) – The setting path (parent path) as dotted string.

  • var_name (str) – The key name for the setting below setting_path.

  • mp_controls (MpConfigControls) – Instance of MpConfigControls data

  • wgt_style (Optional[Dict[str, Any]]) –

    Dict of style and layout items: .. parsed-literal:

    {
        "style": {"description_width": "100px"},
        "layout": widgets.Layout(width="50%")
    }
    

Returns

The widget.

Return type

widgets.Widget

msticpy.config.ce_common.print_debug(*args)

Print nothing std_out (Prod version).

msticpy.config.ce_common.py_to_widget(value: Any, ctrl: Optional[ipywidgets.widgets.widget.Widget] = None, val_type: Optional[str] = None) Any

Adjust type and format to suit target widget.

Parameters
  • value (Any) – The value to process

  • ctrl (Optional[widgets.Widget], optional) – The target widget type, by default None

  • val_type (Optional[str], optional) – The target value type (“str”, “bool”), by default None

Returns

The converted value

Return type

Any

Raises

ValueError – If neither a target control or expected val_type are specified.

Notes

This function handles conversion of None to an empty string or bools expressed as text strings into actual bools.

msticpy.config.ce_common.txt_to_dict(txt_val: str) Dict[str, Any]

Return dict from string of “key:val; key2:val2” pairs.

Parameters

txt_val (str) – The key/value string (items separated by “;”, key/value separated by “:”)

Returns

Dictionary of key/values

Return type

Dict[str, Any]

msticpy.config.ce_common.widget_to_py(ctrl: Union[ipywidgets.widgets.widget.Widget, msticpy.config.comp_edit.SettingsControl]) Any

Adjust type and format of value returned from ctrl.value.

Parameters

ctrl (Union[widgets.Widget, SettingsControl]) – The source widget

Returns

Converted value.

Return type

Any

Notes

This function handles conversion of widget values to configuration (Python) values.

msticpy.config.ce_azure_sentinel module

Module docstring.

class msticpy.config.ce_azure_sentinel.CEAzureSentinel(mp_controls: msticpy.config.mp_config_control.MpConfigControls)

Bases: msticpy.config.comp_edit.CEItemsBase

Microsoft Sentinel Workspaces editor component.

Initialize an instance of CEAzureSentinel.

Parameters

mp_controls (MpConfigControls) – The config/controls/settings database

static border_layout(width='95%')

Return border widget layout.

clear_status()

Clear the status text.

static no_border_layout(width='95%')

Return no-border widget layout.

set_status(status, timeout: float = 3.0)

Set the status text.

status = Label(value='', layout=Layout(width='99%'))
testing = False

msticpy.config.ce_provider_base module

Module docstring.

class msticpy.config.ce_provider_base.CEProviders(mp_controls: msticpy.config.mp_config_control.MpConfigControls)

Bases: msticpy.config.comp_edit.CEItemsBase, abc.ABC

Abstract base class for Provider edit components.

Initialize an instance of the component.

Parameters

mp_controls (MpConfigControls) – The config/controls/settings database

static border_layout(width='95%')

Return border widget layout.

clear_status()

Clear the status text.

static no_border_layout(width='95%')

Return no-border widget layout.

set_status(status, timeout: float = 3.0)

Set the status text.

status = Label(value='', layout=Layout(width='99%'))
testing = False

msticpy.config.ce_ti_providers module

TI Providers Component Edit.

class msticpy.config.ce_ti_providers.CETIProviders(mp_controls: msticpy.config.mp_config_control.MpConfigControls)

Bases: msticpy.config.ce_provider_base.CEProviders

Threat Intel providers edit component.

Initialize an instance of the component.

Parameters

mp_controls (MpConfigControls) – The config/controls/settings database

static border_layout(width='95%')

Return border widget layout.

clear_status()

Clear the status text.

static no_border_layout(width='95%')

Return no-border widget layout.

set_status(status, timeout: float = 3.0)

Set the status text.

status = Label(value='', layout=Layout(width='99%'))
testing = False

msticpy.config.ce_data_providers module

Data Providers Component Edit.

class msticpy.config.ce_data_providers.CEDataProviders(mp_controls: msticpy.config.mp_config_control.MpConfigControls)

Bases: msticpy.config.ce_provider_base.CEProviders

Data providers edit component.

Initialize an instance of the component.

Parameters

mp_controls (MpConfigControls) – The config/controls/settings database

static border_layout(width='95%')

Return border widget layout.

clear_status()

Clear the status text.

static no_border_layout(width='95%')

Return no-border widget layout.

set_status(status, timeout: float = 3.0)

Set the status text.

status = Label(value='', layout=Layout(width='99%'))
testing = False

msticpy.config.ce_other_providers module

Other Providers Component Edit.

class msticpy.config.ce_other_providers.CEOtherProviders(mp_controls: msticpy.config.mp_config_control.MpConfigControls)

Bases: msticpy.config.ce_provider_base.CEProviders

Other (GeoIP) providers edit component.

Initialize an instance of the component.

Parameters

mp_controls (MpConfigControls) – The config/controls/settings database

static border_layout(width='95%')

Return border widget layout.

clear_status()

Clear the status text.

static no_border_layout(width='95%')

Return no-border widget layout.

set_status(status, timeout: float = 3.0)

Set the status text.

status = Label(value='', layout=Layout(width='99%'))
testing = False

msticpy.config.ce_keyvault module

Key Vault component edit.

class msticpy.config.ce_keyvault.CEKeyVault(mp_controls: msticpy.config.mp_config_control.MpConfigControls)

Bases: msticpy.config.ce_simple_settings.CESimpleSettings

Key Vault settings edit component.

Initialize the class. Set the controls and retrieve settings.

static border_layout(width='95%')

Return border widget layout.

clear_status()

Clear the status text.

static no_border_layout(width='95%')

Return no-border widget layout.

set_status(status, timeout: float = 3.0)

Set the status text.

status = Label(value='', layout=Layout(width='99%'))
testing = False

msticpy.config.ce_user_defaults module

Module docstring.

class msticpy.config.ce_user_defaults.CEAutoLoadComps(mp_controls: msticpy.config.mp_config_control.MpConfigControls)

Bases: msticpy.config.ce_user_defaults.CEAutoLoadQProvs

User Default load components edit component.

Initialize an instance of CEAutoLoad class.

Parameters

mp_controls (MpConfigControls) – The config/controls/settings database

static border_layout(width='95%')

Return border widget layout.

clear_status()

Clear the status text.

static no_border_layout(width='95%')

Return no-border widget layout.

set_status(status, timeout: float = 3.0)

Set the status text.

status = Label(value='', layout=Layout(width='99%'))
testing = False
class msticpy.config.ce_user_defaults.CEAutoLoadQProvs(mp_controls: msticpy.config.mp_config_control.MpConfigControls)

Bases: msticpy.config.comp_edit.CEItemsBase

User Default query providers edit component.

Initialize an instance of CEAutoLoad class.

Parameters

mp_controls (MpConfigControls) – The config/controls/settings database

static border_layout(width='95%')

Return border widget layout.

clear_status()

Clear the status text.

static no_border_layout(width='95%')

Return no-border widget layout.

set_status(status, timeout: float = 3.0)

Set the status text.

status = Label(value='', layout=Layout(width='99%'))
testing = False

msticpy.config.comp_edit module

Component Edit base and mixin classes.

class msticpy.config.comp_edit.CEItemsBase(mp_controls)

Bases: msticpy.config.comp_edit.CompEditItems, abc.ABC

Base class for components containing an item list.

Initialize the class. Set the controls and retrieve settings.

static border_layout(width='95%')

Return border widget layout.

clear_status()

Clear the status text.

static no_border_layout(width='95%')

Return no-border widget layout.

set_status(status, timeout: float = 3.0)

Set the status text.

status = Label(value='', layout=Layout(width='99%'))
testing = False
class msticpy.config.comp_edit.CompEditDisplayMixin

Bases: object

Mixin class with common display methods.

static border_layout(width='95%')

Return border widget layout.

static no_border_layout(width='95%')

Return no-border widget layout.

class msticpy.config.comp_edit.CompEditFrame(description: Optional[str] = None)

Bases: msticpy.config.comp_edit.CompEditDisplayMixin, msticpy.config.comp_edit.CompEditUtilsMixin, msticpy.config.comp_edit.CompEditStatusMixin

Edit frame class for components.

Initialize the class. Set a label with description as content.

static border_layout(width='95%')

Return border widget layout.

clear_status()

Clear the status text.

static no_border_layout(width='95%')

Return no-border widget layout.

set_status(status, timeout: float = 3.0)

Set the status text.

status = Label(value='', layout=Layout(width='99%'))
testing = False
class msticpy.config.comp_edit.CompEditHelp(help_text: str = '', help_uri: Optional[Dict[str, str]] = None)

Bases: object

Class to add help control.

Create help sub-component.

Parameters
  • help_text (str, optional) – The help string (HTML), by default “”

  • help_uri (Dict[str, str], optional) – Dict of named URIs {disp_txt: URI}, by default None

property layout

Return the parent widget.

set_help(help_text: str = '', help_uri: Optional[Dict[str, str]] = None)

Set the help string (HTML) and URIs.

class msticpy.config.comp_edit.CompEditItemButtons

Bases: object

Component class to add default buttons.

Initialize the class.

class msticpy.config.comp_edit.CompEditItems(description: str)

Bases: msticpy.config.comp_edit.CompEditFrame

Base class for item list and edit controls.

Initialize the class. Set a label with description as content.

static border_layout(width='95%')

Return border widget layout.

clear_status()

Clear the status text.

static no_border_layout(width='95%')

Return no-border widget layout.

set_status(status, timeout: float = 3.0)

Set the status text.

status = Label(value='', layout=Layout(width='99%'))
testing = False
class msticpy.config.comp_edit.CompEditSimple(description: str)

Bases: msticpy.config.comp_edit.CompEditFrame

Base class for simple component with only edit controls.

Initialize the class. Set a label with description as content.

static border_layout(width='95%')

Return border widget layout.

clear_status()

Clear the status text.

static no_border_layout(width='95%')

Return no-border widget layout.

set_status(status, timeout: float = 3.0)

Set the status text.

status = Label(value='', layout=Layout(width='99%'))
testing = False
class msticpy.config.comp_edit.CompEditStatusMixin

Bases: object

Mixin class with with status label.

clear_status()

Clear the status text.

set_status(status, timeout: float = 3.0)

Set the status text.

status = Label(value='', layout=Layout(width='99%'))
testing = False
class msticpy.config.comp_edit.CompEditTabs(tabs: Optional[Dict[str, Tuple[type, Union[List[Any], Dict[str, Any]]]]] = None)

Bases: object

Tab class.

Initialize the CompEditTabs class.

Parameters

tabs (Optional[Dict[str, Tuple[type, Union[List[Any], Dict[str, Any]]]]], optional) – Tab definitions or contents, by default None. Each definition can be a Tuple of class and list of args or a Tuple of class and dict of kwargs.

add_tab(tab_name: str, control: msticpy.config.comp_edit.CEItemsBase)

Add a tab with name tab_name and content control.

set_tab(tab_name: Optional[str], index: int = 0)

Programatically set the tab by name or index.

property tab_controls: Dict[str, Any]

Return a list of current tab names and controls.

property tab_names: List[str]

Return a list of current tabs.

class msticpy.config.comp_edit.CompEditUtilsMixin

Bases: object

Mixin class with common display methods.

class msticpy.config.comp_edit.SettingsControl

Bases: abc.ABC

Abstract base class for settings controls.

abstract property value: Union[str, Dict[str, Optional[str]]]

Return the current value of the control.

msticpy.config.compound_ctrls module

Compound control classes.

class msticpy.config.compound_ctrls.ArgControl(setting_path: Optional[str], name: str, store_type: str = 'Text', item_value: Optional[Any] = None)

Bases: msticpy.config.comp_edit.SettingsControl, msticpy.config.comp_edit.CompEditStatusMixin

Args setting element edit component.

Initialize and ArgControl object.

Parameters
  • setting_path (Optional[str], optional) – The full path to the setting (minus the name)

  • name (str) – The name of the setting

  • store_type (str, optional) – The storage type for the setting value, by default “Text” Other options are “EnvironmentVar” and “KeyVault”

  • item_value (Any, optional) – The value of the setting, by default None Note None is a legitimate value for store_type “KeyVault”

clear_status()

Clear the status text.

set_status(status, timeout: float = 3.0)

Set the status text.

status = Label(value='', layout=Layout(width='99%'))
testing = False
property value: Union[str, Dict[str, Optional[str]]]

Return the value of the control.

Returns

Either a string value or a dict of: {“EnvironmentVar”: value} or {“KeyVault”: value or None}

Return type

Union[str, Dict[str, Optional[str]]]

class msticpy.config.compound_ctrls.UserDefLoadComponent(mp_controls: msticpy.config.mp_config_control.MpConfigControls, comp_name: str, setting_path: str)

Bases: msticpy.config.comp_edit.SettingsControl

User Defaults Load component edit component.

Initialize the control.

Parameters
  • mp_controls (MpConfigControls) – Msticpy configu controls data store.

  • comp_name (str) – Component name

  • setting_path (str) – Path to setting (minus comp_name)

property layout

Return the widget layout for the control.

property value: Union[str, Dict[str, Optional[str]]]

Return the current value of the control.

Returns

Control value dictionary.

Return type

Optional[Dict[str, Any]]

class msticpy.config.compound_ctrls.UserDefQryProvCtrl(prov_name: str)

Bases: msticpy.config.comp_edit.SettingsControl

User Defaults Query Provider edit component.

Initialize the control.

Parameters

prov_name (str) – The query provider name

property value: Union[str, Dict[str, Optional[str]]]

Return the current value of the control.

Returns

The value dict. In cases where optional ‘alias’ and ‘connect’ settings are not used this will be an empty dictionary.

Return type

Union[str, Dict[str, Optional[str]]]

msticpy.config.compound_ctrls.get_arg_ctrl(setting_path, var_name, mp_controls)

Create the ArgControl based on the current value of the setting.

msticpy.config.file_browser module

File Browser class.

class msticpy.config.file_browser.FileBrowser(path: str = '.', select_cb: Optional[Callable[[str], Any]] = None)

Bases: msticpy.config.comp_edit.CompEditDisplayMixin

File system browser control.

Initialize the class for path and with optional callback.

Parameters
  • path (str, optional) – Path to open at, by default “.”

  • select_cb (Callable[[str], Any], optional) – Callback function, by default None. This is executed when the user hits the “Select File” button. The function is passed the path of the selected file.

PARENT = '..'
static border_layout(width='95%')

Return border widget layout.

get_folder_list(folders: List[str]) List[str]

Return sorted list of folders with ‘..’ inserted if not root.

static no_border_layout(width='95%')

Return no-border widget layout.

static read_folder(folder: str) Tuple[List[str], List[str]]

Return folder contents.

Parameters

folder (str) – Folder path.

Returns

List of folders and files in the folder.

Return type

Tuple[List[str], List[str]]