Merge remote-tracking branch 'refs/remotes/origin/master' into vs-wiprs2

windows/deploy/use-upgrade-readiness-to-manage-windows-upgrades.md

@@ -41,7 +41,7 @@ As mentioned previously, the default target version in Upgrade Readiness is set
 
 The number displayed under **Computers upgraded** in the Upgrade Overview blade is the total number of computers that are already running the same or a later version of Windows compared to the target version. It also is used in the evaluation of apps and drivers: Known issues and guidance for the apps and drivers in Upgrade Readiness is based on the target operating system version.
 
-You now have the ability to change the Windows 10 version you wish to target. The available options currently are: Windows 10 version 1507, Windows 10 version 1511, and Windows version 1610.
+You now have the ability to change the Windows 10 version you wish to target. The available options currently are: Windows 10 version 1507, Windows 10 version 1511, and Windows version 1607.
 
 To change the target version setting, click on **Solutions Settings**, which appears at the top when you open you Upgrade Readiness solution:
 

windows/keep-secure/TOC.md

@@ -781,6 +781,7 @@
 ##### [Create custom threat intelligence alerts](custom-ti-api-windows-defender-advanced-threat-protection.md)
 ##### [PowerShell code examples](powershell-example-code-windows-defender-advanced-threat-protection.md)
 ##### [Python code examples](python-example-code-windows-defender-advanced-threat-protection.md)
+##### [Experiment with custom threat intelligence alerts](experiment-custom-ti-windows-defender-advanced-threat-protection.md)
 ##### [Troubleshoot custom threat intelligence issues](troubleshoot-custom-ti-windows-defender-advanced-threat-protection.md)
 #### [Check sensor state](check-sensor-status-windows-defender-advanced-threat-protection.md)
 ##### [Fix unhealthy sensors](fix-unhealhty-sensors-windows-defender-advanced-threat-protection.md)

windows/keep-secure/code/example-script.ps1

@@ -0,0 +1,60 @@
+$authUrl = 'Your Authorization URL'
+$clientId = 'Your Client ID'
+$clientSecret = 'Your Client Secret'
+
+
+Try
+{
+    $tokenPayload = @{
+        "resource" = 'https://graph.windows.net'
+        "client_id" = $clientId
+        "client_secret" = $clientSecret
+        "grant_type"='client_credentials'}
+
+    "Fetching an access token"
+    $response = Invoke-RestMethod $authUrl -Method Post -Body $tokenPayload
+    $token = $response.access_token
+    "Token fetched successfully"
+
+    $headers = @{
+        "Content-Type" = "application/json"
+        "Accept" = "application/json"
+        "Authorization" = "Bearer {0}" -f $token }
+
+    $apiBaseUrl = "https://ti.securitycenter.windows.com/V1.0/"
+
+    $alertDefinitionPayload = @{
+        "Name" = "Test Alert"
+        "Severity" = "Medium"
+        "InternalDescription" = "A test alert used to demonstrate the Windows Defender ATP TI API feature"
+        "Title" = "Test alert."
+        "UxDescription" = "This is a test alert based on a sample custom alert definition. This alert was triggered manually using a provided test command. It indicates that the Threat Intelligence API has been properly enabled."
+        "RecommendedAction" = "No recommended action for this test alert."
+        "Category" = "SuspiciousNetworkTraffic"
+        "Enabled" = "true"}
+    "Creating an Alert Definition"
+    $alertDefinition =
+        Invoke-RestMethod ("{0}AlertDefinitions" -f $apiBaseUrl) `
+            -Method Post -Headers $headers -Body ($alertDefinitionPayload | ConvertTo-Json)
+    "Alert Definition created successfully"
+    $alertDefinitionId = $alertDefinition.Id
+
+    $iocPayload = @{
+        "Type"="IpAddress"
+        "Value"="52.184.197.12"
+        "DetectionFunction"="Equals"
+        "Enabled"="true"
+        "AlertDefinition@odata.bind"="AlertDefinitions({0})" -f $alertDefinitionId }
+
+    "Creating an Indicator of Compromise"
+    $ioc =
+        Invoke-RestMethod ("{0}IndicatorsOfCompromise" -f $apiBaseUrl) `
+             -Method Post -Headers $headers -Body ($iocPayload | ConvertTo-Json)
+    "Indicator of Compromise created successfully"
+
+    "All done!"
+}
+Catch
+{
+    'Something went wrong! Got the following exception message: {0}' -f $_.Exception.Message
+}

