Public/Compare-PostureCaSnapshot.ps1

# Copyright (c) 2026 Kainor LLC. Source-available, see LICENSE.md.
function Compare-PostureCaSnapshot {
    <#
    .SYNOPSIS
        Compares two Export-PostureCaSnapshot folders and writes an email-ready change report (spec 5.3).
    .DESCRIPTION
        Reports policies added, removed, renamed, state changed and modified with field-level before and after
        using resolved names; named location, authentication strength and authentication context changes; scope
        drift for every group a policy references (member-level when both snapshots were taken with
        -IncludeMembers); and, at the top, the risk-relevant changes: an exclusion added to an MFA or legacy-auth
        policy, a policy moved from enabled to report-only or disabled, a break-glass account removed from an
        exclusion, a trusted location added or widened, an authentication strength weakened, a device compliance
        requirement removed, a policy now referencing a deleted object, and an enabled policy deleted.

        Reads only the two folders. No Graph session is needed.

        For a scheduled runbook that must alert on risk, use -FailOnRiskRelevantChange: the report is written first,
        then the cmdlet throws, so `pwsh -Command` exits non-zero. Without it, inspect HasRiskRelevantChanges on the
        -PassThru object.
    .PARAMETER Before
        The older snapshot folder.
    .PARAMETER After
        The newer snapshot folder.
    .PARAMETER OutputPath
        Folder for ca-changes.md and ca-changes.html. Default: the After folder.
    .PARAMETER Format
        Markdown, Html, or both. Default: both.
    .PARAMETER Brand
        Path to brand.json (spec 7.5).
    .PARAMETER BreakGlass
        UPNs or display names of the break-glass accounts. Default: excluded users whose name or UPN contains
        break-glass or emergency.
    .PARAMETER FailOnRiskRelevantChange
        Throw after writing the report when any risk-relevant change exists.
    .PARAMETER PassThru
        Return an object with Files, Diff, RiskRelevantCount and HasRiskRelevantChanges instead of the file paths.
    .EXAMPLE
        Compare-PostureCaSnapshot -Before ~/tenantkeep/evidence/20261013-0905-ca -After ~/tenantkeep/evidence/20261014-0905-ca

        Writes ca-changes.md and ca-changes.html into the newer folder.
    .EXAMPLE
        pwsh -Command "Compare-PostureCaSnapshot -Before ./prev -After ./latest -FailOnRiskRelevantChange"

        Exit code 1 when a risk-relevant change is present, for a runbook or a GitHub Action step.
    .OUTPUTS
        System.String. Written file paths. With -PassThru, a summary object.
    .LINK
        docs/posture-spec.md section 5.3
    #>

    [CmdletBinding()]
    [OutputType([string], [pscustomobject])]
    param(
        [Parameter(Mandatory, Position = 0)] [ValidateNotNullOrEmpty()] [string] $Before,
        [Parameter(Mandatory, Position = 1)] [ValidateNotNullOrEmpty()] [string] $After,
        [string] $OutputPath,
        [ValidateSet('Markdown', 'Html')] [string[]] $Format = @('Markdown', 'Html'),
        [string] $Brand,
        [string[]] $BreakGlass,
        [switch] $FailOnRiskRelevantChange,
        [switch] $PassThru
    )

    $ErrorActionPreference = 'Stop'
    Set-StrictMode -Version Latest

    $beforeSnap = Import-PostureCaSnapshot -Path $Before
    $afterSnap = Import-PostureCaSnapshot -Path $After
    $brandModel = Import-PostureBrand -Path $Brand

    $bTenant = Get-PostureValue $beforeSnap.Metadata 'tenantId'
    $aTenant = Get-PostureValue $afterSnap.Metadata 'tenantId'
    if ($bTenant -and $aTenant -and $bTenant -ne $aTenant) {
        Write-Warning "The snapshots come from different tenants ($bTenant and $aTenant). The comparison is still produced."
    }

    $diffParams = @{ Before = $beforeSnap; After = $afterSnap }
    if ($BreakGlass) { $diffParams.BreakGlass = $BreakGlass }
    $diff = Compare-PostureCaModel @diffParams

    $counts = [ordered]@{
        added        = @($diff.policies.added).Count
        removed      = @($diff.policies.removed).Count
        renamed      = @($diff.policies.changed | Where-Object { $_.renamed }).Count
        stateChanged = @($diff.policies.changed | Where-Object { $_.stateChanged }).Count
        modified     = @($diff.policies.changed | Where-Object { $_.modified }).Count
        locations    = @($diff.locations.added).Count + @($diff.locations.removed).Count + @($diff.locations.changed).Count
        strengths    = @($diff.strengths.added).Count + @($diff.strengths.removed).Count + @($diff.strengths.changed).Count
        contexts     = @($diff.contexts.added).Count + @($diff.contexts.removed).Count + @($diff.contexts.changed).Count
        scope        = @($diff.scope).Count
        risk         = @($diff.risk).Count
    }
    $noChanges = (($counts.Values | Measure-Object -Sum).Sum -eq 0)

    $clientName = if ($brandModel.client.name) { [string]$brandModel.client.name } else { [string]$aTenant }
    $report = [ordered]@{
        title         = "Conditional Access changes: $clientName"
        brand         = $brandModel
        generatedUtc  = [datetime]::UtcNow
        moduleVersion = $script:ModuleVersion
        breakGlass    = @($BreakGlass)
        counts        = $counts
        noChanges     = $noChanges
        diff          = $diff
    }

    $outFolder = if ($OutputPath) { $OutputPath } else { $afterSnap.Path }
    if (-not (Test-Path -LiteralPath $outFolder)) { New-Item -ItemType Directory -Path $outFolder -Force | Out-Null }
    $outFolder = (Resolve-Path -LiteralPath $outFolder).Path

    $written = [System.Collections.Generic.List[string]]::new()
    foreach ($f in @('Markdown', 'Html')) {
        if ($Format -notcontains $f) { continue }
        $ext, $content = switch ($f) {
            'Markdown' { 'md', (ConvertTo-PostureCaDiffMarkdown -Report $report) }
            'Html' { 'html', (ConvertTo-PostureCaDiffHtml -Report $report) }
        }
        $path = Join-Path $outFolder "ca-changes.$ext"
        [System.IO.File]::WriteAllText($path, $content, [System.Text.UTF8Encoding]::new($false))
        $written.Add($path)
    }

    $riskCount = @($diff.risk).Count
    if ($riskCount -gt 0) { Write-Warning "$riskCount risk-relevant change(s). See $($written -join ', ')" }

    $result = [pscustomobject]@{
        Files                  = $written.ToArray()
        Diff                   = $diff
        Counts                 = $counts
        RiskRelevantCount      = $riskCount
        HasRiskRelevantChanges = ($riskCount -gt 0)
    }
    if ($FailOnRiskRelevantChange -and $riskCount -gt 0) {
        throw "$riskCount risk-relevant Conditional Access change(s) between $($beforeSnap.Path) and $($afterSnap.Path): $(@($diff.risk | ForEach-Object { "$($_.rule) ($($_.subject))" }) -join '; '). Report: $($written -join ', ')"
    }
    if ($PassThru) { return $result }
    return $written.ToArray()
}