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

AzCredentials

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

AzCredentials

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

AzCredentials

Raises

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.

args: msticpy.common.provider_settings.ProviderArgs
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