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.
- settings (Optional[Union[Dict[str, Any], MpConfigFile, str]], optional) –
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¶
-
static
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¶
-
static
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¶
-
static
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¶
-
static
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¶
-
static
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¶
-
static
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¶
-
static
-
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¶
-
static
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¶
-
static
-
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.
-
static
-
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¶
-
static
-
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¶
-
static
-
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¶
-
static
-
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.
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]]