Private/Get-PostureCaPolicySummary.ps1

# Copyright (c) 2026 Kainor LLC. Source-available, see LICENSE.md.
function Get-PostureCaPolicySummary {
    <#
    .SYNOPSIS
        One plain-English sentence for a policy model, spec 5.2:
        "Require phishing-resistant MFA for users in Global Administrator and 2 other roles, all cloud apps, any platform. Excludes BreakGlass-01, BreakGlass-02."
    #>

    [CmdletBinding()]
    [OutputType([string])]
    param(
        [Parameter(Mandatory)] [System.Collections.IDictionary] $Policy
    )

    $ErrorActionPreference = 'Stop'

    $listOf = {
        param([object[]] $Items, [string] $Singular, [string] $Plural)
        $names = @($Items | ForEach-Object { $_.name })
        switch ($names.Count) {
            0 { return $null }
            1 { return "$Singular $($names[0])" }
            2 { return "$Singular $($names[0]) and $($names[1])" }
            default { return "$Singular $($names[0]) and $($names.Count - 1) other $Plural" }
        }
    }
    $isBuiltIn = { param($Ref, [string] $Value) $Ref.id -eq $Value }

    # Who
    $a = $Policy.assignments
    $who = [System.Collections.Generic.List[string]]::new()
    $incUsers = @($a.includeUsers)
    if ($incUsers | Where-Object { & $isBuiltIn $_ 'All' }) { $who.Add('all users') }
    elseif ($incUsers | Where-Object { & $isBuiltIn $_ 'GuestsOrExternalUsers' }) { $who.Add('guests and external users') }
    elseif ($a.includeGuestsOrExternal) { $who.Add('guests and external users') }
    $namedUsers = @($incUsers | Where-Object { $_.type -ne 'builtIn' })
    if ($namedUsers.Count -gt 0) { $who.Add((& $listOf $namedUsers 'user' 'users')) }
    if (@($a.includeGroups).Count -gt 0) { $who.Add((& $listOf $a.includeGroups 'members of' 'groups')) }
    if (@($a.includeRoles).Count -gt 0) { $who.Add((& $listOf $a.includeRoles 'users in' 'roles')) }
    $sps = @($a.includeServicePrincipals)
    if ($sps | Where-Object { & $isBuiltIn $_ 'ServicePrincipalsInMyTenant' }) { $who.Add('all workload identities in the tenant') }
    elseif ($sps.Count -gt 0) { $who.Add((& $listOf $sps 'workload identity' 'workload identities')) }
    $whoText = if ($who.Count -gt 0) { $who -join ', ' } else { 'no one (empty assignment)' }

    # What (apps, actions, contexts)
    $t = $Policy.targets
    $what = [System.Collections.Generic.List[string]]::new()
    $incApps = @($t.includeApplications)
    if ($incApps | Where-Object { & $isBuiltIn $_ 'All' }) { $what.Add('all cloud apps') }
    if ($incApps | Where-Object { & $isBuiltIn $_ 'Office365' }) { $what.Add('Office 365') }
    if ($incApps | Where-Object { & $isBuiltIn $_ 'MicrosoftAdminPortals' }) { $what.Add('Microsoft admin portals') }
    $namedApps = @($incApps | Where-Object { $_.type -ne 'builtIn' -and $_.id -ne 'None' })
    if ($namedApps.Count -gt 0) { $what.Add((& $listOf $namedApps '' 'apps').Trim()) }
    if (@($t.userActions).Count -gt 0) { $what.Add("the action '$(@($t.userActions | ForEach-Object { $_.name.ToLowerInvariant() }) -join "', '")'") }
    if (@($t.authenticationContexts).Count -gt 0) { $what.Add("authentication context $(@($t.authenticationContexts | ForEach-Object { $_.name }) -join ', ')") }
    $whatText = if ($what.Count -gt 0) { $what -join ', ' } else { 'no target resources' }
    $excApps = @($t.excludeApplications)
    if ($excApps.Count -gt 0) { $whatText += " except $(@($excApps | ForEach-Object { $_.name }) -join ', ')" }

    # Where and how
    $c = $Policy.conditions
    $tail = [System.Collections.Generic.List[string]]::new()
    if (@($c.includePlatforms).Count -eq 0) { $tail.Add('any platform') }
    else {
        $plat = if (@($c.includePlatforms) -contains 'all') { 'on all platforms' } else { "on $(@($c.includePlatforms) -join ', ')" }
        if (@($c.excludePlatforms).Count -gt 0) { $plat += " except $(@($c.excludePlatforms) -join ', ')" }
        $tail.Add($plat)
    }
    $incLoc = @($c.includeLocations); $excLoc = @($c.excludeLocations)
    if ($incLoc.Count -gt 0) {
        $loc = if ($incLoc | Where-Object { & $isBuiltIn $_ 'All' }) { 'from any location' } else { "from $(@($incLoc | ForEach-Object { $_.name }) -join ', ')" }
        if ($excLoc.Count -gt 0) {
            $excNames = @($excLoc | ForEach-Object { if (& $isBuiltIn $_ 'AllTrusted') { 'trusted locations' } else { $_.name } })
            $loc += " except $($excNames -join ', ')"
        }
        $tail.Add($loc)
    }
    $clientTypes = @($c.clientAppTypes | Where-Object { $_ })
    $legacy = @('exchangeActiveSync', 'other')
    if ($clientTypes.Count -gt 0 -and $clientTypes -notcontains 'all') {
        if (@($clientTypes | Where-Object { $_ -notin $legacy }).Count -eq 0) { $tail.Add('for legacy authentication clients') }
        elseif (@($clientTypes | Where-Object { $_ -in $legacy }).Count -eq 0) { $tail.Add('for browsers and modern clients') }
        else { $tail.Add("for client types $($clientTypes -join ', ')") }
    }
    if (@($c.signInRiskLevels).Count -gt 0) { $tail.Add("when sign-in risk is $(@($c.signInRiskLevels) -join ' or ')") }
    if (@($c.userRiskLevels).Count -gt 0) { $tail.Add("when user risk is $(@($c.userRiskLevels) -join ' or ')") }
    if ($c.deviceFilter) { $tail.Add("with a device filter ($($c.deviceFilter.mode))") }

    # Action
    $g = $Policy.grant
    $controlLabel = @{
        block = 'Block access'; mfa = 'Require MFA'; compliantDevice = 'Require a compliant device'
        domainJoinedDevice = 'Require a hybrid-joined device'; approvedApplication = 'Require an approved client app'
        compliantApplication = 'Require an app protection policy'; passwordChange = 'Require a password change'
        unknownFutureValue = 'Require an unknown control'
    }
    $actions = [System.Collections.Generic.List[string]]::new()
    foreach ($ctl in @($g.builtInControls)) { $actions.Add($(if ($controlLabel.ContainsKey($ctl)) { $controlLabel[$ctl] } else { "Require $ctl" })) }
    if ($g.authenticationStrength) { $actions.Add("Require $($g.authenticationStrength.name)") }
    if (@($g.termsOfUse).Count -gt 0) { $actions.Add('Require terms of use') }
    $joiner = if ($g.operator -eq 'AND') { ' and ' } else { ' or ' }
    $sessionText = Get-PostureCaSessionSummary -Session $Policy.session
    $action = if ($actions.Count -gt 0) {
        if ($actions.Count -eq 1) { $actions[0] }
        else { $actions[0] + $joiner + (@($actions | Select-Object -Skip 1 | ForEach-Object { $_.Substring(0, 1).ToLowerInvariant() + $_.Substring(1) }) -join $joiner) }
    }
    elseif ($sessionText) { "Apply session controls ($sessionText)" }
    else { 'Grant access with no controls' }

    $sentence = "$action for $whoText, $whatText, $($tail -join ', ')."

    # Exclusions
    $excl = [System.Collections.Generic.List[string]]::new()
    foreach ($u in @($a.excludeUsers)) { $excl.Add($u.name) }
    foreach ($gr in @($a.excludeGroups)) { $excl.Add($(if ($null -ne $gr.memberCount) { "$($gr.name) ($($gr.memberCount) members)" } else { $gr.name })) }
    foreach ($r in @($a.excludeRoles)) { $excl.Add("role $($r.name)") }
    foreach ($sp in @($a.excludeServicePrincipals)) { $excl.Add($sp.name) }
    if ($excl.Count -gt 0) { $sentence += " Excludes $($excl -join ', ')." }

    $prefix = switch ($Policy.state) { 'reportOnly' { 'Report-only: ' } 'disabled' { 'Disabled: ' } default { '' } }
    return $prefix + $sentence
}

