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:
- 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.
- 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
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.
- 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
