Introducing the new Defender for Identity sensor management API

Microsoft Defender for Identity is a cloud-based security solution that helps monitor and protect identities and infrastructure across your organization. Defender for Identity 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.

Last year Microsoft Defender for Identity introduced a Graph based API to view Defender for Identity Health issues. Today I am going to discuss the new Defender for Identity sensor management API.

The sensor management API allows you to now perform the following actions without the need to open the Microsoft Defender XDR portal:

• List of sensors and associated data, such as health status, sensor version, domain, type of sensor and date created.
• Update sensor settings, such as enabling or disabling Delayed Update.
• Get the Sensor deployment package
• Get the access key or update the access key
• Delete a sensor – useful when a domain controller has been taken out of service.

These actions can all still be done from within the Microsoft Defender XDR portal as well:

Potential benefits of the sensor management API:

These programable interfaces, now available to all tenants through MSGraph explorer, enable customers to automate various tasks associated with the deployment, configuration and monitoring of the Defender for Identity sensors within their environment. Including:

• Dashboarding – using the new API customers can now pull/surface the full list of their Defender for Identity sensors into the dashboarding tool of their choice.
• Automation - For customers who use ticketing systems for IT support, this new API will allow for the automatic creation of tickets when a sensor version is outdated or to change sensor settings in bulk. For example, a new IT help ticket would automatically be opened when an outdated sensor version is detected. 

Getting Started

For more information, and examples of how you can get started using these API’s, check out our detailed documentation here.

Required permission:

• Entra ID Enterprise Application consent for Microsoft Graph API permissions
  • SecurityIdentitiesSensors.Read.All
  •  SecurityIdentitiesSensors.ReadWrite.All (required to update sensor settings, delete a sensor or rotate the deployment access key)
• Optional – When connecting in user context the following additional M365 role permissions are required:  Authorization and settings --> System Setting --> Read only (Defender for Office, Defender for Identity).

Sample API Queries:

The easiest way to start to use the Defender for Identity sensors management API is using the Graph Explorer,  Graph Explorer | Try Microsoft Graph APIs - Microsoft Graph.

Login in with a user who meets the minimum required 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.

List all the deployed sensors - https://graph.microsoft.com/v1.0/security/identities/sensors

List all the deployed sensors from Contoso.com domain - https://graph.microsoft.com/v1.0/security/identities/sensors?$filter=domainName eq 'Contoso.com'

List all sensors deployed on domain controllers - https://graph.microsoft.com/v1.0/security/identities/sensors?$filter=sensorType eq 'domainControllerIntegrated'

List all sensors running sensor version older than version X - https://graph.microsoft.com/v1.0/security/identities/sensors?$filter=version lt '2.241'

Note: Replace the version number to what you are looking for.

Get the current deployment access key - https://graph.microsoft.com/v1.0/security/identities/sensors/getDeploymentAccessKey

Rotate the deployment access key – (Post) https://graph.microsoft.com/v1.0/security/identities/sensors/regenerateDeploymentAccessKey

Get the sensor deployment package download URL –   https://graph.microsoft.com/v1.0/security/identities/sensors/getDeploymentPackageUri

Note:

• Copy the full URL without the quotation marks.
• URL is valid for 30 minutes.
  
  

Change the sensor delayed update setting from false to true – (use the sensor list to get the sensor ID)  https://graph.microsoft.com/v1.0/security/identities/sensors/3f8fdd01-267f-4046-84f4-d2f9b164d3ef

Patch request body
{

"settings": {"isDelayedDeploymentEnabled": true}

}

Hope this helps you keep your Defender for Identity deployment up to date and secure.