Merged PR 10298: Advanced Hunting API - Add samples for Python

Advanced Hunting API - Add samples for Python

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)

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
 

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)

windows/security/threat-protection/windows-defender-atp/run-advanced-query-windows-defender-advanced-threat-protection-sample-python.md

@@ -0,0 +1,142 @@
+---
+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)