Windows security center api

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.

Картинка с сайта: write-verbose.com

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:

• https://login.microsoftonline.com/common/oauth2/nativeclient
• http://localhost

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

Картинка с сайта: write-verbose.com

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:

Картинка с сайта: write-verbose.com

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.

Картинка с сайта: write-verbose.com

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

Картинка с сайта: write-verbose.com

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

Sometimes you might want to script checking health of anti-virus/firewall/&c. However since Windows Vista the method frequently used in scripts is accessing the wmi namespace root/securitycenter2 which is undocumented from publicly available Microsoft. Although the values of what productState mean have been guessed with reasonable accuracy, I prefer to stay away from undocumented items in case of future changes…and if there is a case “we guessed wrong”.

The WMI Method

Картинка с сайта: chentiangemalc.wordpress.com

The documented method since Windows Vista has been the Windows API WscGetSecurityProviderHealth in wscapi.dll which is documented here: http://msdn.microsoft.com/en-us/library/bb432506(v=vs.85).aspx

However calling Windows APIs from scripts can be tricky, so here is a wrapper I built in PowerShell that embeds C# code to call the Windows API and retrieve the data so you can manipulate it in PowerShell.

Note this is just sample code – to be more robust I’d recommend adding error checking/&c. and other improvements. Go knock yourself out.

The way the code works:

1. We put our C# code into $wscType
2. Add-Type compiles the C# code and makes the members available in $wscType
3. $wscType[0]::GetSecurityProviderHealth calls the function to get health
4. $wscType[1] is the WSC_SECURITY_PROVIDER enum to specify what security provider to check
5. $wscType[2] is the WSC_SECURITY_PROVIDER_HEALTH enum to check against the result of GetSecurityProviderHealth

Note: The WscGetSecurityProviderHealth API is not supported on Windows XP or earlier, or on any Microsoft Server Operating Systems.

Example

The Script

Картинка с сайта: chentiangemalc.wordpress.com

Action Center

Картинка с сайта: chentiangemalc.wordpress.com

Download script here: https://skydrive.live.com/redir?resid=E1A3C870740A073D!298&authkey=!AF2EGVM6l5lQ0dc (1.57 KB ZIP)

Or copy from here:

# by chentiangemalc

# https://chentiangemalc.wordpress.com

# Define our C# functions to extract info from Windows Security Center (WSC) via Windows API so we can call from PowerShell

