msticpy.data.azure package

Submodules

msticpy.data.azure.azure_blob_storage module

Uses the Azure Python SDK to interact with Azure Blob Storage.

class msticpy.data.azure.azure_blob_storage.AzureBlobStorage(abs_name: Optional[str] = None, connect: bool = False, abs_connection_string: Optional[str] = None)

Bases: object

Class for interacting with Azure Blob Storage.

Initialize connector for Azure Python SDK.

blobs(container_name: str) → Optional[pandas.core.frame.DataFrame]

Get a list of blobs in a container.

Parameters: container_name (str) – The name of the container to get blobs from.
Returns: Details of the blobs.
Return type: pd.DataFrame

connect(auth_methods: Optional[List] = None, silent: bool = False): Authenticate with the SDK.

containers() → pandas.core.frame.DataFrame: Return containers in the Azure Blob Storage Account.

create_container(container_name: str, **kwargs) → pandas.core.frame.DataFrame

Create a new container within the Azure Blob Storage account.

Parameters

container_name (str) – The name for the new container.
kwargs (Additional container parameters can be passed as) –

Returns

Details of the created container.

Return type

pd.DataFrame

delete_blob(container_name: str, blob_name: str) → bool

Delete a blob from the Azure Blob Storage account.

Parameters

container_name (str) – The container name that has the blob.
blob_name (str) – The name of the blob to delete.
snapshots. (Note deleting a blob also deletes associated) –

Returns

True if blob successfully deleted

Return type

bool

get_blob(container_name: str, blob_name: str) → bytes

Get a blob from the Azure Blob Storage account.

Parameters

container_name (str) – The name of the container that holds the blob.
blob_name (str) – The name of the blob to download.

Returns

The content of the blob in bytes.

Return type

bytes

get_sas_token(container_name: str, blob_name: str, end: Optional[datetime.datetime] = None, permission: str = 'r') → str

Generate a shared access string (SAS) token for a blob.

Parameters

container_name (str) – The name of the Azure Blob Storage container that holds the blob.
blob_name (str) – The name of the blob to generate the SAS token for.
end (datetime.datetime, optional) – The datetime the SAS token should expire, by default this is 7 days from now.
permission (str, optional) – The permissions to give the SAS token, by default ‘r’ for read.

Returns

A URI of the blob with SAS token.

Return type

str

upload_to_blob(blob: Any, container_name: str, blob_name: str, overwrite: bool = True)

Upload a blob of data.

Parameters

blob (Any) – The data to upload.
container_name (str) – The name of the container to upload the blob to.
blob_name (str) – The name to give the blob.
overwrite (bool, optional) – Whether or not you want to overwrite the blob if it exists, by default True.

msticpy.data.azure.azure_data module

Uses the Azure Python SDK to collect and return details related to Azure.

class msticpy.data.azure.azure_data.AzureData(connect: bool = False, cloud: Optional[str] = None)

Bases: object

Class for returning data on an Azure tenant.

Initialize connector for Azure Python SDK.

connect(auth_methods: Optional[List] = None, tenant_id: Optional[str] = None, silent: bool = False)

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

Raises

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

