msticpy.context.azure.sentinel_ti module

Mixin Classes for Sentinel Analytics Features.

class msticpy.context.azure.sentinel_ti.SentinelTIMixin(*, connect=False, cloud=None)

Bases: SentinelUtilsMixin

Mixin class for Sentinel Hunting feature integrations.

Initialize connector for Azure Python SDK.

Parameters:

  • connect (bool)

  • cloud (str | None)

add_tag(indicator_id, tag)

Add a tag to an existing indicator.

Parameters:

  • indicator_id (str) – The GUID of the indicator to add a tag to.

  • tag (str) – The tag to add.

  • self (Self)

Return type:

None

base_url
bulk_create_indicators(data, indicator_column='Observable', indicator_type_column='IoCType', *, confidence_column=None)

Bulk create indicators from a DataFrame.

Parameters:

  • data (pd.DataFrame) – A dataframe containing indicators and indicator types

  • indicator_column (str, optional) – The column containing indicator values to create, by default “Observable”

  • indicator_type_column (str, optional) – The column containing indicator type values, by default “IoCType”

  • confidence_column (str, optional) – The column containing indicator confidence values, by default 0 value used.

  • self (Self)

Return type:

None

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_indicator(indicator, ioc_type, name='TI Indicator', confidence=0, *, silent=False, description=None, labels=None, kill_chain_phases=None, threat_types=None, external_references=None, valid_from=None, valid_to=None)

Create a new indicator within the Microsoft Sentinel workspace.

Parameters:

  • indicator (str) – The indicator to create - i.e. IP address, domain name etc.

  • ioc_type (str) – The type of indicator to create - can be: “dns”, “url”, “ipv4”, “ipv6”, “md5_hash”, “sha1_hash”, “sha256_hash”

  • name (str, optional) – A common name to give to the indicator default is ‘TI Indicator’

  • confidence (int, optional) – A score between 0-100 of the confidence in the indicator, defualt is 0

  • silent (bool, optional) – If True no output is displayed, defaults to False

  • description (str, optional) – An description of the indicator

  • labels (list, optional) – A list of string object labels to associate with the indicator

  • kill_chain_phases (list, optional) – A list of string objects relating to the kill chain phases an indicator is assocaited with

  • threat_types (list, optional) – A list of threat types associated with the indicator (list of string objects)

  • external_references (list, optional) – A list of URLs that provide an external reference for the indicator

  • valid_from (datetime, optional) – A datetime from which the indicator is valid from, defaults to now

  • valid_to (datetime, optional) – A datetime to which the indicator is valid until

  • self (Self)

Return type:

The ID of the created indicator

Raises:

  • MsticpyUserError – If invalid ioc_type or confidence value provided

  • ClientAuthenticationError –

  • ResourceNotFoundError –

  • ResourceExistsError –

  • ResourceNotModifiedError –

  • HttpResponseError – If API call fails

credentials
delete_indicator(indicator_id)

Delete a specific TI indicator.

Parameters:

  • indicator_id (str) – The GUID of the indicator to delete

  • self (Self)

Raises:

  • ClientAuthenticationError –

  • ResourceNotFoundError –

  • ResourceExistsError –

  • ResourceNotModifiedError –

  • HttpResponseError – If API call fails

Return type:

None

endpoints
get_all_indicators(limit=None, orderby=None)

Return all TI indicators in a Microsoft Sentinel workspace.

Parameters:

  • limit (int, optional) – If set returns top n results

  • orderby (Optional[str], optional) – Order results by a specific column

  • self (Self)

Returns:

A table of the custom hunting queries.

Return type:

pd.DataFrame

get_indicator(indicator_id)

Get a specific indicator by its ID.

Parameters:

  • indicator_id (str) – The GUID of the indicator to get

  • self (Self)

Returns:

Indicator details

Return type:

dict

Raises:

  • ClientAuthenticationError –

  • ResourceNotFoundError –

  • ResourceExistsError –

  • ResourceNotModifiedError –

  • HttpResponseError – If API call fails.

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)

get_ti_metrics()

Return metrics about TI indicators in a Microsoft Sentinel workspace.

Returns:

A table of the custom hunting queries.

Return type:

pd.DataFrame

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

monitoring_client
network_client
query_indicators(*, include_disabled=False, keywords=None, min_confidence=0, max_confidence=100, max_valid_until=None, min_valid_until=None, page_size=None, pattern_types=None, sort_by=None, sources=None, threat_types=None)

Query for indicators in a Sentinel workspace.

Parameters:

  • include_disabled (bool, optional) – Parameter to include/exclude disabled indicators.

  • keywords (str, optional) – Keyword for searching threat intelligence indicators Use this to search for specific indicator values.

  • max_confidence (int, optional) – Maximum confidence.

  • max_valid_until (str, optional) – End time for ValidUntil filter.

  • min_confidence (int, optional) – Minimum confidence.

  • min_valid_until (str, optional) – Start time for ValidUntil filter.

  • page_size (int, optional) – Maximum number of results to return in one page.

  • pattern_types (list, optional) – A list of IoC types to include.

  • sort_by (List, optional) – Columns to sort by and sorting order as: [{“itemKey”: COLUMN_NAME, “sortOrder”: ascending/descending}]

  • sources (list, optional) – A list of indicator sources to include

  • threat_types (list, optional) – A list of Threat types to include

  • self (Self)

Returns:

A set of matching indicators

Return type:

pd.DataFrame

Raises:

  • ClientAuthenticationError –

  • ResourceNotFoundError –

  • ResourceExistsError –

  • ResourceNotModifiedError –

  • HttpResponseError – If API call fails

resource_client
sent_urls
sub_client
update_indicator(indicator_id, *, name=None, confidence=0, description=None, labels=None, kill_chain_phases=None, threat_types=None, external_references=None, valid_from=None, valid_to=None)

Update an existing indicator within the Microsoft Sentinel workspace.

Parameters:

  • indicator_id (str) – The GUID of the indicator to update

  • name (str, optional) – A common name to give to the indicator default is ‘TI Indicator’

  • confidence (int, optional) – A score between 0-100 of the confidence in the indicator

  • description (str, optional) – An description of the indicator

  • labels (list, optional) – A list of string object labels to associate with the indicator

  • kill_chain_phases (list, optional) – A list of string objects relating to the kill chain phases an indicator is assocaited with

  • threat_types (list, optional) – A list of threat types associated with the indicator (list of string objects)

  • external_references (list, optional) – A list of URLs that provide an external reference for the indicator

  • valid_from (datetime, optional) – A datetime from which the indicator is valid from, defaults to now

  • valid_to (datetime, optional) – A datetime to which the indicator is valid until

  • self (Self)

Raises:

  • ClientAuthenticationError –

  • ResourceNotFoundError –

  • ResourceExistsError –

  • ResourceNotModifiedError –

  • HttpResponseError – If API call fails

Return type:

None

url