Offboarding devices from Microsoft Defender for Business using Power Automate

Recently, I wrote an article to make offboard from Microsoft Defender for Business easier:

Offboarding devices from Microsoft Defender for Business using an API with PowerShell

Because this offboarding process utilises an API we can use that with other services such as Power Automate.

Before devices can be offboarded, a list needs to be created that can be accessed by Power Automate. Refer to this article:

Get a list of devices from Defender for Business into a SharePoint list

for details about creating an inventory of devices saved to a SharePoint Online list.

image

The summary of the Flow to do this device offboarding process is shown above.

image

Once the Flow has been triggered I grab the Azure AD application credentials from the Azure Key Vault. I’ve covered off how to create an Azure AD application here:

https://blog.ciaops.com/2019/04/17/using-interactive-powershell-to-access-the-microsoft-graph/

and using a PowerShell script I wrote here:

https://blog.ciaops.com/2020/04/18/using-the-microsoft-graph-with-multiple-tenants/

Getting the Azure AD application credentials into an Azure Key Vault can be done manually or by using this scripted process I’ve covered previously:

Uploading Graph credentials to Azure Key Vault

Once they are in the Azure Key Vault they are easy to access securely using the Flow action Get secret as shown above.

image

Next comes the Get items action as shown above. This filters the list of devices using a column called Offboard and returns items that have this as Yes (or = 1 for Power Automate).

image

A new variable is then created and the initial API offboarding URL is saved into it. This will later be appended with the actual device number that is being offboarded which is required by the API.

image

For each item that was returned from the filtered list of devices (i.e. those that been selected to offboard),

image

the offboarding API URL needed to be extended to include the unique Device ID from the returned results and the string /offboard.

image

Thus URL now needs to be ingested by the HTTP action as shown above. It is important that the body contain the following JSON:

{
   “Comment”: “Offboard machine by automation”
}

This was taken from the documentation:

Offboard machine API

The other access parameters come from Azure AD application that were extracted from Azure Key Vault earlier on in the Flow.

image

Because the return from the HTTP action can vary, we now need to have a Switch action as shown above.

image

In the top right hand corner of the Switch action, select the ellipse (three dots) and then Configure run after from the menu that appears.

image

Because the result from the HTTP action could be 400 (i.e. failure or BadRequest) we still want the Flow to proceed. If the Switch action is not used the Flow will fail like so:

image

Using the Switch action and selecting both the is successful and has failed options shown above, will allow the Flow to continue on.

image

If the HTTP action does return a BadRequest, the left hand side Case condition is met. For any other return, the right hand side Case condition will be executed.

In the case of a return status code = 400, the body of the returned JSON will be parsed and the field Result will updated in the device list for that item with the Message information taken from the JSON results.

In the case of any other return code the following will be executed:

image

Once again, there could a variety of different returned status codes from the HTTP action, however here I’ll just have a single condition to see if it is successful (status code = 201) and for anything else the results will be updated to the Result field for the device in question.

image

The last action required, after the Switch, is to reset the URL variable back to the original string in case there are other devices that have been selected to offboard. Failing to do this will result in an incorrect API URL for every device after the first match.

image

What this offboarding process looks like in practice would therefore be to select which devices to offboard from the SharePoint list, by setting the Offboard column to be Yes, as shown above.

image

Once the offboard Flow has been run, the results for those selected devices are found in the Result column and Offboard column has been reset to be No for each of these, as shown above.

image

If you set the Offboard column to Yes again for this device and re-rerun the offboarding Flow,

image

the Flow runs successfully, even though a base request resulted  during the HTTP action and the information from that is captured and stored in the Result field as shown above.

There are edge case conditions this Flows doesn’t accommodate. This is normally due to the correct information not being fully populated in the portal. This typically happens in the short period you create or add add a device to Defender for Endpoint. It is simple enough to add these checks in the Flow, but for the sake of simplicity that are not included here.

This whole process again demonstrates the flexibility and capability combining APIs with Power Automate can provide. Remember, you can set this whole process up to work across multiple tenants, it doesn’t have to be restricted to just the tenant you are on. Using Power Automate allows you to easily extend a solution to maybe include email notifications, updates into a Microsoft Team and more.

So these are some ways you can offboard devices from Microsoft Defender for Business:

Via a local script

Using Endpoint Manager and Intune

Using PowerShell

and using Power Automate as detailed here.

Using the Defender for Endpoint API and PowerShell

The Microsoft Defender for Endpoint API is now available. More details can be found here:

https://docs.microsoft.com/en-us/microsoft-365/security/defender-endpoint/management-apis?view=o365-worldwide

Those APIs will enable you to automate workflows and innovate based on Defender for Endpoint capabilities.

In essence, you can now manipulate Defender for Endpoint capabilities using a tool like PowerShell. I’ll show you how to get started.

The first thing you’ll need to do is create an Azure AD app in the destination tenant. I’ve covered off how to do this via the web interface here:

https://blog.ciaops.com/2019/04/17/using-interactive-powershell-to-access-the-microsoft-graph/

and using a PowerShell script I wrote here:

https://blog.ciaops.com/2020/04/18/using-the-microsoft-graph-with-multiple-tenants/

You’ll also need to provide this Azure AD app the appropriate permissions in the Defender for Endpoint API (as well as have a license for Defender for Endpoint in your tenant). To do this, navigate to the Azure AD app you just created and follow the process to add an API permission (you’ll see this process in the above blog posts).

image

You’ll need to however select APIs my organization uses from the menu, and then search for WindowsDefenderATP as shown above to locate the right API.

image

Now select Application permissions on the right from the screen that appears as shown above.

If you have a look at the:

Export software vulnerabilities assessment per device

You’ll see in permissions:

image

You’ll see the permission required for this process is Vulnerability.Read.All.

image

Search for, and select this Vulnerability.Read.All permission in the list as shown above and select it. Scroll down to the bottom of the page and select the Add permissions button to complete the process.

image

Select the Grant admin consent for <tenant> option at the top now to apply these permissions you have just selected to add to this Azure AD app.

In summary, an Azure AD app is used to provide access to the Defender for Endpoint API. This access also requires the appropriate permissions be assigned to that Azure AD app for the Defender for Endpoint API.

When the Azure AD app was initially created the following parameters should have been available:

1. Client (or Application) ID

2. Tenant ID

3. Client (or Application secret)

You’ll need to enter these into the script I have created here:

https://github.com/directorcia/Office365/blob/master/endpoint-api-svbm.ps1

around line 20:

image

Ensure your values these are kept secure! I have discussed ways of doing this using the Azure Keyvault or encrypted XML files previously.

image

After inserting your own Azure AD app values into the script, and running the script you should see the results like that shown above. The output is a list of software vulnerabilities by machine in your Defender for Endpoint environment sorted by machine name and last seen timestamp.

The Defender for Endpoint API has lots of options as you can see here:

https://docs.microsoft.com/en-us/microsoft-365/security/defender-endpoint/exposed-apis-list?view=o365-worldwide#in-this-section

You may need to repeat the process of assigning permissions to your Azure AD app to execute other API commands remember. However, being able to access this information via an API makes it easy to import into things like Power BI and Power Automate as well as access multiple tenant with a single script. Hopefully, this article give you a place to start accessing all the Defender for Endpoint information programmatically.