Microsoft Secure Tech Accelerator
Apr 03 2024, 07:00 AM - 11:00 AM (PDT)
Microsoft Tech Community

Automate Windows Defender ATP response action: Machine isolation

Microsoft

image.png5 Minutes 

image.pngLow complexity 

 

Response teams rely on powerful actions that allow them take immediate action when a threat is identified. Being able to automate those response actions is a powerful way to enhance a SecOps team’s workflow. In this blog, we’re going to demonstrate how you can automate the machine isolation response action. 

In our previous blogs we’ve demonstrated how you can: 

  1. Setup an app and create a script to get WDATP’s alerts (Hello World blog)    
    • This is a good reference for when you need to create a new app. 
  2.  Grant more permission, get and update alerts as part of a ticketing/SIEM/SOAR integration (Ticketing System Integration blog) 
    • This is a good source of information to learn how to add more permissions on apps. 

For response teams, a typical use case involves the ability to enrich SIEM or SOAR playbooks with Windows Defender ATP’s powerful remediation capabilities. Just imagine how powerful it can be to detect a malicious activity using your firewall or IPS and isolate the suspicious machine 

wherever it is (even if the machine is off network at time of response).  

In this blog, we’ll walk you through using the machine isolation API. This response action will leave the machine disconnected from any network connection other than the Windows Defender ATP channel (allowing Windows Defender ATP to undo). 

What’s great about this demonstration is that it can be applied with the other response actions documented here. 

 

Let’s start

In this section, we’ll walk you through the following: 

  • Step 1: Add the required permission to your application 
  • Step 2: Isolate a machine by machine ID or machine name 

Step 1 - Add the required permission to the application:

If you haven’t created an app: 

  • Create an app using the instructions described in the Hello world blog. 
  • Then follow the instructions on how to Add Isolation Permission as described below 

If you’ve already created an app that you’re going to reuse for this demonstration: 

  • Add the “Isolate Machine” permission as described below 
  • We recommend that you follow the detailed steps as described in the “Step 1 - Add the required permission to the application” in the Alert Update API blog  

 

Add Isolation Permission

  • Open Azure portal 
  • Navigate to Azure Active Directory > App registrations 
  • Under All Apps, find and select the application, for example ContosoSIEMConnector 
  • Navigate to Settings > Required permissions > Enable Access 
  • Select the checkbox for Isolate machine application permission. 

add isolation permission.jpg

  • Click Save and Grant Permissions. 

Done! You have successfully added the required permissions to the application. 

 

Step 2 – Isolate a machine by machine ID or machine name:

  • Save the following script file as IsolateMachine.ps1 in the same folder where you saved the Hello World example (where Get-Token.ps1 was saved).  

IsolateMachine.ps1

param (  
    [Parameter(Mandatory=$true)][string]$comment, #any comment that help
    [Parameter(Mandatory=$true)][string]$machineIdOrComputerDnsName, #the machineID or ComputerDnsName 
    [Parameter(Mandatory=$true)]  
    [ValidateSet('Full','Selective')]  #validate that the input contains valid isolation type
    [string]$isolationType    #the type of machine isolation
 )

$token = ./Get-Token.ps1          #Execute Get-Token.ps1 script to get the authorization token
$url = "https://api.securitycenter.windows.com/api/machines/$machineIdOrComputerDnsName/Isolate"

$body = 
@{
  "Comment" = $comment
  “IsolationType” = $isolationType 
}

$headers = @{ 
    'Content-Type' = 'application/json'
    Accept = 'application/json'
    Authorization = "Bearer $token"
}

$response = Invoke-WebRequest -Method Post -Uri $url -Body ($body | ConvertTo-Json) -Headers $headers -ErrorAction Stop
if($response.StatusCode -eq 201)   #check the response status code
{
    return $true        #update ended successfully
}
else
{
    return $false       #update failed
}  

 

Example 1: Isolate by machine DNS name

  • Find the machine FQDN in the machine page (concatenate the machine name and the domain) 
  • For example, to isolate the machine testMachine.contoso.com use the following command:  

.\IsolateMachine.ps1 -machineIdOrComputerDnsName testMachine.contoso.com -comment “isolate because of alert”  -isolationType Full 

 

Example 2: Isolate by using machine ID

  • Find the machine ID in the URL of the machine page 
  • For example, to isolate machine where machine page URL is https://securitycenter.windows.com/_machine/1f2258dc516c7bf8ec62466e2e876774c0a984f3 use the following command: 

.\IsolateMachine.ps1 -machineIdOrComputerDnsName 1f2258dc516c7bf8ec62466e2e876774c0a984f3 -comment “isolate because of alert”  -isolationType Full 

 

