Merge pull request #2032 from MicrosoftDocs/main

Published main to live, Wednesday 5:00 PM IST, 11/27

Author: garycentric

CloudAppSecurityDocs/app-governance-app-policies-create.md

@@ -7,7 +7,7 @@ description: Get started learning about app governance policies with Microsoft D
 
 # Get started with app policies
 
-Policies for app governance are a way to implement proactive and reactive alerts and automatic remediation for your specific needs for app compliance in your organization. You can create policies in app governance to manage OAuth apps in Microsoft Entra ID, Google and Salesforce.
+Policies for app governance are a way to implement proactive and reactive alerts and automatic remediation for your specific needs for app compliance in your organization. You can create policies in app governance to manage OAuth apps in Microsoft 365, Google and Salesforce.
 
 There are two types of policies in app governance:
 

CloudAppSecurityDocs/app-governance-app-policies-get-started.md

@@ -7,14 +7,14 @@ description: Manage your app governance policies.
 
 # Manage app policies
 
-Use app governance to manage OAuth policies for Microsoft Entra ID, Google Workspace, and Salesforce.
+Use app governance to manage OAuth policies for Microsoft 365, Google Workspace, and Salesforce.
 
 You might need to manage your app policies as follows to keep up-to-date with your organization's apps, respond to new app-based attacks, and for ongoing changes to your app compliance needs:
 
 - Create new policies targeted at new apps
 - Change the status of an existing policy (active, inactive, audit mode)
 - Change the conditions of an existing policy
-- Change the actions of an existing policy for autoremediation of alerts
+- Change the actions of an existing policy for auto-remediation of alerts
 
 <a name='manage-oauth-app-policies-for-azure-ad'></a>
 

CloudAppSecurityDocs/app-governance-app-policies-manage.md

