msticpy.context.azure.sentinel_watchlists module

Mixin Classes for Sentinel Watchlist Features.

class msticpy.context.azure.sentinel_watchlists.SentinelWatchlistsMixin(*, connect=False, cloud=None)

Bases: SentinelUtilsMixin

Mixin class for Sentinel Watchlist feature integrations.

Initialize connector for Azure Python SDK.

Parameters:

  • connect (bool)

  • cloud (str | None)

add_watchlist_item(watchlist_name, item, *, overwrite=False)

Add or update an item in a Watchlist.

Parameters:

  • watchlist_name (str) – The name of the watchlist to add items to

  • item (Union[Dict, pd.Series, pd.DataFrame]) – The item to add, this can be a dictionary of valies, a Pandas Series, or DataFrame

  • overwrite (bool, optional) – Wether you want to overwrite an item if it already exists in the watchlist, by default False

  • self (Self)

Raises:

  • MsticpyUserError – If the specified Watchlist does not exist.

  • MsticpyUserError – If the item already exists in the Watchlist and overwrite is set to False

  • ClientAuthenticationError –

  • ResourceNotFoundError –

  • ResourceExistsError –

  • ResourceNotModifiedError –

  • HttpResponseError – If the API returns an error.

Return type:

None

base_url
check_connected()

Check that Sentinel workspace is connected.

Parameters:

self (Self)

Return type:

None

cloud
compute_client
connect(auth_methods=None, tenant_id=None, *, silent=False, cloud=None, **kwargs)

Authenticate to the Azure SDK.

Parameters:

  • auth_methods (List, optional) – list of preferred authentication methods to use, by default None

  • tenant_id (str, optional) – The tenant to authenticate against. If not supplied, the default tenant for the identity will be used.

  • silent (bool, optional) – Set true to prevent output during auth process, by default False

  • 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

  • **kwargs – Additional keyword arguments to pass to the az_connect function.

  • self (Self)

Raises:

ClientAuthenticationError – If no valid credentials are found or if subscription client can’t be created

Return type:

None

See also

msticpy.auth.azure_auth.az_connect

function to authenticate to Azure SDK

create_watchlist(watchlist_name, description, search_key, provider='MSTICPy', source='Notebook', data=None)

Create a new watchlist.

Parameters:

  • watchlist_name (str) – The name of the watchlist you want to create, this can’t be the name of an existing watchlist.

  • description (str) – A description of the watchlist to be created.

  • search_key (str) – The search key is used to optimize query performance when using watchlists for joins with other data. This should be the key column that will be used in the watchlist when joining to other data tables.

  • provider (str, optional) – This is the label attached to the watchlist showing who created it, by default “MSTICPy”

  • source (str, optional) – The source of the data to be put in the watchlist, by default “Notebook”

  • data (pd.DataFrame, optional) – The data you want to upload to the watchlist

  • self (Self)

Returns:

The name/ID of the watchlist.

Return type:

Optional[str]

Raises:

  • MsticpyUserError – Raised if the watchlist name already exists.

  • ClientAuthenticationError –

  • ResourceNotFoundError –

  • ResourceExistsError –

  • ResourceNotModifiedError –

  • HttpResponseError – If there is an issue creating the watchlist.

credentials
delete_watchlist(watchlist_name)

Delete a selected Watchlist.

Parameters:

  • watchlist_name (str) – The name of the Watchlist to deleted

  • self (Self)

Raises:

  • MsticpyUserError – If Watchlist does not exist.

  • ClientAuthenticationError –

  • ResourceNotFoundError –

  • ResourceExistsError –

  • ResourceNotModifiedError –

  • HttpResponseError – If the API returns an error.

Return type:

None

delete_watchlist_item(watchlist_name, watchlist_item_id)

Delete a Watchlist item.

Parameters:

  • watchlist_name (str) – The name of the watchlist with the item to be deleted

  • watchlist_item_id (str) – The watchlist item ID to delete

  • self (Self)

Raises:

  • MsticpyUserError – If the specified Watchlist does not exist.

  • ClientAuthenticationError –

  • ResourceNotFoundError –

  • ResourceExistsError –

  • ResourceNotModifiedError –

  • HttpResponseError – If the API returns an error.

