msticpy.context.azure.sentinel_dynamic_summary module

Sentinel Dynamic Summary Mixin class.

class msticpy.context.azure.sentinel_dynamic_summary.SentinelDynamicSummaryMixin(*, connect: bool = False, cloud: str | None = None)

Bases: SentinelUtilsMixin

Mixin class with Sentinel Dynamic Summary integrations.

Initialize connector for Azure Python SDK.

check_connected() → None: Check that Sentinel workspace is connected.

connect(auth_methods: list[str] | None = None, tenant_id: str | None = None, *, silent: bool = False, cloud: str | None = None, **kwargs) → None

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.

Raises:

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

See also

msticpy.auth.azure_auth.az_connect: function to authenticate to Azure SDK

Create a Dynamic Summary in the Sentinel Workspace.

Parameters:

summary (DynamicSummary) – DynamicSummary instance.
name (str) – The name of the dynamic summary to create
description (str) – Dynamic Summary description
data (pd.DataFrame) – The summary data
summary_id (str | None) – Id of the summary object
tenant_id (str | None) – Tenant Id of the Sentinel workspace
azure_tenant_id (str | None) – Tenant Id of the Sentinel workspace
search_key (str, optional) – Search key for the entire summary, by default None
tactics (Union[str, List[str], None], optional) – Relevant MITRE tactics, by default None
techniques (Union[str, List[str], None], optional) – Relevant MITRE techniques, by default None
source_info (str, optional) – Summary source info, by default None

Returns:

The name/ID of the dynamic summary.

Return type:

Optional[str]

Raises:

MsticpyAzureConnectionError – If API returns an error.

delete_dynamic_summary(summary_id: str) → None

Delete the Dynamic Summary for summary_id.

Parameters:: summary_id (str, optional) – The UUID of the summary to delete.
Raises:: MsticpyAzureConnectionError – If the API returns an error.

df_to_dynamic_summaries() → list[DynamicSummary]

Return a list of DynamicSummary objects from a DataFrame of summaries.

Parameters:: data (pd.DataFrame) – DataFrame containing dynamic summaries
Returns:: List of Dynamic Summary objects.
Return type:: list[DynamicSummary]

Examples

Use the following steps to obtain a list of dynamic summaries from MS Sentinel and convert to DynamicSummary objects.

query = \"\"\"
    DynamicSummary
    | where <some filter criteria>
    | where SummaryStatus == "Active" or SummaryDataType == "SummaryItem"
\"\"\"
data = qry_prov.exec_query(query)
dyn_summaries = df_to_dynamic_summaries(data)

df_to_dynamic_summary() → DynamicSummary

Return a single DynamicSummary object from a DataFrame.

Parameters:: data (pd.DataFrame) – DataFrame containing a single dynamic summary plus summary items.
Returns:: The DynamicSummary object.
Return type:: DynamicSummary

Examples

Use the following steps to query a single dynamic summary from MS Sentinel and convert to a DynamicSummary object.

query = \"\"\"
    DynamicSummary
    | where SummaryId == "26b95b5e-2645-4d33-91a7-ea3c1b8b4b8b"
    | where SummaryStatus == "Active" or SummaryDataType == "SummaryItem"
\"\"\"
data = qry_prov.exec_query(query)
dyn_summaries = df_to_dynamic_summary(data)

get_dynamic_summary(summary_id: str, *, summary_items: bool = False) → DynamicSummary

Return DynamicSummary for ID.

Parameters:

summary_id (str) – The ID of the Dynamic summary object.
summary_items (bool, optional) – Use a data query to retrieve the dynamic summary along with summary items (data records), by default, false.

Returns:

DynamicSummary object.

Return type:

DynamicSummary

Raises:

MsticpyAzureConnectionError – If API returns an error.

get_metrics(metrics: str, resource_id: str, sub_id: str, sample_time: str = 'hour', start_time: int = 30) → dict[str, DataFrame]

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

Returns:

results – A Dictionary of DataFrames containing the metrics details

Return type:

dict

get_network_details(network_id: str, sub_id: str) → tuple[DataFrame, DataFrame]

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

Returns:

details – A dictionary of items related to the network interface

Return type:

dict

get_resource_details(sub_id: str, resource_id: str | None = None, resource_details: dict[str, Any] | None = None) → dict

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

Returns:

resource_details – The details of the requested resource

Return type:

dict

get_resources(sub_id: str, rgroup: str | None = None, *, get_props: bool = False) → pd.DataFrame

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

Returns:

A dataframe of resource details

Return type:

pd.DataFrame

get_sentinel_workspaces(sub_id: str) → dict[str, str]

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.
Returns:: A dictionary of workspace names and ids
Return type:: Dict

get_subscription_info(sub_id: str) → dict

Get information on a specific subscription.

Parameters:: sub_id (str) – The ID of the subscription to return details on.
Returns:: Details on the selected subscription.
Return type:: dict
Raises:: MsticpyNotConnectedError – If .connect() has not been called.

get_subscriptions() → DataFrame

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

list_dynamic_summaries() → pd.DataFrame

Return current list of Dynamic Summaries from a Sentinel workspace.

Returns:: The current Dynamic Summary objects.
Return type:: pd.DataFrame

list_sentinel_workspaces(sub_id: str) → dict[str, str]

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.
Returns:: A dictionary of workspace names and ids
Return type:: Dict

Return a new DynamicSummary object.

Notes

See the DynamicSummary class documentation for details of expected parameters.