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.

One thought on “Using the Defender for Endpoint API and PowerShell

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s