deepblue/windows-itpro-docs
1
0
Fork 0
mirror of https://github.com/MicrosoftDocs/windows-itpro-docs.git synced 2025-06-24 06:43:38 +00:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

Merge branch 'master' into lomayor-wtp

Browse Source
This commit is contained in:
lomayor
2019-08-23 14:17:04 -07:00
parent 346c95ea96 116a2e07cc
commit fe23faef76
25 changed files with 281 additions and 471 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
windows/security/threat-protection/TOC.md
View File

@ -425,15 +425,10 @@
####### [Get user related machines](microsoft-defender-atp/get-user-related-machines.md)
##### [How to use APIs - Samples]()
###### [Advanced Hunting API]()
####### [Schedule advanced Hunting using Microsoft Flow](microsoft-defender-atp/run-advanced-query-sample-ms-flow.md)
####### [Advanced Hunting using PowerShell](microsoft-defender-atp/run-advanced-query-sample-powershell.md)
####### [Advanced Hunting using Python](microsoft-defender-atp/run-advanced-query-sample-python.md)
####### [Create custom Power BI reports](microsoft-defender-atp/run-advanced-query-sample-power-bi-app-token.md)
###### [Multiple APIs]()
####### [PowerShell](microsoft-defender-atp/exposed-apis-full-sample-powershell.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)
###### [Using OData Queries](microsoft-defender-atp/exposed-apis-odata-samples.md)
#### [Windows updates (KB) info]()

81
windows/security/threat-protection/microsoft-defender-atp/api-microsoft-flow.md Normal file
View File

@ -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)

71
windows/security/threat-protection/microsoft-defender-atp/run-advanced-query-sample-power-bi-user-token.md → windows/security/threat-protection/microsoft-defender-atp/api-power-bi.md
View File

@ -1,8 +1,8 @@
---
title: Advanced Hunting API
title: Microsoft Defender ATP APIs connection to Power BI
ms.reviewer:
description: Use this API to run advanced queries
keywords: apis, supported apis, advanced hunting, query
description: Create custom reports using Power BI
keywords: apis, supported apis, Power BI, reports
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
@ -17,24 +17,17 @@ ms.collection: M365-security-compliance
ms.topic: article
---
# Create custom reports using Power BI (user authentication)
# Create custom reports using Power BI
**Applies to:**
**Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
- [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)
[!include[Prerelease information](prerelease.md)]
In this section you will learn create a Power BI report on top of Microsoft Defender ATP APIs.
Run advanced queries and show results in Microsoft Power BI. Please read about [Advanced Hunting API](run-advanced-query-api.md) before.
The first example demonstrates how to connect Power BI to Advanced Hunting API and the second example demonstrates a connection to our OData APIs (e.g. Machine Actions, Alerts, etc..)
In this section we share Power BI query sample to run a query using **user token**.
If you want to use **application token** instead please refer to [this](run-advanced-query-sample-power-bi-app-token.md) tutorial.
## Before you begin
You first need to [create an app](exposed-apis-create-app-nativeapp.md).
## Run a query
## Connect Power BI to Advanced Hunting API
- Open Microsoft Power BI
@ -46,18 +39,15 @@ You first need to [create an app](exposed-apis-create-app-nativeapp.md).
![Image of open advanced editor](images/power-bi-open-advanced-editor.png)
- Copy the below and paste it in the editor, after you update the values of Query
- Copy the below and paste it in the editor:
```
```
let
AdvancedHuntingQuery = "MiscEvents | where ActionType contains 'Anti'",
Query = "MachineInfo | where EventTime > ago(7d) | summarize EventCount=count(), LastSeen=max(EventTime) by MachineId",
HuntingUrl = "https://api.securitycenter.windows.com/api/advancedqueries",
FormattedQuery= Uri.EscapeDataString(Query),
AdvancedHuntingUrl = "https://api.securitycenter.windows.com/api/advancedqueries?key=" & FormattedQuery,
Response = Json.Document(Web.Contents(AdvancedHuntingUrl)),
Response = Json.Document(Web.Contents(HuntingUrl, [Query=[key=AdvancedHuntingQuery]])),
TypeMap = #table(
{ "Type", "PowerBiType" },
@ -88,12 +78,10 @@ You first need to [create an app](exposed-apis-create-app-nativeapp.md).
in Table
```
```
- Click **Done**
![Image of create advanced query](images/power-bi-create-advanced-query.png)
- Click **Edit Credentials**
![Image of edit credentials](images/power-bi-edit-credentials.png)
@ -108,13 +96,32 @@ You first need to [create an app](exposed-apis-create-app-nativeapp.md).
![Image of set credentials](images/power-bi-set-credentials-organizational-cont.png)
- View the results of your query
- Now the results of your query will appear as table and you can start build visualizations on top of it!
![Image of query results](images/power-bi-query-results.png)
- You can duplicate this table, rename it and edit the Advanced Hunting query inside to get any data you would like.
## Connect Power BI to OData APIs
- The only difference from the above example is the query inside the editor.
- Copy the below and paste it in the editor to pull all **Machine Actions** from your organization:
```
let
Query = "MachineActions",
Source = OData.Feed("https://api.securitycenter.windows.com/api/" & Query, null, [Implementation="2.0", MoreColumns=true])
in
Source
```
- You can do the same for **Alerts** and **Machines**.
- You also can use OData queries for queries filters, see [Using OData Queries](exposed-apis-odata-samples.md)
## Related topic
- [Create custom Power BI reports with app authentication](run-advanced-query-sample-power-bi-app-token.md)
- [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)
- [Using OData Queries](exposed-apis-odata-samples.md)

