Customers have been asking for unified APIs that are part of the Microsoft Graph with a single endpoint, permissions, auth model, and access token.
We’re happy to share that the new Microsoft 365 Defender APIs in MS Graph: Incidents, Alerts, and Hunting, are now in public preview!
What’s new
- Alerts (alerts_v2): The Microsoft 365 Defender unified alerts API serves alerts from Microsoft 365 Defender, Microsoft Defender for Endpoint, Microsoft Defender for Office 365, Microsoft Defender for Identity, Microsoft Defender for Cloud Apps, and Microsoft Purview Data Loss Prevention (and any future new signals integrated into M365D).
Integrating with this API will support the entire scope of Microsoft 365 Defender.
As part of the alerts schema, in addition to the alert severity, we added the containing – this allows SOC team to be aware of the overall severity of the incident when triaging an alert, so they can prioritize effectively.
The new alert schema expands and enriches supported evidence entities at parity and beyond with the native service Alert APIs.
Below is an example of email (named 'analyzedMessage' in the MS Graph API) evidence metadata that includes email headers that you’ve been waiting for:
- Incidents: Contain incident metadata and a collection of the new Microsoft 365 Defender unified alerts (see above). This API is at parity with the existing Incidents API on the native Microsoft 365 Defender endpoint and combined with the new alerts API, it provides much richer and actionable information for your automation flows.
- Hunting: The Hunting API is identical to the existing Hunting API on the native Microsoft 365 Defender endpoint, but now available in MS Graph.
Getting started
The following section is a modified version of the Microsoft 365 Defender documentation of how to register an Azure AD application to use the APIs:
Hello World for Microsoft 365 Defender REST API
Register an application in Azure Active Directory
- Sign into Azure Portal as a user with the Global administrator role.
- Navigate to Azure Active Directory > App registrations > New registration.
- In the registration form, enter a name for your application, then select Register. Selecting a redirect URI is optional.
- On your application page, select API Permissions > Microsoft Graph.
- In the page displayed, select Delegated permissions, start typing “security” in the search box, select SecurityIncident.Read.All and then click on Add permission.
- Click admin consent for your tenant. You can select multiple permissions and then grant admin consent for them all.
- Add a secret to the application. Select Certificates & secrets, add a description to the secret, then select Add. Remember to save this secret.
- Record your application ID and tenant ID somewhere safe. They’re listed on your application Overview page.
Authentication and authorization with the Microsoft Graph
(or ‘Get a token using the app and use the token to access the API’)
Because the new Microsoft 365 Defender APIs are hosted in Microsoft Graph, follow the steps as outlined in Microsoft Graph online documentation:
- For Delegated Authentication & authorization (AuthNZ):
https://docs.microsoft.com/en-us/graph/auth-v2-user - For Application only AuthNZ (i.e., without a signed-in user):
https://docs.microsoft.com/en-us/graph/auth-v2-service
The new Microsoft Graph permissions
The new Microsoft 365 Defender incidents, alerts_v2, and hunting APIs require the following Microsoft Graph permissions:
- SecurityAlert.Read.All – Required to list alerts and get alert (by ID)
SecurityAlert.ReadWrite.All – Required for update alert (& list/get alert) - SecurityIncident.Read.All - Required to list incidents & get incident (by ID)
SecurityIncident.ReadWrite.All - Required to update incident (& list/get incident) - ThreatHunting.Read.All – Required for running hunting queries
API documentation and more information
Full API documentation is available in MS Graph documentation. Here are a few sample API calls to get you started:
List Incidents: GET http://graph.microsoft.com/beta/security/incidents/
Get Incident (by ID): GET http://graph.microsoft.com/beta/security/incidents/{id}
List Alerts: GET http://graph.microsoft.com/beta/security/alerts_v2/
Get Alert (by ID): GET http://graph.microsoft.com/beta/security/alerts_v2/{id}
Run Hunting Query:
POST http://graph.microsoft.com/beta/security/runHuntingQuery
Body {
"Query":"DeviceProcessEvents | where InitiatingProcessFileName =~ \"powershell.exe\" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2"
}