Bruno Gabrielli and Tan Tran
Dear IT Pros,
Related to Microsoft Defender for Endpoint, recently we got a request from a customer to create the Defender group of tool devices running Windows 10 Operating Systems. This device group later will be assigned with no-remediation policy. Customer has wanted all the devices which are members of this group, will be audited and alerted about threats by Defender Service only, there should be no action such as quarantine or removal of files on the critical devices which were used to control tool in operation rooms.
The task is easy, just need to create a device group based on the device tags, for example, I use the tag name “OP-Tool” and make a dynamic group based on tag name of OP-Tool:
There is a good techblog article about scoping devices based on tags by Steve Newby (Microsoft).
The question is, how could we tag each of the Defender Endpoint Device with the “OP-tool” label?
We need to do the task on tens of thousands of devices programmatically.
As you already knew it, there are a few ways to tag a device, you could tag it manually by Defender Portal under device and manage tag or by Windows Regedit.exe and modifying the device ‘s registry key. Another method is using the Endpoint MDM Configuration Profile with a custom OMA-URI, or by using Defender portal with the API Explorer feature. We could also make device tags easily by using Microsoft Flow. One of Customer preferred way is tagging device by running PowerShell script with API access to Defender Service data source.
Let us go through the options mentioned above.
For device tagging purpose, you could create the registry key named “DeviceTagging” based on Microsoft document. The key path and value is as follows:
HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Windows Advanced Threat Protection\DeviceTagging
Key name: Group Value: YourTagName
DeviceInfo
|where DeviceName contains "fc-cl01"
|where Timestamp > ago(1h)
|where RegistryDeviceTag contains "NewOP-Tool"
|project Timestamp, DeviceName, RegistryDeviceTag, OSPlatform, LoggedOnUsers, MachineGroup
Query Result:
3.Using Microsoft Defender for Endpoint API Explorer to tag devices.
Let us start with a simple command in API explorer:
To add/remove tag by API explorer:
You just need to run the post command as shown here and replace the device ID with your device ID.
Run Post command:
Result shown in the Device blade:
Run Get command:
https://api-us.securitycenter.windows.com/api/machines?$select=id, computerDnsName,Machinetags
Antonio Vasconcelos from Git Hub has provided us a script to connect to MD for Endpoint API and tag multiple devices in one shot:
# PLEASE NOTE THAT I TAKE NO RESPONSIBILITY ON THE RESULTS THIS SCRIPT MIGHT YIELD
# YOU SHOULD TEST IT AND MAKE SURE IT FITS YOUR NEEDS
# Author: Antonio Vasconcelos
# Twitter: anthonws
# Date/Version/Changelog:
# 2020-01-25 - 1.0 - First release
# Objective:
# Script that adds a specified Tag to machines in MDATP
# Input is expected to be a CSV file with 2 columns, one with "Name" and the other with "Tag". The first line are the headers. Break line for each new entry.
# MachineId is obtained via the ComputerDnsName, which should equate to the Host name or FQDN, depending on the type of machine join (WORKGROUP, Domain, etc.)
$tenantId = '000000000000000000000' ### Paste your own tenant ID here
$appId = '000000000000000000000' ### Paste your own app ID here
$appSecret = '000000000000000000000' ### Paste your own app keys here
$resourceAppIdUri = 'https://api.securitycenter.windows.com'
$oAuthUri = "https://login.windows.net/$TenantId/oauth2/token"
$authBody = [Ordered] @{
resource = "$resourceAppIdUri"
client_id = "$appId"
client_secret = "$appSecret"
grant_type = 'client_credentials'
}
$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
$token = $authResponse.access_token
# Store auth token into header for future use
$headers = @{
'Content-Type' = 'application/json'
Accept = 'application/json'
Authorization = "Bearer $token"
}
# Clean variables
$Data = @();
$MachineName = $null;
$MachineTag = $null;
$MachineId = $null;
##### CSV input file serialization ####
$Data = Import-Csv -Path c:\Temp\MDATP\MachineList.csv
##### Add Tag Block ####
# Added timer to respect API call limits (100 per minute and 1500 per hour)
# Defaulting to the shortest limit, which is 1500 per hour, which equates to 25 calls per minute
# Introduced a 3 sleep at the beginning of every while iteration
# Iterate over the full array
$Data | foreach {
Start-Sleep -Seconds 3
$MachineName = $($_.Name);
$MachineTag = $($_.Tag);
# Obtain the MachineId from MDATP, based on the ComputerDnsName present in the CSV file
$url = "https://api.securitycenter.windows.com/api/machines/$MachineName"
$webResponse = Invoke-RestMethod -Method Get -Uri $url -Headers $headers -ErrorAction Stop
$MachineId = $webResponse.id;
# Body content will carry the tag specified in the CSV file for the given machine
$body = @{
"Value"=$MachineTag;
"Action"="Add";
}
# Add specified tag in CSV to the particular MachineId in MDATP
$url = "https://api.securitycenter.windows.com/api/machines/$MachineId/tags"
$webResponse = Invoke-WebRequest -Method Post -Uri $url -Headers $headers -Body ($body|ConvertTo-Json) -ContentType "application/json" -ErrorAction Stop
# Clean variables (sanity check)
$MachineName = $null;
$MachineTag = $null;
$MachineId = $null;
}
There is note related to the 3 second sleep time in the script above from the MD for Endpoint Program Team:
- API limits. Due to resource constraints, we limit the amount of API calls that can be made to 100 per minute and 1500 per hour. To avoid this, a sleep value has been applied to the script to put a pause in after each API call. Obviously, this can be removed to speed things up if the number of machines you are modifying does not hit this limit.
Prepared steps to run the "Device Tagging" API script:
Sample of machinelist.csv:
Results after running PowerShell tagging script, multiple tags are added to the existing device tags as shown here:
Tomer Brand from Microsoft show us how to easily tag multiple devices by Microsoft flow in the following techblog article:
I hope the information is helpful and save you some precious time when tagging Defender Devices.
Until next time!
Reference
Disclaimer
The sample scripts are not supported under any Microsoft standard support program or service. The sample scripts are provided AS IS without warranty of any kind. Microsoft further disclaims all implied warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The entire risk arising out of the use or performance of the sample scripts and documentation remains with you. In no event shall Microsoft, its authors, or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the sample scripts or documentation, even if Microsoft has been advised of the possibility of such damages.
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.