Merged PR 10181: Add samples for Flow and PowerShell

devices/surface/surface-dock-updater.md

@@ -117,6 +117,12 @@ Microsoft periodically updates Surface Dock Updater. To learn more about the app
 >[!Note]
 >Each update to Surface Dock firmware is included in a new version of Surface Dock Updater. To update a Surface Dock to the latest firmware, you must use the latest version of Surface Dock Updater.
 
+### Version 2.22.139.0
+*Release Date: 26 July 2018*
+
+This version of Surface Dock Updater adds support for the following:
+t.b.d.
+
 ### Version 2.12.136.0
 *Release Date: 29 January 2018*
 

education/windows/use-set-up-school-pcs-app.md

@@ -15,7 +15,7 @@ ms.date: 07/11/2018
 
 # Use the Set up School PCs app  
 
-IT administrators and technical teachers can use the **Set up School PCs** app to quickly set up Windows 10 PCs for students. The app configures PCs with the apps and features students need, and it removes the ones they don't need. During setup, if licensed in your tenant, the app anrolls each student PC into a mobile device management (MDM) provider, such as Intune for Education. You can then manage all the settings Set up School PCs configures through the MDM.   
+IT administrators and technical teachers can use the **Set up School PCs** app to quickly set up Windows 10 PCs for students. The app configures PCs with the apps and features students need, and it removes the ones they don't need. During setup, if licensed in your tenant, the app enrolls each student PC into a mobile device management (MDM) provider, such as Intune for Education. You can then manage all the settings Set up School PCs configures through the MDM.   
 
 Set up School PCs also:  
 * Joins each student PC to your organization's Office 365 and Azure Active Directory tenant.  

mdop/mbam-v25/mbam-25-supported-configurations.md

@@ -365,7 +365,7 @@ https://www.microsoft.com/en-us/download/details.aspx?id=54967<td align="left"><
 </table>
 
 **Note**  
-In order to support SQL 2016 you must install the March 2017 Servicing Release for MDOP https://www.microsoft.com/en-us/download/details.aspx?id=54967 .  In general stay current by always using the most recent servicing update as it also includes all bugfixes and new features.
+In order to support SQL 2016 you must install the March 2017 Servicing Release for MDOP https://www.microsoft.com/en-us/download/details.aspx?id=54967  and to support SQL 2017 you must install the July 2018 Servicing Release for MDOP https://www.microsoft.com/en-us/download/details.aspx?id=57157. In general stay current by always using the most recent servicing update as it also includes all bugfixes and new features.
  
 
 ### <a href="" id="bkmk-sql-stand-alone-ramreqs"></a>SQL Server processor, RAM, and disk space requirements – Stand-alone topology

windows/client-management/mdm/vpnv2-csp.md

@@ -255,7 +255,14 @@ An optional flag to enable Always On mode. This will automatically connect the V
 
 > **Note**  Always On only works for the active profile. The first profile provisioned that can be auto triggered will automatically be set as active.
 
- 
+Preserving user Always On preference
+
+Windows has a feature to preserve a user’s AlwaysOn preference.  In the event that a user manually unchecks the “Connect    automatically” checkbox, Windows will remember this user preference for this profile name by adding the profile name to the value AutoTriggerDisabledProfilesList.  
+Should a management tool remove/add the same profile name back and set AlwaysOn to true, Windows will not check the box if the profile name exists in the below registry value in order to preserve user preference.
+Key: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\RasMan\Config
+Value: AutoTriggerDisabledProfilesList
+Type: REG_MULTI_SZ
+
 
 Valid values:
 

windows/deployment/update/waas-overview.md

@@ -70,7 +70,7 @@ To align with this new update delivery model, Windows 10 has three servicing cha
 ### Naming changes
 
 As part of the alignment with Windows 10 and Office 365 ProPlus, we are adopting common terminology to make it as easy as possible to understand the servicing process. Going forward, these are the new terms we will be using:
-* Semi-Annual Channel - We will be referreing to Current Branch (CB) as "Semi-Annual Channel (Targeted)", while Current Branch for Business (CBB) will simply be referred to as "Semi-Annual Channel". 
+* Semi-Annual Channel - We will be referring to Current Branch (CB) as "Semi-Annual Channel (Targeted)", while Current Branch for Business (CBB) will simply be referred to as "Semi-Annual Channel". 
 * Long-Term Servicing Channel -  The Long-Term Servicing Branch (LTSB) will be referred to as Long-Term Servicing Channel (LTSC).
 
 >[!IMPORTANT]

windows/security/hardware-protection/tpm/change-the-tpm-owner-password.md

@@ -45,7 +45,7 @@ To change to a new TPM owner password, in TPM.msc, click **Change Owner Password
 
 ## Use the TPM cmdlets
 
