msticpy.context.azure.sentinel_incidents module

Mixin Classes for Sentinel Incident Features.

class msticpy.context.azure.sentinel_incidents.SentinelIncidentsMixin(*, connect: bool = False, cloud: str | None = None)

Bases: SentinelBookmarksMixin

Mixin class for Sentinel Incidents feature integrations.

Initialize connector for Azure Python SDK.

add_bookmark_to_incident(incident: str, bookmark: str) → str

Add a bookmark to an incident.

Parameters:

  • incident (str) – Either an incident name or an incident GUID

  • bookmark (str) – Either a bookmark name or bookmark GUID

Raises:

CloudError – If API returns error

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_bookmark(name: str, query: str, results: str | None = None, notes: str | None = None, labels: list[str] | None = None) → str | None

Create a bookmark in the Sentinel Workspace.

Parameters:

  • name (str) – The name of the bookmark to use

  • query (str) – The KQL query for the bookmark

  • results (str, optional) – The results of the query to include with the bookmark, by default None

  • notes (str, optional) – Any notes you want associated with the bookmark, by default None

  • labels (List[str], optional) – Any labels you want associated with the bookmark, by default None

Returns:

The name/ID of the bookmark.

Return type:

str|None

Raises:

CloudError – If API returns an error.

create_incident(title: str, severity: str, status: str = 'New', description: str | None = None, first_activity_time: datetime | None = None, last_activity_time: datetime | None = None, labels: list[dict[str, Any]] | None = None, bookmarks: list[str] | None = None) → str | None

Create a Sentinel Incident.

Parameters:

  • title (str) – The title of the incident to create

  • severity (str) –

    The severity to assign the incident, options are:

    Informational, Low, Medium, High

  • status (str, optional) – The status to assign the incident, by default “New” Options are: New, Active, Closed

  • description (str, optional) – A description of the incident, by default None

  • first_activity_time (datetime, optional) – The start time of the incident activity, by default None

  • last_activity_time (datetime, optional) – The end time of the incident activity, by default None

  • labels (List, optional) – Any labels to apply to the incident, by default None

  • bookmarks (List, optional) – A list of bookmark GUIDS you want to associate with the incident

Returns:

The name/ID of the incident.

Return type:

Optional[str]

Raises:

CloudError – If the API returns an error

delete_bookmark(bookmark: str) → None

Delete the selected bookmark.

Parameters:

bookmark (str, optional) – The name or GIUD of the bookmark to delete.

Raises:

CloudError – If the API returns an error.

get_bookmarks() → DataFrame

Return a list of Bookmarks from a Sentinel workspace.

Returns:

A set of bookmarks.

Return type:

pd.DataFrame

get_entities(incident: str) → list

Get the entities from an incident.

Parameters:

incident (str) – Incident GUID or Name .

Returns:

A list of entities.

Return type:

list

get_incident(incident: str, *, entities: bool = False, alerts: bool = False, comments: bool = False, bookmarks: bool = False) → DataFrame

Get details on a specific incident.

Parameters:

  • incident (str) – Incident ID GUID.

  • entities (bool, optional) – If True include all entities in the response. Default is False.

  • alerts (bool, optional) – If True include all alerts in the response. Default is False.

  • comments (bool, optional) – If True include all comments in the response. Default is False.

  • bookmarks (bool, optional) – If True include all bookmarks in the response. Default is False.

Returns:

Table containing incident details.

Return type:

pd.DataFrame

Raises:

CloudError – If incident could not be retrieved.

get_incident_alerts(incident: str) → list

Get the alerts from an incident.

Parameters:

incident (str) – Incident GUID or Name.

Returns:

A list of alerts.

Return type:

list

get_incident_bookmarks(incident: str) → list

Get the comments from an incident.

Parameters:

incident (str) – Incident GUID or name.

Returns:

A list of bookmarks.

Return type:

list

get_incident_comments(incident: str) → list

Get the comments from an incident.

Parameters:

incident (str) – Incident GUID or Name.

Returns:

A list of comments.

Return type:

list

get_incidents(params: dict | None = None) → pd.DataFrame

Get a list of incident for a Sentinel workspace.

Parameters:

params (Optional[dict], optional) – Additional parameters to pass to the API call, by default None

Returns:

A table of incidents.

Return type:

pd.DataFrame

Raises:

CloudError – If incidents could not be retrieved.

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_bookmarks() → DataFrame

Return a list of Bookmarks from a Sentinel workspace.

Returns:

A set of bookmarks.

Return type:

pd.DataFrame

list_incidents(params: dict | None = None) → pd.DataFrame

Get a list of incident for a Sentinel workspace.

Parameters:

params (Optional[dict], optional) – Additional parameters to pass to the API call, by default None

Returns:

A table of incidents.

Return type:

pd.DataFrame

Raises:

CloudError – If incidents could not be retrieved.

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

post_comment(incident_id: str, comment: str) → str

Write a comment for an incident.

Parameters:

  • incident_id (str) – Incident ID GUID.

  • comment (str) – Comment message to post.

Raises:

CloudError – If message could not be posted.

update_incident(incident_id: str, update_items: dict) → str

Update properties of an incident.

Parameters:
Raises:

CloudError – If incident could not be updated.