Merge pull request #2522 from MicrosoftDocs/repo_sync_working_branch

Confirm merge from repo_sync_working_branch to master to sync with https://github.com/MicrosoftDocs/windows-itpro-docs (branch public)

windows/security/threat-protection/index.md

@@ -77,7 +77,7 @@ To further reinforce the security perimeter of your network, Microsoft Defender
 - [Behavior monitoring](/windows/security/threat-protection/windows-defender-antivirus/configure-real-time-protection-windows-defender-antivirus.md)
 - [Cloud-based protection](/windows/security/threat-protection/windows-defender-antivirus/enable-cloud-protection-windows-defender-antivirus.md)
 - [Machine learning](windows-defender-antivirus/utilize-microsoft-cloud-protection-windows-defender-antivirus.md)
-- [URL Protection](/windows/security/threat-protection/windows-defender-antivirus/configure-network-connections-windows-defender-antivirus.md)
+- [URL Protection](https://docs.microsoft.com/windows/security/threat-protection/windows-defender-antivirus/configure-network-connections-windows-defender-antivirus)
 - [Automated sandbox service](windows-defender-antivirus/configure-block-at-first-sight-windows-defender-antivirus.md)
 
 <a name="edr"></a>

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

@@ -131,10 +131,13 @@ Value: c:\path|e:\path|c:\Whitelisted.exe
 
 5. To exclude files and folders from ASR rules, select the **Exclude files and paths from Attack surface reduction rules** setting and set the option to **Enabled**. Click **Show** and enter each file or folder in the **Value name** column. Enter **0** in the **Value** column for each item.
 
+> [!WARNING]
+> Do not use quotes as they are not supported for either the **Value name** column or the **Value** column.
+
 ## PowerShell
 
->[!WARNING]
->If you manage your computers and devices with Intune, Configuration Manager, or other enterprise-level management platform, the management software will overwrite any conflicting PowerShell settings on startup.
+> [!WARNING]
+> If you manage your computers and devices with Intune, Configuration Manager, or other enterprise-level management platform, the management software will overwrite any conflicting PowerShell settings on startup.
 
 1. Type **powershell** in the Start menu, right-click **Windows PowerShell** and click **Run as administrator**.
 

windows/security/threat-protection/microsoft-defender-atp/enable-siem-integration.md

@@ -67,6 +67,8 @@ Enable security information and event management (SIEM) integration so you can p
    > [!NOTE]
    > You'll need to generate a new Refresh token every 90 days. 
 
+6. Follow the instructions for [creating an Azure AD app registration for Microsoft Defender ATP](https://docs.microsoft.com/windows/security/threat-protection/microsoft-defender-atp/exposed-apis-create-app-webapp) and assign the correct permissions to it to read alerts.
+
 You can now proceed with configuring your SIEM solution or connecting to the detections REST API through programmatic access. You'll need to use the tokens when configuring your SIEM solution to allow it to receive detections from Microsoft Defender Security Center.
 
 ## Integrate Microsoft Defender ATP with IBM QRadar 

windows/security/threat-protection/microsoft-defender-atp/evaluate-controlled-folder-access.md

@@ -58,6 +58,9 @@ Event ID | Description
  1124 | Audited controlled folder access event
  1123 | Blocked controlled folder access event
 
+> [!TIP]
+> You can configure a [Windows Event Forwarding subscription](https://docs.microsoft.com/windows/win32/wec/setting-up-a-source-initiated-subscription) to collect the logs centrally. 
+
 ## Customize protected folders and apps
 
 During your evaluation, you may wish to add to the list of protected folders, or allow certain apps to modify files.

windows/security/threat-protection/microsoft-defender-atp/minimum-requirements.md

@@ -13,7 +13,7 @@ author: mjcaparas
 ms.localizationpriority: medium
 manager: dansimp
 audience: ITPro
-ms.collection: M365-security-compliance 
+ms.collection: M365-security-compliance
 ms.topic: conceptual
 ---
 
@@ -24,12 +24,12 @@ ms.topic: conceptual
 
 There are some minimum requirements for onboarding machines to the service. Learn about the licensing, hardware and software requirements, and other configuration settings to onboard devices to the service.
 
->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-minreqs-abovefoldlink)
+> 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-minreqs-abovefoldlink).
 
 
->[!TIP]
->- Learn about the latest enhancements in Microsoft Defender ATP:[Microsoft Defender Advanced Threat Protection Tech Community](https://techcommunity.microsoft.com/t5/Windows-Defender-Advanced-Threat/ct-p/WindowsDefenderAdvanced).
->- Microsoft Defender ATP demonstrated industry-leading optics and detection capabilities in the recent MITRE evaluation. Read: [Insights from the MITRE ATT&CK-based evaluation](https://cloudblogs.microsoft.com/microsoftsecure/2018/12/03/insights-from-the-mitre-attack-based-evaluation-of-windows-defender-atp/).
+> [!TIP]
+> - Learn about the latest enhancements in Microsoft Defender ATP:[Microsoft Defender Advanced Threat Protection Tech Community](https://techcommunity.microsoft.com/t5/Windows-Defender-Advanced-Threat/ct-p/WindowsDefenderAdvanced).
+> - Microsoft Defender ATP demonstrated industry-leading optics and detection capabilities in the recent MITRE evaluation. Read: [Insights from the MITRE ATT&CK-based evaluation](https://cloudblogs.microsoft.com/microsoftsecure/2018/12/03/insights-from-the-mitre-attack-based-evaluation-of-windows-defender-atp/).
 
 ## Licensing requirements
 Microsoft Defender Advanced Threat Protection requires one of the following Microsoft Volume Licensing offers:
@@ -40,7 +40,7 @@ Microsoft Defender Advanced Threat Protection requires one of the following Micr
 - Microsoft 365 E5 Security
 - Microsoft 365 A5 (M365 A5)
 
-For detailed licensing information, see the [Product terms page](https://www.microsoft.com/en-us/licensing/product-licensing/products) and work with your account team to learn the detailed terms and conditions for the product. 
+For detailed licensing information, see the [Product terms page](https://www.microsoft.com/licensing/product-licensing/products) and work with your account team to learn the detailed terms and conditions for the product.
 
 For more information on the array of features in Windows 10 editions, see [Compare Windows 10 editions](https://www.microsoft.com/windowsforbusiness/compare).
 
@@ -53,13 +53,14 @@ For more information about licensing requirements for Microsoft Defender ATP pla
 Access to Microsoft Defender ATP is done through a browser, supporting the following browsers:
 - Microsoft Edge
 - Internet Explorer version 11
-- Google Chrome  
+- Google Chrome
 
->[!NOTE]
->While other browsers might work, the mentioned browsers are the ones supported.
+> [!NOTE]
+> While other browsers might work, the mentioned browsers are the ones supported.
 
 
 ## Hardware and software requirements
+
 ### Supported Windows versions
 - Windows 7 SP1 Enterprise
 - Windows 7 SP1 Pro
@@ -82,24 +83,26 @@ Machines on your network must be running one of these editions.
 The hardware requirements for Microsoft Defender ATP on machines is the same as those for the supported editions.
 
 > [!NOTE]
-> Machines that are running mobile versions of Windows are not supported.
+> Machines running mobile versions of Windows are not supported.
 
 
 ### Other supported operating systems
--  macOSX
--  Linux
--  Android
+- macOSX
+- Linux (currently, Microsoft Defender ATP is only available in the Public Preview Edition for Linux)
+- Android
 
->[!NOTE]
->You'll need to know the exact Linux distros, Android, and macOS versions that are compatible with Microsoft Defender ATP for the integration to work. 
+> [!NOTE]
+> You'll need to know the exact Linux distros, Android, and macOS versions that are compatible with Microsoft Defender ATP for the integration to work.
+>
+> Also note that Microsoft Defender ATP is currently only available in the Public Preview Edition for Linux.
 
 
 ### Network and data storage and configuration requirements
 When you run the onboarding wizard for the first time, you must choose where your Microsoft Defender Advanced Threat Protection-related information is stored: in the European Union, the United Kingdom, or the United States datacenter.
 
 > [!NOTE]
-> -   You cannot change your data storage location after the first-time setup.
-> -   Review the [Microsoft Defender ATP data storage and privacy](data-storage-privacy.md) for more information on where and how Microsoft stores your data.
+> - You cannot change your data storage location after the first-time setup.
+> - Review the [Microsoft Defender ATP data storage and privacy](data-storage-privacy.md) for more information on where and how Microsoft stores your data.
 
 
 ### Diagnostic data settings
@@ -131,12 +134,11 @@ By default, this service is enabled, but it's good practice to check to ensu
 If the **START_TYPE** is not set to **AUTO_START**, then you'll need to set the service to automatically start.
 
 
-
 **Use the command line to set the Windows 10 diagnostic data service to automatically start:**
 
 1.  Open an elevated command-line prompt on the endpoint:
 
-	  a. Go to **Start** and type **cmd**.
+      a. Go to **Start** and type **cmd**.
 
     b. Right-click **Command prompt** and select **Run as administrator**.
 
@@ -153,7 +155,6 @@ If the **START_TYPE** is not set to **AUTO_START**, then you'll need to set the
     ```
 
 
-
 #### Internet connectivity
 Internet connectivity on machines is required either directly or through proxy.
 
@@ -164,11 +165,8 @@ For more information on additional proxy configuration settings see, [Configure
 Before you onboard machines, the diagnostic data service must be enabled. The service is enabled by default in Windows 10.
 
 
-
-
-
 ## Windows Defender Antivirus configuration requirement
-The Microsoft Defender ATP agent depends on the ability of Windows Defender Antivirus to scan files and provide information about them. 
+The Microsoft Defender ATP agent depends on the ability of Windows Defender Antivirus to scan files and provide information about them.
 
 You must configure Security intelligence updates on the Microsoft Defender ATP machines whether Windows Defender Antivirus is the active antimalware or not. For more information, see [Manage Windows Defender Antivirus updates and apply baselines](../windows-defender-antivirus/manage-updates-baselines-windows-defender-antivirus.md).
 
@@ -188,9 +186,6 @@ If you're running Windows Defender Antivirus as the primary antimalware product
 If you're running a third-party antimalware client and use Mobile Device Management solutions or Microsoft Endpoint Configuration Manager (current branch), you'll need to ensure that the Windows Defender Antivirus ELAM driver is enabled. For more information, see [Ensure that Windows Defender Antivirus is not disabled by policy](troubleshoot-onboarding.md#ensure-that-windows-defender-antivirus-is-not-disabled-by-a-policy).
 
 
-
-
-
-## Related topic
+## Related topics
 - [Validate licensing and complete setup](licensing.md)
 - [Onboard machines](onboard-configure.md)

windows/security/threat-protection/microsoft-defender-atp/pull-alerts-using-rest-api.md

@@ -175,7 +175,7 @@ Here is an example return value:
 
 ## Code examples
 ### Get access token
-The following code example demonstrates how to obtain an access token and call the Microsoft Defender ATP API.
+The following code examples demonstrate how to obtain an access token for calling the Microsoft Defender ATP SIEM API.
 
 ```csharp
 AuthenticationContext context = new AuthenticationContext(string.Format("https://login.windows.net/{0}", tenantId));
@@ -183,19 +183,114 @@ ClientCredential clientCredentials = new ClientCredential(clientId, clientSecret
 AuthenticationResult authenticationResult = context.AcquireTokenAsync(detectionsResource, clientCredentials).GetAwaiter().GetResult();
 ```
 
-### Use token to connect to the detections endpoint
+```PowerShell
+#Get current working directory
+$scriptDir = Split-Path -Path $MyInvocation.MyCommand.Definition -Parent
 
+#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 secret here
+
+$resourceAppIdUri = 'https://graph.windows.net'
+$oAuthUri = "https://login.windows.net/$tenantId/oauth2/token"
+$authBody = [Ordered] @{
+    resource = "$resourceAppIdUri"
+    client_id = "$appId"
+    client_secret = "$appSecret"
+    grant_type = 'client_credentials'
+}
+
+#call API
+$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
+$authResponse
+Out-File -FilePath "$scriptDir\LatestSIEM-token.txt" -InputObject $authResponse.access_token
 ```
+
+```Bash
+tenantId='' ### Paste your tenant ID here
+appId='' ### Paste your Application ID here
+appSecret='' ### Paste your Application secret here
+resourceAppIdUri='https://graph.windows.net'
+oAuthUri="https://login.windows.net/$tenantId/oauth2/token"
+scriptDir=$(pwd)
+
+apiResponse=$(curl -s X POST "$oAuthUri" -d "resource=$resourceAppIdUri&client_id=$appId&client_secret=$appSecret&\
+        grant_type=client_credentials" | cut -d "{" -f2 | cut -d "}" -f1)
+IFS=","
+apiResponseArr=($apiResponse)
+IFS=":"
+tokenArr=(${apiResponseArr[6]})
+echo ${tokenArr[1]} | cut -d "\"" -f2 | cut -d "\"" -f1 >> $scriptDir/LatestSIEM-token.txt
+```
+
+### Use token to connect to the detections endpoint
+The following code examples demonstrate how to use an access token for calling the Microsoft Defender ATP SIEM API to get alerts.
+
+```csharp
 HttpClient httpClient = new HttpClient();
 httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(authenticationResult.AccessTokenType, authenticationResult.AccessToken);
 HttpResponseMessage response = httpClient.GetAsync("https://wdatp-alertexporter-eu.windows.com/api/alert").GetAwaiter().GetResult();
 string detectionsJson = response.Content.ReadAsStringAsync().Result;
 Console.WriteLine("Got detections list: {0}", detectionsJson);
-
 ```
 
+```PowerShell
+#Get current working directory
+$scriptDir = Split-Path -Path $MyInvocation.MyCommand.Definition -Parent
 
+#run the script Get-Token.ps1  - make sure you are running this script from the same folder of Get-SIEMToken.ps1
+$token = Get-Content "$scriptDir\LatestSIEM-token.txt"
 
+#Get Alert from the last xx hours 200 in this example. Make sure you have alerts in that time frame.
+$dateTime = (Get-Date).ToUniversalTime().AddHours(-200).ToString("o")
+
+#test SIEM API
+$url = 'https://wdatp-alertexporter-us.windows.com/api/alerts?limit=20&sinceTimeUtc=2020-01-01T00:00:00.000'
+
+#Set the WebRequest headers
+$headers = @{ 
+    'Content-Type' = 'application/json'
+    Accept = 'application/json'
+    Authorization = "Bearer $token" 
+}
+
+#Send the webrequest and get the results. 
+$response = Invoke-WebRequest -Method Get -Uri $url -Headers $headers -ErrorAction Stop
+$response
+Write-Host
+
+#Extract the alerts from the results.  This works for SIEM API:
+$alerts =  $response.Content | ConvertFrom-Json | ConvertTo-Json
+
+#Get string with the execution time. We concatenate that string to the output file to avoid overwrite the file
+$dateTimeForFileName = Get-Date -Format o | foreach {$_ -replace ":", "."}    
+
+#Save the result as json and as csv
+$outputJsonPath = "$scriptDir\Latest Alerts $dateTimeForFileName.json"     
+$outputCsvPath = "$scriptDir\Latest Alerts $dateTimeForFileName.csv"
+
+Out-File -FilePath $outputJsonPath -InputObject $alerts
+Get-Content -Path $outputJsonPath -Raw | ConvertFrom-Json | Select-Object -ExpandProperty value | Export-CSV $outputCsvPath -NoTypeInformation
+```
+
+```Bash
+#Get current working directory
+scriptDir=$(pwd)
+
+#get the token
+token=$(<$scriptDir/LatestSIEM-token.txt)
+
+#test the SIEM API, get alerts since 1/1/2020
+url='https://wdatp-alertexporter-us.windows.com/api/alerts?limit=20&sinceTimeUtc=2020-01-01T00:00:00.000'
+
+#send web requst to API and echo JSON content
+apiResponse=$(curl -s X GET "$url" -H "Content-Type: application/json" -H "Accept: application/json"\
+         -H "Authorization: Bearer $token" | cut -d "[" -f2 | cut -d "]" -f1)
+echo "If you see Alert info in JSON format, congratulations you accessed the MDATP SIEM API!"
+echo
+echo $apiResponse
+```
 
 ## Error codes
 The Microsoft Defender ATP REST API returns the following error codes caused by an invalid request.