-You can manage the TPM using Windows PowerShell. For details, see [TPM Cmdlets in Windows PowerShell](http://technet.microsoft.com/library/jj603116.aspx).
+You can manage the TPM using Windows PowerShell. For details, see [TPM Cmdlets in Windows PowerShell](https://docs.microsoft.com/en-us/powershell/module/trustedplatformmodule).
 
 ## Related topics
 

windows/security/hardware-protection/tpm/trusted-platform-module-overview.md

@@ -68,7 +68,7 @@ Some things that you can check on the device are:
 -   Is SecureBoot supported and enabled?
 
 > [!NOTE]
-> The device must be running Windows 10 and it must support at least TPM 2.0.
+> The device must be running Windows 10 and it must support at least TPM 2.0 in order to utilize Device Health Attestation.
 
 ## Supported versions
 

windows/security/identity-protection/vpn/vpn-auto-trigger-profile.md

@@ -58,6 +58,15 @@ When the trigger occurs, VPN tries to connect. If an error occurs or any user in
 
 When a device has multiple profiles with Always On triggers, the user can specify the active profile in **Settings** > **Network & Internet** > **VPN** > *VPN profile* by selecting the **Let apps automatically use this VPN connection** checkbox. By default, the first MDM-configured profile is marked as **Active**. 
 
+Preserving user Always On preference
+
+Windows has a feature to preserve a user’s AlwaysOn preference.  In the event that a user manually unchecks the “Connect automatically” checkbox, Windows will remember this user preference for this profile name by adding the profile name to the value AutoTriggerDisabledProfilesList.  
+Should a management tool remove/add the same profile name back and set AlwaysOn to true, Windows will not check the box if the profile name exists in the below registry value in order to preserve user preference.
+Key: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\RasMan\Config
+Value: AutoTriggerDisabledProfilesList
+Type: REG_MULTI_SZ
+
+
 ## Trusted network detection
 
 This feature configures the VPN such that it would not get triggered if a user is on a trusted corporate network. The value of this setting is a list of DNS suffices. The VPN stack will look at the DNS suffix on the physical interface and if it matches any in the configured list and the network is private or provisioned by MDM, then VPN will not get triggered.

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)
+#### 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)
 
 
 ### [Use the Windows Defender ATP exposed APIs](exposed-apis-windows-defender-advanced-threat-protection.md)

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

@@ -160,7 +160,7 @@ Check out the [Advanced Hunting repository](https://github.com/Microsoft/Windows
 
 ## Related topic
 - [Advanced hunting reference](advanced-hunting-reference-windows-defender-advanced-threat-protection.md)
-- [Advanced hunting query language best practices](/advanced-hunting-best-practices-windows-defender-advanced-threat-protection.md)
-
+- [Advanced hunting query language best practices](advanced-hunting-best-practices-windows-defender-advanced-threat-protection.md)
+- [Programmatic Advanced Hunting](run-advanced-query-windows-defender-advanced-threat-protection.md)
 
 

windows/security/threat-protection/windows-defender-atp/exposed-apis-windows-defender-advanced-threat-protection-new.md

@@ -10,7 +10,7 @@ ms.pagetype: security
 ms.author: macapara
 author: mjcaparas
 ms.localizationpriority: medium
-ms.date: 10/23/2017
+ms.date: 30/07/2018
 ---
 
 # Use Windows Defender ATP APIs 
@@ -24,7 +24,6 @@ ms.date: 10/23/2017
 - Windows Defender Advanced Threat Protection (Windows Defender ATP)
 
 
-
 >Want to experience Windows Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/en-us/WindowsForBusiness/windows-atp?ocid=docs-wdatp-exposedapis-abovefoldlink) 
 
 Windows Defender ATP exposes much of its data and actions through a set of programmatic APIs. Those APIs will enable you to automate workflows and innovate based on Windows Defender ATP capabilities. The API access requires OAuth2.0 authentication. For more information, see [OAuth 2.0 Authorization Code Flow](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-protocols-oauth-code).
@@ -32,10 +31,9 @@ Windows Defender ATP exposes much of its data and actions through a set of progr
 In general, you’ll need to take the following steps to use the APIs:
 - Create an app
 - Get an access token
--	Use Windows Defender ATP API
+- Use the token to access Windows Defender ATP API
 
-### Before you begin
-Before using the APIs, you’ll need to create an app that you’ll use to authenticate against the graph. You’ll need to create a web app to use for the adhoc queries. 
+This page explains how to create an app, get an access token to Windows Defender ATP and validate the token includes the required permission.
 
 ## Create an app
 
@@ -99,13 +97,28 @@ Before using the APIs, you’ll need to create an app that you’ll use to authe
 	![Image of multi tenant](images/webapp-edit-multitenant.png)
 
 
+## Application consent
+
+You need your application to be approved in each tenant where you intend to use it. This is because your application interacts with WDATP application on behalf of your customer.
+
+You (or your customer if you are writing a 3rd party application) need to click the consent link and approve your application. The consent should be done with a user who has admin privileges in the active directory.
+
+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 Azure application ID
+
+
 ## Get an access token
 
 For more details on AAD token, refer to [AAD tutorial](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-protocols-oauth-client-creds)
 
 ### Using dedicated executable
 
-- Download [AadTokenGetter.zip](exe/AadTokenGetter.zip) application​
+- Download AadTokenGetter.zip application​
 - Unzip the application
 - Open 'AadTokenGetter.exe.config' file and fill the 3 required settings:
 	- tenantId
@@ -119,7 +132,7 @@ The token is displayed in the application window
 ### Using Curl 
 
 > [!NOTE]
-> The below procedure supposed Curl is already installed on your computer
+> 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
@@ -127,9 +140,6 @@ The token is displayed in the application window
 - Set TENANT_ID to the Azure tenant ID of the customer that wants to use your application to access WDATP application
 - Run the below command:
 
-> [!NOTE]
-> The below syntax is for curl in Windows. For Linux you should use $CLIENT_ID​ instead of %CLIENT_ID% (same for CLIENT_SECRET and TENANT_ID​)
-
 ```
 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​
 ```
@@ -147,20 +157,5 @@ You will get an answer of the form:
 
 ![Image of token validation](images/webapp-validate-token.png)
 
-## Application consent
-
-You need your application to be approved in each tenant where you intend to use it. This is because your application interacts with WDATP application on behalf of your customer.
-
-You (or your customer if you are writing a 3rd party application) need to click the consent link and approve your application. The consent should be done with a user who has admin privileges in the active directory.
-
-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 Azure application ID
-
-
 ## Related topics
 - [Supported Windows Defender ATP APIs](supported-apis-windows-defender-advanced-threat-protection-new.md)

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

@@ -0,0 +1,86 @@
+---
+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
+---
+
+# Schedule Advanced Hunting using Microsoft Flow 
+
+**Applies to:**
+
+- Windows Defender Advanced Threat Protection (Windows Defender ATP)
+
+Schedule advanced query.
+
+>**Prerequisite**: You first need to [create an app](exposed-apis-windows-defender-advanced-threat-protection-new.md).
+
+## Use case
+
+If you need to schedule an advanced query and use the results 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 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
+- [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)

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

@@ -0,0 +1,112 @@
+---
+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 PowerShell
+
+Run advanced queries using PowerShell. Please read about [Advanced Hunting API](run-advanced-query-windows-defender-advanced-threat-protection.md) before.
+
+In this section we share PowerShell 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).
+
+## Preparation Instructions
+
+- 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
+```
+
+>For more details, refer to [PowerShell documentation](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy)
+
+## Get token
+
+- Run the below
+
+```
+$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
+
+$resourceAppIdUri = 'https://securitycenter.onmicrosoft.com/windowsatpservice'
+$oAuthUri = "https://login.windows.net/$TenantId/oauth2/token"
+$body = [Ordered] @{
+	resource = "$resourceAppIdUri"
+	client_id = "$appId"
+	client_secret = "$appSecret"
+	grant_type = 'client_credentials'
+}
+$response = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $body -ErrorAction Stop
+$aadToken = $response.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
+
+$queryServiceUri = "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
+$response =  $webResponse | ConvertFrom-Json
+$results = $response.Results
+$schema = $response.Schema
+```
+
+- $results contains the results of your query
+- $schema contains the schema of 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:
+
+```
+$query = [IO.File]::ReadAllText("C:\myQuery.txt"); # Replace with the path to your file
+```
+
+## Work with query results
+
+You can now use the query results.
+
+To output the results of the query in CSV format in file file1.csv do the below:
+
+```
+$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"
+```
+
+
+## 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)

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

@@ -10,20 +10,32 @@ ms.pagetype: security
 ms.author: macapara
 author: mjcaparas
 ms.localizationpriority: medium
-ms.date: 12/08/2017
+ms.date: 30/07/2018
 ---
 
-# Advanced Hunting API
+# Advanced hunting API
+
+[!include[Prerelease information](prerelease.md)]
 
 **Applies to:**
 
 - 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
-Application needs 'Run advanced queries' role (See [How to select a permission](exposed-apis-windows-defender-advanced-threat-protection-new#create-an-app)).
+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)
+
+Permission type |	Permission	|	Permission display name
+:---|:---|:---
+Application |	AdvancedQuery.Read.All |	'Run advanced queries'
 
 ## HTTP request
 ```
@@ -54,6 +66,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
@@ -103,3 +121,18 @@ 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,
+	[Check the permissions](exposed-apis-windows-defender-advanced-threat-protection-new.md#validate-the-token) included in your token.
+	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 your app](exposed-apis-windows-defender-advanced-threat-protection-new.md#create-an-app)) or you did not authorized your app in the tenant (refer to [Application consent](exposed-apis-windows-defender-advanced-threat-protection-new.md#application-consent))
+
+
+## Related topic
+- [Advanced Hunting from Portal](advanced-hunting-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)

windows/security/threat-protection/windows-defender-atp/supported-apis-windows-defender-advanced-threat-protection-new.md

@@ -10,7 +10,7 @@ ms.pagetype: security
 ms.author: macapara
 author: mjcaparas
 ms.localizationpriority: medium
-ms.date: 04/24/2018
+ms.date: 30/07/2018
 ---
 
 # Supported Windows Defender ATP query APIs