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.

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: Union[Dict[str, Any], msticpy.config.mp_config_file.MpConfigFile, str, None] = None, conf_filepath: 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.

controls

Return a list of current tab names and controls.

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.

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()

Return number of occurrences of value.

index()

Return first index of value.

Raises ValueError if the value is not present.

result

Alias for field number 0

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[KT, VT]]

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: 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: 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
layout

Return the parent widget.

set_help(help_text: str = '', help_uri: 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.

tab_controls

Return a list of current tab names and controls.

tab_names

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.

value

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: 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
value

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)
layout

Return the widget layout for the control.

value

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
value

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: 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]]