windows/keep-secure/code/example.ps1

@@ -1,8 +1,6 @@
-$tenantId = '{Your Tenant ID}'
+$authUrl = 'Your Authorization URL'
-$clientId = '{Your Client ID}'
+$clientId = 'Your Client ID'
-$clientSecret = '{Your Client Secret}'
+$clientSecret = 'Your Client Secret'
-
-$authUrl = "https://login.windows.net/{0}/oauth2/token" -f $tenantId
 
 $tokenPayload = @{
     "resource"='https://graph.windows.net'

windows/keep-secure/code/example.py

@@ -2,11 +2,9 @@ import json
 import requests
 from pprint import pprint
 
-tenant_id="{your tenant ID}"
+auth_url="Your Authorization URL"
-client_id="{your client ID}"
+client_id="Your Client ID"
-client_secret="{your client secret}"
+client_secret="Your Client Secret"
-
-auth_url = "https://login.windows.net/{0}/oauth2/token".format(tenant_id)
 
 payload = {"resource": "https://graph.windows.net",
            "client_id": client_id,

windows/keep-secure/enable-custom-ti-windows-defender-advanced-threat-protection.md

@@ -27,6 +27,8 @@ Before you can create custom threat intelligence (TI) using REST API, you'll nee
 
 1. In the navigation pane, select **Preference Setup** > **Threat intel API**.
 
+  ![Image of threat intel API menu](images/atp-threat-intel-api.png)
+
 2. Select **Enable threat intel API**. This activates the **Azure Active Directory application** setup sections with pre-populated values.
 
 3. Copy the individual values or select **Save details to file** to download a file that contains all the values.

windows/keep-secure/experiment-custom-ti-windows-defender-advanced-threat-protection.md

@@ -0,0 +1,85 @@
+---
+title: Experiment with custom threat intelligence alerts
+description: Use this end-to-end guide to start using the Windows Defender ATP threat intelligence API.
+keywords: alert definitions, indicators of compromise, threat intelligence, custom threat intelligence, rest api, api
+search.product: eADQiWindows 10XVcnh
+ms.prod: w10
+ms.mktglfcycl: deploy
+ms.sitesec: library
+ms.pagetype: security
+author: mjcaparas
+localizationpriority: high
+---
+
+# Experiment with custom threat intelligence (TI) alerts
+
+**Applies to:**
+
+- Windows 10 Enterprise
+- Windows 10 Education
+- Windows 10 Pro
+- Windows 10 Pro Education
+- Windows Defender Advanced Threat Protection (Windows Defender ATP)
+
+<span style="color:#ED1C24;">[Some information relates to pre-released product, which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.]</span>
+
+With the Windows Defender ATP threat intelligence API, you can create custom threat intelligence alerts that can help you keep track of possible attack activities in your organization.  
+
+For more information about threat intelligence concepts, see [Understand threat intelligence concepts](threat-indicator-concepts-windows-defender-advanced-threat-protection.md).
+
+This article demonstrates an end-to-end usage of the threat intelligence API to get you started in using the threat intelligence API.
+
+You'll be guided through sample steps so you can experience how the threat intelligence API feature works. Sample steps include creating alerts definitions and indicators of compromise (IOCs), and examples of how triggered custom TI alerts look like.
+
+## Step 1: Enable the threat intelligence API and obtain authentication details
+To use the threat intelligence API feature, you'll need to enable the feature. For more information, see [Enable the custom threat intelligence application](enable-custom-ti-windows-defender-advanced-threat-protection.md).
+
+This step is required to generate security credentials that you need to use while working with the API.
+
+## Step 2: Create a sample alert definition and IOCs
+This step will guide you in creating an alert definition and an IOC for a malicious IP.
+
+1. Open a Windows PowerShell ISE.
+
+2. Copy and paste the following PowerShell script. This script will upload a sample alert definition and IOC to Windows Defender ATP which you can use to generate an alert.
+
+    NOTE:<br>
+    Make sure you replace the `authUrl`, `clientId`, and `clientSecret` values with your details which you saved in when you enabled the threat intelligence application.
+
+    [!code[ExampleScript](./code/example-script.ps1#L1-L60)]
+
+3. Run the script and verify that the operation succeeded in the results the window. Wait up to 20 minutes until the new or updated alert definition propagates to the detection engines.
+
+    ![Image of the script running](images/atp-running-script.png)
+
+    NOTE:<br>
+    If you get the exception “The remote server returned an error: (407) Proxy Authentication Required", you need to add the proxy configuration by adding the following code to the PowerShell script:
+
+    ```syntax
+    $webclient=New-Object System.Net.WebClient
+    $creds=Get-Credential
+    $webclient.Proxy.Credentials=$creds
+    ```
+
+## Step 3: Simulate a custom TI alert
+This step will guide you in simulating an event in connection to a malicious IP that will trigger the Windows Defender ATP custom TI alert.
+
+1. Open a Windows PowerShell ISE in the machine you onboarded to Windows Defender ATP.
+
+2. Type `Invoke-WebRequest 52.184.197.12` in the editor and click **Run**. This call will generate a network communication event to a Microsoft's dedicated demo server that will raise an alert based on the custom alert definition.
+
+    ![Image of editor with command to Invoke-WebRequest](images/atp-simulate-custom-ti.png)
+
+## Step 4: Explore the custom alert in the portal
+This step will guide you in exploring the custom alert in the portal.
+
+1.	Open the [Windows Defender ATP portal](http: /securitycenter.windows.com/) on a browser.
+
+2.	Log in with your Windows Defender ATP credentials.
+
+3.	The dashboard should display the custom TI alert for the victim machine resulting from the simulated attack.
+
+    ![Image of sample custom ti alert in the portal](images/atp-sample-custom-ti-alert.png)
+
+> [!NOTE]
+> It can take up to 15 minutes for the alert to appear in the portal.

windows/keep-secure/powershell-example-code-windows-defender-advanced-threat-protection.md

@@ -36,7 +36,7 @@ These code examples demonstrate the following tasks:
 ## Step 1: Obtain an Azure AD access token
 The following example demonstrates how to obtain an Azure AD access token that you can use to call methods in the custom threat intelligence API. After you obtain a token, you have 60 minutes to use this token in calls to the custom threat intelligence API before the token expires. After the token expires, you can generate a new token.
 
-Replace the *tenantid*, *clientid*, and *clientSecret* values with the ones you got from **Preferences settings** page in the portal:
+Replace the *authUrl*, *clientid*, and *clientSecret* values with the ones you got from **Preferences settings** page in the portal:
 
 [!code[CustomTIAPI](./code/example.ps1#L1-L14)]
 

windows/keep-secure/python-example-code-windows-defender-advanced-threat-protection.md

@@ -37,7 +37,7 @@ These code examples demonstrate the following tasks:
 ## Step 1: Obtain an Azure AD access token
 The following example demonstrates how to obtain an Azure AD access token that you can use to call methods in the custom threat intelligence API. After you obtain a token, you have 60 minutes to use this token in calls to the custom threat intelligence API before the token expires. After the token expires, you can generate a new token.
 
-Replace the *tenant\_id*, *client_id*, and *client_secret* values with the ones you got from **Preferences settings** page in the portal:
+Replace the *auth_url*, *client_id*, and *client_secret* values with the ones you got from **Preferences settings** page in the portal:
 
 [!code[CustomTIAPI](./code/example.py#L1-L17)]