From 97fde0fc12dbe83574cadbe9a518ff7f5fa5ff94 Mon Sep 17 00:00:00 2001 From: David Laufer Date: Sun, 29 Jul 2018 16:26:04 +0300 Subject: [PATCH] PowerShell page --- ...ced-threat-protection-sample-powershell.md | 79 +++++++++++++------ 1 file changed, 53 insertions(+), 26 deletions(-) diff --git a/windows/security/threat-protection/windows-defender-atp/run-advanced-query-windows-defender-advanced-threat-protection-sample-powershell.md b/windows/security/threat-protection/windows-defender-atp/run-advanced-query-windows-defender-advanced-threat-protection-sample-powershell.md index fd0ad63a0f..4a68c2a45c 100644 --- a/windows/security/threat-protection/windows-defender-atp/run-advanced-query-windows-defender-advanced-threat-protection-sample-powershell.md +++ b/windows/security/threat-protection/windows-defender-atp/run-advanced-query-windows-defender-advanced-threat-protection-sample-powershell.md @@ -17,58 +17,85 @@ ms.date: 12/08/2017 Run advanced queries using PowerShell. Please read about [Advanced Hunting API](run-advanced-query-windows-defender-advanced-threat-protection.md) before. +In this section we share PowerShell samples to retrieve a token and use it to run a query. + ## Preparation Instructions -In this section you will find a PowerShell module that retrieves a token and uses it to run a query. You can download the module and use it to run your own query. - -- ​​Download and unzip 'AdvancedHunting' PowerShell module. - 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 ``` ->Please see PowerShell documentation for full understanding - -- Run -``` -Import-Module \AdvancedHunting.psd1​ -``` -where is the folder in which you extracted the zip. e.g., Import-Module 'D:\Dev\AAD Auth\AdvancedHunting.psd1' +>For more details, refer to [PowerShell documentation](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy) ## Get token + - Run ``` -$aadToken = Get-WdatpAppToken -Tid -AppId -AppSecret +$tenantId = '00000000-0000-0000-0000-000000000000' # Paste your own tenant ID here +$appId = '00000000-0000-0000-0000-000000000000' # Paste your own app ID here +$appSecret = '00000000-0000-0000-0000-000000000000' # Paste your own app secret here + +$resourceAppIdUri = 'https://securitycenter.onmicrosoft.com/windowsatpservice' +$oAuthUri = "https://login.windows.net/$TenantId/oauth2/token" +$body = [Ordered] @{ + resource = "$resourceAppIdUri" + client_id = "$appId" + client_secret = "$appSecret" + grant_type = 'client_credentials' +} +$response = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $body -ErrorAction Stop +$aadToken = $response.access_token + ``` where -- : 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) -- : ID of your AAD app (the app must have 'Run advanced queries' permission to WDATP) -- : Secret of your AAD app +- $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 ## Run query Run the below ``` -$response = Invoke-Query -AadToken $aadToken -Query "RegistryEvents | limit 10"​ -$response.results -$response.schema -$response.results | ConvertTo-Csv -NoTypeInformation | Set-Content file1.csv -$response.results | ConvertTo-Json | Set-Content "file1.json" +$query = 'RegistryEvents | limit 10' # Paste your own query here + +$queryServiceUri = "https://api.securitycenter.windows.com/advancedqueries/query" +$headers = @{ + 'Content-Type' = 'application/json' + Accept = 'application/json' + Authorization = "Bearer $aadToken" +} +$body = ConvertTo-Json -InputObject $query +$webResponse = Invoke-WebRequest -Method Post -Uri $queryServiceUri -Headers $headers -Body $body -ErrorAction Stop +$response = $webResponse | ConvertFrom-Json +$results = $response.Results +$schema = $response.Schema ``` -- Line 2 and 3 will show you the results or the schema in the PowerShell window -- Line 4 outputs the results of the query in CSV format in file file1.csv -- Line 5 outputs the results of the query in JSON format in file file1.json​ +- $results contains the results of your query +- $schema contains the schema of the results of your query -If you want to run complex queries (or multilines queries), save your query in a file and run the below commands: ->Replace C:\myQuery.txt with the path to your file. +### Complex queries + +If you want to run complex queries (or multilines queries), save your query in a file and, instead of the first line in the above sample, run the below command: ``` -​​​​$myQuery = [IO.File]::ReadAllText("C:\myQuery.txt"); -$queryResults = Invoke-Query -AadToken $aadToken -Query $myQuery​​​ +​​​​$query = [IO.File]::ReadAllText("C:\myQuery.txt"); # Replace with the path to your file ``` +## Work with query results + +To work with the results you can, for instance, do the below + +``` +$results | ConvertTo-Csv -NoTypeInformation | Set-Content file1.csv +$results | ConvertTo-Json | Set-Content "file1.json" +``` + +- Line 1 outputs the results of the query in CSV format in file file1.csv +- Line 2 outputs the results of the query in JSON format in file file1.json​ + ## Related topic - [Advanced Hunting API](run-advanced-query-windows-defender-advanced-threat-protection.md)