msticpy.common package
msticpy.common.utility module
Miscellaneous helper methods for Jupyter Notebooks.
- msticpy.common.utility.arg_to_list(arg: Union[str, List[str]], delims=',; ') List[str]
Convert an optional list/str/str with delims into a list.
- Parameters
arg (Union[str, List[str]]) – A string, delimited string or list
delims (str, optional) – The default delimiters to use, by default “,; “
- Returns
List of string components
- Return type
List[str]
- Raises
TypeError – If arg is not a string or list
- msticpy.common.utility.check_and_install_missing_packages(required_packages: List[str], force_notebook: bool = False, user: bool = False, upgrade: bool = False) bool
Check and install missing packages from provided list of packages.
- Parameters
required_packages (List[str]) – List of packages to check and install in a current environment Note you can add package version constraints by appending them to the package name, e.g. pandas>=1.01
force_notebook (bool, optional) – Boolean value to force notebook version of progress bar, by default False (autodetect)
user (bool, optional) – Boolean value to toggle user flag while installing pip packages, by default False
upgrade (bool, option) – If true supply –upgrade flag to pip to install the latest version (applies to all package in required_packages)
- Returns
True if successful, else False
- Return type
bool
- msticpy.common.utility.check_kwarg(arg_name: str, legal_args: List[str])
Check argument names against a list.
- Parameters
arg_name (str) – Argument to check
legal_args (List[str]) – List of possible arguments.
- Raises
NameError – If the argument is not legal. If the arg_name is a close match to one or more, legal_args these are returned in the exception.
- msticpy.common.utility.check_kwargs(supplied_args: Dict[str, Any], legal_args: List[str])
Check all kwargs names against a list.
- Parameters
supplied_args (Dict[str, Any]) – Arguments to check
legal_args (List[str]) – List of possible arguments.
- Raises
NameError – If any of the arguments are not legal. If the an arg is a close match to one or more legal_args, these are returned in the exception.
- msticpy.common.utility.check_py_version(min_ver: Tuple = (3, 6))
Check that the current python version is not less than min_ver.
- Parameters
min_ver (Tuple, optional) – Minimum required version, by default (3,6)
- msticpy.common.utility.collapse_dicts(*dicts: Dict[Any, Any]) Dict[Any, Any]
Merge multiple dictionaries - later dicts have higher precendence.
- msticpy.common.utility.enum_parse(enum_cls: type, value: str) Optional[enum.Enum]
Try to parse a string value to an Enum member.
- msticpy.common.utility.escape_windows_path(str_path: str) str
Escape backslash characters in a string.
- msticpy.common.utility.export(func: Callable)
Decorate function or class to export to __all__.
- msticpy.common.utility.is_ipython() bool
Return True if running in IPython environment.
- Returns
True if running in IPython environment, otherwise False
- Return type
bool
- msticpy.common.utility.is_not_empty(test_object: Any) bool
Return True if the test_object is not None or empty.
- msticpy.common.utility.is_valid_uuid(uuid_str: Any) bool
Return true if uuid_str is a value GUID/UUID.
- Parameters
uuid_str (Any) – String to test
- Returns
True if valid GUID/UUID.
- Return type
bool
- msticpy.common.utility.md(string: str, styles: Optional[Union[str, Iterable[str]]] = None, disp_id: Optional[Union[bool, IPython.core.display.DisplayHandle]] = None) IPython.core.display.DisplayHandle
Display a string as Markdown with optional style.
- Parameters
string (str) – The string to display
styles (Union[str, Iterable[str]], optional) – A style mnemonic or collection of styles. If multiple styles, these can be supplied as an interable of strings or a comma-separated string, by default None
disp_id (Optional[Union[bool, DisplayHandle]], optional) – If True, the function will return a display handle that can be re-used in subsequent calls to update the display object. If this is previously-created display handle, this is used as the target display object to update it with the content of this call, by default None
- Returns
A handle to the display object that can be used to update the contents.
- Return type
DisplayHandle
- msticpy.common.utility.md_error(string: str, disp_id: Optional[IPython.core.display.DisplayHandle] = None)
Return string as an error - red text prefixed by “Error”.
- Parameters
string (str) – The error message.
disp_id (Optional[Union[bool, DisplayHandle]], optional) – If True, the function will return a display handle that can be re-used in subsequent calls to update the display object. If this is previously-created display handle, this is used as the target display object to update it with the content of this call, by default None
- msticpy.common.utility.md_warn(string: str, disp_id: Optional[IPython.core.display.DisplayHandle] = None)
Return string as a warning - orange text prefixed by “Warning”.
- Parameters
string (str) – The warning message.
disp_id (Optional[DisplayHandle], optional) – If True, the function will return a display handle that can be re-used in subsequent calls to update the display object. If this is previously-created display handle, this is used as the target display object to update it with the content of this call, by default None
- Returns
A handle to the display object that can be used to update the contents.
- Return type
DisplayHandle
- msticpy.common.utility.resolve_pkg_path(part_path: str)
Resolve a path relative to the package.
- Parameters
part_path (str) – Absolute or relative path to resolve.
- msticpy.common.utility.search_for_file(pattern: str, paths: Optional[List[Union[str, pathlib.Path]]] = None) Optional[str]
Search paths for file pattern.
- msticpy.common.utility.set_unit_testing(on: bool = True)
Set flag env var to indicated that code is being unit-tested.
- Parameters
on (bool, optional) – Turn unit testing flag on or off, by default True
- msticpy.common.utility.string_empty(string: str) bool
Return True if the input string is None or whitespace.
- msticpy.common.utility.unescape_windows_path(str_path: str) str
Remove escaping from backslash characters in a string.
- msticpy.common.utility.unit_testing() bool
Return True if in unit testing.
- Returns
True if in unit testing
- Return type
bool
- msticpy.common.utility.valid_pyname(identifier: str) str
Return legal Python identifier, which doesn’t collide with builtins.
- Parameters
identifier (str) – The input identifier
- Returns
The cleaned identifier
- Return type
str
msticpy.common.wsconfig module
Module for Log Analytics-related configuration.
- class msticpy.common.wsconfig.WorkspaceConfig(workspace: Optional[str] = None, config_file: Optional[str] = None, interactive: bool = True)
Bases:
object
Workspace configuration class.
Load current Azure Notebooks configuration for Log Analytics.
- Parameters
config_file (Optional[str], optional) – path to a configuration file, If not specified, the defaults is to use a configured msticpyconfig.yaml If this isn’t configured, it will search for (first) a config.json and (second) a msticpyconfig.yaml in (first) the current directory and (second) the parent directory and subfolders.
workspace (str, Optional[str]) – Workspace name (where multiple workspaces are configured), by default the Default workspace will be used.
interactive (bool, optional) – If this is False, initializing the class will not raise an exception if no configuration is found. By default, True.
- CONF_RES_GROUP_KEY = 'resource_group'
- CONF_SUB_ID_KEY = 'subscription_id'
- CONF_TENANT_ID_KEY = 'tenant_id'
- CONF_WS_ID_KEY = 'workspace_id'
- CONF_WS_NAME_KEY = 'workspace_name'
- PKG_CONF_TENANT_KEY = 'TenantId'
- PKG_CONF_WS_KEY = 'WorkspaceId'
- RESOURCE_GROUP = '{{cookiecutter.resource_group}}'
- SUBSCRIPTION_ID = '{{cookiecutter.subscription_id}}'
- TENANT_ID = '{{cookiecutter.tenant_id}}'
- WORKSPACE_ID = '{{cookiecutter.workspace_id}}'
- WORKSPACE_NAME = '{{cookiecutter.workspace_name}}'
- property code_connect_str: str
Return the Log Analytics connection string for dev code auth.
- Returns
Connection string
- Return type
str
- property config_loaded: bool
Return True if workspace id and tenant id have values.
- Returns
True if configuration loaded.
- Return type
bool
- classmethod list_workspaces() Dict
Return list of available workspaces.
- Returns
Dictionary of workspaces with workspace and tenantIds.
- Return type
Dict
- prompt_for_ws()
Display an interactive prompt for Workspace details.
msticpy.common.azure_auth module
Azure authentication handling.
- msticpy.common.azure_auth.az_connect(auth_methods: Optional[List[str]] = None, silent: bool = False) msticpy.common.azure_auth_core.AzCredentials
Connect to Azure SDK/API.
- Parameters
auth_methods (List[str], optional) – List of authentication methods to try Possible options are: - “env” - to get authentication details from environment variables - “cli” - to use Azure CLI authentication details - “msi” - to user Managed Service Identity details - “interactive” - to prompt for interactive login Default is [“env”, “cli”, “msi”, “interactive”]
silent (bool, optional) – Set True to hide all output during connection, by default False
- Returns
Named tuple of: - legacy (ADAL) credentials - modern (MSAL) credentials
- Return type
- Raises
CloudError – If chained token credential creation fails.
- msticpy.common.azure_auth.az_user_connect(silent: bool = False) msticpy.common.azure_auth_core.AzCredentials
Authenticate to the SDK using user based authentication methods, Azure CLI or interactive logon.
- Parameters
silent (bool, optional) – Whether you want the auth process to display any output, by default False
- Returns
- Return type
msticpy.common.azure_auth_core module
Azure KeyVault pre-authentication.
- class msticpy.common.azure_auth_core.AzCredentials(legacy, modern)
Bases:
tuple
Create new instance of AzCredentials(legacy, modern)
- 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 legacy
Alias for field number 0
- property modern
Alias for field number 1
- class msticpy.common.azure_auth_core.AzureCliStatus(value)
Bases:
enum.Enum
Enumeration for _check_cli_credentials return values.
- CLI_NEEDS_SIGN_IN = 2
- CLI_NOT_INSTALLED = 1
- CLI_OK = 0
- CLI_TOKEN_EXPIRED = 3
- CLI_UNKNOWN_ERROR = 4
- class msticpy.common.azure_auth_core.AzureCloudConfig(cloud: Optional[str] = None)
Bases:
object
Azure Cloud configuration.
Initialize AzureCloudConfig from cloud or configuration.
- Parameters
cloud (str, optional) – The cloud to retrieve configuration for. If not supplied, the cloud ID is read from configuration. If this is not available, it defaults to ‘global’.
- property cloud_names: List[str]
Return a list of current cloud names.
- property endpoints: msrestazure.azure_cloud.CloudEndpoints
Get a list of all the endpoints for an Azure cloud.
- Returns
A dictionary of endpoints for the cloud.
- Return type
dict
- Raises
MsticpyAzureConfigError – If the cloud name is not valid.
- static resolve_cloud_alias(alias) Optional[str]
Return match of cloud alias or name.
- property suffixes: msrestazure.azure_cloud.CloudSuffixes
Get a list of all the suffixes for an Azure cloud.
- Returns
A dictionary of suffixes for the cloud.
- Return type
dict
- Raises
MsticpyAzureConfigError – If the cloud name is not valid.
- property token_uri: str
Return the resource manager token URI.
- msticpy.common.azure_auth_core.az_connect_core(*args, **kwargs)
Authenticate using multiple authentication sources.
- Parameters
auth_methods (List[str], optional) – List of authentication methods to try Possible options are: - “env” - to get authentication details from environment variables - “cli” - to use Azure CLI authentication details - “msi” - to user Managed Service Identity details - “interactive” - to prompt for interactive login If not set, it will use the value defined in msticpyconfig.yaml. If this is not set, the default is [“env”, “cli”, “msi”, “interactive”]
cloud (str, optional) – What Azure cloud to connect to. By default it will attempt to use the cloud setting from config file. If this is not set it will default to Azure Public Cloud
silent (bool, optional) – Whether to display any output during auth process. Default is False.
- Returns
Named tuple of: - legacy (ADAL) credentials - modern (MSAL) credentials
- Return type
- Raises
MsticpyAzureConnectionError – If invalid auth options are presented.
CloudError – If chained token credential creation fails.
Notes
The function tries to obtain credentials from the following sources: - Azure Auth Environment variables - Azure CLI (if an active session is logged on) - Managed Service Identity - Interactive browser logon If the authentication is successful both ADAL (legacy) and MSAL (modern) credential types are returned.
- msticpy.common.azure_auth_core.check_cli_credentials() Tuple[msticpy.common.azure_auth_core.AzureCliStatus, Optional[str]]
Check to see if there is a CLI session with a valid AAD token.
- msticpy.common.azure_auth_core.default_auth_methods() List[str]
Get the default (all) authentication options.
- msticpy.common.azure_auth_core.only_interactive_cred(chained_cred: azure.identity.ChainedTokenCredential)
Return True if only interactivebrowser credentials available.
msticpy.common.keyvault_client module
Keyvault client - adapted from Bluehound code.
- class msticpy.common.keyvault_client.BHKeyVaultClient(tenant_id: Optional[str] = None, vault_uri: Optional[str] = None, vault_name: Optional[str] = None, settings: Optional[msticpy.common.keyvault_settings.KeyVaultSettings] = None, **kwargs)
Bases:
object
Core KeyVault client.
Initialize the BHKeyVault client.
- Parameters
tenant_id (str) – The tenant ID of the service
vault_uri (str, optional) – The full URI of the keyvault, by default None
vault_name (str, optional) – The name of the keyvault in the public cloud, by default None
auth_methods (List[str]) – The authentication methods to use for Key Vault auth Possible values are: - “env” - to get authentication details from environment varibales - “cli” - to use Azure CLI authentication details - “msi” - to user Managed Service Indenity details - “interactive” - to prompt for interactive login
authn_type (str, optional) – [deprecated - use auth_methods] Authentication mode, by default ‘interactive’ Supported options are: - ‘device’ for device code authentication - ‘interactive’ for interactive browser authentication
authority (str, optional) – The AAD authority - one of ‘global’, ‘usgov’, ‘de’ or ‘chi’
authority_uri (str, optional) – The AAD authority URI - overrides authority
settings (KeyVaultSettings) – An instance of KeyVaultSettings containing KV parameters.
debug (bool, optional) – [description], by default False
- Raises
KeyVaultMissingVaultException – No Vault name or URI supplied.
Notes
The parameter values can also be obtained from the KeyVault section of msticpyconfig.yaml.
- get_secret(secret_name: str) Any
Retrieve a secret from the Vault.
- Parameters
secret_name (str) – Name of the secret
- Returns
The secret value
- Return type
Any
- Raises
KeyVaultMissingSecretException – Secret not found in the Vault.
- property secrets
Return the list of secret names from the vault.
- set_secret(secret_name: str, value: Any) azure.keyvault.secrets.KeyVaultSecret
Set a secret in the Vault.
- Parameters
secret_name (str) – Name of the secret
value (Any) – Secret value
- Returns
The secrets bundle for the secret
- Return type
KeyVaultSecret
- class msticpy.common.keyvault_client.BHKeyVaultMgmtClient(tenant_id: Optional[str] = None, subscription_id: Optional[str] = None, resource_group: Optional[str] = None, azure_region: Optional[str] = None, settings: Optional[msticpy.common.keyvault_settings.KeyVaultSettings] = None, **kwargs)
Bases:
object
Core KeyVault Management client.
Initialize BH KeyVault Management Client.
- Parameters
tenant_id (str, Optional) – Tenant ID
subscription_id (str, Optional) – Subscription ID
resource_group (str, Optional) – Resource Group name
azure_region (str, Optional) – Azure region - needed to create a new vault. By default, None
settings (KeyVaultSettings) – An instance of KeyVaultSettings containing KV parameters.
mgmt_uri (str, Optional) – The URI for Azure management endpoints.
Notes
The parameter values can also be obtained from the KeyVault section of msticpyconfig.yaml.
- create_vault(vault_name: str) azure.mgmt.keyvault.models.Vault
Create new or update existing vault.
- Parameters
vault_name (str) – Name of the Vault
- Returns
The Vault object.
- Return type
Vault
- get_vault_uri(vault_name: str) str
Return the URI for a vault name.
- Parameters
vault_name (str) – The Vault name.
- Returns
Vault URI.
- Return type
str
- list_vaults() List[str]
Return a list of vaults for the subscription.
- Returns
Vault names
- Return type
List[str]
msticpy.common.secret_settings module
Settings provider for secrets.
- class msticpy.common.secret_settings.KeyringClient(name: str = 'key-cache', debug: bool = False)
Bases:
object
Keyring client wrapper.
Initialize the keyring client.
- Parameters
name (str, optional) – Name of the credential group, by default “key-cache”
debug (bool, optional) – Output debug info, by default False
- get_secret(secret_name: str) Any
Retrieve a secret from the keyring.
- Parameters
secret_name (str) – Secret name.
- Returns
Secret value.
- Return type
Any
- static is_keyring_available() bool
Test if valid keyring backend is available.
- Returns
True if Keyring has a usable backend, False if not.
- Return type
bool
- set_secret(secret_name: str, secret_value: Any)
Set a secret in the keyring group.
- Parameters
secret_name (str) – Name of the secret
secret_value (Any) – Secret value
- class msticpy.common.secret_settings.SecretsClient(tenant_id: Optional[str] = None, use_keyring: bool = False)
Bases:
object
Secrets client - manages keyvault and keyring secrets.
Initialize SecretsClient instance.
- Parameters
tenant_id (str, optional) – TenantID, by default None
use_keyring (bool, optional) – If True use keyring to cache secrets, by default False
- Raises
MsticpyKeyVaultConfigError – Missing or invalid configuration settings.
Notes
Requires KeyVault settings to be defined in msticpyconfig.yaml
- static format_kv_name(setting_path)
Return normalized name for use as a KeyVault secret name.
- get_secret_accessor(setting_path: str) Callable[[], Any]
Return accessor function for a secret.
- Parameters
setting_path (str) – The msticpy configuration path (dot-separated)
- Returns
Accessor function for the secret value.
- Return type
Callable[[None], Any]
- static read_secret(secret_object: Any) Any
Return the secret value.
- Parameters
secret_object (Any) – If it is a func, call and return the return value of that func. Otherwise just return the object.
- Returns
The secret value
- Return type
Any
msticpy.common.provider_settings module
Helper functions for configuration settings.
- class msticpy.common.provider_settings.ProviderArgs(**kwargs)
Bases:
collections.UserDict
ProviderArgs dictionary.
- clear() None. Remove all items from D.
- copy()
- classmethod fromkeys(iterable, value=None)
- get(k[, d]) D[k] if k in D, else d. d defaults to None.
- items() a set-like object providing a view on D's items
- keys() a set-like object providing a view on D's keys
- pop(k[, d]) v, remove specified key and return the corresponding value.
If key is not found, d is returned if given, otherwise KeyError is raised.
- popitem() (k, v), remove and return some (key, value) pair
as a 2-tuple; but raise KeyError if D is empty.
- setdefault(k[, d]) D.get(k,d), also set D[k]=d if k not in D
- update([E, ]**F) None. Update D from mapping/iterable E and F.
If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v
- values() an object providing a view on D's values
- class msticpy.common.provider_settings.ProviderSettings(name: str, description: str, provider: Optional[str] = None, args: msticpy.common.provider_settings.ProviderArgs = NOTHING, primary: bool = False)
Bases:
object
Provider settings.
Method generated by attrs for class ProviderSettings.
- description: str
- name: str
- primary: bool
- provider: Optional[str]
- msticpy.common.provider_settings.get_provider_settings(config_section='TIProviders') Dict[str, msticpy.common.provider_settings.ProviderSettings]
Read Provider settings from package config.
- Parameters
config_section (str, optional) – [description], by default “TIProviders”
- Returns
Provider settings indexed by provider name.
- Return type
Dict[str, ProviderSettings]
- msticpy.common.provider_settings.reload_settings()
Reload settings from config files.
- Parameters
clear_keyring (bool, optional) – Clears any secrets cached in keyring, by default False
msticpy.common.exceptions module
Miscellaneous helper methods for Jupyter Notebooks.
- exception msticpy.common.exceptions.MsticpyAzureConfigError(*args, help_uri: Optional[Union[Tuple[str, str], str]] = None, **kwargs)
Bases:
msticpy.common.exceptions.MsticpyUserConfigError
Exception class for AzureData.
Create Azure data missing configuration exception.
- Parameters
help_uri (Union[Tuple[str, str], str, None], optional) – Override the default help URI.
- DEF_HELP_URI = ('Using the Azure API connector', 'https://msticpy.readthedocs.io/en/latest/data_acquisition/AzureData.html#instantiating-and-connecting-with-an-azure-data-connector')
- args
- property help_uri: Union[Tuple[str, str], str]
Get the default help URI.
- classmethod no_display_exceptions()
Context manager to block exception display to IPython/stdout.
- with_traceback()
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception msticpy.common.exceptions.MsticpyAzureConnectionError(*args, help_uri: Optional[Union[Tuple[str, str], str]] = None, **kwargs)
Bases:
msticpy.common.exceptions.MsticpyUserError
Exception class for Azure Connection errors.
Create an instance of the MsticpyUserError class.
- Parameters
args (Iterable of strings) – Args will be printed as text of the exception.
help_uri (Union[Tuple[str, str], str, None], optional) – Primary URL, by default “https://msticpy.readthedocs.org”
title (str) – If a title keyword argument is supplied it will be used to create the title line.
*_uri (str) – Additional keyword arguments who’s names end in “_uri” will be used to create a list of references in addition to the primary help_uri
Notes
The exception text is displayed when the exception is created and not when it is raised. We recommend creating the exception within the raise statement. E.g.
raise MsticpyUserException(arg1, arg2…)
Developer note: Any classes derived from MsticpyUserError should be named with an “Error” suffix to distinguish these from standard exception types.
- DEF_HELP_URI = ('Connecting to Microsoft Sentinel', 'https://msticpy.readthedocs.io/en/latest/data_acquisition/AzureData.html#instantiating-and-connecting-with-an-azure-data-connector')
- args
- property help_uri: Union[Tuple[str, str], str]
Get the default help URI.
- classmethod no_display_exceptions()
Context manager to block exception display to IPython/stdout.
- with_traceback()
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception msticpy.common.exceptions.MsticpyConfigException
Bases:
msticpy.common.exceptions.MsticpyException
Configuration exception class for msticpy.
- args
- with_traceback()
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception msticpy.common.exceptions.MsticpyConnectionError(*args, help_uri: Optional[Union[Tuple[str, str], str]] = None, **kwargs)
Bases:
msticpy.common.exceptions.MsticpyUserError
Exception class for KqlConnection errors.
Create an instance of the MsticpyUserError class.
- Parameters
args (Iterable of strings) – Args will be printed as text of the exception.
help_uri (Union[Tuple[str, str], str, None], optional) – Primary URL, by default “https://msticpy.readthedocs.org”
title (str) – If a title keyword argument is supplied it will be used to create the title line.
*_uri (str) – Additional keyword arguments who’s names end in “_uri” will be used to create a list of references in addition to the primary help_uri
Notes
The exception text is displayed when the exception is created and not when it is raised. We recommend creating the exception within the raise statement. E.g.
raise MsticpyUserException(arg1, arg2…)
Developer note: Any classes derived from MsticpyUserError should be named with an “Error” suffix to distinguish these from standard exception types.
- DEF_HELP_URI = ('DataProviders', 'https://msticpy.readthedocs.io/en/latest/data_acquisition/DataProviders.html')
- args
- property help_uri: Union[Tuple[str, str], str]
Get the default help URI.
- classmethod no_display_exceptions()
Context manager to block exception display to IPython/stdout.
- with_traceback()
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception msticpy.common.exceptions.MsticpyDataQueryError(*args, help_uri: Optional[Union[Tuple[str, str], str]] = None, **kwargs)
Bases:
msticpy.common.exceptions.MsticpyUserError
Exception class for data query errors.
Create an instance of the MsticpyUserError class.
- Parameters
args (Iterable of strings) – Args will be printed as text of the exception.
help_uri (Union[Tuple[str, str], str, None], optional) – Primary URL, by default “https://msticpy.readthedocs.org”
title (str) – If a title keyword argument is supplied it will be used to create the title line.
*_uri (str) – Additional keyword arguments who’s names end in “_uri” will be used to create a list of references in addition to the primary help_uri
Notes
The exception text is displayed when the exception is created and not when it is raised. We recommend creating the exception within the raise statement. E.g.
raise MsticpyUserException(arg1, arg2…)
Developer note: Any classes derived from MsticpyUserError should be named with an “Error” suffix to distinguish these from standard exception types.
- DEF_HELP_URI = ('Query failed', 'https://msticpy.readthedocs.io/en/latest/DataAcquisition.html#querying-and-importing-data')
- args
- property help_uri: Union[Tuple[str, str], str]
Get the default help URI.
- classmethod no_display_exceptions()
Context manager to block exception display to IPython/stdout.
- with_traceback()
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception msticpy.common.exceptions.MsticpyException
Bases:
Exception
Default exception class for msticpy.
- args
- with_traceback()
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception msticpy.common.exceptions.MsticpyImportExtraError(*args, help_uri: Optional[Union[Tuple[str, str], str]] = None, **kwargs)
Bases:
msticpy.common.exceptions.MsticpyUserError
,ImportError
Exception class for Imports that need an extra.
Create import missing extra exception.
- Parameters
help_uri (Union[Tuple[str, str], str, None], optional) – Override the default help URI.
extra (str) – The name of the setup extra that needs to be installed.
- DEF_HELP_URI = ('Installing msticpy', 'https://msticpy.readthedocs.io/en/latest/getting_started/Installing.html')
- args
- property help_uri: Union[Tuple[str, str], str]
Get the default help URI.
- msg
exception message
- name
module name
- classmethod no_display_exceptions()
Context manager to block exception display to IPython/stdout.
- path
module path
- with_traceback()
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception msticpy.common.exceptions.MsticpyKeyVaultConfigError(*args, help_uri: Optional[Union[Tuple[str, str], str]] = None, **kwargs)
Bases:
msticpy.common.exceptions.MsticpyUserConfigError
Key Vault configuration exception.
Create Key Vault configuration exception.
- Parameters
help_uri (Union[Tuple[str, str], str, None], optional) – Override the default help URI.
- DEF_HELP_URI = ('Using keyvault to store msticpy secrets', 'https://msticpy.readthedocs.io/en/latest/getting_started/msticpyconfig.html#specifying-secrets-as-key-vault-secrets')
- args
- property help_uri: Union[Tuple[str, str], str]
Get the default help URI.
- classmethod no_display_exceptions()
Context manager to block exception display to IPython/stdout.
- with_traceback()
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception msticpy.common.exceptions.MsticpyKeyVaultMissingSecretError(*args, help_uri: Optional[Union[Tuple[str, str], str]] = None, **kwargs)
Bases:
msticpy.common.exceptions.MsticpyKeyVaultConfigError
Missing secret exception.
Create Key Vault missing key exception.
- Parameters
help_uri (Union[Tuple[str, str], str, None], optional) – Override the default help URI.
- DEF_HELP_URI = ('Using keyvault to store msticpy secrets', 'https://msticpy.readthedocs.io/en/latest/getting_started/msticpyconfig.html#specifying-secrets-as-key-vault-secrets')
- args
- property help_uri: Union[Tuple[str, str], str]
Get the default help URI.
- classmethod no_display_exceptions()
Context manager to block exception display to IPython/stdout.
- with_traceback()
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception msticpy.common.exceptions.MsticpyKqlConnectionError(*args, help_uri: Optional[Union[Tuple[str, str], str]] = None, **kwargs)
Bases:
msticpy.common.exceptions.MsticpyUserError
Exception class for KqlConnection errors.
Create an instance of the MsticpyUserError class.
- Parameters
args (Iterable of strings) – Args will be printed as text of the exception.
help_uri (Union[Tuple[str, str], str, None], optional) – Primary URL, by default “https://msticpy.readthedocs.org”
title (str) – If a title keyword argument is supplied it will be used to create the title line.
*_uri (str) – Additional keyword arguments who’s names end in “_uri” will be used to create a list of references in addition to the primary help_uri
Notes
The exception text is displayed when the exception is created and not when it is raised. We recommend creating the exception within the raise statement. E.g.
raise MsticpyUserException(arg1, arg2…)
Developer note: Any classes derived from MsticpyUserError should be named with an “Error” suffix to distinguish these from standard exception types.
- DEF_HELP_URI = ('Connecting to Microsoft Sentinel', 'https://msticpy.readthedocs.io/en/latest/data_acquisition/DataProviders.html#connecting-to-an-azure-sentinel-workspace')
- args
- property help_uri: Union[Tuple[str, str], str]
Get the default help URI.
- classmethod no_display_exceptions()
Context manager to block exception display to IPython/stdout.
- with_traceback()
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception msticpy.common.exceptions.MsticpyNoDataSourceError(*args, help_uri: Optional[Union[Tuple[str, str], str]] = None, **kwargs)
Bases:
msticpy.common.exceptions.MsticpyUserError
Exception class for missing data source errors.
Create an instance of the MsticpyUserError class.
- Parameters
args (Iterable of strings) – Args will be printed as text of the exception.
help_uri (Union[Tuple[str, str], str, None], optional) – Primary URL, by default “https://msticpy.readthedocs.org”
title (str) – If a title keyword argument is supplied it will be used to create the title line.
*_uri (str) – Additional keyword arguments who’s names end in “_uri” will be used to create a list of references in addition to the primary help_uri
Notes
The exception text is displayed when the exception is created and not when it is raised. We recommend creating the exception within the raise statement. E.g.
raise MsticpyUserException(arg1, arg2…)
Developer note: Any classes derived from MsticpyUserError should be named with an “Error” suffix to distinguish these from standard exception types.
- DEF_HELP_URI = ('Querying and importing data', 'https://msticpy.readthedocs.io/en/latest/DataAcquisition.html#querying-and-importing-data')
- args
- property help_uri: Union[Tuple[str, str], str]
Get the default help URI.
- classmethod no_display_exceptions()
Context manager to block exception display to IPython/stdout.
- with_traceback()
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception msticpy.common.exceptions.MsticpyNotConnectedError(*args, help_uri: Optional[Union[Tuple[str, str], str]] = None, **kwargs)
Bases:
msticpy.common.exceptions.MsticpyUserError
Exception class for NotConnected errors.
Create an instance of the MsticpyUserError class.
- Parameters
args (Iterable of strings) – Args will be printed as text of the exception.
help_uri (Union[Tuple[str, str], str, None], optional) – Primary URL, by default “https://msticpy.readthedocs.org”
title (str) – If a title keyword argument is supplied it will be used to create the title line.
*_uri (str) – Additional keyword arguments who’s names end in “_uri” will be used to create a list of references in addition to the primary help_uri
Notes
The exception text is displayed when the exception is created and not when it is raised. We recommend creating the exception within the raise statement. E.g.
raise MsticpyUserException(arg1, arg2…)
Developer note: Any classes derived from MsticpyUserError should be named with an “Error” suffix to distinguish these from standard exception types.
- DEF_HELP_URI = ('Querying and importing data', 'https://msticpy.readthedocs.io/en/latest/DataAcquisition.html#querying-and-importing-data')
- args
- property help_uri: Union[Tuple[str, str], str]
Get the default help URI.
- classmethod no_display_exceptions()
Context manager to block exception display to IPython/stdout.
- with_traceback()
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception msticpy.common.exceptions.MsticpyParameterError(*args, help_uri: Optional[Union[Tuple[str, str], str]] = None, **kwargs)
Bases:
msticpy.common.exceptions.MsticpyUserError
Exception class for missing/incorrect parameters.
Create parameter exception.
- Parameters
help_uri (Union[Tuple[str, str], str, None], optional) – Override the default help URI.
parameters (Union[str, List[str]) – The name of the bad parameter(s).
- DEF_HELP_URI = ('MSTICPy documentation', 'https://msticpy.readthedocs.io')
- args
- property help_uri: Union[Tuple[str, str], str]
Get the default help URI.
- classmethod no_display_exceptions()
Context manager to block exception display to IPython/stdout.
- with_traceback()
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception msticpy.common.exceptions.MsticpyResourceException
Bases:
msticpy.common.exceptions.MsticpyException
Exception class for resource errors.
- args
- with_traceback()
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception msticpy.common.exceptions.MsticpyUserConfigError(*args, help_uri: Optional[Union[Tuple[str, str], str]] = None, **kwargs)
Bases:
msticpy.common.exceptions.MsticpyUserError
Configuration user exception class for msticpy.
Create generic user configuration exception.
- Parameters
help_uri (Union[Tuple[str, str], str, None], optional) – Override the default help URI.
- DEF_HELP_URI = ('Configuring msticpy', 'https://msticpy.readthedocs.io/en/latest/getting_started/msticpyconfig.html')
- args
- property help_uri: Union[Tuple[str, str], str]
Get the default help URI.
- classmethod no_display_exceptions()
Context manager to block exception display to IPython/stdout.
- with_traceback()
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception msticpy.common.exceptions.MsticpyUserError(*args, help_uri: Optional[Union[Tuple[str, str], str]] = None, **kwargs)
Bases:
msticpy.common.exceptions.MsticpyException
Msticpy User exception displaying friendly message.
Create an instance of the MsticpyUserError class.
- Parameters
args (Iterable of strings) – Args will be printed as text of the exception.
help_uri (Union[Tuple[str, str], str, None], optional) – Primary URL, by default “https://msticpy.readthedocs.org”
title (str) – If a title keyword argument is supplied it will be used to create the title line.
*_uri (str) – Additional keyword arguments who’s names end in “_uri” will be used to create a list of references in addition to the primary help_uri
Notes
The exception text is displayed when the exception is created and not when it is raised. We recommend creating the exception within the raise statement. E.g.
raise MsticpyUserException(arg1, arg2…)
Developer note: Any classes derived from MsticpyUserError should be named with an “Error” suffix to distinguish these from standard exception types.
- DEF_HELP_URI = ('msticpy documentation', 'https://msticpy.readthedocs.org')
- args
- property help_uri: Union[Tuple[str, str], str]
Get the default help URI.
- classmethod no_display_exceptions()
Context manager to block exception display to IPython/stdout.
- with_traceback()
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
msticpy.common.timespan module
Timespan class.
- class msticpy.common.timespan.TimeSpan(timespan: Optional[Union[msticpy.common.timespan.TimeSpan, Tuple[Any, Any], Any]] = None, start: Optional[Union[str, datetime.datetime]] = None, end: Optional[Union[str, datetime.datetime]] = None, period: Optional[Union[datetime.timedelta, str]] = None)
Bases:
object
Timespan parameter for notebook modules.
Initialize Timespan.
- Parameters
timespan (Union(TimeSpan, Tuple(Any, Any), Any), optional) – A TimeSpan object or a tuple of datetimes or datetime strings, or an object that has either start and end or start and period date_time-like attributes. By default None
start (Optional[Union[datetime, str]], optional) – datetime of the start of the time period, by default None
end (Optional[Union[datetime, str]], optional) – datetime of the end of the time period, by default utcnow
period (Optional[Union[timedelta, str]], optional) – duration of the period, by default None
- Raises
ValueError – If neither start nor period are specified.
- property end: datetime.datetime
Return the end of the timeperiod.
- Returns
End datetime.
- Return type
datetime
- property period: datetime.timedelta
Return the period of the timeperiod.
- Returns
Period timedelta.
- Return type
timedelta
- property start: datetime.datetime
Return the start of the timeperiod.
- Returns
Start datetime.
- Return type
datetime