Microsoft Sentinel has several different APIs that you can interact with, and we've recently released the Sentinel Management API to add another API into the mix. This topic can – initially – be slightly confusing as we have APIs at both the Sentinel and Log Analytics level that can both be used in conjunction with Azure Sentinel. In this article we are going to explore the following:
We also have an accompanying bitesize video on the Microsoft Security Channel for this topic here.
We can categorize Microsoft Sentinel APIs as follows:
The below diagram summarizes where the different APIs within Sentinel sit architecturally and what calls can be made to them:
The Sentinel Management API allows you to manage aspects of Microsoft Sentinel specifically outside of Log Analytics e.g. incidents and analytic rules. The GitHub repo link to our API branches can be found here, and the MS Docs article about the Sentinel Management API can be found here.
Sentinel Management API uses*
*Please refer to the GitHub repo for a comprehensive list of API uses.
Example API call
GET https://management.azure.com/subscriptions/{SubscriptionID}/resourceGroups/{ResourceGroup}/providers/Microsoft.OperationalInsights/workspaces/{WorkspaceName}/providers/Microsoft.SecurityInsights/incidents/{IncidentID}?api-version=2020-01-01
Sentinel Management API authentication
Register an application in Azure AD. To authenticate to the Sentinel Management API, grant Sentinel Contributor / Microsoft Sentinel Responder / MicrosoftSentinel Reader” permissions* to the application created in the IAM setting of the Resource Group where Microsoft Sentinel has been built:
*Adhering to the principle of least privilege, always grant the lowest possible permissions required to your API.
Tools to use with this API
The most common use for the API is to automate the deployment and update of Analytics alert rules and hunting queries. Wortell has created a PowerShell tool called AzSentinel and this can be used to export and import all rules from a workspace. @Javier Soriano and @Philippe Zenhaeusern have implemented a CI/CD flow using GitHub, Azure DevOps, and the Sentinel automation capabilities. It enables you to manage rules, queries, playbooks, workbooks, and more on GitHub and have them continuously deployed to your Sentinel workspace which you can read about here.
You may be familiar with the Graph Security API from using other Microsoft security products. The Microsoft Graph Security API provides a unified interface and schema to integrate with security solutions from Microsoft and ecosystem partners. The Microsoft Graph Security API federates queries to all onboarded security providers and aggregates responses. @Stefan Simon blogged about ingesting M365 alerts into Sentinel on MS Tech Community, the link to this article is here.
Microsoft Graph Security API uses
More details on calling the Graph Security API can be found here.
Example API call
GET https://graph.microsoft.com/v1.0/security/alerts?$filter=vendorInformation/provider eq
‘Azure Sentinel’
Microsoft Graph Security authentication
To authenticate to the Graph Security API, you need to register an app in Azure AD and grant the app permissions to Microsoft Graph:
*Adhering to the principle of least privilege, always grant the lowest possible permissions required to your API.
More details on authenticating to the Graph Security API can be found here.
Tools to use with this API
The Log Analytics API allows you to query a Log Analytics workspace, including workspaces that have Sentinel set up on them. @RinUre blogged on this topic previously in on MS Tech Community and went into great detail, you can read his blog here.
Log Analytics API uses
*sometimes POST requests will need to be used to read data (not to send data to the LA workspace). More details on the API request format can be found here.
Example API call
GET https://api.loganalytics.io/v1/workspaces/{workspace-id}/query?query=AzureActivity%20|%20summarize%20count()%20by%20Category
Authorization: Bearer <access token>
Log Analytics API authentication
To authenticate to the Log Analytics API, you need to register an app in Azure AD and grant the app Data.Read permissions to the Log Analytics API:
Next, go to the IAM section of your Sentinel Log Analytics workspace and grant "Log Analytics Reader" or “Log Analytics Contributor” permission to the application*:
*Adhering to the principle of least privilege, always grant the lowest possible permissions required to your API.
Limitations of the Log Analytics API
As well as call rate limits and daily quota caps, there are also limits on queries themselves:
For up to date limitations of the Log Analytics API, please see here.
Tools to use with this API
There are some tools that already use the API and can make life simpler:
You can use the HTTP Data Collector API to send log data to a Log Analytics from any client that can call a REST API. This might be a runbook in Azure Automation that collects management data from Azure or another cloud, or it might be an alternate management system that uses Azure Monitor to consolidate and analyze log data. More details about this connector can be found here.
HTTP Data Collector API uses
Example API call
We've put together a simple C# console application to demonstrate how you can leverage the HTTP Data Collector API to post data to Log Analytics custom logs, click here for details.
HTTP Data Collector API authentication
Any request to the Azure Monitor HTTP Data Collector API must include an authorization header. To authenticate a request, you must sign the request with either the primary or the secondary key for the workspace that is making the request. Then, pass that signature as part of the request.
Authorization: SharedKey <WorkspaceID>:<Signature>
HTTP Data Collector API limitations
There are some constraints around the data posted to the HTTP Data Collector API.
For up to date limitations of the HTTP Data Collector API, please see here.
Tools to use with this API
The API and the different ways to use it are discussed in the custom connectors blog post.
You have many options to interface with Microsoft Sentinel using APIs, and what method you choose will depend on what you're ultimately trying to achieve and your organization's use cases. This blog post was intended to serve as a brief introduction to APIs in Sentinel. If you'd like to dive deeper into this topic, we'd encourage you to watch our presentation on Extending and Integrating Sentinel (APIs) from our Security Community webinar series and to check out @Ofer_Shezaf's accompanying tech community post here.
The diagrams in this article were drawn by @Takeshi Muto. Credit to @Chi Nguyen for the sample HTTP Data Collector API in our GitHub repo. Final thanks to @Ofer_Shezaf for reviewing the content
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.