$wscDefinition = @”

        // WSC_SECURITY_PROVIDER as defined in Wscapi.h or http://msdn.microsoft.com/en-us/library/bb432509(v=vs.85).aspx

              [Flags]

        public enum WSC_SECURITY_PROVIDER : int

        {

            WSC_SECURITY_PROVIDER_FIREWALL = 1,                      // The aggregation of all firewalls for this computer.

            WSC_SECURITY_PROVIDER_AUTOUPDATE_SETTINGS = 2,    // The automatic update settings for this computer.

            WSC_SECURITY_PROVIDER_ANTIVIRUS = 4,                     // The aggregation of all antivirus products for this computer.

            WSC_SECURITY_PROVIDER_ANTISPYWARE = 8,                   // The aggregation of all anti-spyware products for this computer.

            WSC_SECURITY_PROVIDER_INTERNET_SETTINGS = 16,     // The settings that restrict the access of web sites in each of the Internet zones for this computer.

            WSC_SECURITY_PROVIDER_USER_ACCOUNT_CONTROL = 32,  // The User Account Control (UAC) settings for this computer.

            WSC_SECURITY_PROVIDER_SERVICE = 64,                      // The running state of the WSC service on this computer.

            WSC_SECURITY_PROVIDER_NONE = 0,                                // None of the items that WSC monitors.

                     // All of the items that the WSC monitors.

            WSC_SECURITY_PROVIDER_ALL = WSC_SECURITY_PROVIDER_FIREWALL | WSC_SECURITY_PROVIDER_AUTOUPDATE_SETTINGS | WSC_SECURITY_PROVIDER_ANTIVIRUS |

            WSC_SECURITY_PROVIDER_ANTISPYWARE | WSC_SECURITY_PROVIDER_INTERNET_SETTINGS | WSC_SECURITY_PROVIDER_USER_ACCOUNT_CONTROL |

            WSC_SECURITY_PROVIDER_SERVICE | WSC_SECURITY_PROVIDER_NONE

        }

        [Flags]

        public enum WSC_SECURITY_PROVIDER_HEALTH : int

        {

            WSC_SECURITY_PROVIDER_HEALTH_GOOD,                // The status of the security provider category is good and does not need user attention.

            WSC_SECURITY_PROVIDER_HEALTH_NOTMONITORED, // The status of the security provider category is not monitored by WSC.

            WSC_SECURITY_PROVIDER_HEALTH_POOR,                // The status of the security provider category is poor and the computer may be at risk.

            WSC_SECURITY_PROVIDER_HEALTH_SNOOZE,              // The security provider category is in snooze state. Snooze indicates that WSC is not actively protecting the computer.

            WSC_SECURITY_PROVIDER_HEALTH_UNKNOWN

        }

              // as defined in http://msdn.microsoft.com/en-us/library/bb432506(v=vs.85).aspx

        [DllImport(“wscapi.dll”)]

        private static extern int WscGetSecurityProviderHealth(int inValue, ref int outValue);

              // code to call our interop function and return the relevant result based on what input value we provide

        public static WSC_SECURITY_PROVIDER_HEALTH GetSecurityProviderHealth(WSC_SECURITY_PROVIDER inputValue)

        {

            int inValue = (int)inputValue;

            int outValue = -1;

            int result = WscGetSecurityProviderHealth(inValue, ref outValue);

            foreach (WSC_SECURITY_PROVIDER_HEALTH wsph in Enum.GetValues(typeof(WSC_SECURITY_PROVIDER_HEALTH)))

                if ((int)wsph == outValue) return wsph;

            return WSC_SECURITY_PROVIDER_HEALTH.WSC_SECURITY_PROVIDER_HEALTH_UNKNOWN;

        }

“@

$wscType=Add-Type -memberDefinition $wscDefinition -name “wscType” -UsingNamespace “System.Reflection”,“System.Diagnostics” -PassThru

”            Firewall: “ + $wscType[0]::GetSecurityProviderHealth($wscType[1]::WSC_SECURITY_PROVIDER_FIREWALL)

”         Auto-Update: “ + $wscType[0]::GetSecurityProviderHealth($wscType[1]::WSC_SECURITY_PROVIDER_AUTOUPDATE_SETTINGS)

”          Anti-Virus: “ + $wscType[0]::GetSecurityProviderHealth($wscType[1]::WSC_SECURITY_PROVIDER_ANTIVIRUS)

”        Anti-Spyware: “ + $wscType[0]::GetSecurityProviderHealth($wscType[1]::WSC_SECURITY_PROVIDER_ANTISPYWARE)

”   Internet Settings: “ + $wscType[0]::GetSecurityProviderHealth($wscType[1]::WSC_SECURITY_PROVIDER_INTERNET_SETTINGS)

“User Account Control: “ + $wscType[0]::GetSecurityProviderHealth($wscType[1]::WSC_SECURITY_PROVIDER_USER_ACCOUNT_CONTROL)

”         WSC Service: “ + $wscType[0]::GetSecurityProviderHealth($wscType[1]::WSC_SECURITY_PROVIDER_SERVICE)

# some examples of checking the “health” status…

if ($wscType[0]::GetSecurityProviderHealth($wscType[1]::WSC_SECURITY_PROVIDER_FIREWALL) -eq $wscType[2]::WSC_SECURITY_PROVIDER_HEALTH_POOR)

{

       “Your firewall settings are lame.”

}

if ($wscType[0]::GetSecurityProviderHealth($wscType[1]::WSC_SECURITY_PROVIDER_USER_ACCOUNT_CONTROL) -eq $wscType[2]::WSC_SECURITY_PROVIDER_HEALTH_POOR)

{

       “Don’t tell me you switched off UAC. oh dear.”

}

if ($wscType[0]::GetSecurityProviderHealth($wscType[1]::WSC_SECURITY_PROVIDER_ANTIVIRUS) -eq $wscType[2]::WSC_SECURITY_PROVIDER_HEALTH_GOOD)

{

       “At least you have anti-virus running and up-to-date.”

}