get_metrics(metrics: str, resource_id: str, sub_id: str, sample_time: str = 'hour', start_time: int = 30) → Dict[str, pandas.core.frame.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[pandas.core.frame.DataFrame, pandas.core.frame.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: Optional[str] = None, resource_details: Optional[dict] = 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: Optional[str] = None, get_props: bool = False) → pandas.core.frame.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_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() → pandas.core.frame.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

class msticpy.data.azure.azure_data.InterfaceItems(interface_id, private_ip, private_ip_allocation, public_ip, public_ip_allocation, app_sec_group, subnet, subnet_nsg, subnet_route_table)

Bases: object

attr class to build network interface details dictionary.

Method generated by attrs for class InterfaceItems.

class msticpy.data.azure.azure_data.Items(resource_id, name, resource_type, location, tags, plan, properties, kind, managed_by, sku, identity, state)

Bases: object

attr class to build resource details dictionary.

Method generated by attrs for class Items.

class msticpy.data.azure.azure_data.NsgItems(rule_name, description, protocol, direction, src_ports, dst_ports, src_addrs, dst_addrs, action)

Bases: object

attr class to build NSG rule dictionary.

Method generated by attrs for class NsgItems.

msticpy.data.azure.azure_data.get_api_headers(token: str) → Dict

Return authorization header with current token.

Parameters: token (str) – Azure auth token.
Returns: A dictionary of headers to be used in API calls.
Return type: Dict

msticpy.data.azure.azure_data.get_token(credential: msticpy.common.azure_auth_core.AzCredentials, tenant_id: Optional[str] = None) → str

Extract token from a azure.identity object.

Parameters

credential (AzCredentials) – Azure OAuth credentials.
tenant_id (str, optional) – The tenant to connect to if not the users home tenant.

Returns

A token to be used in API calls.

Return type

str

msticpy.data.azure.sentinel_analytics module

Mixin Classes for Sentinel Analytics Features.

class msticpy.data.azure.sentinel_analytics.SentinelAnalyticsMixin

Bases: object

Mixin class for Sentinel Analytics feature integrations.

create_analytic_rule(template: Optional[str] = None, name: Optional[str] = None, enabled: bool = True, query: Optional[str] = None, query_frequency: str = 'PT5H', query_period: str = 'PT5H', severity: str = 'Medium', suppression_duration: str = 'PT1H', suppression_enabled: bool = False, trigger_operator: str = 'GreaterThan', trigger_threshold: int = 0, description: Optional[str] = None, tactics: Optional[list] = None)

Create a Sentinel Analytics Rule.

Parameters

template (str, optional) – The GUID or name of a templated to create the analytic from, by default None
name (str, optional) – The name to give the analytic, by default None
enabled (bool, optional) – Whether you want the analytic to be enabled once deployed, by default True
query (str, optional) – The KQL query string to use in the anlaytic, by default None
query_frequency (str, optional) – How often the query should run in ISO8601 format, by default “PT5H”
query_period (str, optional) – How far back the query should look in ISO8601 format, by default “PT5H”
severity (str, optional) – The severity to raise incidents as, by default “Medium” Options are; Informational, Low, Medium, or High
suppression_duration (str, optional) – How long to suppress duplicate alerts in ISO8601 format, by default “PT1H”
suppression_enabled (bool, optional) – Whether you want to suppress duplicates, by default False
trigger_operator (str, optional) – The operator for the trigger, by default “GreaterThan”
trigger_threshold (int, optional) – The threshold of events required to create the incident, by default 0
description (str, optional) – A description of the analytic, by default None
tactics (list, optional) – A list of MITRE ATT&CK tactics related to the analytic, by default None

Raises

MsticpyUserError – If template provided isn’t found.
CloudError – If the API returns an error.

delete_analytic_rule(analytic_rule: str)

Delete a deployed Analytic rule from a Sentinel workspace.

Parameters: analytic_rule (str) – The GUID or name of the analytic.
Raises: CloudError – If the API returns an error.

get_alert_rules() → pandas.core.frame.DataFrame

Return all Microsoft Sentinel alert rules for a workspace.

Returns: A table of the workspace’s alert rules.
Return type: pd.DataFrame

get_analytic_rules() → pandas.core.frame.DataFrame

Return all Microsoft Sentinel alert rules for a workspace.

Returns: A table of the workspace’s alert rules.
Return type: pd.DataFrame

list_alert_rules() → pandas.core.frame.DataFrame

Return all Microsoft Sentinel alert rules for a workspace.

Returns: A table of the workspace’s alert rules.
Return type: pd.DataFrame

list_analytic_rules() → pandas.core.frame.DataFrame

Return all Microsoft Sentinel alert rules for a workspace.

Returns: A table of the workspace’s alert rules.
Return type: pd.DataFrame

list_analytic_templates() → pandas.core.frame.DataFrame

List Analytic Templates.

Returns: A DataFrame containing the analytics templates
Return type: pd.DataFrame
Raises: CloudError – If a valid result is not returned.

class msticpy.data.azure.sentinel_analytics.SentinelHuntingMixin

Bases: object

Mixin class for Sentinel Hunting feature integrations.

get_hunting_queries() → pandas.core.frame.DataFrame

Return all hunting queries in a Microsoft Sentinel workspace.

Returns: A table of the hunting queries.
Return type: pd.DataFrame

list_hunting_queries() → pandas.core.frame.DataFrame

Return all hunting queries in a Microsoft Sentinel workspace.

Returns: A table of the hunting queries.
Return type: pd.DataFrame

msticpy.data.azure.sentinel_bookmarks module

Mixin Classes for Sentinel Bookmark Features.

class msticpy.data.azure.sentinel_bookmarks.SentinelBookmarksMixin

Bases: object

Mixin class with Sentinel Bookmark integrations.

create_bookmark(name: str, query: str, results: Optional[str] = None, notes: Optional[str] = None, labels: Optional[List[str]] = None)

Create a bookmark in the Sentinel Workpsace.

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

Raises

CloudError – If API retunrs an error.

delete_bookmark(bookmark: str)

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() → pandas.core.frame.DataFrame

Return a list of Bookmarks from a Sentinel workspace.

Returns: A set of bookmarks.
Return type: pd.DataFrame

list_bookmarks() → pandas.core.frame.DataFrame

Return a list of Bookmarks from a Sentinel workspace.

Returns: A set of bookmarks.
Return type: pd.DataFrame

msticpy.data.azure.sentinel_core module

Uses the Microsoft Sentinel APIs to interact with Microsoft Sentinel Workspaces.

msticpy.data.azure.sentinel_core.AzureSentinel: alias of msticpy.data.azure.sentinel_core.MicrosoftSentinel

class msticpy.data.azure.sentinel_core.MicrosoftSentinel(res_id: Optional[str] = None, connect: bool = False, cloud: Optional[str] = None, sub_id: Optional[str] = None, res_grp: Optional[str] = None, ws_name: Optional[str] = None, **kwargs)

Bases: msticpy.data.azure.sentinel_analytics.SentinelAnalyticsMixin, msticpy.data.azure.sentinel_analytics.SentinelHuntingMixin, msticpy.data.azure.sentinel_bookmarks.SentinelBookmarksMixin, msticpy.data.azure.sentinel_incidents.SentinelIncidentsMixin, msticpy.data.azure.sentinel_utils.SentinelUtilsMixin, msticpy.data.azure.sentinel_watchlists.SentinelWatchlistsMixin, msticpy.data.azure.sentinel_search.SentinelSearchlistsMixin, msticpy.data.azure.azure_data.AzureData

Class for returning key Microsoft Sentinel elements.

Initialize connector for Azure APIs.

Parameters

res_id (str, optional) – Set the Sentinel workspace resource ID you want to use, if not specified defaults will be looked for or details can be passed seperately with functions.
connect (bool, optional) – Set true if you want to connect to API on initialization, by default False
cloud (str, optional) – Specify cloud to use, overriding any configuration value. Default is to use configuration setting or public cloud if no configuration setting is available.
sub_id (str, optional) – If not specifying a resource ID the Subscription ID of the Sentinel Workspace by default None
res_grp (str, optional) – If not specifying a resource ID the Resource Group name of the Sentinel Workspace, by default None
ws_name (str, optional) – If not specifying a resource ID the Workspace name of the Sentinel Workspace, by default None

add_bookmark_to_incident(incident: str, bookmark: 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

add_watchlist_item(watchlist_name: str, item: Union[Dict, pandas.core.series.Series, pandas.core.frame.DataFrame], overwrite: bool = 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

Raises

MsticpyUserError – If the specified Watchlist does not exist.
MsticpyUserError – If the item already exists in the Watchlist and overwrite is set to False
CloudError – If the API returns an error.

check_search_status(search_name: str) → bool

Check the status of a search job.

Parameters: search_name (str) – The name of the search job to check.
Returns: Returns True if search is ready.
Return type: bool
Raises: CloudError – If error in checking the search job status.

connect(auth_methods: Optional[List] = None, tenant_id: Optional[str] = None, silent: bool = False, **kwargs)

Authenticate with the SDK & API.

Parameters

auth_methods (List, optional) – list of preferred authentication methods to use, by default None
tenant_id (str, optional) – Specify cloud tenant to use
silent (bool, optional) – Set true to prevent output during auth process, by default False

create_analytic_rule(template: Optional[str] = None, name: Optional[str] = None, enabled: bool = True, query: Optional[str] = None, query_frequency: str = 'PT5H', query_period: str = 'PT5H', severity: str = 'Medium', suppression_duration: str = 'PT1H', suppression_enabled: bool = False, trigger_operator: str = 'GreaterThan', trigger_threshold: int = 0, description: Optional[str] = None, tactics: Optional[list] = None)

Create a Sentinel Analytics Rule.

Parameters

template (str, optional) – The GUID or name of a templated to create the analytic from, by default None
name (str, optional) – The name to give the analytic, by default None
enabled (bool, optional) – Whether you want the analytic to be enabled once deployed, by default True
query (str, optional) – The KQL query string to use in the anlaytic, by default None
query_frequency (str, optional) – How often the query should run in ISO8601 format, by default “PT5H”
query_period (str, optional) – How far back the query should look in ISO8601 format, by default “PT5H”
severity (str, optional) – The severity to raise incidents as, by default “Medium” Options are; Informational, Low, Medium, or High
suppression_duration (str, optional) – How long to suppress duplicate alerts in ISO8601 format, by default “PT1H”
suppression_enabled (bool, optional) – Whether you want to suppress duplicates, by default False
trigger_operator (str, optional) – The operator for the trigger, by default “GreaterThan”
trigger_threshold (int, optional) – The threshold of events required to create the incident, by default 0
description (str, optional) – A description of the analytic, by default None
tactics (list, optional) – A list of MITRE ATT&CK tactics related to the analytic, by default None

Raises

MsticpyUserError – If template provided isn’t found.
CloudError – If the API returns an error.

create_bookmark(name: str, query: str, results: Optional[str] = None, notes: Optional[str] = None, labels: Optional[List[str]] = None)

Create a bookmark in the Sentinel Workpsace.

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

Raises

CloudError – If API retunrs an error.

create_incident(title: str, severity: str, status: str = 'New', description: Optional[str] = None, first_activity_time: Optional[datetime.datetime] = None, last_activity_time: Optional[datetime.datetime] = None, labels: Optional[List] = None, bookmarks: Optional[List] = 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

Raises

CloudError – If the API returns an error

create_search(query: str, start: Optional[datetime.datetime] = None, end: Optional[datetime.datetime] = None, search_name: Optional[str] = None, **kwargs)

Create a Search job.

Parameters

query (str) – The KQL query to run as a job.
start (datetime, optional) – The start time for the query, by default 90 days ago.
end (datetime, optional) – The end time for the query, by default now.
search_name (str, optional) – A name to apply to the search, by default a random GUID is generated.

Raises

CloudError – If there is an error creating the search job.

create_watchlist(watchlist_name: str, description: str, search_key: str, provider: str = 'MSTICPy', source: str = 'Notebook', data: Optional[pandas.core.frame.DataFrame] = 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

Raises

MsticpyUserError – Raised if the watchlist name already exists.
CloudError – If there is an issue creating the watchlist.

delete_analytic_rule(analytic_rule: str)

Delete a deployed Analytic rule from a Sentinel workspace.

Parameters: analytic_rule (str) – The GUID or name of the analytic.
Raises: CloudError – If the API returns an error.

delete_bookmark(bookmark: str)

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.

delete_search(search_name: str)

Delete a search result.

Parameters: search_name (str) – The name of the search to delete.
Raises: CloudError – If an error occurs when attempting to delete the search

delete_watchlist(watchlist_name: str)

Delete a selected Watchlist.

Parameters

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

Raises

MsticpyUserError – If Watchlist does not exist.
CloudError – If the API returns an error.

get_alert_rules() → pandas.core.frame.DataFrame

Return all Microsoft Sentinel alert rules for a workspace.

Returns: A table of the workspace’s alert rules.
Return type: pd.DataFrame

get_analytic_rules() → pandas.core.frame.DataFrame

Return all Microsoft Sentinel alert rules for a workspace.

Returns: A table of the workspace’s alert rules.
Return type: pd.DataFrame

get_bookmarks() → pandas.core.frame.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_hunting_queries() → pandas.core.frame.DataFrame

Return all hunting queries in a Microsoft Sentinel workspace.

Returns: A table of the hunting queries.
Return type: pd.DataFrame

get_incident(incident: str, entities: bool = False, alerts: bool = False, comments: bool = False, bookmarks: bool = False) → pandas.core.frame.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() → pandas.core.frame.DataFrame

Get a list of incident for a Sentinel workspace.

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, pandas.core.frame.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[pandas.core.frame.DataFrame, pandas.core.frame.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: Optional[str] = None, resource_details: Optional[dict] = 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: Optional[str] = None, get_props: bool = False) → pandas.core.frame.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: Optional[str] = None) → 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() → pandas.core.frame.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_alert_rules() → pandas.core.frame.DataFrame

Return all Microsoft Sentinel alert rules for a workspace.

Returns: A table of the workspace’s alert rules.
Return type: pd.DataFrame

list_analytic_rules() → pandas.core.frame.DataFrame

Return all Microsoft Sentinel alert rules for a workspace.

Returns: A table of the workspace’s alert rules.
Return type: pd.DataFrame

list_analytic_templates() → pandas.core.frame.DataFrame

List Analytic Templates.

Returns: A DataFrame containing the analytics templates
Return type: pd.DataFrame
Raises: CloudError – If a valid result is not returned.

list_bookmarks() → pandas.core.frame.DataFrame

Return a list of Bookmarks from a Sentinel workspace.

Returns: A set of bookmarks.
Return type: pd.DataFrame

list_data_connectors() → pandas.core.frame.DataFrame

List deployed data connectors.

Returns: A DataFrame containing the deployed data connectors
Return type: pd.DataFrame
Raises: CloudError – If a valid result is not returned.

list_hunting_queries() → pandas.core.frame.DataFrame

Return all hunting queries in a Microsoft Sentinel workspace.

Returns: A table of the hunting queries.
Return type: pd.DataFrame

list_incidents() → pandas.core.frame.DataFrame

Get a list of incident for a Sentinel workspace.

Returns: A table of incidents.
Return type: pd.DataFrame
Raises: CloudError – If incidents could not be retrieved.

list_sentinel_workspaces(sub_id: Optional[str] = None) → 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

list_watchlist_items(watchlist_name: str) → pandas.core.frame.DataFrame

List items in a watchlist.

Parameters: watchlist_name (str) – The name of the watchlist to get items from
Returns: A DataFrame containing the watchlists
Return type: pd.DataFrame
Raises: CloudError – If a valid result is not returned.

list_watchlists() → pandas.core.frame.DataFrame

List Deployed Watchlists.

Returns: A DataFrame containing the watchlists
Return type: pd.DataFrame
Raises: CloudError – If a valid result is not returned.

post_comment(incident_id: str, comment: 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.

set_default_subscription(subscription_id: str): Set the default subscription to use to subscription_id.

set_default_workspace(sub_id: Optional[str], workspace: Optional[str] = None)

Set the default workspace.

Parameters

sub_id (Optional[str], optional) – Subscription ID containing the workspace. If not specified, the subscription will be taken from the default_subscription or from configuration.
workspace (Optional[str], optional) – Name of the workspace, by default None. If not specified and there is only one workspace in the subscription, this will be set as the default.

update_incident(incident_id: str, update_items: dict)

Update properties of an incident.

Parameters

incident_id (str) – Incident ID GUID.
update_items (dict) – Dictionary of properties to update and their values. Ref: https://docs.microsoft.com/en-us/rest/api/securityinsights/incidents/createorupdate

Raises

CloudError – If incident could not be updated.

msticpy.data.azure.sentinel_incidents module

Mixin Classes for Sentinel Incident Features.

class msticpy.data.azure.sentinel_incidents.SentinelIncidentsMixin

Bases: object

Mixin class for Sentinel Incidents feature integrations.

add_bookmark_to_incident(incident: str, bookmark: 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

create_incident(title: str, severity: str, status: str = 'New', description: Optional[str] = None, first_activity_time: Optional[datetime.datetime] = None, last_activity_time: Optional[datetime.datetime] = None, labels: Optional[List] = None, bookmarks: Optional[List] = 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

Raises

CloudError – If the API returns an error

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) → pandas.core.frame.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() → pandas.core.frame.DataFrame

Get a list of incident for a Sentinel workspace.

Returns: A table of incidents.
Return type: pd.DataFrame
Raises: CloudError – If incidents could not be retrieved.

list_incidents() → pandas.core.frame.DataFrame

Get a list of incident for a Sentinel workspace.

Returns: A table of incidents.
Return type: pd.DataFrame
Raises: CloudError – If incidents could not be retrieved.

post_comment(incident_id: str, comment: 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)

Update properties of an incident.

Parameters

incident_id (str) – Incident ID GUID.
update_items (dict) – Dictionary of properties to update and their values. Ref: https://docs.microsoft.com/en-us/rest/api/securityinsights/incidents/createorupdate

Raises

CloudError – If incident could not be updated.

msticpy.data.azure.sentinel_utils module

Mixin Classes for Sentinel Utilties.

class msticpy.data.azure.sentinel_utils.SentinelUtilsMixin

Bases: object

Mixin class for Sentinel core feature integrations.

msticpy.data.azure.sentinel_utils.validate_res_id(res_id): Validate a Resource ID String and fix if needed.

msticpy.data.azure.sentinel_watchlists module

Mixin Classes for Sentinel Watchlist Features.

class msticpy.data.azure.sentinel_watchlists.SentinelWatchlistsMixin

Bases: object

Mixin class for Sentinel Watchlist feature integrations.

add_watchlist_item(watchlist_name: str, item: Union[Dict, pandas.core.series.Series, pandas.core.frame.DataFrame], overwrite: bool = 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

Raises

MsticpyUserError – If the specified Watchlist does not exist.
MsticpyUserError – If the item already exists in the Watchlist and overwrite is set to False
CloudError – If the API returns an error.

create_watchlist(watchlist_name: str, description: str, search_key: str, provider: str = 'MSTICPy', source: str = 'Notebook', data: Optional[pandas.core.frame.DataFrame] = 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

Raises

MsticpyUserError – Raised if the watchlist name already exists.
CloudError – If there is an issue creating the watchlist.

delete_watchlist(watchlist_name: str)

Delete a selected Watchlist.

Parameters

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

Raises

MsticpyUserError – If Watchlist does not exist.
CloudError – If the API returns an error.

list_watchlist_items(watchlist_name: str) → pandas.core.frame.DataFrame

List items in a watchlist.

Parameters: watchlist_name (str) – The name of the watchlist to get items from
Returns: A DataFrame containing the watchlists
Return type: pd.DataFrame
Raises: CloudError – If a valid result is not returned.

list_watchlists() → pandas.core.frame.DataFrame

List Deployed Watchlists.

Returns: A DataFrame containing the watchlists
Return type: pd.DataFrame
Raises: CloudError – If a valid result is not returned.

Module contents

Data provider sub-package.