Example 3: Isolate machines with severe alerts

  • Read high severity alerts as described in the previous blogs 
  • Use the machine ID found in the alert to isolate the machine using the following script 

GetSevereAlertsAndIsolate.ps1

# Returns Alerts created in the past 1 hour. and Isolate machines with high severity alerts  
$token = .\get-token.ps1 
$dateTime = (Get-Date).ToUniversalTime().AddHours(-1).ToString("o") 

#create url with filter for date and severity 
$url = "https://api.securitycenter.windows.com/api/alerts?`$filter=alertCreationTime ge $dateTime and severity eq 'High'" 

$headers = @{  
    'Content-Type' = 'application/json' 
    Accept = 'application/json' 
    Authorization = "Bearer $token"  
} 

$response = Invoke-RestMethod -Method Get -Uri $url -Headers $headers -ErrorAction Stop 

#foreach alert, get the machineId and alertId and isloate machine while writing the alert ID in the isolation comments. 
foreach ($alert in $response.value){ 
    $machineId = $alert.machineId 
    $alertId = $alert.id 
$url = "https://api.securitycenter.windows.com/api/machines/$machineId/Isolate"
$body = @{ Comment = "Isolate machine because alert - $alertId" } $headers = @{ 'Content-Type' = 'application/json' Accept = 'application/json' Authorization = "Bearer $token" } $response = Invoke-WebRequest -Method Post -Uri $url -Body ($body | ConvertTo-Json) -Headers $headers -ErrorAction Stop #check the isolatino request code and write to log file. if($response.StatusCode -eq 201) { Add-Content c:\temp\api\log.txt "The isolation of machine $machineId ended successfully" } else { Add-Content c:\temp\api\log.txt "Failed to isolate machine $machineId" } }

 

Example 4: Release machine (un-isolate)

  • Save the script below as UnIsolateMachine.ps1 file to the same folder where you save the Hello World example (where Get-Token.ps1 was saved). 

UnisolateMachine.ps1

param (
    [Parameter(Mandatory=$true)][string]$comment,
    [Parameter(Mandatory=$true)][string]$machineId
 )

$token = ./Get-Token.ps1
$url = "https://api.securitycenter.windows.com/api/machines/$machineId/UnIsolate"

$body = 
@{
	Comment = $comment
}

$headers = @{ 
    'Content-Type' = 'application/json'
    Accept = 'application/json'
    Authorization = "Bearer $token"
}

$response = Invoke-WebRequest -Method Post -Uri $url -Body ($body | ConvertTo-Json) -Headers $headers -ErrorAction Stop
return ($response.Content | ConvertFrom-Json)

 

  • Use the following script in the same way to release the machine from isolation 

.\UnIsolateMachine.ps1 -machineId 1f2258dc516c7bf8ec62466e2e876774c0a984f3 -comment “un-isolate – machine was found clean” 

 

Conclusion:

In this blog we demonstrated how you can easily automate Windows Defender ATP response actions. There are more actions you can automate such as run an antivirus scan and restrict app execution. For more information, see more the other actions here . 

 

Let us know if you are interested in more specific remediation examples. 

In the next blog we’ll demonstrate the integration of alerts from other detection sources. 

 

Thanks! 

@Haim Goldshtein, security software engineer, Windows Defender ATP  

@Dan Michelson, program manager, Windows Defender ATP  

 

5 Replies

We wrote a blog on how to do a similar thing with Microsoft Flow and the ATP connector with approval step

http://blog.sec-labs.com/2019/04/automate-response-with-defender-atp-and-microsoft-flow/

@Mattias Borg This is exactly what I was looking for. The approve and isolation proces works like a charm and it is very easy to set up. I didn't know about the integration between flow and ATP, but I will definitely start using it for incident response management.
I have been browsing your website http://blog.sec-labs.com/ and found many valuable tips, like how to create custom IOC's in ATP. Thank you!   

@Andre Coninck 

No problem, I'm happy it's usable :)

 

Happy hunting!

@Haim Goldshtein - For testing, I used the APIs to Isolate and then Unisolate the on boarded machine in Windows Defender Security Center, but the machine is still not unisolated, Release from isolation is pending. How long does it take the machine to be released from isolation? When does the Isolate machine become available?

@Haim Goldshtein is it possible to programatically list which machines are in an isolated state?

Last night we had ~100 false positive alerts due to an over-enthusiastic (!) detection based on O365 which resulted in ~80 machines being automatically isolated with my Flow. Whilst we manually went through them one at a time last night to release them, I think due to some of them being off-line it looks like the release isolation has timed out and today some are still isolated but we are either waiting for the owners to call us or have to check them all individually again?

Thanks

Mike