@@ -17,7 +17,7 @@ Before you start, verify that you satisfy the following prerequisites:
 
 - Microsoft Defender for Cloud Apps must be present in your account as either a standalone product or as part of the various [license](#licensing) packages.
 
-    If you aren't already a Defender for Cloud Apps customer, you can [sign up for a free trial](https://www.microsoft.com/security/business/cloud-apps-defender).
+  If you aren't already a Defender for Cloud Apps customer, you can [sign up for a free trial](https://www.microsoft.com/security/business/cloud-apps-defender).
 
 - You must have [one of the appropriate roles](#roles) to turn on app governance and access it.
 

CloudAppSecurityDocs/app-governance-get-started.md

@@ -19,41 +19,41 @@ The **Overview** page shows the following details:
 For example:
 
 > [!div class="mx-imgBorder"]
->![Relative number of detected and policy-based incidents.](incidents-summary1.png)
->
+> ![Relative number of detected and policy-based incidents.](incidents-summary1.png)
+> 
 > [!div class="mx-imgBorder"]
->![top alerts.](media/app-governance-visibility-insights-compliance-posture/top-alerts.png)
+> ![top alerts.](media/app-governance-visibility-insights-compliance-posture/top-alerts.png)
 
 ## Data usage cards
 
 Data usage cards show the following types of information:
 
-- **Total data accessed by apps** in the tenant through Graph API over the current month and previous three calendar months. (Currently includes emails, files, and chat and channel messages read and written by apps that access Microsoft 365 using Graph API)
+- **Total data accessed by apps** in the tenant through Microsoft Graph and EWS APIs over the current month and previous three calendar months. (Currently includes emails, files, and chat and channel messages read and written by apps that access Microsoft 365 using Microsoft Graph and EWS APIs)
 
-- **Data usage over the current month and previous three calendar months**, broken down by resource type. (Currently includes emails, files, and chat and channel messages read and written by apps that access Microsoft 365 using Graph API)
+- **Data usage over the current month and previous three calendar months**, broken down by resource type. (Currently includes emails, files, and chat and channel messages read and written by apps that access Microsoft 365 using Microsoft Graph and EWS APIs)
 
 For example:
 
 > [!div class="mx-imgBorder"]
->![Total data accessed by apps.](media/app-governance-visibility-insights-compliance-posture/data-usage-chart.png)
+> ![Total data accessed by apps.](media/app-governance-visibility-insights-compliance-posture/data-usage-chart.png)
 
 ## Apps that access data on Microsoft 365
 
-For apps that access data on Microsoft 365, cards show the number of apps that have accessed data on SharePoint, OneDrive, Exchange Online, or Teams in the last 30 days
+For apps that access data on Microsoft 365, cards show the number of apps that have accessed data on SharePoint, OneDrive, Exchange Online, or Teams using Microsoft Graph and EWS APIs in the last 30 days.
 
 For example:
 
 > [!div class="mx-imgBorder"]
->![Apps that have accessed data on SharePoint, OneDrive, Exchange Online, or Teams in the last 30 days.](media/app-governance-visibility-insights-compliance-posture/apps-accessed-m365-services-chart.png)
+> ![Apps that have accessed data on SharePoint, OneDrive, Exchange Online, or Teams in the last 30 days.](media/app-governance-visibility-insights-compliance-posture/apps-accessed-m365-services-chart.png)
 
 ## Sensitivity labels accessed
 
-For sensitivity labeling data, cards show the number apps that have accessed content with sensitivity labels on SharePoint, OneDrive, Exchange Online or Teams in the last 30 days.
+For sensitivity labeling data, cards show the number apps that have accessed content with sensitivity labels on SharePoint, OneDrive, Exchange Online or Teams using Microsoft Graph and EWS APIs in the last 30 days.
 
 For example:
 
 > [!div class="mx-imgBorder"]
->![number apps that have accessed content with sensitivity labels.](sensitive-data-accessed-chart1.png)
+> ![number apps that have accessed content with sensitivity labels.](sensitive-data-accessed-chart1.png)
 
 ## Next steps
 

CloudAppSecurityDocs/app-governance-visibility-insights-compliance-posture.md

@@ -38,32 +38,48 @@ One of the primary value points for app governance is the ability to quickly vie
 1. On the **App governance** page, select one of the apps tabs to display your apps.
 
     The apps listed depend on the apps present in your tenant.
-
+   
 1. Filter the apps listed using one or more of the following default filter options:
 
-    - **API access**
-    - **Privilege level**
-    - **Permission usage**
-    - **Permission type**
-    - **Publisher verified**
-
+   - **API access**
+      
+   - **Privilege level**
+      
+   - **Permission** (Preview)
+      
+   - **Permission usage**
+      
+   - **App origin**
+      
+   - **Permission type**
+      
+   - **Publisher verified**
+      
     Use one of the following nondefault filters to further customize the apps listed:
-
-    - **Last modified**
-    - **Added on**
-    - **Certification**
-    - **Users**
-    - **Services accessed**
-    - **Data usage**
-    - **Sensitivity labels accessed**
-
-    > [!TIP]
-    > Save the query to save the currently selected filters for use again in the future.
-
+   
+   - **Last modified**
+      
+   - **Added on**
+      
+   - **Certification**
+      
+   - **Users**
+      
+   - **Services accessed**
+      
+   - **Data usage**
+      
+   - **Sensitivity labels accessed**
+   
+     > [!TIP]
+     > Save the query to save the currently selected filters for use again in the future.
+     
 1. Select the name of an app to view more details. For example:
 
-    :::image type="content" source="media/app-governance-visibility-insights-get-started/image2.png" alt-text="Screenshot of an app details pane showing an app summary.":::
-
+   ![Screenshot of an app details pane showing an app summary.](media/app-governance-visibility-insights-get-started/app-governance-app-list-view.png)
+   
+   
+   
 The details pane lists the app usage over the past 30 days, the users who have consented to the app, and the permissions assigned to the app. 
 
 For example, an administrator might review the activity and permissions of an app that is generating alerts and make a decision to disable the app using the **Disable App** button towards the bottom of the app details pane.

CloudAppSecurityDocs/app-governance-visibility-insights-get-started.md

@@ -17,21 +17,21 @@ For a summary of apps in your tenant, in Microsoft 365, go to **Cloud app > App
 
 For example:
 
-:::image type="content" source="media/app-governance-visibility-insights-view-apps/appg-cc-apps.png" alt-text="Screenshot of the Azure AD apps tab on the App governance page.":::
-
+:::image type="content" source="media/app-governance-visibility-insights-view-apps/app-governance-app-list-view-new.png" alt-text="Screenshot of the Azure AD apps tab on the App governance page.":::
 
 >[!NOTE]
 > Your sign-in account must have one of [these roles](app-governance-get-started.md#roles) to view any app governance data.
 >
 
-On the **Azure AD apps** tab, the apps in your tenant are listed with the following details:
+On the **Microsoft 365** tab, the apps in your tenant are listed with the following details:
 
 |Column name  |Description  |
 |---------|---------|
-|**App name** | The display name of the app as registered on Microsoft Entra ID |
-|**App status** | Shows whether the app is enabled or disabled, and if disabled by whom |
+| **App name** | The display name of the app as registered on Microsoft Entra ID |
+| **App status** | Shows whether the app is enabled or disabled, and if disabled by whom |
 | **Graph API access**| Shows whether the app has at least one Graph API permission |
 | **Permission type**| Shows whether the app has application (app only), delegated, or mixed permissions |
+| **App origin** (Preview)| Shows whether the app originated within the tenant or was registered in an external tenant |
 | **Consent type**| Shows whether the app consent has been given at the user or the admin level, and the number of users whose data is accessible to the app |
 | **Publisher**| Publisher of the app and their verification status |
 | **Last modified**| Date and time when registration information was last updated on Microsoft Entra ID |
@@ -55,13 +55,13 @@ You can also select **Search** to search for an app by name.
 
 Select a specific app in the grid to view more details on an apps details pane on the right. For example:
 
-:::image type="content" source="media/app-governance-visibility-insights-view-apps/image2.png" alt-text="Screenshot of an app details pane on the Azure AD tab.":::
+:::image type="content" source="media/app-governance-visibility-insights-view-apps/app-governance-app-list-view.png" alt-text="Screenshot of an app details pane on the Azure AD tab.":::
 
-The **Summary** tab also shows more data about the app, such as the date first consented and the App ID. To see the properties of the app as registered in Microsoft Entra ID, select **View app in Azure AD**.
+The **Summary** tab also shows more data about the app, such as the date first consented and the App ID. To see the properties of the app as registered in Microsoft Entra ID, select **View in Microsoft Entra ID**.
 
 In the details pane, select any of the following tabs to view more details:
 
-- Select the **Data usage** tab to view a graph of data usage over time, for Exchange, SharePoint, OneDrive, and Teams resources. For example:
+- Select the **Data usage** tab to view a graph of data usage over time, for Exchange, SharePoint, OneDrive, and Teams resources via Microsoft Graph and EWS APIs. For example:
 
     :::image type="content" source="media/app-governance-visibility-insights-view-apps/data-usage.png" alt-text="Screenshot of the Data usage tab.":::
 
@@ -73,7 +73,7 @@ In the details pane, select any of the following tabs to view more details:
 
     If an app is *admin consented*, the **Total consented users** are all users in the tenant.
 
-- Select the **Permissions** tab to see a summary and list of the Graph API and legacy permissions granted to the app, consent type, and whether they are in use. For example:
+- Select the **Permissions** tab to see a summary and list of the Graph API and legacy permissions granted to the app, consent type, privilege level and whether they are in use. For example:
 
     :::image type="content" source="media/app-governance-visibility-insights-view-apps/permissions.png" alt-text="Screenshot of the Permissions tab.":::
 
@@ -83,13 +83,8 @@ In the details pane, select any of the following tabs to view more details:
 
     :::image type="content" source="media/app-governance-visibility-insights-view-apps/sensitive-labels-details.png" alt-text="Screenshot of the Sensitivity labels tab.":::
 
-For an enabled app, there's also a **Disable app** control to disable the use of the selected app and an **Enable app** control to enable the use of the disabled app. These actions require at least the following administrator roles:
-
+For an enabled app, there's also a **Disable app** control to disable the use of the selected app and an **Enable app** control to enable the use of the disabled app. These actions require a *Company Administrator* administrator role.
 
-- *Compliance Administrator*
-- *Company Administrator*
-- *Security Administrator*
-- *Security Operator*
 
 ## Managing Google Workspace and Salesforce OAuth apps
 

CloudAppSecurityDocs/app-governance-visibility-insights-view-apps.md

@@ -28,7 +28,7 @@ The following types of policies can be created:
 |![access policy icon.](media/proxy-policy.png)|Access policy|Conditional Access|Access policies provide you with real-time monitoring and control over user logins to your cloud apps. [Learn more](access-policy-aad.md)|
 |![session policy icon.](media/proxy-policy.png)|Session policy|Conditional Access|Session policies provide you with real-time monitoring and control over user activity in your cloud apps. [Learn more](session-policy-aad.md)|
 |![cloud discovery policy icon.](media/discovery-policy.png)|App discovery policy|Shadow IT|App discovery policies enable you to set alerts that notify you when new apps are detected within your organization. [Learn more](cloud-discovery-policies.md)|
-|![anomaly detection policy icon.](media/anomaly-detection-policy.png)|cloud discovery anomaly detection policy|Shadow IT|Cloud discovery anomaly detection policies look at the logs you use for discovering cloud apps and search for unusual occurrences. For example, when a user who never used Dropbox before suddenly uploads 600 GB to Dropbox, or when there are a lot more transactions than usual on a particular app. [Learn more](cloud-discovery-anomaly-detection-policy.md)|
+
 
 ## Identifying risk
 

CloudAppSecurityDocs/control-cloud-apps-with-policies.md

@@ -0,0 +1,91 @@
+---
+title: Work with discovered apps via Graph API | Microsoft Defender for Cloud Apps
+description: Learn how to work with apps discovered by Microsoft Defender for Cloud Apps via Graph API.
+ms.topic: how-to #Don't change
+ms.date: 06/24/2024
+
+#customer intent: As a security engineer, I want to work with discovered apps via API so that I can customize and automate the Microsoft Defender for Cloud Apps **Discovered apps** page functionality.
+
+---
+
+# Work with discovered apps via Graph API (Preview)
+
+Microsoft Defender for Cloud Apps supports a Microsoft Graph API that you can use to work with discovered cloud apps, to customize and automate the **Discovered apps** page functionality in the Microsoft Defender portal.
+
+This article provides sample procedures for using the [uploadedStreams API](/graph/api/security-datadiscoveryreport-list-uploadedstreams?view=graph-rest-beta) for common purposes.
+
+## Prerequisites
+
+Before you start using the Graph API, make sure to create an app and get an access token to use the application. Then, use the token to access the Defender for Cloud Apps API.
+
+- Make sure to give the app permissions to access Defender for Cloud Apps, by granting it with `CloudApp-Discovery.Read.All` permissions and admin consent.
+
+- Take note of your app secret and copy its value to use later on in your scripts.
+
+You'll also need cloud app data streaming into Microsoft Defender for Cloud Apps.
+
+For more information, see:
+
+- [Manage admin access](manage-admins.md)
+- [Graph API authentication and authorization basics](/graph/auth/auth-concepts)
+- [Use the Microsoft Graph API](/graph/use-the-api)
+- [Set up Cloud Discovery](set-up-cloud-discovery.md)
+
+## Get data about discovered apps
+
+To get a high level summary of all the data available on your **Discovered apps** page, run the following GET command:
+
+```http
+GET https://graph.microsoft.com/beta/dataDiscovery/cloudAppDiscovery/uploadedStreams
+```
+
+To drill down to data for a specific stream:
+
+1. Copy the relevant `<streamID>` value from the previous command's output.
+1. Run the following GET command using the `<streamID>` value:
+
+    ```http
+    GET https://graph.microsoft.com/beta/security/dataDiscovery/cloudAppDiscovery/uploadedStreams/<streamId>/aggregatedAppsDetails(period=duration'P90D')
+    ```
+
+## Filter for a specific time period and risk score
+
+Filter your API commands using `$select` and `$filter` to get data for a specific time period and risk score. For example, to view the names of all apps discovered in the last 30 days with a risk score lower or equal to 4, run:
+
+```http
+GET https://graph.microsoft.com/beta/security/dataDiscovery/cloudAppDiscovery/uploadedStreams/<streamId>/aggregatedAppsDetails (period=duration'P30D')?$filter=riskRating  le 4 &$select=displayName
+```
+
+## Get the userIdentifier of all users, devices, or IP addresses using a specific app
+
+Identify the users, devices, or IP addresses that are currently using a specific app, run one of the following commands:
+
+- **To return users**:
+
+    ```http
+    GET  https://graph.microsoft.com/beta/security/dataDiscovery/cloudAppDiscovery/uploadedStreams/<streamId>/aggregatedAppsDetails (period=duration'P30D')/ <id>/users  
+    ```
+
+- **To return IP addresses**:
+
+    ```http
+    GET  https://graph.microsoft.com/beta/security/dataDiscovery/cloudAppDiscovery/uploadedStreams/<streamId>/aggregatedAppsDetails (period=duration'P30D')/ <id>/ipAddress  
+    ```
+
+- **To return devices**:
+
+    ```http
+    GET  https://graph.microsoft.com/beta/security/dataDiscovery/cloudAppDiscovery/uploadedStreams/<streamId>/aggregatedAppsDetails (period=duration'P30D')/ <id>/name  
+    ```
+
+## Use filters to see apps by category
+
+Use filters to see apps of a specific category, such as apps that are categorized as *Marketing*, and are also not HIPPA compliant. For example, run:
+
+```http
+GET  https://graph.microsoft.com/beta/security/dataDiscovery/cloudAppDiscovery/uploadedStreams/<MDEstreamId>/aggregatedAppsDetails (period=duration 'P30D')?$filter= (appInfo/Hippa eq 'false') and category eq 'Marketing'  
+```
+
+## Related content
+
+For more information, see [Working with discovered apps](discovered-apps.md) and the [Microsoft Graph API reference](/graph/api/resources/security-cloudappdiscovery-overview?view=graph-rest-beta).