1
windows/security/threat-protection/microsoft-defender-atp/exposed-apis-full-sample-powershell.md
View File

@ -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)

BIN
windows/security/threat-protection/microsoft-defender-atp/images/api-flow-0.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 60 KiB

BIN
windows/security/threat-protection/microsoft-defender-atp/images/api-flow-1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 18 KiB

BIN
windows/security/threat-protection/microsoft-defender-atp/images/api-flow-2.PNG Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 39 KiB

BIN
windows/security/threat-protection/microsoft-defender-atp/images/api-flow-3.PNG Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 8.9 KiB

BIN
windows/security/threat-protection/microsoft-defender-atp/images/api-flow-4.PNG Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 35 KiB

BIN
windows/security/threat-protection/microsoft-defender-atp/images/api-flow-5.PNG Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 46 KiB

BIN
windows/security/threat-protection/microsoft-defender-atp/images/power-bi-query-results.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 59 KiB

13
windows/security/threat-protection/microsoft-defender-atp/oldTOC.txt
View File

@ -413,15 +413,10 @@
####### [Get user related machines](get-user-related-machines.md)
##### [How to use APIs - Samples]()
###### [Advanced Hunting API]()
####### [Schedule advanced Hunting using Microsoft Flow](run-advanced-query-sample-ms-flow.md)
####### [Advanced Hunting using PowerShell](run-advanced-query-sample-powershell.md)
####### [Advanced Hunting using Python](run-advanced-query-sample-python.md)
####### [Create custom Power BI reports](run-advanced-query-sample-power-bi-app-token.md)
###### [Multiple APIs]()
####### [PowerShell](exposed-apis-full-sample-powershell.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)
###### [Using OData Queries](exposed-apis-odata-samples.md)
#### [API for custom alerts]()

2
windows/security/threat-protection/microsoft-defender-atp/overview-secure-score.md
View File

@ -22,7 +22,7 @@ ms.topic: conceptual
- [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
>[!NOTE]
> Secure score is now part of [Threat & Vulnerability Management](next-gen-threat-and-vuln-mgt.md) as [Configuration score](configuration-score.md). The secure score page will be available for a few weeks. View the [Secure score](https://docs.microsoft.com/windows/security/threat-protection/microsoft-defender-atp/overview-secure-score) page.
> Secure score is now part of [Threat & Vulnerability Management](next-gen-threat-and-vuln-mgt.md) as [Configuration score](configuration-score.md). The secure score page will be available for a few weeks.
The Secure score dashboard expands your visibility into the overall security posture of your organization. From this dashboard, you'll be able to quickly assess the security posture of your organization, see machines that require attention, as well as recommendations for actions to further reduce the attack surface in your organization - all in one place. From there you can take action based on the recommended configuration baselines.

2
windows/security/threat-protection/microsoft-defender-atp/powerbi-reports.md
View File

@ -202,7 +202,7 @@ In general, if you know of a specific threat name, CVE, or KB, you can identify
## Related topic
- [**Beta** Create custom Power BI reports](run-advanced-query-sample-power-bi-app-token.md)
- [Create custom Power BI reports](api-power-bi.md)

1
windows/security/threat-protection/microsoft-defender-atp/run-advanced-query-api.md
View File

@ -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)

92
windows/security/threat-protection/microsoft-defender-atp/run-advanced-query-sample-ms-flow.md
View File

@ -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)

