Azure Sentinel API 101

 

• What APIs Sentinel has available
• How to authenticate to each API
• What you can use each API for
• Tools that you can use with the APIs

 

Overview of Sentinel APIs

 

We can categorize Azure Sentinel APIs as follows:

 

• Azure Sentinel Management API
• Microsoft Graph Security API
• Log Analytics API
• HTTP Data Collector API

The below diagram summarizes where the different APIs within Sentinel sit architecturally and what calls can be made to them:

 

 

Azure Sentinel Management API

 

The Sentinel Management API allows you to manage aspects of Azure Sentinel specifically outside of Log Analytics e.g. incidents and analytic rules. The GitHub repo link to our API branches can be found here.

 

Sentinel Management API uses*

• GET / CREATE / DELETE incidents
• GET / CREATE / DELETE analytic rules
• GET / DELETE data connectors
• POST / UPDATE bookmarks
• GET entity info

*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/{workspaceID}/providers/Microsoft.SecurityInsights/incidents/?api-version=2019-01-01-preview

 

Sentinel Management API authentication

Register an application in Azure AD. To authenticate to the Sentinel Management API, grant Sentinel Contributor / Azure Sentinel Responder / Azure Sentinel Reader” permissions* to the application created in the IAM setting of the Resource Group where Azure 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.

 

 

Microsoft Graph Security API

 

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

• GET security alerts.
• POST security alerts.
• Ingest TI into Sentinel.

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:

• SecurityEvents.Read.All or;
• SecurityEvents.ReadWrite.All*

*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

https://docs.microsoft.com/en-us/graph/api/resources/security-api-overview?view=graph-rest-1.0#alerts

https://docs.microsoft.com/en-us/azure/sentinel/connect-threat-intelligence#connect-azure-sentinel-to-your-threat-intelligence-platform

 

 

Log Analytics 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

• GET / POST data stored in a Log Analytics workspace*

*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:

• Queries cannot return more than 500,000 rows
• Queries cannot return more than 64,000,000 bytes (~61 MiB total data)
• Queries cannot run longer than 10 minutes by default. See this for details.

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:

• PowerShell script – now includes CSV export
• PowerShell cmdlet
• Azure CLI
• Logic Apps Azure Monitor logs connector

 

 

HTTP Data Collector API (Public Preview)

 

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

• POST data to a Log Analytics workspace

 

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.

• Maximum of 30 MB per post to Azure Monitor Data Collector API. This is a size limit for a single post. If the data from a single post that exceeds 30 MB, you should split the data up to smaller sized chunks and send them concurrently.
• Maximum of 32 KB limit for field values. If the field value is greater than 32 KB, the data will be truncated.
• Recommended maximum number of fields for a given type is 50. This is a practical limit from a usability and search experience perspective.
• A table in a Log Analytics workspace only supports up to 500 columns (referred to as a field in this article).
• The maximum number of characters for the column name is 500.

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.

 

 

Summary

 

You have many options to interface with Azure 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.