function Get-PostureCaSessionSummary {
    <#
    .SYNOPSIS
        Short description of a policy's session controls, or $null when it has none: "sign-in frequency 4 hours, non-persistent browser, token protection".
    #>

    [CmdletBinding()]
    [OutputType([string])]
    param(
        [Parameter()] [AllowNull()] [System.Collections.IDictionary] $Session
    )

    $ErrorActionPreference = 'Stop'
    if ($null -eq $Session) { return $null }
    $parts = [System.Collections.Generic.List[string]]::new()
    $sf = $Session['signInFrequency']
    if ($sf -and (Get-PostureValue $sf 'isEnabled')) {
        $parts.Add($(if ((Get-PostureValue $sf 'frequencyInterval') -eq 'everyTime') { 'sign-in frequency every time' } else { "sign-in frequency $(Get-PostureValue $sf 'value') $(Get-PostureValue $sf 'type')" }))
    }
    $pb = $Session['persistentBrowser']
    if ($pb -and (Get-PostureValue $pb 'isEnabled')) {
        $parts.Add($(if ((Get-PostureValue $pb 'mode') -eq 'never') { 'non-persistent browser' } else { 'persistent browser' }))
    }
    $aer = $Session['applicationEnforcedRestrictions']
    if ($aer -and (Get-PostureValue $aer 'isEnabled')) { $parts.Add('app-enforced restrictions') }
    $cas = $Session['cloudAppSecurity']
    if ($cas -and (Get-PostureValue $cas 'isEnabled')) { $parts.Add('Defender for Cloud Apps') }
    $cae = $Session['continuousAccessEvaluation']
    if ($cae) { $parts.Add("continuous access evaluation $(Get-PostureValue $cae 'mode')") }
    $tp = $Session['secureSignInSession']
    if ($tp -and (Get-PostureValue $tp 'isEnabled')) { $parts.Add('token protection') }
    if ($Session['disableResilienceDefaults']) { $parts.Add('resilience defaults off') }
    if ($parts.Count -eq 0) { return $null }
    return ($parts -join ', ')
}