138
windows/security/threat-protection/microsoft-defender-atp/run-advanced-query-sample-power-bi-app-token.md
View File

@ -1,138 +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
---
# Create custom reports using Power BI (app authentication)
Run advanced queries and show results in Microsoft Power BI. Please read about [Advanced Hunting API](run-advanced-query-api.md) before.
In this section we share Power BI query sample to run a query using **application token**.
If you want to use **user token** instead please refer to [this](run-advanced-query-sample-power-bi-user-token.md) tutorial.
>**Prerequisite**: You first need to [create an app](exposed-apis-create-app-webapp.md).
## Run a query
- Open Microsoft Power BI
- Click **Get Data** > **Blank Query**
![Image of create blank query](images/power-bi-create-blank-query.png)
- Click **Advanced Editor**
![Image of open advanced editor](images/power-bi-open-advanced-editor.png)
- Copy the below and paste it in the editor, after you update the values of TenantId, AppId, AppSecret, Query
```
let
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
Query = "MachineInfo | where EventTime > ago(7d) | summarize EventCount=count(), LastSeen=max(EventTime) by MachineId", // Paste your own query here
ResourceAppIdUrl = "https://api.securitycenter.windows.com",
OAuthUrl = Text.Combine({"https://login.windows.net/", TenantId, "/oauth2/token"}, ""),
Resource = Text.Combine({"resource", Uri.EscapeDataString(ResourceAppIdUrl)}, "="),
ClientId = Text.Combine({"client_id", AppId}, "="),
ClientSecret = Text.Combine({"client_secret", Uri.EscapeDataString(AppSecret)}, "="),
GrantType = Text.Combine({"grant_type", "client_credentials"}, "="),
Body = Text.Combine({Resource, ClientId, ClientSecret, GrantType}, "&"),
AuthResponse= Json.Document(Web.Contents(OAuthUrl, [Content=Text.ToBinary(Body)])),
AccessToken= AuthResponse[access_token],
Bearer = Text.Combine({"Bearer", AccessToken}, " "),
AdvancedHuntingUrl = "https://api.securitycenter.windows.com/api/advancedqueries/run",
Response = Json.Document(Web.Contents(
AdvancedHuntingUrl,
[
Headers = [#"Content-Type"="application/json", #"Accept"="application/json", #"Authorization"=Bearer],
Content=Json.FromValue([#"Query"=Query])
]
)),
TypeMap = #table(
{ "Type", "PowerBiType" },
{
{ "Double", Double.Type },
{ "Int64", Int64.Type },
{ "Int32", Int32.Type },
{ "Int16", Int16.Type },
{ "UInt64", Number.Type },
{ "UInt32", Number.Type },
{ "UInt16", Number.Type },
{ "Byte", Byte.Type },
{ "Single", Single.Type },
{ "Decimal", Decimal.Type },
{ "TimeSpan", Duration.Type },
{ "DateTime", DateTimeZone.Type },
{ "String", Text.Type },
{ "Boolean", Logical.Type },
{ "SByte", Logical.Type },
{ "Guid", Text.Type }
}),
Schema = Table.FromRecords(Response[Schema]),
TypedSchema = Table.Join(Table.SelectColumns(Schema, {"Name", "Type"}), {"Type"}, TypeMap , {"Type"}),
Results = Response[Results],
Rows = Table.FromRecords(Results, Schema[Name]),
Table = Table.TransformColumnTypes(Rows, Table.ToList(TypedSchema, (c) => {c{0}, c{2}}))
in Table
```
- Click **Done**
![Image of create advanced query](images/power-bi-create-advanced-query.png)
- Click **Edit Credentials**
![Image of edit credentials](images/power-bi-edit-credentials.png)
- Select **Anonymous** and click **Connect**
![Image of set credentials](images/power-bi-set-credentials-anonymous.png)
- Repeat the previous step for the second URL
- Click **Continue**
![Image of edit data privacy](images/power-bi-edit-data-privacy.png)
- Select the privacy level you want and click **Save**
![Image of set data privacy](images/power-bi-set-data-privacy.png)
- View the results of your query
![Image of query results](images/power-bi-query-results.png)
## Related topic
- [Create custom Power BI reports with user authentication](run-advanced-query-sample-power-bi-user-token.md)
- [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)

1
windows/security/threat-protection/microsoft-defender-atp/run-advanced-query-sample-powershell.md
View File

@ -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)

3
windows/security/threat-protection/microsoft-defender-atp/run-advanced-query-sample-python.md
View File

@ -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)