From 3e2bcba371591a4d707b4c55b283f8a454603807 Mon Sep 17 00:00:00 2001 From: Chris Davis Date: Tue, 24 Jun 2025 15:31:08 -0700 Subject: [PATCH 1/5] Check-PurviewConfig --- .../exchange/Check-PurviewConfig.md | 363 ++++++++++++++++++ exchange/exchange-ps/exchange/exchange.md | 2 + exchange/mapping/serviceMapping.json | 1 + 3 files changed, 366 insertions(+) create mode 100644 exchange/exchange-ps/exchange/Check-PurviewConfig.md diff --git a/exchange/exchange-ps/exchange/Check-PurviewConfig.md b/exchange/exchange-ps/exchange/Check-PurviewConfig.md new file mode 100644 index 0000000000..5cc2de7f08 --- /dev/null +++ b/exchange/exchange-ps/exchange/Check-PurviewConfig.md @@ -0,0 +1,363 @@ +--- +external help file: Microsoft.Exchange.TransportMailflow-Help.xml +online version: https://learn.microsoft.com/powershell/module/exchange/check-purviewconfig +applicable: Security & Compliance +title: Check-PurviewConfig +schema: 2.0.0 +author: chrisda +ms.author: chrisda +ms.reviewer: +--- + +# Check-PurviewConfig + +## SYNOPSIS +This cmdlet is available only in Security & Compliance PowerShell. For more information, see [Security & Compliance PowerShell](https://learn.microsoft.com/powershell/exchange/scc-powershell). + +Use the Check-PurviewConfig cmdlet to validate and review your organization's configuration settings in Microsoft Purview. + +For information about the parameter sets in the Syntax section below, see [Exchange cmdlet syntax](https://learn.microsoft.com/powershell/exchange/exchange-cmdlet-syntax). + +## SYNTAX + +``` +Check-PurviewConfig + [[-Component] ] + [[-DateTimeUTC] ] + [[-File] ] + [[-IncidentId] ] + [[-ItemId] ] + [[-MessageId] ] + [[-RecordId] ] + [[-RuleName] ] + [[-TestCases] ] + [[-Theme] ] + [[-UserPrincipalName] ] + [[-Workload] ] + [-Confirm] + [-WhatIf] + [] +``` + +## DESCRIPTION +Use the Check-PurviewConfig cmdlet to run Microsoft Information Protection diagnostic test cases for your organization and check the results. + +To use this cmdlet in Security & Compliance PowerShell, you need to be assigned permissions. For more information, see [Permissions in the Microsoft Purview compliance portal](https://learn.microsoft.com/purview/microsoft-365-compliance-center-permissions). + +## EXAMPLES + +### Example 1 +```powershell +Check-PurviewConfig +``` + +This example runs all Microsoft Information Protection test cases that don't require additional parameters. + +### Example 2 +```powershell +Check-PurviewConfig -Component Encryption +``` + +This example runs all test cases for the Encryption component. + +### Example 3 +```powershell +Check-PurviewConfig -Component Encryption -Theme LicenseAvailability +``` + +This example runs all cases for the LicenseAvailability theme in the Encryption component. + +### Example 4 +```powershell +Check-PurviewConfig -TestCases "MipLabels_EnabledEntities_ScopedLabels" -UserPrincipalName sathya@contoso.onmicrosoft.com +``` + +This example runs the test case named MipLabels_EnabledEntities_ScopedLabels, which requires a UserPrincipalName value. + +### Example 5 +```powershell +Check-PurviewConfig -TestCases "MipLabels_EnabledEntities_ScopedLabels","MipLabels_EnabledEntities_CompareSyncStatus" -UserPrincipalName sathya@contoso.onmicrosoft.com +``` + +This example runs the specified test cases. A UserPrincipalName value is required for the MipLabels_EnabledEntities_ScopedLabels test case. + +## PARAMETERS + +### -Component +The Component parameter specifies the component to analyze in the test case. Valid values are: + +- DLP +- DLPAlerts +- Encryption +- MIPLabels + +```yaml +Type: PurviewConfigComponent +Parameter Sets: (All) +Aliases: +Applicable: Security & Compliance + +Required: False +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm +The Confirm switch specifies whether to show or hide the confirmation prompt. How this switch affects the cmdlet depends on if the cmdlet requires confirmation before proceeding. + +- Destructive cmdlets (for example, Remove-\* cmdlets) have a built-in pause that forces you to acknowledge the command before proceeding. For these cmdlets, you can skip the confirmation prompt by using this exact syntax: `-Confirm:$false`. +- Most other cmdlets (for example, New-\* and Set-\* cmdlets) don't have a built-in pause. For these cmdlets, specifying the Confirm switch without a value introduces a pause that forces you acknowledge the command before proceeding. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf +Applicable: Security & Compliance + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -DateTimeUTC +The DateTimeUTC specifies the date-time of the test case in Coordinated Universal Time (UTC). For example, "2025-06-05 14:30:00". + +This parameter is required for the following TestCases values: + +- DlpAlerts_CheckAlertsCreated +- DlpAlerts_FindAlertForActivity + +```yaml +Type: String +Parameter Sets: (All) +Aliases: +Applicable: Security & Compliance + +Required: False +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -File +{{ Fill File Description }} + +```yaml +Type: String +Parameter Sets: (All) +Aliases: +Applicable: Security & Compliance + +Required: False +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -IncidentId +The IncidentId parameter specifies the incident to analyze in the test case. + +This parameter is required for the TestCases value **DlpAlerts_FindAlertForActivity**. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: +Applicable: Security & Compliance + +Required: False +Position: 3 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ItemId +{{ Fill ItemId Description }} + +```yaml +Type: String +Parameter Sets: (All) +Aliases: +Applicable: Security & Compliance + +Required: False +Position: 4 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -MessageId +{{ Fill MessageId Description }} + +```yaml +Type: String +Parameter Sets: (All) +Aliases: +Applicable: Security & Compliance + +Required: False +Position: 5 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -RecordId +The RuleName parameter specifies the record to analyze in the test case. + +This parameter is optional with the TestCases value DlpAlerts_FindAlertForActivity. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: +Applicable: Security & Compliance + +Required: False +Position: 6 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -RuleName +The RuleName parameter specifies the rule to analyze in the test case. + +This parameter is optional with the TestCases value DlpAlerts_CheckAlertsCreated. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: +Applicable: Security & Compliance + +Required: False +Position: 7 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -TestCases +The TestCases parameter specifies the name of the test case to analyze. The available test cases and their required parameters are described in the following list: + +- **Encryption_EvaluationDetails**: Validates email encryption evaluation details. No other parameters are required. +- **Encryption_LicenseAvailability**: Checks email encryption configurations. No other parameters are required. +- **MipLabels_EnabledEntities_ScopedLabels**: Shows the labels and label settings that apply to a user. Requires the UserPrincipalName parameter. +- **MipLabels_LicenseAvailability**: Verifies whether the MIP Label feature is enabled. No other parameters required. +- **DlpAlerts_CheckAlertsCreated**: Validates the DLP rule configuration for alerts created in last 5 days. Requires the DateTimeUTC parameter. The RuleName parameter is optional. +- **DlpAlerts_FindAlertForActivity**: Identifies missing alerts for an activity. Requires the DateTimeUTC parameter. The IncidentId and RecordId parameters are optional. +- **DLP_ScopedEntities**: Returns all DLP policies and rules that apply to a user or a site. Requires the Workload parameter. The SiteUrl and UserPrincipalName parameters are optional. + +You can specify multiple values separated by commas. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: +Applicable: Security & Compliance + +Required: False +Position: 8 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Theme +The Theme parameter filters specifies the them to analyze in the test case. Valid values are: + +- EnabledEntities +- EvaluationDetails +- LicenseAvailability + +```yaml +Type: PurviewConfigTheme +Parameter Sets: (All) +Aliases: +Applicable: Security & Compliance + +Required: False +Position: 9 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -UserPrincipalName +The UserPrincipalName parameter specifies the user account to analyze in the test case (for example, `sathya@contoso.onmicrosoft.com`). + +- Required for the TestCases value MipLabels_EnabledEntities_ScopedLabels. +- Optional for the TestCases value DLP_ScopedEntities. + +```yaml +Type: Object +Parameter Sets: (All) +Aliases: +Applicable: Security & Compliance + +Required: False +Position: 10 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf +The WhatIf switch doesn't work in Security & Compliance PowerShell. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi +Applicable: Security & Compliance + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Workload +The Workload parameter specifies the service workload. Value values are: + +- EndpointDevices +- Exchange +- OneDriveForBusiness +- SharePoint +- Teams + +This parameter is required for the TestCases value DLP_ScopedEntities. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: +Applicable: Security & Compliance + +Required: False +Position: 11 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/p/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES + +## RELATED LINKS diff --git a/exchange/exchange-ps/exchange/exchange.md b/exchange/exchange-ps/exchange/exchange.md index 8ead57cb12..b65ce43828 100644 --- a/exchange/exchange-ps/exchange/exchange.md +++ b/exchange/exchange-ps/exchange/exchange.md @@ -1729,6 +1729,8 @@ Exchange PowerShell is built on Windows PowerShell technology and provides a pow ### [Update-ExchangeHelp](Update-ExchangeHelp.md) ## policy-and-compliance Cmdlets +### [Check-PurviewConfig](Check-PurviewConfig.md) + ### [Disable-JournalArchiving](Disable-JournalArchiving.md) ### [Disable-JournalRule](Disable-JournalRule.md) diff --git a/exchange/mapping/serviceMapping.json b/exchange/mapping/serviceMapping.json index b6691a949e..663de1cf39 100644 --- a/exchange/mapping/serviceMapping.json +++ b/exchange/mapping/serviceMapping.json @@ -847,6 +847,7 @@ "Test-ServicePrincipalAuthorization": "organization", "Test-SystemHealth": "organization", "Update-ExchangeHelp": "organization", + "Check-PurviewConfig": "policy-and-compliance", "Disable-JournalArchiving": "policy-and-compliance", "Disable-JournalRule": "policy-and-compliance", "Disable-OutlookProtectionRule": "policy-and-compliance", From 85e77c6d31617f24210159dfcc1a1b177ce16051 Mon Sep 17 00:00:00 2001 From: Chris Davis Date: Tue, 24 Jun 2025 15:40:45 -0700 Subject: [PATCH 2/5] Update Check-PurviewConfig.md --- exchange/exchange-ps/exchange/Check-PurviewConfig.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/exchange/exchange-ps/exchange/Check-PurviewConfig.md b/exchange/exchange-ps/exchange/Check-PurviewConfig.md index 5cc2de7f08..c6dd4b4357 100644 --- a/exchange/exchange-ps/exchange/Check-PurviewConfig.md +++ b/exchange/exchange-ps/exchange/Check-PurviewConfig.md @@ -32,7 +32,7 @@ Check-PurviewConfig [[-RuleName] ] [[-TestCases] ] [[-Theme] ] - [[-UserPrincipalName] ] + [[-UserPrincipalName] ] [[-Workload] ] [-Confirm] [-WhatIf] @@ -229,7 +229,7 @@ Accept wildcard characters: False ``` ### -RuleName -The RuleName parameter specifies the rule to analyze in the test case. +The RuleName parameter specifies the DLP rule to analyze in the test case. This parameter is optional with the TestCases value DlpAlerts_CheckAlertsCreated. @@ -299,7 +299,7 @@ The UserPrincipalName parameter specifies the user account to analyze in the tes - Optional for the TestCases value DLP_ScopedEntities. ```yaml -Type: Object +Type: SmtpAddress Parameter Sets: (All) Aliases: Applicable: Security & Compliance From 58e21fe023219da25d9ae78c39be7ae4fa3ee12a Mon Sep 17 00:00:00 2001 From: Chris Davis Date: Mon, 30 Jun 2025 17:32:14 -0700 Subject: [PATCH 3/5] Update Check-PurviewConfig.md Updates per TR --- exchange/exchange-ps/exchange/Check-PurviewConfig.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/exchange/exchange-ps/exchange/Check-PurviewConfig.md b/exchange/exchange-ps/exchange/Check-PurviewConfig.md index c6dd4b4357..3b3a4faf9f 100644 --- a/exchange/exchange-ps/exchange/Check-PurviewConfig.md +++ b/exchange/exchange-ps/exchange/Check-PurviewConfig.md @@ -145,7 +145,7 @@ Accept wildcard characters: False ``` ### -File -{{ Fill File Description }} +This parameter is reserved for internal Microsoft use. ```yaml Type: String @@ -163,7 +163,9 @@ Accept wildcard characters: False ### -IncidentId The IncidentId parameter specifies the incident to analyze in the test case. -This parameter is required for the TestCases value **DlpAlerts_FindAlertForActivity**. +You can find a value for this parameter in audit log searches filtered by the operation DLPRuleMatch in the IncidentId property. + +This parameter is required for the TestCases value DlpAlerts_FindAlertForActivity. ```yaml Type: String @@ -179,7 +181,7 @@ Accept wildcard characters: False ``` ### -ItemId -{{ Fill ItemId Description }} +This parameter is reserved for internal Microsoft use. ```yaml Type: String @@ -195,7 +197,7 @@ Accept wildcard characters: False ``` ### -MessageId -{{ Fill MessageId Description }} +This parameter is reserved for internal Microsoft use. ```yaml Type: String @@ -213,6 +215,8 @@ Accept wildcard characters: False ### -RecordId The RuleName parameter specifies the record to analyze in the test case. +You can find a value for this parameter in Activity Explorer filtered by the activity type DLPRuleMatch in the RecordId property. + This parameter is optional with the TestCases value DlpAlerts_FindAlertForActivity. ```yaml From ca51ebc5e1127de78f8d4d6780d06f1d8494e51b Mon Sep 17 00:00:00 2001 From: sathya-3445 <97036584+sathya-3445@users.noreply.github.com> Date: Thu, 3 Jul 2025 00:16:18 +0530 Subject: [PATCH 4/5] Update Check-PurviewConfig.md --- exchange/exchange-ps/exchange/Check-PurviewConfig.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/exchange/exchange-ps/exchange/Check-PurviewConfig.md b/exchange/exchange-ps/exchange/Check-PurviewConfig.md index 3b3a4faf9f..fe2278af9b 100644 --- a/exchange/exchange-ps/exchange/Check-PurviewConfig.md +++ b/exchange/exchange-ps/exchange/Check-PurviewConfig.md @@ -42,7 +42,7 @@ Check-PurviewConfig ## DESCRIPTION Use the Check-PurviewConfig cmdlet to run Microsoft Information Protection diagnostic test cases for your organization and check the results. -To use this cmdlet in Security & Compliance PowerShell, you need to be assigned permissions. For more information, see [Permissions in the Microsoft Purview compliance portal](https://learn.microsoft.com/purview/microsoft-365-compliance-center-permissions). +To use this cmdlet in Security & Compliance PowerShell, you need to be assigned Global Administrator permission. ## EXAMPLES From e1a0cc7358cb5212bd124cf9ae974819dff8578d Mon Sep 17 00:00:00 2001 From: Chris Davis Date: Wed, 2 Jul 2025 13:32:36 -0700 Subject: [PATCH 5/5] Update Check-PurviewConfig.md --- exchange/exchange-ps/exchange/Check-PurviewConfig.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/exchange/exchange-ps/exchange/Check-PurviewConfig.md b/exchange/exchange-ps/exchange/Check-PurviewConfig.md index fe2278af9b..e24cba8717 100644 --- a/exchange/exchange-ps/exchange/Check-PurviewConfig.md +++ b/exchange/exchange-ps/exchange/Check-PurviewConfig.md @@ -42,7 +42,12 @@ Check-PurviewConfig ## DESCRIPTION Use the Check-PurviewConfig cmdlet to run Microsoft Information Protection diagnostic test cases for your organization and check the results. -To use this cmdlet in Security & Compliance PowerShell, you need to be assigned Global Administrator permission. +You need to be a member of the Global Administrators role to run this cmdlet. + +To learn more about administrator role permissions in Microsoft Entra ID, see [Role template IDs](https://learn.microsoft.com/entra/identity/role-based-access-control/permissions-reference#role-template-ids). + +> [!IMPORTANT] +> Microsoft recommends that you use roles with the fewest permissions. Using lower permissioned accounts helps improve security for your organization. Global Administrator is a highly privileged role that should be limited to emergency scenarios when you can't use an existing role. ## EXAMPLES