diff --git a/windows/security/threat-protection/windows-defender-atp/TOC.md b/windows/security/threat-protection/windows-defender-atp/TOC.md index 10b1f2f16b..2cbcc1047c 100644 --- a/windows/security/threat-protection/windows-defender-atp/TOC.md +++ b/windows/security/threat-protection/windows-defender-atp/TOC.md @@ -100,6 +100,9 @@ ### [**Beta!** Use Windows Defender ATP APIs](exposed-apis-windows-defender-advanced-threat-protection-new.md) #### [Supported Windows Defender ATP APIs](supported-apis-windows-defender-advanced-threat-protection-new.md) ##### [Advanced Hunting](run-advanced-query-windows-defender-advanced-threat-protection.md) +#### [Examples how to use APIs] +##### [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) ### [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/images/ms-flow-choose-action.png b/windows/security/threat-protection/windows-defender-atp/images/ms-flow-choose-action.png new file mode 100644 index 0000000000..867fb4d976 Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/ms-flow-choose-action.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/ms-flow-define-action.png b/windows/security/threat-protection/windows-defender-atp/images/ms-flow-define-action.png new file mode 100644 index 0000000000..f3d0b2ba68 Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/ms-flow-define-action.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/ms-flow-e2e.png b/windows/security/threat-protection/windows-defender-atp/images/ms-flow-e2e.png new file mode 100644 index 0000000000..6017a74d89 Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/ms-flow-e2e.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/ms-flow-insert-db.png b/windows/security/threat-protection/windows-defender-atp/images/ms-flow-insert-db.png new file mode 100644 index 0000000000..6017a74d89 Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/ms-flow-insert-db.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/ms-flow-parse-json.png b/windows/security/threat-protection/windows-defender-atp/images/ms-flow-parse-json.png new file mode 100644 index 0000000000..b42c9ec193 Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/ms-flow-parse-json.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/ms-flow-read-db.png b/windows/security/threat-protection/windows-defender-atp/images/ms-flow-read-db.png new file mode 100644 index 0000000000..89e20f3a67 Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/ms-flow-read-db.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/run-advanced-query-windows-defender-advanced-threat-protection-sample-ms-flow.md b/windows/security/threat-protection/windows-defender-atp/run-advanced-query-windows-defender-advanced-threat-protection-sample-ms-flow.md new file mode 100644 index 0000000000..7ca777cbc5 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/run-advanced-query-windows-defender-advanced-threat-protection-sample-ms-flow.md @@ -0,0 +1,84 @@ +--- +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: 12/08/2017 +--- + +# Schedule Advanced Hunting using Microsoft Flow + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +Schedule advanced query. + +## Use case + +You need to schedule an advanced query and use the result for follow up actions and processing. + +You can use [Microsoft Flow](https://flow.microsoft.com/) (or Logic Apps) for it! + +## Define a flow to run query and parse results + +You will find below a very basic flow example: + +1. Define the trigger – Recurrence by time + +2. Add an action – Select HTTP + + ![Image of MsFlow choose an action](images/ms-flow-choose-action.png) + + - Set method to be POST + - Uri is https://api.securitycenter.windows.com/advancedqueries/query or one of the region specific locations + - US: https://api-us.securitycenter.windows.com/advancedqueries/query + - Europe: https://api-eu.securitycenter.windows.com/advancedqueries/query + - United Kingdom: https://api-uk.securitycenter.windows.com/advancedqueries/query + - Add the Header: Content-Type application/json + - In the body write your query surrounded by single quotation mark (') + - In the Advanced options select Authentication to be Active Directory OAuth + - Set the Tenant with proper AAD Tenant Id + - Audience is https://securitycenter.onmicrosoft.com/windowsatpservice + - Client ID is your application ID + - Credential Type should be Secret + - Secret is the application secret generated in the Azure Active directory. + + ![Image of MsFlow define action](images/ms-flow-define-action.png) + +3. You can use the "Parse JSON" action to get the schema of data – just "use sample payload to generate schema" and copy an output from of the expected result. + + ![Image of MsFlow parse json](images/ms-flow-parse-json.png) + +## Expand the flow to use the query results + +The below section shows how to use the parsed results to insert them in SQL database. + +This is an example only, you could perform on your results any other action supported by Microsoft Flow. + + - Add an 'Apply to each' action + - Select the Results json (which was an output of the last parse action) + - Add an 'Insert row' action – you will need to supply the connection details + - Select the table you want to update and define the mapping between the WD-ATP output to the SQL. Note it is possible to manipulate the data inside the flow. In the example I changed the type of the EventTime. + + ![Image of select from DB](images/ms-flow-insert-db.png) + +The output in the SQL DB is getting updates and can be used for correlation with other data sources. You can now read from your table: + + ![Image of select from DB](images/ms-flow-read-db.png) + +You can find below the full definition + + ![Image of select from DB](images/ms-flow-e2e.png) + +## 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) +- [Create your app](exposed-apis-windows-defender-advanced-threat-protection-new.md) \ No newline at end of file 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 new file mode 100644 index 0000000000..fd0ad63a0f --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/run-advanced-query-windows-defender-advanced-threat-protection-sample-powershell.md @@ -0,0 +1,76 @@ +--- +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: 12/08/2017 +--- + +# Advanced Hunting using PowerShell + +Run advanced queries using PowerShell. Please read about [Advanced Hunting API](run-advanced-query-windows-defender-advanced-threat-protection.md) before. + +## 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' + +## Get token +- Run +``` +$aadToken = Get-WdatpAppToken -Tid -AppId -AppSecret +``` +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 + +## 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" +``` + +- 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​ + +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. + +``` +​​​​$myQuery = [IO.File]::ReadAllText("C:\myQuery.txt"); +$queryResults = Invoke-Query -AadToken $aadToken -Query $myQuery​​​ +``` + + +## Related topic +- [Advanced Hunting API](run-advanced-query-windows-defender-advanced-threat-protection.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.md b/windows/security/threat-protection/windows-defender-atp/run-advanced-query-windows-defender-advanced-threat-protection.md index 9171ffb5a6..a86e132470 100644 --- a/windows/security/threat-protection/windows-defender-atp/run-advanced-query-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/run-advanced-query-windows-defender-advanced-threat-protection.md @@ -22,8 +22,14 @@ ms.date: 12/08/2017 - Windows Defender Advanced Threat Protection (Windows Defender ATP) +This API allows you to run programatically queries that you are used to run from [Windows Defender ATP Portal](https://securitycenter.windows.com/hunting) -Run advanced query. + +## Limitations +This API is a beta version only and is currently restricted +1. ​You can only run a query on data from the last 30 days +2. The results will include a maximum of 10,000 rows +3. The nu​mber of executions is limited​ (up to 15 minutes every hour and 4 hours a day) ## Permissions One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Create your app](exposed-apis-windows-defender-advanced-threat-protection-new.md#create-an-app) @@ -61,6 +67,12 @@ Request Here is an example of the request. +>[!NOTE] +>For better performance, you can use server closer to your geo location: +> - api-us.securitycenter.windows.com +> - api-eu.securitycenter.windows.com +> - api-uk.securitycenter.windows.com + ``` POST https://api.securitycenter.windows.com/advancedqueries/query Content-type: application/json @@ -110,3 +122,17 @@ Content-Type: application/json​ ``` + +## T​roubl​eshooting: + + - (403) Forbidden. + + If you get this error when calling WDATP API, your token probably does not include the necessary permission. + Please refer to section "Verify you can access WDATP app using your app" in Create an AAD app. + If the 'roles' section in the token does not include the necessary permission, either you did not add the necessary permission to your app (refer to step 6 in Create an AAD app) or you did not authorized your app in the tenant (refer to "Application consent" in Create an AAD app​) + + +## Related topic +- [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)