This post is an introduction to accessing the Defender Security Center API in PowerShell using interactive authentication. It is the basis for building tools and scripts to enhance day-to-day productivity that I’ll explore in future posts.

Background

The Defender Security API is a gold mine as it can provide access to key MDE features including:

  • Device information
  • Alerts
  • MDE Configuration
  • Run Advanced Hunting queries
  • Initiate Live Response and manage Library scripts
  • Initiate Scans and Isolation

I struggled to find examples of using the API interactively. Microsoft articles have examples using a client secret, which is fine for automation, but not ideal for interactive use. The following steps demonstrate interactive access to the API.

Azure App

The first step is to create an Azure Application to control the permissions available and limit admin access to the API.

Create the App

In the Azure Portal, go to the App Registrations blade and select New Registration

Enter a name for the app e.g. DefenderSecurityAPI (visible in MFA challenges and sign-in logs)

Leave the Supported Account Types on the default Single Tenant

Do not configure a Redirect URL at this stage.

Register App

Select Register to create the app.

You are presented with the App Overview page. Select Add a redirect URI, then Add a Platform

Select Mobile and Desktop applications

Enable the check box next to the nativeclient URL and also add local host in the Custom Redirect URIs:

Select Configure to save the redirect URLs

Next select API Permissions in the left pane, then Add a permission

Select the APIs my organization uses tab and then use the search box to find WindowsDefenderATP

Select Delegated Permissions

API Permissions

Expand the categories and select the individual permissions required
e.g. Alert.Read, AdvancedQuery.Read, Machine.Read, Machine.Scan, Machine.RestrictExecution, Machine.Isolate, Machine.CollectForensics, Machine.Offboard, Software.Read

Once you’ve finished adding permissions, select Grant admin consent for tenant_name

Delegated permissions mean both the user and the app must have the required permission. The app won’t elevate privileges.

Restrict Access to the app

To restrict who can use the app, we need to go to the Enterprise applications blade, either using the Azure Portal search box, or by navigating to the root of Azure AD and selecting it in the left pane.

Select the app in the list to open its Overview page, then select Properties in the left pane.
Change Assignment Required to Yes and then Save
Select Users and groups in the left pane and then select Add user/group
Select an existing group that will be allowed to authenticate using the App.

NOTE: Although we consented to API permissions in the previous step, it was only delegated permissions. The group members must also be granted permission to read or change Security assets e.g. through a built-in Role, such as Security Administrator.

Select the Overview link in the left pane and copy the Application ID as this will be a script variable along with the TenantID.

Authenticate using MSAL.PS

Use the MSAL.PS PowerShell module to authenticate interactively and cache an access token. The important part is to specify a security API scope.

# Pre-req
Install-Module -Name MSAL.PS -MinimumVersion 4.37.0.0

# Replace with your Application and Tenant IDs
$ApplicationID = '446e4714-3226-489e-b602-1515d6822e09'
$TenantID = 'b0530087-fc9a-44e7-ad6f-1b045d56e15d'

# Specify at least one security center API scope
$Scopes = @("https://api.securitycenter.microsoft.com/Machine.Read")

# Authenticate interactively with authorization code flow
$AccessToken = Get-MsalToken -ClientId $ApplicationID -TenantId $TenantID -Scopes $Scopes

If authentication fails with a message “You can’t get there from here”, see the Conditional Access section below.

Call the API

With an access token cached, its straight forward to call the Security Center API using Invoke-Restmethod. The following is a basic example of getting device information:

# Build the authentication header
$AuthenticationHeader = @{
    "Content-Type"  = "application/json"
    "Authorization" = $AccessToken.CreateAuthorizationHeader()
    "ExpiresOn"     = $AccessToken.ExpiresOn.UTCDateTime
}

# Example getting details of an MDE client device
# The deviceID is available on the device details blade in the Security Center portal
$Method = 'Get'
$MachineID = 'c6a833d8a0da6ad439076368d1681e7930c49fef'
$URI = "https://api.securitycenter.microsoft.com/api/machines/$MachineID"

Invoke-RestMethod -Uri $URI -Headers $AuthenticationHeader -Method $Method

Example output:

Device info

Conditional Access

There’s an automatically created Conditional Access policy that must be modified before you can query the API. If authentication fails with the error below, you need to edit the policy.

Conditional Access

The CA policy gets created during Defender for Endpoint setup, when MDE is linked to Intune. Its only visible in the CA Classic view:

Azure Active Directory > Security > Conditional Access > Classic Policies > [Windows Defender ATP] Device Policy

Classic Policy

Don’t delete or disable the policy. It could have undesirable results as indicated in this Microsoft article. Instead, add a group exclusion to the policy for the same group authorised to use the Azure App.

Summary

This article is an introduction to accessing the Defender Security Center API using PowerShell with interactive authentication. Future articles will explore practical use cases.



This article was originally posted on Write-Verbose.com