Return type:

None

endpoints
get_metrics(metrics, resource_id, sub_id, sample_time='hour', start_time=30)

Return specified metrics on Azure Resource.

Parameters:

  • metrics (str) – A string list of metrics you wish to collect (https://docs.microsoft.com/en-us/azure/azure-monitor/platform/metrics-supported)

  • resource_id (str) – The resource ID of the resource to collet the metrics from

  • sub_id (str) – The subscription ID that the resource is part of

  • sample_time (str (Optional)) – You can select to collect the metrics every hour of minute - default is hour Accepted inputs = ‘hour’ or ‘minute’

  • start_time (int (Optional)) – The number of days prior to today to collect metrics for, default is 30

  • self (Self)

Returns:

results – A Dictionary of DataFrames containing the metrics details

Return type:

dict

get_network_details(network_id, sub_id)

Return details related to an Azure network interface and associated NSG.

Parameters:

  • network_id (str) – The ID of the network interface to return details on

  • sub_id (str) – The subscription ID that the network interface is part of

  • self (Self)

Returns:

details – A dictionary of items related to the network interface

Return type:

dict

get_resource_details(sub_id, resource_id=None, resource_details=None)

Return the details of a specific Azure resource.

Parameters:

  • resource_id (str, optional) – The ID of the resource to get details on

  • resource_details (dict, optional) –

    If ID is unknown provide the following details:

    -resource_group_name -resource_provider_namespace -resource_type -resource_name -parent_resource_path

  • sub_id (str) – The ID of the subscription to get resources from

  • self (Self)

Returns:

resource_details – The details of the requested resource

Return type:

dict

get_resources(sub_id, rgroup=None, *, get_props=False)

Return details on all resources in a subscription or Resource Group.

Parameters:

  • sub_id (str) – The subscription ID to get resources for

  • rgroup (str (Optional)) – The name of a Resource Group to get resources for

  • get_props (bool (Optional)) – Set to True if you want to get the full properties of every resource Warning this may be a slow process depending on the number of resources

  • self (Self)

Returns:

A dataframe of resource details

Return type:

pd.DataFrame

get_sentinel_workspaces(sub_id)

Return a list of Microsoft Sentinel workspaces in a Subscription.

Parameters:

  • sub_id (str) – The subscription ID to get a list of workspaces from. If not provided it will attempt to get sub_id from config files.

  • self (Self)

Returns:

A dictionary of workspace names and ids

Return type:

Dict

get_subscription_info(sub_id)

Get information on a specific subscription.

Parameters:

  • sub_id (str) – The ID of the subscription to return details on.

  • self (Self)

Returns:

Details on the selected subscription.

Return type:

dict

Raises:

MsticpyNotConnectedError – If .connect() has not been called.

get_subscriptions()

Get details of all subscriptions within the tenant.

Returns:

Details of the subscriptions present in the users tenant.

Return type:

pd.DataFrame

Raises:

MsticpyNotConnectedError – If .connect() has not been called

Parameters:

self (Self)

list_sentinel_workspaces(sub_id)

Return a list of Microsoft Sentinel workspaces in a Subscription.

Parameters:

  • sub_id (str) – The subscription ID to get a list of workspaces from. If not provided it will attempt to get sub_id from config files.

  • self (Self)

Returns:

A dictionary of workspace names and ids

Return type:

Dict

list_watchlist_items(watchlist_name)

List items in a watchlist.

Parameters:

  • watchlist_name (str) – The name of the watchlist to get items from

  • self (Self)

Returns:

A DataFrame containing the watchlists

Return type:

pd.DataFrame

Raises:

  • ClientAuthenticationError –

  • ResourceNotFoundError –

  • ResourceExistsError –

  • ResourceNotModifiedError –

  • HttpResponseError – If a valid result is not returned.

list_watchlists()

List Deployed Watchlists.

Returns:

A DataFrame containing the watchlists

Return type:

pd.DataFrame

Raises:

  • ClientAuthenticationError –

  • ResourceNotFoundError –

  • ResourceExistsError –

  • ResourceNotModifiedError –

  • HttpResponseError – If a valid result is not returned.

Parameters:

self (Self)

monitoring_client
network_client
resource_client
sent_urls
sub_client
url