Private/Get-PostureCaRiskChange.ps1

# Copyright (c) 2026 Kainor LLC. Source-available, see LICENSE.md.
function Get-PostureCaStrengthLevel {
    <#
    .SYNOPSIS
        Ranks what a policy demands: 3 phishing-resistant, 2 passwordless, 1 any MFA, 0 nothing.
    #>

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

    $ErrorActionPreference = 'Stop'
    $phishingResistant = @('fido2', 'windowsHelloForBusiness', 'x509CertificateMultiFactor')
    $st = $Policy.grant.authenticationStrength
    if ($st -and @($st.allowedCombinations).Count -gt 0) {
        $combos = @($st.allowedCombinations)
        if (@($combos | Where-Object { $_ -notin $phishingResistant }).Count -eq 0) { return 3 }
        if (@($combos | Where-Object { $_ -match 'password' }).Count -eq 0) { return 2 }
        return 1
    }
    if ($st) { return 1 }
    if (@($Policy.grant.builtInControls) -contains 'mfa') { return 1 }
    return 0
}

function Get-PostureCaRiskChange {
    <#
    .SYNOPSIS
        Applies the spec 5.3 risk-relevant change rules to a Compare-PostureCaModel result.
    .DESCRIPTION
        Rules: exclusionAdded (to an MFA or legacy-auth policy), stateWeakened (enabled to report-only or disabled),
        breakGlassExclusionRemoved, trustedLocationAdded (new trusted location, location made trusted, or ranges
        changed on a trusted location), authStrengthWeakened (policy demands less, or a strength definition allows
        more), deviceComplianceRemoved, deletedReference (new), and enabledPolicyRemoved, which the spec list omits
        but is the loudest change of all.
    .PARAMETER BreakGlass
        UPNs or display names of break-glass accounts. Default: any excluded user whose name or UPN matches
        break-glass or emergency.
    #>

    [CmdletBinding()]
    [OutputType([System.Collections.Specialized.OrderedDictionary[]])]
    param(
        [Parameter(Mandatory)] [System.Collections.IDictionary] $Diff,
        [string[]] $BreakGlass
    )

    $ErrorActionPreference = 'Stop'
    $risks = [System.Collections.Generic.List[object]]::new()
    $add = { param([string] $Rule, [string] $Subject, [string] $Id, [string] $Detail) $risks.Add([ordered]@{ rule = $Rule; subject = $Subject; id = $Id; detail = $Detail }) }
    $split = { param([string] $s) if ([string]::IsNullOrEmpty($s)) { @() } else { @($s -split '; ') } }

    $isBreakGlass = {
        param($Ref)
        $name = [string]$Ref.name; $upn = [string](Get-PostureValue $Ref 'userPrincipalName')
        if ($BreakGlass) { return [bool]($BreakGlass | Where-Object { $_ -eq $name -or $_ -eq $upn }) }
        return ($name -match '(?i)break.?glass|emergency') -or ($upn -match '(?i)break.?glass|emergency')
    }
    $isMfaOrLegacy = {
        param($P)
        if ((Get-PostureCaStrengthLevel -Policy $P) -ge 1) { return $true }
        $types = @($P.conditions.clientAppTypes)
        $legacyOnly = $types.Count -gt 0 -and @($types | Where-Object { $_ -notin @('exchangeActiveSync', 'other') }).Count -eq 0
        return $legacyOnly -and (@($P.grant.builtInControls) -contains 'block')
    }

    foreach ($r in @($Diff.policies.removed)) {
        if ($r.state -eq 'enabled') { & $add 'enabledPolicyRemoved' $r.name $r.id 'An enabled policy was deleted. Whatever it enforced is no longer enforced.' }
    }
    foreach ($a in @($Diff.policies.added)) {
        $deleted = @($a.after.healthFlags | Where-Object { $_.code -eq 'deletedReference' })
        foreach ($f in $deleted) { & $add 'deletedReference' $a.name $a.id $f.message }
    }

    foreach ($c in @($Diff.policies.changed)) {
        $b = $c.before; $a = $c.after
        if ($c.stateChanged -and $c.stateBefore -eq 'enabled' -and $c.stateAfter -in @('reportOnly', 'disabled')) {
            & $add 'stateWeakened' $c.name $c.id "Moved from enabled to $($c.stateAfter). It no longer enforces anything."
        }
        if (& $isMfaOrLegacy $a) {
            foreach ($path in 'assignments.excludeUsers', 'assignments.excludeGroups', 'assignments.excludeRoles') {
                $field = $c.fields | Where-Object { $_.path -eq $path }
                if (-not $field) { continue }
                $new = @((& $split $field.after) | Where-Object { $_ -notin (& $split $field.before) })
                if ($new.Count -gt 0) { & $add 'exclusionAdded' $c.name $c.id "Exclusion added on an MFA or legacy-auth policy: $($new -join ', ') ($($path -replace '^assignments\.', ''))." }
            }
        }
        $afterIds = @($a.assignments.excludeUsers | ForEach-Object { $_.id })
        foreach ($u in @($b.assignments.excludeUsers)) {
            if ($u.id -notin $afterIds -and (& $isBreakGlass $u)) {
                & $add 'breakGlassExclusionRemoved' $c.name $c.id "Break-glass account $($u.name) was removed from the exclusions. A policy misfire can now lock the tenant out."
            }
        }
        $lb = Get-PostureCaStrengthLevel -Policy $b; $la = Get-PostureCaStrengthLevel -Policy $a
        if ($la -lt $lb) {
            $labels = @('no MFA requirement', 'any MFA', 'passwordless MFA', 'phishing-resistant MFA')
            & $add 'authStrengthWeakened' $c.name $c.id "Required strength dropped from $($labels[$lb]) to $($labels[$la])."
        }
        $deviceControls = @('compliantDevice', 'domainJoinedDevice')
        $hadDevice = @($b.grant.builtInControls | Where-Object { $_ -in $deviceControls }).Count -gt 0
        $hasDevice = @($a.grant.builtInControls | Where-Object { $_ -in $deviceControls }).Count -gt 0
        if ($hadDevice -and -not $hasDevice) { & $add 'deviceComplianceRemoved' $c.name $c.id 'The device compliance or hybrid-join requirement was removed.' }
        $beforeDeleted = @($b.healthFlags | Where-Object { $_.code -eq 'deletedReference' } | ForEach-Object { $_.message })
        foreach ($f in @($a.healthFlags | Where-Object { $_.code -eq 'deletedReference' })) {
            if ($f.message -notin $beforeDeleted) { & $add 'deletedReference' $c.name $c.id $f.message }
        }
    }

    foreach ($l in @($Diff.locations.added)) {
        if (Get-PostureValue $l.after 'isTrusted') { & $add 'trustedLocationAdded' $l.name $l.id 'A new trusted named location. Policies that exclude trusted locations now skip it.' }
    }
    foreach ($l in @($Diff.locations.changed)) {
        $trustedField = $l.fields | Where-Object { $_.path -eq 'isTrusted' }
        if ($trustedField -and $trustedField.after -eq 'True') { & $add 'trustedLocationAdded' $l.name $l.id 'An existing named location was marked trusted.' }
        elseif ((Get-PostureValue $l.after 'isTrusted') -and @($l.fields | Where-Object { $_.path -like 'ipRanges*' -or $_.path -like 'countriesAndRegions*' }).Count -gt 0) {
            & $add 'trustedLocationAdded' $l.name $l.id 'The ranges of a trusted named location changed. Every policy that excludes trusted locations is affected.'
        }
    }

    foreach ($s in @($Diff.strengths.changed)) {
        $field = $s.fields | Where-Object { $_.path -eq 'allowedCombinations' }
        if (-not $field) { continue }
        $gained = @((& $split $field.after) | Where-Object { $_ -notin (& $split $field.before) })
        if ($gained.Count -gt 0) { & $add 'authStrengthWeakened' $s.name $s.id "Strength definition now also allows: $($gained -join ', '). Every policy using it accepts weaker sign-ins." }
    }

    return $risks.ToArray()
}