Skip to content
Open
Show file tree
Hide file tree
Changes from 4 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions powershell/Maester.psd1
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,7 @@
'Get-MtAuthenticationMethodPolicyConfig',
'Get-MtAzureManagementGroup',
'Get-MtConditionalAccessPolicy',
'Get-MtConditionalAccessPolicyPlan',
'Get-MtConnectionState',
'Get-MtConnector',
'Get-MtExo',
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@
) {
$result = $true
$currentResult = $true
$testResult += " - [$(Get-MtSafeMarkdown $policy.displayName)](https://entra.microsoft.com/#view/Microsoft_AAD_ConditionalAccess/PolicyBlade/policyId/$($($policy.id))?%23view/Microsoft_AAD_ConditionalAccess/ConditionalAccessBlade/~/Policies?=)`n"
$testResult += "$(Get-GraphObjectMarkdown -GraphObjects $policy -GraphObjectType ConditionalAccess)"
} else {
$currentResult = $false
}
Expand Down
8 changes: 6 additions & 2 deletions powershell/internal/report/Get-GraphObjectMarkdown.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@
# The type of graph object, this will be used to show the right deeplink to the test results report.
# If not specified, the function will try to determine the type based on the object.
[Parameter(Mandatory = $false)]
[ValidateSet('AuthenticationMethod', 'AuthorizationPolicy', 'ConditionalAccess', 'ConsentPolicy',
[ValidateSet('AuthenticationMethod', 'AuthorizationPolicy', 'ConditionalAccess', 'ConditionalAccessPlan', 'ConsentPolicy',
'Devices', 'Domains', 'Groups', 'IdentityProtection', 'Users', 'UserRole'
)]
[string] $GraphObjectType,
Expand Down Expand Up @@ -52,7 +52,11 @@
}

if($currentGraphObjectType) {
$link = $markdownLinkTemplate[$currentGraphObjectType] -f $item.id
if ($currentGraphObjectType -eq 'ConditionalAccess' -and (Get-ObjectProperty $item 'planId')) {
$link = $markdownLinkTemplate.ConditionalAccessPlan -f $item.planId
} else {
$link = $markdownLinkTemplate[$currentGraphObjectType] -f $item.id
}
}
else {
$link = "#"
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@
# Get-MtAffectedObjectFromMarkdown so records from both sources dedupe correctly.
$canonicalType = @{
ConditionalAccess = 'ConditionalAccessPolicy'
ConditionalAccessPlan = 'ConditionalAccessPolicyPlan'
Users = 'User'
UserRole = 'User'
Groups = 'Group'
Expand Down Expand Up @@ -67,12 +68,13 @@
$type = $objectTypeAlias[$type]
}

$isPlanRule = (Get-ObjectProperty $item 'sourceType') -eq 'PolicyPlanRule' -and (Get-ObjectProperty $item 'planId')
$portalLink = $null
if ($type -and $portalLinkTemplate.LinkTemplates.ContainsKey($type)) {
$template = $portalLinkTemplate.LinkTemplates[$type]
# A per-object template without the id would open a broken blade.
if ($id -or -not $template.Contains('{0}')) {
$portalLink = $template -f $id
$portalLink = if ($isPlanRule) { $portalLinkTemplate.LinkTemplates.ConditionalAccessPlan -f $item.planId } else { $template -f $id }
}
}

Expand All @@ -90,7 +92,8 @@
[PSCustomObject]@{
System = 'EntraID'
AnchorKind = $anchorKind
Type = if ($type -and $canonicalType.ContainsKey($type)) { $canonicalType[$type] }
Type = if ($isPlanRule) { 'ConditionalAccessPolicyRule' }
elseif ($type -and $canonicalType.ContainsKey($type)) { $canonicalType[$type] }
elseif ($type) { $type }
elseif ($odataType -and $odataObjectType.ContainsKey($odataType)) { $odataObjectType[$odataType] }
elseif ($odataType) { $odataType }
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@

# Ordered: more specific patterns first. Id = first capture group.
$patterns = @(
@{ System = 'EntraID'; Type = 'ConditionalAccessPolicyPlan'; Regex = "Microsoft_AAD_ConditionalAccess/PolicyPlanView\.ReactView/planId/($guid)" }
@{ System = 'EntraID'; Type = 'ConditionalAccessPolicy'; Regex = "Microsoft_AAD_ConditionalAccess/PolicyBlade/policyId/($guid)" }
# The appId suffix is optional: some checks link the enterprise app by object id only.
@{ System = 'EntraID'; Type = 'ServicePrincipal'; Regex = "ManagedAppMenuBlade/~/\w+/objectId/($guid)(?:/appId/$guid)?" }
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,8 @@
'AuthenticationMethod'
'AuthorizationPolicy'
'ConditionalAccessPolicy'
'ConditionalAccessPolicyPlan'
'ConditionalAccessPolicyRule'
'ConsentPolicy'
'Device'
'DirectoryRole'
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@
LinkTemplates = @{
AuthenticationMethod = "$($__MtSession.AdminPortalUrl.Entra)#view/Microsoft_AAD_IAM/AuthenticationMethodsMenuBlade/~/AdminAuthMethods"
AuthorizationPolicy = "$($__MtSession.AdminPortalUrl.Entra)#view/Microsoft_AAD_UsersAndTenants/UserManagementMenuBlade/~/UserSettings/menuId/UserSettings"
ConditionalAccessPlan = "$($__MtSession.AdminPortalUrl.Entra)#view/Microsoft_AAD_ConditionalAccess/PolicyPlanView.ReactView/planId/{0}"
ConditionalAccess = "$($__MtSession.AdminPortalUrl.Entra)#view/Microsoft_AAD_ConditionalAccess/PolicyBlade/policyId/{0}"
ConsentPolicy = "$($__MtSession.AdminPortalUrl.Entra)#view/Microsoft_AAD_IAM/ConsentPoliciesMenuBlade/~/UserSettings"
Devices = "$($__MtSession.AdminPortalUrl.Entra)#view/Microsoft_AAD_Devices/DeviceDetailsMenuBlade/~/Properties/objectId/{0}"
Expand All @@ -31,12 +32,14 @@
}
# @odata.type → GraphObjectType (auto-detection when no explicit type is passed)
OdataTypeMapping = @{
'#microsoft.graph.conditionalAccessPolicyPlan' = 'ConditionalAccessPlan'
'#microsoft.graph.conditionalAccessPolicyRule' = 'ConditionalAccess'
'#microsoft.graph.user' = 'Users'
'#microsoft.graph.group' = 'Groups'
'#microsoft.graph.device' = 'Devices'
}
# GraphObjectType → whether the deep link addresses a single object instance
# (types not listed here resolve to a tenant-level settings surface)
InstanceTypes = @('ConditionalAccess', 'Devices', 'Groups', 'Users', 'UserRole')
InstanceTypes = @('ConditionalAccess', 'ConditionalAccessPlan', 'Devices', 'Groups', 'Users', 'UserRole')
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
function ConvertTo-MtConditionalAccessPolicy {
<#
.SYNOPSIS
Projects a plan rule into the policy shape used by Maester's Conditional Access checks.

.DESCRIPTION
Preserves the real rule ID, state, original rule conditions and controls. Exposes inherited effective conditions,
grantControls and sessionControls at the same paths as a standalone policy, with explicit parent-plan metadata.
Never mutates the cached plan or rule and never treats a plan owner as an administrator or a rule assignment.
#>
[CmdletBinding()]
[OutputType([pscustomobject])]
param(
[Parameter(Mandatory)] [object] $Plan,
[Parameter(Mandatory)] [object] $Rule
)

if ([string]::IsNullOrWhiteSpace([string]$Plan.id) -or [string]::IsNullOrWhiteSpace([string]$Rule.id)) {
throw 'Conditional Access plans and rules must have IDs before they can be evaluated.'
}
if ($Rule.state -notin @('enabled', 'disabled', 'enabledForReportingButNotEnforced')) {
throw "Conditional Access rule '$($Rule.id)' has an unsupported state '$($Rule.state)'."
}
$parent = $Plan | ConvertTo-Json -Depth 100 | ConvertFrom-Json -AsHashtable
Comment thread
FiraSenax marked this conversation as resolved.
Resolved
$copy = $Rule | ConvertTo-Json -Depth 100 | ConvertFrom-Json -AsHashtable
if (-not $copy.controls -or (-not $copy.controls.grantControls -and -not $copy.controls.sessionControls)) {
throw "Conditional Access rule '$($Rule.id)' has no supported enforcement controls."
}
$copy['@odata.type'] = '#microsoft.graph.conditionalAccessPolicyRule'
$copy['ruleConditions'] = $copy.conditions
try {
$copy['conditions'] = Merge-MtConditionalAccessCondition -Shared $parent.sharedConditions -Rule $copy.conditions
} catch {
throw "Cannot evaluate rule '$($Rule.id)' in plan '$($Plan.id)': $($_.Exception.Message)"
}
$copy['grantControls'] = $copy.controls.grantControls
$copy['sessionControls'] = $copy.controls.sessionControls
$copy['displayName'] = "[Plan: $($Plan.displayName)] [Rule: $($Rule.displayName)]"
$copy['planId'] = $Plan.id
$copy['planDisplayName'] = $Plan.displayName
$copy['planOwners'] = @($Plan.owners)
$copy['sharedConditions'] = $parent.sharedConditions
$copy['sourceType'] = 'PolicyPlanRule'
return [pscustomobject]$copy
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
function Merge-MtConditionalAccessCondition {
<#
.SYNOPSIS
Combines inherited and rule-specific Conditional Access conditions without overwriting exclusions.

.DESCRIPTION
Merges Graph condition dictionaries recursively and unions collection values. Null and empty optional
values do not erase inherited targeting. Incompatible scalar values, including conflicting filter expressions,
terminate the read: inventing a lossy effective policy could make an uncovered scenario pass a security check.
Inputs are JSON-compatible copies owned by the policy adapter, not objects in the Graph session cache.
#>
[CmdletBinding()]
param(
[AllowNull()] [object] $Shared,
[AllowNull()] [object] $Rule,
[string] $PropertyPath = 'conditions'
)

if ($null -eq $Shared) { Write-Output -NoEnumerate -InputObject $Rule; return }
if ($null -eq $Rule) { Write-Output -NoEnumerate -InputObject $Shared; return }

if ($Shared -is [System.Collections.IDictionary] -and $Rule -is [System.Collections.IDictionary]) {
# Guest type and tenant membership form a pair. Unioning both independently invents cross-products
# (type A in tenant X plus type B in tenant Y must not become both types in both tenants).
if ($PropertyPath -match '\.(includeGuestsOrExternalUsers|excludeGuestsOrExternalUsers)$') {
$sharedTypes = @(([string]$Shared.guestOrExternalUserTypes -split ',') | Sort-Object -Unique) -join ','
$ruleTypes = @(([string]$Rule.guestOrExternalUserTypes -split ',') | Sort-Object -Unique) -join ','
$sharedTenants = $Shared.externalTenants | ConvertTo-Json -Depth 100 -Compress
$ruleTenants = $Rule.externalTenants | ConvertTo-Json -Depth 100 -Compress
if ($sharedTypes -ne $ruleTypes -and $sharedTenants -ne $ruleTenants) {
Comment thread
FiraSenax marked this conversation as resolved.
Resolved
throw "Cannot safely combine guest types and tenant sets at '$PropertyPath' without broadening the targeting."
}
}
# The all-external-tenants discriminator denotes the union's entire tenant set.
if ($PropertyPath -like '*.externalTenants' -and ($Shared.membershipKind -eq 'all' -or $Rule.membershipKind -eq 'all')) {
$all = if ($Shared.membershipKind -eq 'all') { $Shared } else { $Rule }
Write-Output -NoEnumerate -InputObject $all
return
}
$merged = [ordered]@{}
$keys = @(@($Shared.Keys) + @($Rule.Keys) | Select-Object -Unique)
foreach ($key in $keys) {
if ($key -like '*@odata.context') { continue }
$merged[$key] = Merge-MtConditionalAccessCondition -Shared $Shared[$key] -Rule $Rule[$key] -PropertyPath "$PropertyPath.$key"
}
Write-Output -NoEnumerate -InputObject $merged
return
}

if ($Shared -is [System.Collections.IList] -and $Rule -is [System.Collections.IList]) {
$union = [System.Collections.Generic.List[object]]::new()
$seen = [System.Collections.Generic.HashSet[string]]::new([System.StringComparer]::OrdinalIgnoreCase)
foreach ($value in @($Shared) + @($Rule)) {
$key = ConvertTo-Json -InputObject $value -Depth 100 -Compress
if ($seen.Add($key)) { $union.Add($value) }
}
# These collection properties use All as a wildcard, not an additional narrowing condition.
if ($PropertyPath -match '\.(includeUsers|includeApplications|includePlatforms|includeLocations|clientAppTypes)$') {
$all = @($union | Where-Object { $_ -is [string] -and $_ -eq 'all' })
if ($all.Count -gt 0) { Write-Output -NoEnumerate -InputObject @($all[0]); return }
}
Write-Output -NoEnumerate -InputObject $union.ToArray()
return
}

if ($Shared -is [string] -and [string]::IsNullOrWhiteSpace($Shared)) { Write-Output -NoEnumerate -InputObject $Rule; return }
if ($Rule -is [string] -and [string]::IsNullOrWhiteSpace($Rule)) { Write-Output -NoEnumerate -InputObject $Shared; return }
if (($Shared | ConvertTo-Json -Depth 100 -Compress) -ceq ($Rule | ConvertTo-Json -Depth 100 -Compress)) {
Write-Output -NoEnumerate -InputObject $Shared
return
}
if ($Shared -is [string] -and $Rule -is [string] -and
$PropertyPath -match '\.(guestOrExternalUserTypes|insiderRiskLevels|agentIdRiskLevels|transferMethods)$') {
$flags = @(@($Shared -split ',') + @($Rule -split ',') | ForEach-Object { $_.Trim() } | Where-Object { $_ } | Select-Object -Unique)
return $flags -join ','
}
throw "Cannot safely combine Conditional Access plan and rule values at '$PropertyPath'. The inventory is incomplete; use a scenario evaluation for this condition instead of assuming coverage."
}
2 changes: 1 addition & 1 deletion powershell/public/run/Add-MtTestResultDetail.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@
[Object[]] $GraphObjects,

# The type of graph object, this will be used to show the right deep-link to the test results report.
[ValidateSet('AuthenticationMethod', 'AuthorizationPolicy', 'ConditionalAccess', 'ConsentPolicy',
[ValidateSet('AuthenticationMethod', 'AuthorizationPolicy', 'ConditionalAccess', 'ConditionalAccessPlan', 'ConsentPolicy',
'Devices', 'Domains', 'Groups', 'IdentityProtection', 'Users', 'UserRole'
)]
[string] $GraphObjectType,
Expand Down
Original file line number Diff line number Diff line change
@@ -1,26 +1,53 @@
function Get-MtConditionalAccessPolicy {
<#
.Synopsis
Returns all the Conditional Access policies in the tenant.
.SYNOPSIS
Returns standalone Conditional Access policies and effective policy plan rules.

.Description
Returns all the Conditional Access policies in the tenant.
.DESCRIPTION
Reads standalone policies and beta policy plans through the Graph session cache. Each plan rule is projected
into the policy shape used by existing checks: inherited conditions are combined without dropping exclusions,
and nested grant/session controls are exposed at the policy level. The rule retains its own ID and state,
with planId, planDisplayName, planOwners, sourceType, sharedConditions and ruleConditions identifying its source.
Owners are metadata only. Disabled and report-only rules retain their states and are not promoted to enabled.
An empty plan inventory is valid. A failed read or an unsafe condition combination terminates the inventory
instead of presenting partial data as complete. Reading requires CA read access, not write permissions.

.Example
Get-MtConditionalAccessPolicy
.PARAMETER StandaloneOnly
Returns only standalone policies, without reading the preview plans endpoint. This is an explicit inventory
selection for callers that need original Graph policy objects, not a fallback used by security checks.

.PARAMETER DisableCache
Forwards an explicit diagnostic caller's cache choice. Security checks leave this switch unset.

.EXAMPLE
Get-MtConditionalAccessPolicy | Where-Object state -EQ enabled

Returns enabled standalone policies and enabled plan rules with effective conditions.

.EXAMPLE
Get-MtConditionalAccessPolicy -StandaloneOnly

Returns the standalone policy inventory without making a plans request.

.LINK
https://maester.dev/docs/commands/Get-MtConditionalAccessPolicy
#>
[CmdletBinding()]
param(
# Specify if this request should skip cache and go directly to Graph.
[Parameter(Mandatory = $false)]
[Switch]$DisableCache
)

Write-Verbose -Message "Getting Conditional Access policies."
[CmdletBinding()]
[OutputType([object[]])]
param(
[switch] $StandaloneOnly,
[switch] $DisableCache
)

return Invoke-MtGraphRequest -RelativeUri 'identity/conditionalAccess/policies' -ApiVersion beta -DisableCache:$DisableCache
Write-Verbose -Message 'Reading standalone Conditional Access policies and effective plan rules.'
$policies = @(Invoke-MtGraphRequest -RelativeUri 'identity/conditionalAccess/policies' -ApiVersion beta -DisableCache:$DisableCache -ErrorAction Stop)
if ($StandaloneOnly) { return $policies }

$effectiveRules = [System.Collections.Generic.List[object]]::new()
foreach ($plan in @(Get-MtConditionalAccessPolicyPlan -DisableCache:$DisableCache -ErrorAction Stop)) {
foreach ($rule in @($plan.rules)) {
$effectiveRules.Add((ConvertTo-MtConditionalAccessPolicy -Plan $plan -Rule $rule))
}
}
return @($policies) + @($effectiveRules.ToArray())
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
function Get-MtConditionalAccessPolicyPlan {
<#
.SYNOPSIS
Returns Conditional Access policy plans with their complete rule inventories.

.DESCRIPTION
Reads the beta plans and rules endpoints through Maester's Graph session cache. Rules are kept in their
original Graph shape, including controls and rule-specific conditions. Shared conditions and owners stay
on the parent plan. Empty plans inventories return no objects; failed reads terminate instead of hiding plans.
This preview API requires CA read access. Policy.Read.All is sufficient; write permissions are not required.

.PARAMETER MetadataOnly
Reads only plan metadata and does not request child rules. Useful for accountability checks.

.PARAMETER DisableCache
Forwards an explicit diagnostic caller's cache choice to every inventory request. Security checks leave the
switch unset so that they use the same tenant snapshot as the rest of the Maester run.

.EXAMPLE
Get-MtConditionalAccessPolicyPlan

Returns each plan and its rules without modifying the cached Graph objects.

.LINK
https://maester.dev/docs/commands/Get-MtConditionalAccessPolicyPlan
#>
[CmdletBinding()]
[OutputType([pscustomobject])]
param(
[switch] $MetadataOnly,
[switch] $DisableCache
)

Write-Verbose -Message 'Reading Conditional Access policy plan metadata and rule inventories.'
$plans = @(Invoke-MtGraphRequest -RelativeUri 'identity/conditionalAccess/plans' -ApiVersion beta -DisableCache:$DisableCache -ErrorAction Stop)
$inventory = [System.Collections.Generic.List[object]]::new()
foreach ($plan in $plans) {
if ([string]::IsNullOrWhiteSpace([string]$plan.id)) { throw 'Conditional Access plan inventory contains a plan without an ID.' }
$planId = [uri]::EscapeDataString([string]$plan.id)
$copy = $plan | ConvertTo-Json -Depth 100 | ConvertFrom-Json -AsHashtable
if (-not $MetadataOnly) {
$copy['rules'] = @(Invoke-MtGraphRequest -RelativeUri "identity/conditionalAccess/plans/$planId/rules" -ApiVersion beta -DisableCache:$DisableCache -ErrorAction Stop)
}
$inventory.Add([pscustomobject]$copy)
}
return $inventory.ToArray()
}
Loading
Loading