diff --git a/windows/security/threat-protection/windows-defender-atp/TOC.md b/windows/security/threat-protection/windows-defender-atp/TOC.md index 7ae86fbea9..1b26c144a4 100644 --- a/windows/security/threat-protection/windows-defender-atp/TOC.md +++ b/windows/security/threat-protection/windows-defender-atp/TOC.md @@ -104,10 +104,12 @@ #### [Supported Windows Defender ATP APIs](exposed-apis-list.md) ##### [Advanced Hunting](run-advanced-query-api.md) #### How to use APIs - Samples -##### [Schedule advanced Hunting using Microsoft Flow](run-advanced-query-sample-ms-flow.md) -##### [Advanced Hunting using PowerShell](run-advanced-query-sample-powershell.md) -##### [Advanced Hunting using Python](run-advanced-query-sample-python.md) - +##### Advanced Hunting API +###### [Schedule advanced Hunting using Microsoft Flow](run-advanced-query-sample-ms-flow.md) +###### [Advanced Hunting using PowerShell](run-advanced-query-sample-powershell.md) +###### [Advanced Hunting using Python](run-advanced-query-sample-python.md) +##### Multiple APIs +###### [PowerShell](exposed-apis-full-sample-powershell.md) ### [Use the Windows Defender ATP exposed APIs](exposed-apis-windows-defender-advanced-threat-protection.md) #### [Supported Windows Defender ATP APIs](supported-apis-windows-defender-advanced-threat-protection.md) diff --git a/windows/security/threat-protection/windows-defender-atp/exposed-apis-full-sample-powershell.md b/windows/security/threat-protection/windows-defender-atp/exposed-apis-full-sample-powershell.md new file mode 100644 index 0000000000..cc35edb442 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/exposed-apis-full-sample-powershell.md @@ -0,0 +1,120 @@ +--- +title: Advanced Hunting API +description: Use this API to run advanced queries +keywords: apis, supported apis, advanced hunting, query +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 30/07/2018 +--- + +# Windows Defender ATP APIs using PowerShell + +Full scenario using multiple APIs from Windows Defender ATP. + +In this section we share PowerShell samples to + - Retrieve a token + - Use token to retrieve the latest alerts in Windows Defender ATP + - Run a query to retrieve command line of the process related to the alert, if the alert has medium priority and is still in progress + - Remediate the machine related to the alert if teh command line + +>**Prerequisite**: You first need to [create an app](exposed-apis-intro.md). + +## Preparation Instructions + +- Open a PowerShell window. +- If your policy does not allow you to run the PowerShell commands, you can run the below command: +``` +Set-ExecutionPolicy -ExecutionPolicy Bypass +``` + +>For more details, refer to [PowerShell documentation](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy) + +## Get token + +- Run the below + +> - $tenantId: ID of the tenant on behalf of which you want to run the query (i.e., the query will be run on the data of this tenant) +> - $appId: ID of your AAD app (the app must have 'Run advanced queries' permission to WDATP) +> - $appSecret: Secret of your AAD app + + +$tenantId = 'b3c1b5fc-828c-45fa-a1e1-10d74f6d6e9c' +$appId = 'c71cd133-0e50-4bd4-a1a8-ec14152af1c4' +$appSecret = '8zFkg61mDxH7DuMGFJHZd6CRr9J5HNMuJGIV6p0shMY=' + + + +``` +$tenantId = '00000000-0000-0000-0000-000000000000' # Paste your own tenant ID here +$appId = '11111111-1111-1111-1111-111111111111' # Paste your own app ID here +$appSecret = '22222222-2222-2222-2222-222222222222' # Paste your own app secret here + +$resourceAppIdUri = 'https://securitycenter.onmicrosoft.com/windowsatpservice' +$oAuthUri = "https://login.windows-ppe.net/$TenantId/oauth2/token" +# TODO!!!!!!!!! $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 +$aadToken = $authResponse.access_token + + +#Get latest alert +$alertUrl = "https://wdatpapi-eus-stg.cloudapp.net/api/alerts?`$top=10" +# TODO!!!!!!!!! $alertUrl = "https://api.securitycenter.windows.com/api/alerts?`$top=10" +$headers = @{ + 'Content-Type' = 'application/json' + Accept = 'application/json' + Authorization = "Bearer $aadToken" +} +$alertResponse = Invoke-WebRequest -Method Get -Uri $alertUrl -Headers $headers -ErrorAction Stop +$alerts = ($alertResponse | ConvertFrom-Json).value + +$machinesToInvestigate = New-Object System.Collections.ArrayList + +Foreach($alert in $alerts) +{ + echo $alert.id $alert.machineId $alert.severity $alert.status + + $isSevereAlert = $alert.severity -in 'Medium', 'High' + $isOpenAlert = $alert.status -in 'InProgress', 'New' + if($isOpenAlert -and $isSevereAlert) + { + if (-not $machinesToInvestigate.Contains($alert.machineId)) + { + $machinesToInvestigate.Add($alert.machineId) > $null + } + } +} + +$commaSeparatedMachines = '"{0}"' -f ($machinesToInvestigate -join '","') + +$query = "NetworkCommunicationEvents +| where MachineId in ($commaSeparatedMachines) +| where RemoteUrl == `"www.bing.com`" +| summarize ConnectionsCount = count() by MachineId" + +$queryUrl = "https://wdatpapi-eus-stg.cloudapp.net/advancedqueries/query" +# TODO!!!!!!!!! $queryUrl = "https://api.securitycenter.windows.com/advancedqueries/query" + +$queryBody = ConvertTo-Json -InputObject $query +$queryResponse = Invoke-WebRequest -Method Post -Uri $queryUrl -Headers $headers -Body $queryBody -ErrorAction Stop +$response = ($queryResponse | ConvertFrom-Json).Results + +``` + + +## Related topic +- [Windows Defender ATP APIs](exposed-apis-intro.md) +- [Advanced Hunting API](run-advanced-query-api.md) +- [Advanced Hunting using Python](run-advanced-query-sample-python.md) +- [Schedule Advanced Hunting](run-advanced-query-sample-ms-flow.md)