Blog Post

Microsoft Defender XDR Blog
3 MIN READ

The new Microsoft 365 Defender APIs in Microsoft Graph are now available in public preview!

Naama Schlesinger's avatar
Aug 18, 2022

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

  1. Sign into Azure Portal as a user with the Global administrator role.
  2. Navigate to Azure Active Directory > App registrations > New registration.

  1. In the registration form, enter a name for your application, then select Register. Selecting a redirect URI is optional.
  2. On your application page, select API Permissions > Microsoft Graph.

 

  1. In the page displayed, select Delegated permissions, start typing “security” in the search box, select SecurityIncident.Read.All and then click on Add permission.

 

  1. Click admin consent for your tenant. You can select multiple permissions and then grant admin consent for them all.

 

  1. Add a secret to the application. Select Certificates & secrets, add a description to the secret, then select Add. Remember to save this secret.

 

  1. 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:

 

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"

}

 

 

 

 

 

 

Updated Oct 29, 2024
Version 3.0
  • ebstes's avatar
    ebstes
    Copper Contributor

    Hei, I was actually wondering if one can pull incidents from splunk this way and for alarm sentralization. We have splunk es and we would like to do our triage in xdr and ingest our incidents to xdr. could this be the way?

  • ceemon's avatar
    ceemon
    Copper Contributor

    Do you happen to know if this will be able to delineate MDE alerts which have had suppression applied or if excludes them altogether? The old v1 Alerts Graph excluded them but the new Streaming API does not which forced us to stay with SIEM API because of the APIs inability to do this. Roadmap wise, this is a little confusing as I thought consuming through Graph was where MS was heading away from? Would you advise moving to the new Graph API if SOCs are using alert suppressions for whitelisting / tuning purposes?

  • David_Caddick's avatar
    David_Caddick
    Brass Contributor

    Hi Naama Schlesinger, I was initially very excited, until I realized it was more API elements focused on Operational aspects, do we have any ETA or Roadmap on when we might see some API Elements that would enable the "Deployment" and/or configuration?

     

    I realize that from a PM perspective it might appear that this is a request you might see occasionally from a number of Partners, and not Customers (who typically only configure this once), but we are seeking API Deployment access to enable this for potentially hundreds if not thousands of Customers? With other Partners wanting to do the same - so it would be great if we could at least get some idea of when this might be "a thing?"

     

    Equally, if it's not going to get any air-time at all then let's please call that out, then at least we know we'll have to resort to very crude methods like Screen Scraping of the Defender Web Console using Power Automate Desktop to pull/push the details as required...

     

    Regards,

    Dave C