Introducing the new Defender for Identity Health Alert API

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!