Merge branch 'main' into WI440239-mda-dynamic-threat-detection-model

Author: DeCohen

ATADocs/ata-capacity-planning.md

@@ -4,7 +4,7 @@
 title: Planning your Advanced Threat Analytics deployment
 description: Helps you plan your deployment and decide how many ATA servers will be needed to support your network
 ms.date: 01/10/2023
-ms.topic: conceptual
+ms.topic: concept-article
 ms.service: advanced-threat-analytics
 ms.assetid: 1b5b24ff-0df8-4660-b4f8-64d68cc72f65
 

ATADocs/ata-threats.md

@@ -4,7 +4,7 @@
 title: What threats does Advanced Threat Analytics detect?
 description: Lists the threats that Advanced Threat Analytics detects 
 ms.date: 01/10/2023
-ms.topic: conceptual
+ms.topic: concept-article
 ms.service: advanced-threat-analytics
 ms.assetid: 283e7b4e-996a-4491-b7f6-ff06e73790d2
 

ATADocs/monitoring-alerts.md

@@ -4,7 +4,7 @@
 title: Understanding ATA health alerts
 description: Describes all the health alerts for each component, listing the cause and the steps needed to resolve the problem
 ms.date: 01/10/2023
-ms.topic: conceptual
+ms.topic: concept-article
 ms.collection: M365-security-compliance
 ms.service: advanced-threat-analytics
 ms.assetid: b04fb8a4-b366-4b55-9d4c-6f054fa58a90

ATADocs/troubleshoot-audit.md

@@ -4,7 +4,7 @@
 title: Working with ATA audit logs
 description: This article describes how to work with ATA audit logs in the Windows Event Log.
 ms.date: 01/10/2023
-ms.topic: conceptual
+ms.topic: concept-article
 ms.service: advanced-threat-analytics
 ms.assetid: 1d186a96-ef70-4787-aa64-c03d1db94ce0
 

ATPDocs/deploy/activate-capabilities.md

@@ -1,5 +1,5 @@
 ---
-title: Activate Microsoft Defender for Identity capabilities directly on a domain controller 
+title: Activate Microsoft Defender for Identity capabilities directly on a domain controller (Preview)
 description: Learn about the Microsoft Defender for Identity capabilities on domain controllers and how to activate them.
 ms.date: 08/13/2024
 ms.topic: how-to
@@ -14,7 +14,7 @@ This article describes how to activate and test Microsoft Defender for Identity
 > The capabilities described in this article are currently available as Preview features. Preview features are features that aren't complete, but are made available on a "preview" basis so customers can get early access and provide feedback.
 > 
 > Preview features are still in development, have limited or restricted functionality and may be available only in selected geographic areas.
-> For more information, see the [Microsoft Defender XDR preview features](/defender-xdr/preview)
+> For more information, see the [Microsoft Defender XDR preview features](/defender-xdr/preview).
 
 > [!IMPORTANT]
 > The new Defender for Identity sensor (version 3.x) is recommended for customers looking to deploy core identity protections to new domain controllers running Windows Server 2019 or newer. For all other identity infrastructure, or for customers looking to deploy the most robust identity protections available from Microsoft Defender for Identity today, we recommend deploying the classic sensor [here](quick-installation-guide.md).
