Merge branch 'master' into api-update

windows/security/threat-protection/TOC.md

@@ -363,9 +363,10 @@
 ##### [Microsoft Defender ATP API license and terms](microsoft-defender-atp/api-terms-of-use.md)
 ##### [Get started with Microsoft Defender ATP APIs]()
 ###### [Access the Microsoft Defender ATP APIs](microsoft-defender-atp/apis-intro.md)
+###### [Hello World](microsoft-defender-atp/api-hello-world.md)
 ###### [Get access with application context](microsoft-defender-atp/exposed-apis-create-app-webapp.md)
 ###### [Get access with user context](microsoft-defender-atp/exposed-apis-create-app-nativeapp.md)
-###### [Hello World](microsoft-defender-atp/api-hello-world.md)
+###### [Get partner application access](microsoft-defender-atp/exposed-apis-create-app-partners.md)
 
 ##### [Investigation, response, and entities APIs]()
 ###### [Supported Microsoft Defender ATP APIs](microsoft-defender-atp/exposed-apis-list.md)

windows/security/threat-protection/microsoft-defender-atp/advanced-hunting-best-practices.md

@@ -45,7 +45,7 @@ Process IDs (PIDs) are recycled in Windows and reused for new processes. On thei
 
 The following example query finds processes that access more than 10 IP addresses over port 445 (SMB), possibly scanning for file shares.
 
-```
+```kusto
 DeviceNetworkEvents
 | where RemotePort == 445 and Timestamp > ago(12h) and InitiatingProcessId !in (0, 4)
 | summarize RemoteIPCount=dcount(RemoteIP) by DeviceName, InitiatingProcessId, InitiatingProcessCreationTime, InitiatingProcessFileName
@@ -68,7 +68,7 @@ To create more durable queries using command lines, apply the following practice
 
 The following examples show various ways to construct a query that looks for the file *net.exe* to stop the Windows Defender Firewall service:
 
-```
+```kusto
 // Non-durable query - do not use
 DeviceProcessEvents
 | where ProcessCommandLine == "net stop MpsSvc"

windows/security/threat-protection/microsoft-defender-atp/api-microsoft-flow.md

@@ -17,7 +17,7 @@ ms.collection: M365-security-compliance
 ms.topic: article
 ---
 
-# Microsoft Defender ATP Flow connector
+# Microsoft Power Automate (formerly Microsoft Flow), and Azure Functions
 
 **Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
 

windows/security/threat-protection/microsoft-defender-atp/attack-surface-reduction.md

