diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json index 0639090a11..761b93800a 100644 --- a/.openpublishing.redirection.json +++ b/.openpublishing.redirection.json @@ -14862,9 +14862,9 @@ "redirect_document_id": true }, { -"source_path": "windows/security/threat-protection/windows-defender-atp/run-advanced-query-sample-ms-flow.md", -"redirect_url": "/windows/security/threat-protection/microsoft-defender-atp/run-advanced-query-sample-ms-flow", -"redirect_document_id": true + "source_path": "windows/security/threat-protection/windows-defender-atp/api-microsoft-flow.md", + "redirect_url": "/windows/security/threat-protection/microsoft-defender-atp/api-microsoft-flow", + "redirect_document_id": true }, { "source_path": "windows/security/threat-protection/windows-defender-atp/api-power-bi.md", diff --git a/windows/security/threat-protection/TOC.md b/windows/security/threat-protection/TOC.md index 84208d8683..a41132770f 100644 --- a/windows/security/threat-protection/TOC.md +++ b/windows/security/threat-protection/TOC.md @@ -418,7 +418,7 @@ ####### [Get user related machines](microsoft-defender-atp/get-user-related-machines.md) ##### [How to use APIs - Samples]() -###### [Microsoft Flow](microsoft-defender-atp/run-advanced-query-sample-ms-flow.md) +###### [Microsoft Flow](microsoft-defender-atp/api-microsoft-flow.md) ###### [Power BI](microsoft-defender-atp/api-power-bi.md) ###### [Advanced Hunting using Python](microsoft-defender-atp/run-advanced-query-sample-python.md) ###### [Advanced Hunting using PowerShell](microsoft-defender-atp/run-advanced-query-sample-powershell.md) diff --git a/windows/security/threat-protection/microsoft-defender-atp/api-microsoft-flow.md b/windows/security/threat-protection/microsoft-defender-atp/api-microsoft-flow.md new file mode 100644 index 0000000000..4af26a7805 --- /dev/null +++ b/windows/security/threat-protection/microsoft-defender-atp/api-microsoft-flow.md @@ -0,0 +1,81 @@ +--- +title: Microsoft Defender ATP Flow connector +ms.reviewer: +description: Microsoft Defender ATP Flow connector +keywords: flow, supported apis, api, Microsoft flow, query, automation +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +manager: dansimp +audience: ITPro +ms.collection: M365-security-compliance +ms.topic: article +--- + +# Microsoft Defender ATP Flow connector + +**Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559) + +- Want to experience Microsoft Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/WindowsForBusiness/windows-atp?ocid=docs-wdatp-exposedapis-abovefoldlink) + +Automating security procedures is a standard requirement for every modern Security Operations Center. The lack of professional Cyber defenders, forces SOC to work in the most efficient way and automation is a must. MS flow supports different connectors that were built exactly for that. You can build an end-to-end procedure automation within few minutes. + +Microsoft Defender API has an official Flow Connector with a lot of capabilities: + +![Image of edit credentials](images/api-flow-0.png) + +## Usage example + +The following example demonstrates how you can create a Flow that will be triggered any time a new Alert occurs on your tenant. + +- Login to [Microsoft Flow](https://flow.microsoft.com) + +- Go to: My flows > New > Automated + +![Image of edit credentials](images/api-flow-1.png) + +- Choose a name for your Flow, Search for **Microsoft Defender ATP Triggers** as the trigger and choose the new Alerts trigger. + +![Image of edit credentials](images/api-flow-2.png) + +- Now you have a Flow that is triggered every time a new Alert occurs. + +![Image of edit credentials](images/api-flow-3.png) + +All you need to do now, is to choose your next steps. +Lets, for example, Isolate the machine if the Severity of the Alert is **High** and mail about it. +The Alert trigger gives us only the Alert ID and the Machine ID. We can use the Connector to expand these entities. + +### Get the Alert entity using the connector + +- Choose Microsoft Defender ATP for new step. + +- Choose Alerts - Get single alert API. + +- Set the Alert Id from the last step as Input. + +![Image of edit credentials](images/api-flow-4.png) + +### Isolate the machine if the Alert's severity is High + +- Add **Condition** as a new step . + +- Check if Alert severity equals to **High**. + +- If yes, add Microsoft Defender ATP - Isolate machine action with the Machine Id and a comment. + +![Image of edit credentials](images/api-flow-5.png) + +Now you can add a new step for mailing about the Alert and the Isolation. +There are multiple Email connectors that are very easy to use, e.g. Outlook, GMail, etc.. +Save your flow and that's all. + +- You can also create **scheduled** flow that will run Advanced Hunting queries and much more! + +## Related topic +- [Microsoft Defender ATP APIs](apis-intro.md) diff --git a/windows/security/threat-protection/microsoft-defender-atp/api-power-bi.md b/windows/security/threat-protection/microsoft-defender-atp/api-power-bi.md index e8e0a98c12..e7ed0a1212 100644 --- a/windows/security/threat-protection/microsoft-defender-atp/api-power-bi.md +++ b/windows/security/threat-protection/microsoft-defender-atp/api-power-bi.md @@ -1,5 +1,5 @@ --- -title: Power BI +title: Microsoft Defender ATP APIs connection to Power BI ms.reviewer: description: Create custom reports using Power BI keywords: apis, supported apis, Power BI, reports @@ -109,7 +109,7 @@ The first example demonstrates how to connect Power BI to Advanced Hunting API a ``` let - Query = "MachineACtions", + Query = "MachineActions", Source = OData.Feed("https://api.securitycenter.windows.com/api/" & Query, null, [Implementation="2.0", MoreColumns=true]) in diff --git a/windows/security/threat-protection/microsoft-defender-atp/exposed-apis-full-sample-powershell.md b/windows/security/threat-protection/microsoft-defender-atp/exposed-apis-full-sample-powershell.md index 31fa70aa03..b90c36d11c 100644 --- a/windows/security/threat-protection/microsoft-defender-atp/exposed-apis-full-sample-powershell.md +++ b/windows/security/threat-protection/microsoft-defender-atp/exposed-apis-full-sample-powershell.md @@ -117,4 +117,3 @@ $response - [Microsoft Defender ATP APIs](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) diff --git a/windows/security/threat-protection/microsoft-defender-atp/images/api-flow-0.png b/windows/security/threat-protection/microsoft-defender-atp/images/api-flow-0.png new file mode 100644 index 0000000000..7cbc10748b Binary files /dev/null and b/windows/security/threat-protection/microsoft-defender-atp/images/api-flow-0.png differ diff --git a/windows/security/threat-protection/microsoft-defender-atp/images/api-flow-1.png b/windows/security/threat-protection/microsoft-defender-atp/images/api-flow-1.png new file mode 100644 index 0000000000..07d00ddf20 Binary files /dev/null and b/windows/security/threat-protection/microsoft-defender-atp/images/api-flow-1.png differ diff --git a/windows/security/threat-protection/microsoft-defender-atp/images/api-flow-2.PNG b/windows/security/threat-protection/microsoft-defender-atp/images/api-flow-2.PNG new file mode 100644 index 0000000000..3afdf8262b Binary files /dev/null and b/windows/security/threat-protection/microsoft-defender-atp/images/api-flow-2.PNG differ diff --git a/windows/security/threat-protection/microsoft-defender-atp/images/api-flow-3.PNG b/windows/security/threat-protection/microsoft-defender-atp/images/api-flow-3.PNG new file mode 100644 index 0000000000..1db4fe594a Binary files /dev/null and b/windows/security/threat-protection/microsoft-defender-atp/images/api-flow-3.PNG differ diff --git a/windows/security/threat-protection/microsoft-defender-atp/images/api-flow-4.PNG b/windows/security/threat-protection/microsoft-defender-atp/images/api-flow-4.PNG new file mode 100644 index 0000000000..857188379d Binary files /dev/null and b/windows/security/threat-protection/microsoft-defender-atp/images/api-flow-4.PNG differ diff --git a/windows/security/threat-protection/microsoft-defender-atp/images/api-flow-5.PNG b/windows/security/threat-protection/microsoft-defender-atp/images/api-flow-5.PNG new file mode 100644 index 0000000000..9c85162428 Binary files /dev/null and b/windows/security/threat-protection/microsoft-defender-atp/images/api-flow-5.PNG differ diff --git a/windows/security/threat-protection/microsoft-defender-atp/oldTOC.txt b/windows/security/threat-protection/microsoft-defender-atp/oldTOC.txt index 6a33e88ccf..422ba4da32 100644 --- a/windows/security/threat-protection/microsoft-defender-atp/oldTOC.txt +++ b/windows/security/threat-protection/microsoft-defender-atp/oldTOC.txt @@ -413,7 +413,7 @@ ####### [Get user related machines](get-user-related-machines.md) ##### [How to use APIs - Samples]() -###### [Microsoft Flow](run-advanced-query-sample-ms-flow.md) +###### [Microsoft Flow](api-microsoft-flow.md) ###### [Power BI](api-power-bi.md) ###### [Advanced Hunting using Python](run-advanced-query-sample-python.md) ###### [Advanced Hunting using PowerShell](run-advanced-query-sample-powershell.md) diff --git a/windows/security/threat-protection/microsoft-defender-atp/run-advanced-query-api.md b/windows/security/threat-protection/microsoft-defender-atp/run-advanced-query-api.md index cffc0ad85b..457a33f85a 100644 --- a/windows/security/threat-protection/microsoft-defender-atp/run-advanced-query-api.md +++ b/windows/security/threat-protection/microsoft-defender-atp/run-advanced-query-api.md @@ -147,4 +147,3 @@ If the 'roles' section in the token does not include the necessary permission: - [Microsoft Defender ATP APIs](apis-intro.md) - [Advanced Hunting from Portal](advanced-hunting.md) - [Advanced Hunting using PowerShell](run-advanced-query-sample-powershell.md) -- [Schedule Advanced Hunting](run-advanced-query-sample-ms-flow.md) diff --git a/windows/security/threat-protection/microsoft-defender-atp/run-advanced-query-sample-ms-flow.md b/windows/security/threat-protection/microsoft-defender-atp/run-advanced-query-sample-ms-flow.md deleted file mode 100644 index 12a021ec3d..0000000000 --- a/windows/security/threat-protection/microsoft-defender-atp/run-advanced-query-sample-ms-flow.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: Advanced Hunting API -ms.reviewer: -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 -manager: dansimp -audience: ITPro -ms.collection: M365-security-compliance -ms.topic: article ---- - -# Schedule Advanced Hunting using Microsoft Flow -**Applies to:** -- Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP) - -[!include[Prerelease information](prerelease.md)] - -Schedule advanced query. - -## Before you begin -You first need to [create an app](apis-intro.md). - -## Use case - -A common scenario is scheduling an advanced query and using the results for follow up actions and processing. -In this section we share sample for this purpose using [Microsoft Flow](https://flow.microsoft.com/) (or [Logic Apps](https://azure.microsoft.com/services/logic-apps/)). - -## Define a flow to run query and parse results - -Use the following basic flow as an 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/api/advancedqueries/run or one of the region specific locations - - US: https://api-us.securitycenter.windows.com/api/advancedqueries/run - - Europe: https://api-eu.securitycenter.windows.com/api/advancedqueries/run - - United Kingdom: https://api-uk.securitycenter.windows.com/api/advancedqueries/run - - 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://api.securitycenter.windows.com - - 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 following section shows how to use the parsed results to insert them in SQL database. - -This is an example only, you can use other actions 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 insert into 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) - -## Full flow definition - -You can find below the full definition - -![Image of E2E flow](images/ms-flow-e2e.png) - -## Related topic -- [Microsoft Defender ATP APIs](apis-intro.md) -- [Advanced Hunting API](run-advanced-query-api.md) -- [Advanced Hunting using PowerShell](run-advanced-query-sample-powershell.md) diff --git a/windows/security/threat-protection/microsoft-defender-atp/run-advanced-query-sample-powershell.md b/windows/security/threat-protection/microsoft-defender-atp/run-advanced-query-sample-powershell.md index a5154e0ab4..a5c71022b4 100644 --- a/windows/security/threat-protection/microsoft-defender-atp/run-advanced-query-sample-powershell.md +++ b/windows/security/threat-protection/microsoft-defender-atp/run-advanced-query-sample-powershell.md @@ -117,4 +117,3 @@ $results | ConvertTo-Json | Set-Content file1.json - [Microsoft Defender ATP APIs](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) diff --git a/windows/security/threat-protection/microsoft-defender-atp/run-advanced-query-sample-python.md b/windows/security/threat-protection/microsoft-defender-atp/run-advanced-query-sample-python.md index 95fe03d4b0..69056ed0d0 100644 --- a/windows/security/threat-protection/microsoft-defender-atp/run-advanced-query-sample-python.md +++ b/windows/security/threat-protection/microsoft-defender-atp/run-advanced-query-sample-python.md @@ -146,5 +146,4 @@ outputFile.close() ## Related topic - [Microsoft Defender ATP APIs](apis-intro.md) - [Advanced Hunting API](run-advanced-query-api.md) -- [Advanced Hunting using PowerShell](run-advanced-query-sample-powershell.md) -- [Schedule Advanced Hunting](run-advanced-query-sample-ms-flow.md) +- [Advanced Hunting using PowerShell](run-advanced-query-sample-powershell.md) \ No newline at end of file