Azure Sentinel APIs¶
Description¶
This package contains functionality making calls to Azure Sentinel directly. These can be used to get data from Azure Sentinel, as well as perform configuration and other actions on the Azure Sentinel Workspace
Azure Sentinel API documentation
The first step in using this package is to install the msticpy package.
!pip install msticpy --upgrade --user
Collecting msticpy
Building wheels for collected packages: msticpy
Building wheel for msticpy (setup.py): started
Building wheel for msticpy (setup.py): finished with status 'done'
Successfully built msticpy
Installing collected packages: msticpy
Successfully installed msticpy-0.3.0
#Check we are running Python 3.6
import sys
MIN_REQ_PYTHON = (3,6)
if sys.version_info < MIN_REQ_PYTHON:
print('Check the Kernel->Change Kernel menu and ensure that Python 3.6')
print('or later is selected as the active kernel.')
sys.exit("Python %s.%s or later is required.\n" % MIN_REQ_PYTHON)
#imports
from msticpy.data.azure_data import AzureData
from msticpy.data.azure_sentinel import AzureSentinel
print('Imports Complete')
Imports Complete
Instantiating and Connecting the Azure Sentinel API Connector¶
See Azure Sentinel
In order to connect to the Azure Sentinel API and retrieve the required data we need to instantiate the AzureSentinel class and authenticate to Azure. Authentication to the Azure Sentinel API is handled via an the azure_auth package. By default this function will attempt to use a prioritized list of authentication options. Available options are:
- ‘env’ - This checks for credentials stored as environment variables. If this option is selected valid credentials in msticpyconfig.yaml will be written as environment variable values and used.
- ‘cli’ - This attempts to use credentials generated by logging in via the Azure CLI on the host running the notebook kernel.
- ‘msi’ - This attempts to use an Azure Managed Identity.
- ‘interactive’ - This prompts the browser to interactively login using the device’s browser.
By default [‘env’, ‘cli’, ‘msi’, ‘interactive’] is used but you can provide an alternative list to .connect via the auth_methods parameter.
azs = AzureSentinel()
azs.connect(auth_methods=['cli','interactive'])
Get the workspace Azure Subscription ID¶
You need the ID of the Azure subscription in which the Azure Sentinel workspace resides.
AzureData.get_subscriptions() returns a pandas DataFrame with details of all the subscriptions within your tenant.
az_data = AzureData()
az_data.connect()
az_data.get_subscriptions()
| Subscription ID | Display Name | State | |
|---|---|---|---|
| 0 | 3b701f84-d04b-4479-89b1-fa8827eb537e | Visual Studio Enterprise | SubscriptionState.enabled |
Get Azure Sentinel Workspaces¶
Pick the subscription ID that contains the Azure Sentinel workspace that you want to connect to.
get_sentinel_workspaces returns a list of Azure Sentinel workspaces within
a specified subscription.
Note
this will only return workspaces that the authenticated account is permitted to view.
azs.get_sentinel_workspaces(sub_id="3b701f84-d04b-4479-89b1-fa8827eb537e")
List Hunting Queries¶
Return a dataframe detailing all hunting queries configured in the workspace. This allows for analysis and configuration of hunting queries, as well as the ability to take a hunting query and run it with a QueryProvider. This function requires that you pass it the resource ID string of the Azure Sentinel workspace to get the queries from. This ID can be obtained with get_sentinel_workspaces
azs.get_hunting_queries(res_id = "subscriptionId/3b701f84-d04b-4479-89b1-fa8827eb537e/resourceGroup/SentinelRG/workspaceName/SentinelWorkspace")
List Configured Alert Rules¶
Return a dataframe detailing all configured alert/analytics rules configured with Azure Sentinel. This includes scheduled queries, as well as Fusion based detections. The returned dataframe include details of the rule configuration as well as the query run (where applicable). As with other functions the resource ID of the workspace to get alerts from is required.
See get_alert_rules
azs.get_alert_rules(res_id = "subscriptionId/3b701f84-d04b-4479-89b1-fa8827eb537e/resourceGroup/SentinelRG/workspaceName/SentinelWorkspace")
List Bookmarks¶
Return a list of all the bookmarks saved in the workspace. This includes details of the bookmark, who created it, when and with what details. It also includes query text that can be executed with a QueryProvider in order to get the details of the bookmark’s logs. As with other functions the resource ID of the workspace to get alerts from is required.
See get_bookmarks
azs.get_bookmarks(res_id = "subscriptionId/3b701f84-d04b-4479-89b1-fa8827eb537e/resourceGroup/SentinelRG/workspaceName/SentinelWorspace")
Get Incidents¶
It is possible to return a list of all incidents within a workspace, as well as get the details of a specific incident. Whilst it is possible to access these incident details via the Incident table in the Workspace, you can also interact with them via the Azure Sentinel APIs which are utilized in these functions. As with other functions the resource ID of the workspace to get incidents from is required.
See get_incidents
azs.get_incidents(res_id = "subscriptionId/3b701f84-d04b-4479-89b1-fa8827eb537e/resourceGroup/SentinelRG/workspaceName/SentinelWorspace")
This returns a DataFrame with details of all incidents.
To get details of a single incident you can call .get_incident and pass the ID of an incident. This ID can be found in the name column of the DataFrame returned by .get_incidents and appears in the form of a GUID.
See get_incident
azs.get_incidents(incident_id = "875409ee-9e1e-40f6-b0b8-a38aa64a1d1c",
res_id = "subscriptionId/3b701f84-d04b-4479-89b1-fa8827eb537e/resourceGroup/SentinelRG/workspaceName/SentinelWorspace")
Update Incidents¶
Via the Azure Sentinel API it is possible to update incidents, this includes updating details such as Severity and Status, as well as adding comments to an incident.
To interact with an incident use .post_comment or .update_incident.
To update the incident’s features you need to pass .update_incident a dictionary of parameters and values to update. Details of what parameters can be updated can be found in the Azure Sentinel documentation.
Note
When modifying severity, status, or title there is no need to include the ‘properties.’ in the key name within the update_items dictionary
See update_incident
azs.update_incident(incident_id = "875409ee-9e1e-40f6-b0b8-a38aa64a1d1c",
update_items = {"severity":"High"},
res_id = "subscriptionId/3b701f84-d04b-4479-89b1-fa8827eb537e/resourceGroup/SentinelRG/workspaceName/SentinelWorspace")
Posting comments to an incident uses the .post_comment function. Simply pass this function a comment as a string, along with an incident and workspace ID. If successful a “Comment posted.” message will be displayed.
See post_comment
azs.post_comment(incident_id = "875409ee-9e1e-40f6-b0b8-a38aa64a1d1c",
comment = "This is my comment",
res_id = "subscriptionId/3b701f84-d04b-4479-89b1-fa8827eb537e/resourceGroup/SentinelRG/workspaceName/SentinelWorspace")