Public/Export-PostureCaSnapshot.ps1
|
# Copyright (c) 2026 Kainor LLC. Source-available, see LICENSE.md. function Export-PostureCaSnapshot { <# .SYNOPSIS Writes a read-only snapshot of the tenant's Conditional Access configuration to one folder per run. .DESCRIPTION Exports the seven files from spec section 5.1 into <OutRoot>/<yyyyMMdd-HHmm>-ca/: policies.json full policy objects, untouched wire JSON named-locations.json all named locations auth-strengths.json built-in and custom authentication strengths auth-context.json authentication context class references resolved-names.json every ID any policy references, mapped to display name and type; deleted objects flagged group-scope.json per included or excluded group: transitive member count and a SHA-256 of the sorted member ids metadata.json tenant, timestamp, account, scopes, API versions used, module version, policy count Requires an existing Microsoft Graph session (Connect-MgGraph) with Policy.Read.All, Directory.Read.All and Group.Read.All. The cmdlet never connects on its own and never writes to the tenant. A failure on one endpoint is written to errors.txt in the run folder and the run continues. Group member UPNs are stored only with -IncludeMembers. Without it, group-scope.json holds counts and hashes. The policy export is pinned to Graph v1.0. Use -ApiVersion beta to capture properties that only the beta schema exposes, such as insider risk conditions (verify). Snapshots compared later should use the same version. .PARAMETER OutRoot Root folder for evidence. Default: ~/tenantkeep/evidence, the audit plan's convention. The run folder is created under it. .PARAMETER OutputFolder Write into this exact folder instead of creating <OutRoot>/<stamp>-ca. Used by Invoke-PostureCollection so one run folder holds every domain's evidence. .PARAMETER IncludeMembers Also store the transitive member list (id, type, display name, UPN) of every referenced group in group-scope.json. .PARAMETER ApiVersion Graph API version for the four Conditional Access endpoints. v1.0 (default) or beta. Recorded in metadata.json. .PARAMETER PassThru Return a summary object (Folder, PolicyCount, Files, Errors) instead of the folder path. .EXAMPLE Connect-MgGraph -Scopes Policy.Read.All, Directory.Read.All, Group.Read.All -NoWelcome Export-PostureCaSnapshot Writes ~/tenantkeep/evidence/20261013-0905-ca/ and returns that path. .EXAMPLE Export-PostureCaSnapshot -OutRoot ./snapshots -IncludeMembers -PassThru Stores member lists for scope diffing and returns a summary object. .OUTPUTS System.String. The run folder path. With -PassThru, a summary object. .LINK docs/posture-spec.md section 5.1 #> [CmdletBinding()] [OutputType([string], [pscustomobject])] param( [Parameter()] [ValidateNotNullOrEmpty()] [string] $OutRoot = (Join-Path $HOME 'tenantkeep' 'evidence'), [string] $OutputFolder, [switch] $IncludeMembers, [ValidateSet('v1.0', 'beta')] [string] $ApiVersion = 'v1.0', [switch] $PassThru ) $ErrorActionPreference = 'Stop' Set-StrictMode -Version Latest $requiredScopes = @('Policy.Read.All', 'Directory.Read.All', 'Group.Read.All') $context = Assert-PostureGraphScope -RequiredScope $requiredScopes $startedUtc = [datetime]::UtcNow $folder = if ($OutputFolder) { New-Item -ItemType Directory -Path $OutputFolder -Force | Out-Null (Resolve-Path -LiteralPath $OutputFolder).Path } else { New-PostureEvidenceFolder -OutRoot $OutRoot -Suffix 'ca' } $script:GraphApiVersionsUsed.Clear() Write-Verbose "Writing CA snapshot to $folder" try { # 1. Raw exports, untouched. $policies = @(Invoke-PostureStep -Label 'CA policies' -Folder $folder -Script { Invoke-PostureGraphRequest -Uri 'identity/conditionalAccess/policies' -ApiVersion $ApiVersion }) $locations = @(Invoke-PostureStep -Label 'Named locations' -Folder $folder -Script { Invoke-PostureGraphRequest -Uri 'identity/conditionalAccess/namedLocations' -ApiVersion $ApiVersion }) $strengths = @(Invoke-PostureStep -Label 'Authentication strengths' -Folder $folder -Script { Invoke-PostureGraphRequest -Uri 'policies/authenticationStrengthPolicies' -ApiVersion $ApiVersion }) $contexts = @(Invoke-PostureStep -Label 'Authentication context' -Folder $folder -Script { Invoke-PostureGraphRequest -Uri 'identity/conditionalAccess/authenticationContextClassReferences' -ApiVersion $ApiVersion }) $files = [System.Collections.Generic.List[string]]::new() $files.Add((Write-PostureEvidence -Folder $folder -Name 'policies' -InputObject $policies -AsArray)) $files.Add((Write-PostureEvidence -Folder $folder -Name 'named-locations' -InputObject $locations -AsArray)) $files.Add((Write-PostureEvidence -Folder $folder -Name 'auth-strengths' -InputObject $strengths -AsArray)) $files.Add((Write-PostureEvidence -Folder $folder -Name 'auth-context' -InputObject $contexts -AsArray)) # 2. Resolve every referenced ID to a name and type. $refs = Get-PostureCaReference -Policy $policies $resolved = Invoke-PostureStep -Label 'Resolve names' -Folder $folder -Script { Resolve-PostureCaName -Reference $refs -Location $locations -Strength $strengths -Context $contexts } if ($null -eq $resolved) { $resolved = [ordered]@{} } $files.Add((Write-PostureEvidence -Folder $folder -Name 'resolved-names' -InputObject $resolved)) # 3. Group scope: count and hash per referenced group, members only on request. $groupScope = foreach ($groupId in ($refs['groups'] | Sort-Object)) { $entry = Get-PostureValue $resolved $groupId if ($entry -and $entry['deleted']) { [ordered]@{ groupId = $groupId; deleted = $true; memberCount = $null; memberHash = $null } continue } $scope = Invoke-PostureStep -Label "Group members $groupId" -Folder $folder -Script { Get-PostureGroupScope -GroupId $groupId -IncludeMembers:$IncludeMembers } if ($scope) { $scope } else { [ordered]@{ groupId = $groupId; error = $true; memberCount = $null; memberHash = $null } } } $files.Add((Write-PostureEvidence -Folder $folder -Name 'group-scope' -InputObject @($groupScope) -AsArray)) # 4. Metadata. $errorsPath = Join-Path $folder 'errors.txt' $errorCount = if (Test-Path $errorsPath) { @(Get-Content -Path $errorsPath).Count } else { 0 } $metadata = [ordered]@{ product = 'TenantKeep.Posture' moduleVersion = $script:ModuleVersion snapshotType = 'conditional-access' snapshotSchema = 1 tenantId = $context.TenantId account = $context.Account authType = $context.AuthType scopes = @($context.Scopes | Sort-Object) timestampUtc = $startedUtc.ToString('o') completedUtc = [datetime]::UtcNow.ToString('o') graphApiVersions = @($script:GraphApiVersionsUsed | Sort-Object) modules = (Get-PostureModuleVersionUsed) policyCount = $policies.Count namedLocationCount = $locations.Count authStrengthCount = $strengths.Count authContextCount = $contexts.Count groupCount = @($groupScope).Count includeMembers = [bool]$IncludeMembers errorCount = $errorCount powerShell = $PSVersionTable.PSVersion.ToString() platform = [System.Runtime.InteropServices.RuntimeInformation]::OSDescription } $files.Add((Write-PostureEvidence -Folder $folder -Name 'metadata' -InputObject $metadata)) if ($errorCount -gt 0) { Write-Warning "$errorCount step(s) failed; see $errorsPath" } if ($PassThru) { return [pscustomobject]@{ Folder = $folder PolicyCount = $policies.Count GroupCount = @($groupScope).Count Errors = $errorCount Files = $files.ToArray() Metadata = $metadata } } return $folder } finally { if (-not $OutputFolder) { try { Stop-Transcript | Out-Null } catch { Write-Verbose 'No transcript to stop.' } } } } |