@@ -50,7 +50,7 @@ You can query Microsoft Defender ATP data by using [Advanced hunting](advanced-h
 
 Here is an example query:
 
-```PowerShell
+```kusto
 DeviceEvents
 | where ActionType startswith 'Asr'
 ```

windows/security/threat-protection/microsoft-defender-atp/automated-investigations.md

@@ -35,6 +35,7 @@ When an alert is triggered, a security playbook goes into effect. Depending on t
 
 >[!NOTE]
 >Currently, automated investigation only supports the following OS versions:
+>- Windows Server 2019
 >- Windows 10, version 1709 (OS Build 16299.1085 with [KB4493441](https://support.microsoft.com/help/4493441/windows-10-update-kb4493441)) or later
 >- Windows 10, version 1803 (OS Build 17134.704 with [KB4493464](https://support.microsoft.com/help/4493464/windows-10-update-kb4493464)) or later
 >- Later versions of Windows 10

windows/security/threat-protection/microsoft-defender-atp/custom-detection-rules.md

@@ -40,7 +40,7 @@ There are various ways to ensure more complex queries return these columns. For
 
 The sample query below counts the number of unique machines (`DeviceId`) with antivirus detections and uses this count to find only the machines with more than five detections. To return the latest `Timestamp` and the corresponding `ReportId`, it uses the `summarize` operator with the `arg_max` function.
 
-```
+```kusto
 DeviceEvents
 | where Timestamp > ago(7d)
 | where ActionType == "AntivirusDetection"

windows/security/threat-protection/microsoft-defender-atp/exploit-protection.md

@@ -53,7 +53,7 @@ You can query Microsoft Defender ATP data by using [Advanced hunting](https://do
 
 Here is an example query:
 
-```PowerShell
+```kusto
 DeviceEvents
 | where ActionType startswith 'ExploitGuard' and ActionType !contains 'NetworkProtection'
 ```

windows/security/threat-protection/microsoft-defender-atp/exposed-apis-create-app-partners.md

@@ -0,0 +1,239 @@
+---
+title: Create an Application to access Microsoft Defender ATP without a user
+ms.reviewer: 
+description: Learn how to design a web app to get programmatic access to Microsoft Defender ATP without a user.
+keywords: apis, graph api, supported apis, actor, alerts, machine, user, domain, ip, file, 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
+---
+
+# Partner access through Microsoft Defender ATP APIs
+
+**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/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-exposedapis-abovefoldlink)
+
+This page describes how to create an AAD application to get programmatic access to Microsoft Defender ATP on behalf of your customers.
+
+Microsoft Defender ATP exposes much of its data and actions through a set of programmatic APIs. Those APIs will help you automate work flows and innovate based on Microsoft Defender ATP capabilities. The API access requires OAuth2.0 authentication. For more information, see [OAuth 2.0 Authorization Code Flow](https://docs.microsoft.com/azure/active-directory/develop/active-directory-v2-protocols-oauth-code).
+
+In general, you’ll need to take the following steps to use the APIs:
+- Create a **multi-tenant** AAD application.
+- Get authorized(consent) by your customer administrator for your application to access Microsoft Defender ATP resources it needs.
+- Get an access token using this application.
+- Use the token to access Microsoft Defender ATP API.
+
+The following steps with guide you how to create an AAD application, get an access token to Microsoft Defender ATP and validate the token.
+<br>**To become an official partner of Microsoft Defender ATP and appear in our partner page, you will provide us with your application identifier.**
+
+## Create the multi-tenant app
+
+1. Log on to your [Azure tenant](https://portal.azure.com) with user that has **Global Administrator** role.
+
+2. Navigate to **Azure Active Directory** > **App registrations** > **New registration**. 
+
+   ![Image of Microsoft Azure and navigation to application registration](images/atp-azure-new-app2.png)
+
+3. In the registration form:
+
+	- Choose a name for your application.
+
+	- Supported account types - accounts in any organizational directory.
+
+	- Redirect URI - type: Web, URI: https://portal.azure.com
+
+	![Image of Microsoft Azure partner application registration](images/atp-api-new-app-partner.png)
+
+
+4. Allow your Application to access Microsoft Defender ATP and assign it with the minimal set of permissions required to complete the integration.
+
+   - On your application page, click **API Permissions** > **Add permission** > **APIs my organization uses** > type **WindowsDefenderATP** and click on **WindowsDefenderATP**.
+
+   - **Note**: WindowsDefenderATP does not appear in the original list. You need to start writing its name in the text box to see it appear.
+
+   ![Image of API access and API selection](images/add-permission.png)
+   
+   ### Request API permissions
+
+   To determine which permission you need, please look at the **Permissions** section in the API you are interested to call. For instance:
+
+   - To [run advanced queries](run-advanced-query-api.md), select 'Run advanced queries' permission
+   
+   - To [isolate a machine](isolate-machine.md), select 'Isolate machine' permission
+
+   In the following example we will use **'Read all alerts'** permission:
+
+   Choose **Application permissions** > **Alert.Read.All** > Click on **Add permissions**
+
+   ![Image of API access and API selection](images/application-permissions.png)
+
+
+5. Click **Grant consent**
+
+	- **Note**: Every time you add permission you must click on **Grant consent** for the new permission to take effect.
+
+	![Image of Grant permissions](images/grant-consent.png)
+
+6. Add a secret to the application.
+
+	- Click **Certificates & secrets**, add description to the secret and click **Add**.
+
+    **Important**: After click Add, **copy the generated secret value**. You won't be able to retrieve after you leave!
+
+    ![Image of create app key](images/webapp-create-key2.png)
+
+7. Write down your application ID:
+
+   - On your application page, go to **Overview** and copy the following:
+
+   ![Image of created app id](images/app-id.png)
+
+8. Add the application to your customer's tenant.
+
+    You need your application to be approved in each customer tenant where you intend to use it. This is because your application interacts with Microsoft Defender ATP application on behalf of your customer.
+
+    A user with **Global Administrator** from your customer's tenant need to click the consent link and approve your application.
+
+    Consent link is of the form:
+
+    ```
+    https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=true
+    ```
+
+    Where 00000000-0000-0000-0000-000000000000 should be replaced with your Application ID
+
+	After clicking on the consent link, login with the Global Administrator of the customer's tenant and consent the application.
+
+	![Image of consent](images/app-consent-partner.png)
+
+	In addition, you will need to ask your customer for their tenant ID and save it for future use when acquiring the token.
+
+- **Done!** You have successfully registered an application! 
+- See examples below for token acquisition and validation.
+
+## Get an access token examples:
+
+**Note:** to get access token on behalf of your customer, use the customer's tenant ID on the following token acquisitions.
+
+<br>For more details on AAD token, refer to [AAD tutorial](https://docs.microsoft.com/azure/active-directory/develop/active-directory-v2-protocols-oauth-client-creds)
+
+### Using PowerShell
+
+```
+# That code gets the App Context Token and save it to a file named "Latest-token.txt" under the current directory
+# Paste below your Tenant ID, App ID and App Secret (App key).
+
+$tenantId = '' ### Paste your tenant ID here
+$appId = '' ### Paste your Application ID here
+$appSecret = '' ### Paste your Application key here
+
+$resourceAppIdUri = 'https://api.securitycenter.windows.com'
+$oAuthUri = "https://login.windows.net/$TenantId/oauth2/token"
+$authBody = [Ordered] @{
+    resource = "$resourceAppIdUri"
+    client_id = "$appId"
+    client_secret = "$appSecret"
+    grant_type = 'client_credentials'
+}
+$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
+$token = $authResponse.access_token
+Out-File -FilePath "./Latest-token.txt" -InputObject $token
+return $token
+```
+
+### Using C#:
+
+>The below code was tested with Nuget Microsoft.IdentityModel.Clients.ActiveDirectory
+
+- Create a new Console Application
+- Install Nuget [Microsoft.IdentityModel.Clients.ActiveDirectory](https://www.nuget.org/packages/Microsoft.IdentityModel.Clients.ActiveDirectory/)
+- Add the below using
+
+    ```
+    using Microsoft.IdentityModel.Clients.ActiveDirectory;
+    ```
+
+- Copy/Paste the below code in your application (do not forget to update the 3 variables: ```tenantId, appId, appSecret```)
+
+    ```
+    string tenantId = "00000000-0000-0000-0000-000000000000"; // Paste your own tenant ID here
+    string appId = "11111111-1111-1111-1111-111111111111"; // Paste your own app ID here
+    string appSecret = "22222222-2222-2222-2222-222222222222"; // Paste your own app secret here for a test, and then store it in a safe place! 
+
+    const string authority = "https://login.windows.net";
+    const string wdatpResourceId = "https://api.securitycenter.windows.com";
+
+    AuthenticationContext auth = new AuthenticationContext($"{authority}/{tenantId}/");
+    ClientCredential clientCredential = new ClientCredential(appId, appSecret);
+    AuthenticationResult authenticationResult = auth.AcquireTokenAsync(wdatpResourceId, clientCredential).GetAwaiter().GetResult();
+    string token = authenticationResult.AccessToken;
+    ```
+
+
+### Using Python
+
+Refer to [Get token using Python](run-advanced-query-sample-python.md#get-token)
+
+### Using Curl
+
+> [!NOTE]
+> The below procedure supposed Curl for Windows is already installed on your computer
+
+- Open a command window
+- Set CLIENT_ID to your Azure application ID
+- Set CLIENT_SECRET to your Azure application secret
+- Set TENANT_ID to the Azure tenant ID of the customer that wants to use your application to access Microsoft Defender ATP application
+- Run the below command:
+
+```
+curl -i -X POST -H "Content-Type:application/x-www-form-urlencoded" -d "grant_type=client_credentials" -d "client_id=%CLIENT_ID%" -d "scope=https://securitycenter.onmicrosoft.com/windowsatpservice/.default" -d "client_secret=%CLIENT_SECRET%" "https://login.microsoftonline.com/%TENANT_ID%/oauth2/v2.0/token" -k
+```
+
+You will get an answer of the form:
+
+```
+{"token_type":"Bearer","expires_in":3599,"ext_expires_in":0,"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn <truncated> aWReH7P0s0tjTBX8wGWqJUdDA"}
+```
+
+## Validate the token
+
+Sanity check to make sure you got a correct token:
+- Copy/paste into [JWT](https://jwt.ms) the token you get in the previous step in order to decode it
+- Validate you get a 'roles' claim with the desired permissions
+- In the screenshot below, you can see a decoded token acquired from an Application with multiple permissions to Microsoft Defender ATP:
+- The "tid" claim is the tenant ID the token belongs to.
+
+![Image of token validation](images/webapp-decoded-token.png)
+
+## Use the token to access Microsoft Defender ATP API
+
+- Choose the API you want to use, for more information, see [Supported Microsoft Defender ATP APIs](exposed-apis-list.md)
+- Set the Authorization header in the Http request you send to "Bearer {token}" (Bearer is the Authorization scheme)
+- The Expiration time of the token is 1 hour (you can send more then one request with the same token)
+
+- Example of sending a request to get a list of alerts **using C#** 
+    ```
+    var httpClient = new HttpClient();
+
+    var request = new HttpRequestMessage(HttpMethod.Get, "https://api.securitycenter.windows.com/api/alerts");
+
+    request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
+
+    var response = httpClient.SendAsync(request).GetAwaiter().GetResult();
+
+    // Do something useful with the response
+    ```
+
+## Related topics
+- [Supported Microsoft Defender ATP APIs](exposed-apis-list.md)
+- [Access Microsoft Defender ATP on behalf of a user](exposed-apis-create-app-nativeapp.md)

windows/security/threat-protection/microsoft-defender-atp/network-protection.md

@@ -56,7 +56,7 @@ You can query Microsoft Defender ATP data by using [Advanced hunting](https://do
 
 Here is an example query
 
-```PowerShell
+```kusto
 DeviceEvents
 | where ActionType in ('ExploitGuardNetworkProtectionAudited','ExploitGuardNetworkProtectionBlocked')
 ```

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

@@ -341,6 +341,7 @@
 ###### [Hello World](api-hello-world.md)
 ###### [Get access with application context](exposed-apis-create-app-webapp.md)
 ###### [Get access with user context](exposed-apis-create-app-nativeapp.md)
+###### [Get partner application access](microsoft-defender-atp/exposed-apis-create-app-partners.md)
 
 ##### [APIs]()
 ###### [Supported Microsoft Defender ATP APIs](exposed-apis-list.md)

windows/security/threat-protection/microsoft-defender-atp/threat-and-vuln-mgt-scenarios.md

@@ -167,7 +167,7 @@ When an exception is created for a recommendation, the recommendation is no long
 
 3. Enter the following queries:
 
-```
+```kusto
 // Search for machines with High active alerts or Critical CVE public exploit 
 DeviceTvmSoftwareInventoryVulnerabilities 
 | join kind=inner(DeviceTvmSoftwareVulnerabilitiesKB) on CveId