AzureSentinelAPIs.ipynb

Kernel: Python 3

Table of Contents

• Microsoft Sentinel API Calls
  • • Description
    • Installation and imports
    • Authentication

Microsoft Sentinel API Calls

MSTICpy versions > 0.8.5

Description

This Notebook provides an example of using the Microsoft Sentinel API features of MSTICpy in order retrieve specific data from Microsoft Sentinel

Installation and imports

%pip install --upgrade msticpy[azsentinel]

from msticpy.data.azure_sentinel import AzureSentinel
import msticpy.nbtools.nbwidgets as widgets
from msticpy.data import data_obfus as mask

Authentication

The first step to be able to use the features is to call the AzureSentinel class and connect to it. Authentication uses the standardized Azure authentication options of using environment variables, Azure CLI credentials, Managed Identities, and interactive logons.

azs = AzureSentinel()
azs.connect()

Attempting to sign-in with environment variable credentials...

Once connected we need to select a Microsoft Sentinel workspace to get details from. The easies way to do this is with the get_subscriptions() and get_sentinel_workspaces() functions to select the subscription and workspace you with to connect to. If you already know which workspace you wish to connect to you can skip straight to the other functions and enter these details.

# Query for our subscriptions
subs = azs.get_subscriptions()
subs = subs.mp_obf.obfuscate(column_map={"Display Name": "str"})

# Display subscriptions (masked names) in a pick list
print("Select a subscription:")
sub = widgets.SelectItem(
    item_list=subs['Display Name'].to_list(),
    auto_display=True
)

Attempting to sign-in with environment variable credentials...
obfuscating columns:
Display Name, 
done
Select a subscription:

VBox(children=(Text(value='', description='Filter:', style=DescriptionStyle(description_width='initial')), Sel…

# Get the subscription ID
sub_id = subs[subs['Display Name'] == sub.value].iloc[0]['Subscription ID']
# Query for workspaces in that subscription
workspaces = azs.get_sentinel_workspaces(sub_id = sub_id)
# Display workspaces in a list
print("Select a Microsoft Sentinel Workspace:")
ws = widgets.SelectItem(
    item_dict=workspaces,
    auto_display=True
)

Finding Microsoft Sentinel Workspaces...
Attempting to sign-in with environment variable credentials...
Select a Microsoft Sentinel Workspace:

VBox(children=(Text(value='', description='Filter:', style=DescriptionStyle(description_width='initial')), Sel…

Now that we have selected our workspace we can call various functions to get details about content in the workspace. These are typically returned as DataFrames. Below we get a list of hunting queries configured in our workspace.

queries = azs.get_hunting_queries(ws.value)
queries.head().drop(columns=["id", "etag", "name"])

Hunting queries return the raw queries associated with them, this allows us to pass the query directly to a QueryProvider in order to get the results of the hunting query within the notebook.

from msticpy.data.data_providers import QueryProvider
from msticpy.common.wsconfig import WorkspaceConfig
qry_prov = QueryProvider('LogAnalytics')
wkspace = WorkspaceConfig()
qry_prov.connect(wkspace.code_connect_str)
qry_prov.exec_query(queries['properties.Query'].iloc[2])

<IPython.core.display.Javascript object>

<IPython.core.display.Javascript object>

<IPython.core.display.Javascript object>

We can also get a list of configured alert rules:

alert_rules = azs.get_alert_rules(ws.value)
alert_rules.head().drop(columns=["id", "etag", "name"])

We can also get a list of saved bookmarks. To see the events these bookmarks relate to you can pass the query value to a QueryProvider.

bkmarks = azs.get_bookmarks(ws.value)
bkmarks.head().drop(columns=["id", "etag", "name"])

We can also interact with Incidents via the API to get a set of all incidents, or a single incident:

incidents = azs.get_incidents(res_id=ws.value)
display(incidents.head())

incident = azs.get_incident(incident_id = incidents.iloc[0]['name'] , res_id=ws.value)
display(incident)

You can also interact with an incident - adding comments or changing properties such as severity or status:

azs.post_comment(incident_id = incident.iloc[0]['name'], comment="This is a test comment", res_id=ws.value)

Comment posted.

azs.update_incident(incident_id = incident.iloc[0]['name'], update_items={"severity":"High"}, res_id=ws.value)

Incident updated.