Blog Post

Microsoft Defender XDR Blog
3 MIN READ

Introducing the new Defender for Identity Health Alert API

Gerson Levitz's avatar
Gerson Levitz
Iron Contributor
May 02, 2024

Microsoft Defender for Identity (MDI) is a cloud-based security solution that helps monitor and protect identities and infrastructure across your organization. MDI is a core component of Microsoft Defender XDR, leveraging signals from both on-premises Active Directory and cloud identities to help you better identify, detect, and investigate advanced cyberthreats directed at your organization. 

Recently, Defender for Identity (MDI) introduced Graph based API to view Defender for Identity Health issues.  

 

Understanding Health Alerts

MDI Health alerts notify you of any problems or issues within your Defender for Identity workspace and are essential for maintaining a secure environment.   

MDI health alerts fall into two areas:  

  • Domain-related or aggregated health issues, listed on the Global health issues tab in the Microsoft 365 portal. 
  • Sensor-specific health issues, listed on the Sensor health issues tab in the Microsoft 365 portal.  

 
For more information on MDI Health alerts see, https://learn.microsoft.com/en-us/defender-for-identity/health-alerts.  

 

Benefits of the Health API 

 

  • Dashboarding –Using this new API, customers can now pull/surface the MDI health alerts information to their dashboarding tool of choice.
  • Automation – For customers who use ticketing systems for IT support, this new API will allow for the automatic creation of tickets when a new health alert is opened.  For example, a new IT help ticket would automatically be opened when an outdated sensor is detected.  
  • Update the status of a health alert. MDI will automatically close a health alert when it detects that the issue has been resolved. You can also suppress the health alert for 7 days if you are aware of the issue that might last for a few days.  For example, if a domain controller has been taken offline for maintenance, you will receive a Sensor stopped communicating health alert. As you have taken this domain controller offline this is expected, so you can use the API to change the status from open to suppress. After the sensor is brought back online you can change the status back to open and let MDI automatically close the health alert.

Getting Started with MDI Health Alerts APIs 

Requirements: 

  • Permissions: user requires at a minimum M365 role permission:  Authorization and settings --> System Setting --> Read only (Defender for Office, Defender for Identity). 
  • Entra ID Enterprise Application consent permissions for Graph Explorer. 
    • SecurityIdenitiesHeath 
      • SecurityIdentitiesHealth.Read.All
      • SecurityIdentitiesHealthRead Write.All (only required to update the status of a health alert.) 

 

Sample API Queries: 

The easiest way to start to use the MDI Health Alert API is using the Graph Explorer,  Graph Explorer | Try Microsoft Graph APIs - Microsoft Graph.  

Login in with a user who has the minimum permissions, copy a query from below and paste it in the query bar in Graph Explorer. 

Note: If you are using a query that is based on DNSName or SensorDNSName make sure to change the text with the name of your domain DNS name. 

 

See all open health alerts - https://graph.microsoft.com/beta/security/identities/healthIssues?$filter=Status eq 'open' 

See open Global health alerts - https://graph.microsoft.com/beta/security/identities/healthIssues?$filter=Status eq 'open' and healthIssueType eq 'global' 

See open sensor health alerts - https://graph.microsoft.com/beta/security/identities/healthIssues?$filter=Status eq 'open' and healthIssueType eq 'sensor' 

See open health alerts by severity -  

https://graph.microsoft.com/beta/security/identities/healthIssues?$filter=Status eq 'open' and severity eq 'medium' 

https://graph.microsoft.com/beta/security/identities/healthIssues?$filter=Status eq 'open' and severity eq 'low' 

See open global health alerts that domain name ends with contoso.com -https://graph.microsoft.com/beta/security/identities/healthissues?$filter=Status eq 'open' and healthIssueType eq 'global' and domainNames/any(s:endswith(s,'contoso.com')) 

See open global health alerts that sensor DNS name ends with contoso.com -https://graph.microsoft.com/beta/security/identities/healthissues?$filter=Status eq 'open' and healthIssueType eq 'global' and sensorDNSNames/any(s:endswith(s,'contoso.com')) 

See open sensor health alerts with sensor DNS name ends with consoto.com -https://graph.microsoft.com/beta/security/identities/healthissues?$filter=Status eq 'open' and healthIssueType eq 'sensor' and sensorDNSNames/any(s:endswith(s,'contoso.corp')) 

Keep your Defender for Identity deployment healthy and secure! 

 

 

 

Updated Apr 17, 2024
Version 1.0
automation
microsoft defender for identity
  • hib1000's avatar
    hib1000
    Copper Contributor
    Sep 24, 2024

    Thanks for this, it works great.  I'm trying to do the same for Sensor resource type (https://graph.microsoft.com/beta/security/identities/sensors) with the permission SecurityIdentitiesSensors.Read.All - but i'm getting an "Expression.Error: Access to the resource is forbidden." - any idea on why this might be? 

     

    ***This is working now, not sure what changed 🙂 ***

  • PSec-IT's avatar
    PSec-IT
    Copper Contributor
    Oct 03, 2024

    Indeed works great for SecurityIdentitiesHealth.Read.All when using Graph through PowerShell command Get-MgBetaSecurityIdentityHealthIssue, the health issues are returned nicely...

    But I'm getting a similar error when trying to access the sensor list using permission SecurityIdentitiesSensors.Read.All as hib1000.


    Any idea what could be the issue for the unknown error 403 forbidden ?
    Anyone else having the same problem ?

     

    Get-MgBetaSecurityIdentitySensor_List:

    Status: 403 (Forbidden)
    ErrorCode: UnknownError
    Date: 2024-10-03T12:11:25

    Headers:
    Vary : Accept-Encoding
    Strict-Transport-Security : max-age=31536000
    request-id : ********-****-****-****-************
    client-request-id : ********-****-****-****-************
    x-ms-ags-diagnostic : {"ServerInfo":{"DataCenter":"North Europe","Slice":"E","Ring":"4",...
    Date : Thu, 03 Oct 2024 12:11:25 GMT

  • PSec-IT's avatar
    PSec-IT
    Copper Contributor
    Oct 07, 2024

    When I use the command Get-MgBetaSecurityIdentitySensorCount then I see the expected amount of sensors. But when using Get-MgBetaSecurityIdentitySensor -All then I count 100 sensors less... Making it difficult to create a simple inventory list of the sensors.

    PS C:\temp> (Get-MgBetaSecurityIdentitySensor -All).count
    136
    PS C:\temp> Get-MgBetaSecurityIdentitySensorCount
    236

    According the documentation the -All parameter should return all pages.
    https://learn.microsoft.com/en-us/powershell/module/microsoft.graph.beta.security/get-mgbetasecurityidentitysensor?view=graph-powershell-beta#-all 

    Trying to see if adding additional filters returns the whole list but no victory yet...

  • PSec-IT's avatar
    PSec-IT
    Copper Contributor
    Oct 10, 2024

    Finally, Get-MgBetaSecurityIdentitySensor -All didn't provide what is needed, requiring a little creativity to get what is needed.


    [    System.Collections.ArrayList]$MDIHosts = (Get-ADForest).Domains | ForEach-Object -parallel {
            get-mgbetaSecurityIdentitySensor -Filter "DomainName eq '$_'"
            get-mgbetaSecurityIdentitySensor -Filter "DomainName eq '$($_.ToLower())'"

    }

    $MDIHosts


  • praveen8888's avatar
    praveen8888
    Copper Contributor
    Nov 21, 2024

    Hello, when I use the API, I get a 302 error, indicating that the URL is not functional for reporting health issues.