@@ -90,8 +90,8 @@ Activate the Defender for Identity from the [Microsoft Defender portal](https://
    [![Screenshot that shows how to activate the new sensor.](media/activate-capabilities/1.jpg)](media/activate-capabilities/1.jpg#lightbox)
 
 
-> [!NOTE]
-> You can choose to activate eligible domain controllers either automatically, where Defender for Identity activates them as soon as they're discovered, or manually, where you select specific domain controllers from the list of eligible servers.
+   > [!NOTE]
+   > You can choose to activate eligible domain controllers either automatically, where Defender for Identity activates them as soon as they're discovered, or manually, where you select specific domain controllers from the list of eligible servers.
 
 1. When the activation is complete, a green success banner shows. In the banner, select **Click here to see the onboarded servers** to jump to the **Settings > Identities > Sensors** page, where you can check your sensor health.  
 
@@ -207,9 +207,9 @@ We recommend simulating risky behavior in a test environment to trigger supporte
     Get-ADObject -Identity ((Get-ADDomain).distinguishedname) -Properties ms-DS-MachineAccountQuota
     ```
 
-1. In Microsoft Secure Score, select **Recommended Actions** to check for a new **Resolve unsecure domain configurations** recommendation. You might want to filter recommendations by the **Defender for Identity** product.
+1. In the Microsoft Secure Score, select **Recommended Actions** to check for a new **Resolve unsecure domain configurations** recommendation. You might want to filter recommendations by the **Defender for Identity** product.
 
-For more information, see [Microsoft Defender for Identity's security posture assessments](../security-assessment.md)
+For more information, see [Microsoft Defender for Identity's security posture assessments](../security-assessment.md).
 
 ### Test alert functionality
 
@@ -253,7 +253,7 @@ Deactivating Defender for Identity capabilities from your domain controller does
 ### Offboard Defender for Identity capabilities on your domain controller 
 Download the Defender for Identity offboarding package from the [Microsoft Defender portal](https://security.microsoft.com).
 
-1. Navigate to **Settings** > **Identities** > **Activation**
+1. Navigate to **Settings** > **Identities** > **Activation**.
 
 1. Select Download offboarding package and save the file in a location you can access from your domain controller.  
 ![Screenshot that shows how to offboard the new sensor.](media/activate-capabilities/screenshot-that-shows-how-to-offboard-the-new-sensor.png)

CloudAppSecurityDocs/api-authentication-application.md

@@ -28,37 +28,43 @@ This article explains how to create a Microsoft Entra application, get an access
 1. To enable your app to access Defender for Cloud Apps and assign it **'Read all alerts'** permission, on your application page, select **API Permissions** > **Add permission** > **APIs my organization uses** >, type **Microsoft Cloud App Security**, and then select **Microsoft Cloud App Security**.
 
    > [!NOTE]
-   > *Microsoft Cloud App Security* does not appear in the original list. Start writing its name in the text box to see it appear. Make sure to type this name, even though the product is now called Defender for Cloud Apps.
+   > *Microsoft Cloud App Security* doesn't appear in the original list. Start writing its name in the text box to see it appear. Make sure to type this name, even though the product is now called Defender for Cloud Apps.
 
-   ![Screenshot of adding permission.](media/add-permission.png)
 
-   - Select **Application permissions** > **Investigation.Read**, and then select **Add permissions**.
+   :::image type="content" source="media/api-authentication-application/add-app-permissions.png" alt-text="Screenshot showing how to configure API permissions for your application." lightbox="media/api-authentication-application/add-app-permissions.png":::
 
-        :::image type="content" source="media/application-permissions.png" alt-text="Screenshot of adding app permission." lightbox="media/application-permissions.png":::
 
-     You need to select the relevant permissions. **Investigation.Read** is only an example. For other permission scopes, see [Supported permission scopes](#supported-permission-scopes)
+1. Select **Application permissions** > **Investigation.Read**, and then select **Add permissions**. 
 
-     - To determine which permission you need, look at the **Permissions** section in the API you're interested to call.
+    :::image type="content" source="media/api-authentication-application/request-permissions.png" alt-text="Screenshot that shows which API permissions to request for your application." lightbox="media/api-authentication-application/request-permissions.png":::
+
+1. You need to select the relevant permissions. **Investigation.Read** is only an example. For other permission scopes, see [Supported permission scopes](#supported-permission-scopes)
+
+1. To determine which permission you need, look at the **Permissions** section in the API you're interested to call.
 
 1. Select **Grant admin consent**.
 
      > [!NOTE]
      > Every time you add a permission, you must select **Grant admin consent** for the new permission to take effect.
 
-    ![Screenshot of granting admin permissions.](media/grant-consent.png)
 
-1. To add a secret to the application, select **Certificates & secrets**, select **New client secret**, add a description to the secret, and then select **Add**.
+    :::image type="content" source="media/api-authentication-application/grant-consent.png" alt-text="Screenshot that shows the option to grant admin consent." lightbox="media/api-authentication-application/grant-consent.png":::
+ 
+
+1. To add a secret to the application, select **Certificates & secrets**, select **New client secret**. Add a description to the secret, and then select **Add**.
 
     > [!NOTE]
     > After you select **Add**, select **copy the generated secret value**. You won't be able to retrieve this value after you leave.
 
-    ![Screenshot of creating an app key.](media/webapp-create-key2.png)
+    :::image type="content" source="media/api-authentication-application/webapp-create-key2.png" alt-text="Screenshot that shows how to create an app key." lightbox="media/api-authentication-application/webapp-create-key2.png":::
+
 
 1. Write down your application ID and your tenant ID. On your application page, go to **Overview** and copy the **Application (client) ID** and the **Directory (tenant) ID**.
 
-   ![Screenshot of the created app ID.](media/app-and-tenant-ids.png)
+    :::image type="content" source="media/api-authentication-application/app-and-tenant-ids.png" alt-text="Screenshot that shows the created app ID." lightbox="media/api-authentication-application/app-and-tenant-ids.png":::
 
-1. **For Microsoft Defender for Cloud Apps Partners only**. Set your app to be multitenanted (available in all tenants after consent). This is **required** for third-party apps (for example, if you create an app that is intended to run in multiple customers' tenant). This is **not required** if you create a service that you want to run in your tenant only (for example, if you create an application for your own usage that will only interact with your own data). To set your app to be multitenanted:
+
+1. **For Microsoft Defender for Cloud Apps Partners only**. Set your app to be multitenant (available in all tenants after consent). This is **required** for third-party apps (for example, if you create an app that is intended to run in multiple customers' tenant). This is **not required** if you create a service that you want to run in your tenant only (for example, if you create an application for your own usage that will only interact with your own data). To set your app to be multitenant:
 
     - Go to **Authentication**, and add `https://portal.azure.com` as the **Redirect URI**.
 
@@ -161,45 +167,46 @@ See [Microsoft Authentication Library (MSAL) for Python](https://github.com/Azur
 1. Set TENANT_ID to the Azure tenant ID of the customer that wants to use your app to access Defender for Cloud Apps.
 1. Run the following command:
 
-```curl
-curl -i -X POST -H "Content-Type:application/x-www-form-urlencoded" -d "grant_type=client_credentials" -d "client_id=%CLIENT_ID%" -d "scope=05a65629-4c1b-48c1-a78b-804c4abdd4af/.default" -d "client_secret=%CLIENT_SECRET%" "https://login.microsoftonline.com/%TENANT_ID%/oauth2/v2.0/token" -k
-```
+   ```curl
+   curl -i -X POST -H "Content-Type:application/x-www-form-urlencoded" -d "grant_type=client_credentials" -d "client_id=%CLIENT_ID%" -d "scope=05a65629-4c1b-48c1-a78b-804c4abdd4af/.default" -d "client_secret=%CLIENT_SECRET%" "https://login.microsoftonline.com/%TENANT_ID%/oauth2/v2.0/token" -k
+   ```
 
-You get an answer in the following form:
+   You get an answer in the following form:
 
-```output
-{"token_type":"Bearer","expires_in":3599,"ext_expires_in":0,"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn <truncated> aWReH7P0s0tjTBX8wGWqJUdDA"}
-```
+   ```output
+   {"token_type":"Bearer","expires_in":3599,"ext_expires_in":0,"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn <truncated> aWReH7P0s0tjTBX8wGWqJUdDA"}
+   ```
 
 ## Validate the token
 
 Ensure that you got the correct token:
 
 1. Copy and paste the token you got in the previous step into [JWT](https://jwt.ms) in order to decode it.
-1. Validate that you get a 'roles' claim with the desired permissions
+1. Validate that you get a 'roles' claim with the desired permissions.
 1. In the following image, you can see a decoded token acquired from an app with permissions to all Microsoft Defender for Cloud Apps roles:
 
-![Screenshot of token validation.](media/webapp-decoded-token.png)
+   :::image type="content" source="media/api-authentication-application/webapp-decoded-token.png" alt-text="Screenshot that shows the decoded token.":::
+
 
 ## Use the token to access Microsoft Defender for Cloud Apps API
 
 1. Choose the API you want to use. For more information, see [Defender for Cloud Apps APIs](api-introduction.md).
 1. Set the authorization header in the http request you send to "Bearer {token}" (Bearer is the authorization scheme).
 1. The expiration time of the token is one hour. You can send more than one request with the same token.
 
-The following is an example of sending a request to get a list of alerts **using C#**:
-
-```C#
-    var httpClient = new HttpClient();
-
-    var request = new HttpRequestMessage(HttpMethod.Get, "https://portal.cloudappsecurity.com/cas/api/v1/alerts/");
-
-    request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
-
-    var response = httpClient.SendAsync(request).GetAwaiter().GetResult();
-
-    // Do something useful with the response
-```
+   The following is an example of sending a request to get a list of alerts **using C#**:
+
+   ```C#
+       var httpClient = new HttpClient();
+   
+       var request = new HttpRequestMessage(HttpMethod.Get, "https://portal.cloudappsecurity.com/cas/api/v1/alerts/");
+   
+       request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
+   
+       var response = httpClient.SendAsync(request).GetAwaiter().GetResult();
+   
+       // Do something useful with the response
+   ```
 
 ## See also
 

CloudAppSecurityDocs/api-authentication-user.md

@@ -25,8 +25,8 @@ In general, you need to take the following steps to use the APIs:
 This page explains how to create a Microsoft Entra application, get an access token to Microsoft Defender for Cloud Apps and validate the token.
 
 >[!NOTE]
-> When accessing Microsoft Defender for Cloud Apps API on behalf of a user, you will need the correct Application permission and user permission.
-> If you are not familiar with user permissions on Microsoft Defender for Cloud Apps, see [Manage admin access](manage-admins.md).
+> When accessing Microsoft Defender for Cloud Apps API on behalf of a user, you'll need the correct Application permission and user permission.
+> If you aren't familiar with user permissions on Microsoft Defender for Cloud Apps, see [Manage admin access](manage-admins.md).
 
 >[!TIP]
 > If you have the permission to perform an action in the portal, you have the permission to perform the action in the API.
@@ -57,31 +57,37 @@ This page explains how to create a Microsoft Entra application, get an access to
 
 1. Allow your Application to access Microsoft Defender for Cloud Apps and assign it 'Read alerts' permission:
 
-    - On your application page, select **API Permissions** > **Add permission** > **APIs my organization uses** > type *Microsoft Cloud App Security* and then select **Microsoft Cloud App Security**.
+1. On your application page, select **API Permissions** > **Add permission** > **APIs my organization uses** > type *Microsoft Cloud App Security* and then select **Microsoft Cloud App Security**.
 
-    - **Note**: *Microsoft Cloud App Security* doesn't appear in the original list. Start writing its name in the text box to see it appear. Make sure to type this name, even though the product is now called Defender for Cloud Apps.
+    > [!NOTE]
+    > *Microsoft Cloud App Security* doesn't appear in the original list. Start writing its name in the text box to see it appear. Make sure to type this name, even though the product is now called Defender for Cloud Apps.
 
-      ![Screenshot of adding permissions.](media/add-permission.png)
+    :::image type="content" source="media/add-permission.png" alt-text="Screenshot that shows how to add permissions.":::
 
-    - Choose **Delegated permissions** > **Investigation.Read** > select **Add permissions**
+1. Choose **Delegated permissions** > **Investigation.Read** > select **Add permissions**
 
-      ![Screenshot of adding application permissions.](media/application-permissions-public-client.png)
+    :::image type="content" source="media/application-permissions-public-client.png" alt-text="Screenshot showing how to add application permissions.":::
 
-    - **Important note**: Select the relevant permissions. **Investigation.Read** is only an example. For other permission scopes, see [Supported permission scopes](#supported-permission-scopes)
 
-      - To determine which permission you need, view the **Permissions** section in the API you're interested to call.
+    > [!NOTE]
+    > Select the relevant permissions. **Investigation.Read** is only an example. For other permission scopes, see [Supported permission scopes](#supported-permission-scopes)
 
-    - Select **Grant admin consent**
+1. To determine which permission you need, view the **Permissions** section in the API you're interested to call.
 
-      **Note**: Every time you add permission you must select **Grant admin consent** for the new permission to take effect.
+1. Select **Grant admin consent**
 
-      ![Screenshot of of granting admin permissions.](media/grant-consent.png)
+     > [!NOTE]
+    > Every time you add permission you must select **Grant admin consent** for the new permission to take effect.
 
-1. Write down your application ID and your tenant ID:
+    :::image type="content" source="media/api-authentication-application/grant-consent.png" alt-text="Screenshot that shows the option to grant admin consent." lightbox="media/api-authentication-application/grant-consent.png":::
 
-   - On your application page, go to **Overview** and copy the following information:
 
-        ![Screenshot of the created app ID.](media/app-and-tenant-ids.png)
+1. Write down your application ID and your tenant ID.
+
+1. On your application page, go to **Overview** and copy the following information:
+   
+   :::image type="content" source="media/api-authentication-application/app-and-tenant-ids.png" alt-text="Screenshot that shows the created app ID." lightbox="media/api-authentication-application/app-and-tenant-ids.png":::
+
 
 ## Supported permission scopes
 
@@ -152,19 +158,19 @@ namespace MDA
 
 Verify to make sure you got a correct token:
 
-- Copy/paste into [JWT](https://jwt.ms) the token you got in the previous step in order to decode it
-- Validate that you get a 'scp' claim with the desired app permissions
+- Copy/paste into [JWT](https://jwt.ms) the token you got in the previous step in order to decode it.
+- Validate that you get a 'scp' claim with the desired app permissions.
 - In the screenshot below you can see a decoded token acquired from the app in the tutorial:
 
-    ![Screenshot of token validation.](media/webapp-decoded-token.png)
+    :::image type="content" source="media/api-authentication-application/webapp-decoded-token.png" alt-text="Screenshot that shows the decoded token.":::
 
 ## Use the token to access the Microsoft Defender for Cloud Apps API
 
 - Choose the API you want to use. For more information, see [Defender for Cloud Apps API](api-introduction.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 than one request with the same token)
+- 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 than one request with the same token).
 
-- Example of sending a request to get a list of alerts **using C#**
+- Example of sending a request to get a list of alerts **using C#**:
 
     ```csharp
     var httpClient = new HttpClient();