diff --git a/windows/security/threat-protection/windows-defender-atp/TOC.md b/windows/security/threat-protection/windows-defender-atp/TOC.md index f011865f79..425c6b1128 100644 --- a/windows/security/threat-protection/windows-defender-atp/TOC.md +++ b/windows/security/threat-protection/windows-defender-atp/TOC.md @@ -103,6 +103,7 @@ #### How to use APIs - Samples ##### [Schedule advanced Hunting using Microsoft Flow](run-advanced-query-windows-defender-advanced-threat-protection-sample-ms-flow.md) ##### [Advanced Hunting using PowerShell](run-advanced-query-windows-defender-advanced-threat-protection-sample-powershell.md) +##### [Advanced Hunting using Python](run-advanced-query-windows-defender-advanced-threat-protection-sample-python.md) ### [Use the Windows Defender ATP exposed APIs](exposed-apis-windows-defender-advanced-threat-protection.md) diff --git a/windows/security/threat-protection/windows-defender-atp/exposed-apis-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/exposed-apis-windows-defender-advanced-threat-protection-new.md index b687e0a4bd..3541fd8546 100644 --- a/windows/security/threat-protection/windows-defender-atp/exposed-apis-windows-defender-advanced-threat-protection-new.md +++ b/windows/security/threat-protection/windows-defender-atp/exposed-apis-windows-defender-advanced-threat-protection-new.md @@ -146,7 +146,11 @@ For more details on AAD token, refer to [AAD tutorial](https://docs.microsoft.co ### Using PowerShell -Refer to [Get token](run-advanced-query-windows-defender-advanced-threat-protection-sample-powershell.md#get-token) section in the Advanced Hunting document +Refer to [Get token using PowerShell](run-advanced-query-windows-defender-advanced-threat-protection-sample-powershell.md#get-token) + +### Using Python + +Refer to [Get token using Python](run-advanced-query-windows-defender-advanced-threat-protection-sample-python.md#get-token) ### Using Curl diff --git a/windows/security/threat-protection/windows-defender-atp/images/webapp-add-permission-2.png b/windows/security/threat-protection/windows-defender-atp/images/webapp-add-permission-2.png index 44708818ef..9c00076cfd 100644 Binary files a/windows/security/threat-protection/windows-defender-atp/images/webapp-add-permission-2.png and b/windows/security/threat-protection/windows-defender-atp/images/webapp-add-permission-2.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/webapp-create-key.png b/windows/security/threat-protection/windows-defender-atp/images/webapp-create-key.png index 2784135cc4..31e916edc5 100644 Binary files a/windows/security/threat-protection/windows-defender-atp/images/webapp-create-key.png and b/windows/security/threat-protection/windows-defender-atp/images/webapp-create-key.png differ 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 fdbaa62d91..cfca29d851 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 @@ -65,14 +65,14 @@ Run the below ``` $query = 'RegistryEvents | limit 10' # Paste your own query here -$queryServiceUri = "https://api.securitycenter.windows.com/advancedqueries/query" +$url = "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 +$webResponse = Invoke-WebRequest -Method Post -Uri $url -Headers $headers -Body $body -ErrorAction Stop $response = $webResponse | ConvertFrom-Json $results = $response.Results $schema = $response.Schema @@ -102,11 +102,12 @@ $results | ConvertTo-Csv -NoTypeInformation | Set-Content file1.csv To output the results of the query in JSON format in file file1.json​ do the below: ``` -$results | ConvertTo-Json | Set-Content "file1.json" +$results | ConvertTo-Json | Set-Content file1.json ``` ## Related topic - [Advanced Hunting API](run-advanced-query-windows-defender-advanced-threat-protection.md) +- [Advanced Hunting using Python](run-advanced-query-windows-defender-advanced-threat-protection-sample-python.md) - [Schedule Advanced Hunting](run-advanced-query-windows-defender-advanced-threat-protection-sample-ms-flow.md) - [Create your app](exposed-apis-windows-defender-advanced-threat-protection-new.md) diff --git a/windows/security/threat-protection/windows-defender-atp/run-advanced-query-windows-defender-advanced-threat-protection-sample-python.md b/windows/security/threat-protection/windows-defender-atp/run-advanced-query-windows-defender-advanced-threat-protection-sample-python.md new file mode 100644 index 0000000000..b26196cbb3 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/run-advanced-query-windows-defender-advanced-threat-protection-sample-python.md @@ -0,0 +1,139 @@ +--- +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 +--- + +# Advanced Hunting using Python + +Run advanced queries using Python. Please read about [Advanced Hunting API](run-advanced-query-windows-defender-advanced-threat-protection.md) before. + +In this section we share Python samples to retrieve a token and use it to run a query. + +>**Prerequisite**: You first need to [create an app](exposed-apis-windows-defender-advanced-threat-protection-new.md). + +## Get token + +- Run the below + +``` + +import json +import urllib.request +import urllib.parse + +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 + +url = "https://login.windows.net/%s/oauth2/token" % (tenantId) + +resourceAppIdUri = 'https://securitycenter.onmicrosoft.com/windowsatpservice' + +body = { + 'resource' : resourceAppIdUri, + 'client_id' : appId, + 'client_secret' : appSecret, + 'grant_type' : 'client_credentials' +} + +data = urllib.parse.urlencode(body).encode("utf-8") + +req = urllib.request.Request(url, data) +response = urllib.request.urlopen(req) +jsonResponse = json.loads(response.read()) +aadToken = jsonResponse["access_token"] + +``` + +where +- $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 + +``` +query = 'RegistryEvents | limit 10' # Paste your own query here + +url = "https://api.securitycenter.windows.com/advancedqueries/query" +headers = { + 'Content-Type' : 'application/json', + 'Accept' : 'application/json', + 'Authorization' : "Bearer " + aadToken +} + +data = json.dumps(query).encode("utf-8") + +req = urllib.request.Request(url, data, headers) +response = urllib.request.urlopen(req) +jsonResponse = json.loads(response.read()) +schema = jsonResponse["Schema"] +results = jsonResponse["Results"] + +``` + +- schema contains the schema of the results of your query +- results contains the results of your query + +### 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: + +``` +queryFile = open("D:\\Temp\\myQuery.txt", 'r') # Replace with the path to your file +query = queryFile.read() +queryFile.close() +``` + +## Work with query results + +You can now use the query results. + +To iterate over the results do the below: + +``` +for result in results: + print(result) # Prints the whole result + print(result["EventTime"]) # Prints only the property 'EventTime' from the result +``` + + +To output the results of the query in CSV format in file file1.csv do the below: + +``` +import csv + +outputFile = open("D:\\Temp\\file1.csv", 'w') +output = csv.writer(outputFile) +output.writerow(results[0].keys()) +for result in results: + output.writerow(result.values()) +outputFile.close() +``` + +To output the results of the query in JSON format in file file1.json​ do the below: + +``` +outputFile = open("D:\\Temp\\file1.json", 'w') +json.dump(results, outputFile) +outputFile.close() +``` + + +## Related topic +- [Advanced Hunting API](run-advanced-query-windows-defender-advanced-threat-protection.md) +- [Advanced Hunting using PowerShell](run-advanced-query-windows-defender-advanced-threat-protection-sample-powershell.md) +- [Schedule Advanced Hunting](run-advanced-query-windows-defender-advanced-threat-protection-sample-ms-flow.md) +- [Create your app](exposed-apis-windows-defender-advanced-threat-protection-new.md)