schedules/ca-snapshot-cycle.ps1
|
#Requires -Version 7.4 # Copyright (c) 2026 Kainor LLC. Source-available, see LICENSE.md. <# .SYNOPSIS One Conditional Access monitoring cycle: snapshot, document, compare with the previous run, notify, prune. .DESCRIPTION The shared body behind the three schedulers in deploy/schedules (Azure Automation runbook, GitHub Action, macOS launchd). Expects an existing Microsoft Graph session; each scheduler signs in its own way before calling this. Steps: 1. Export-PostureCaSnapshot into <OutRoot>/<stamp>-ca 2. New-PostureCaDocument for the new snapshot, with the Coverage findings page, and checks.json next to it 3. Compare-PostureCaSnapshot against the newest earlier <stamp>-ca folder, when one exists 4. Notify, when there are risk-relevant changes (or always, with -EmailAlways): Teams Workflows webhook card, when -TeamsWebhookUrl is set email with ca-changes.html attached, when -EmailTo and -EmailFrom are set, through Graph sendMail (needs Mail.Send on the identity, opt-in) or an SMTP relay (-EmailMethod Smtp) 5. Delete the oldest runs beyond -KeepRuns, when -KeepRuns is greater than 0 Returns a summary object. With -FailOnRiskRelevantChange it throws at the end when the comparison found risk-relevant changes, so the scheduler's job fails and its own alerting fires too. Every send goes to the customer's own services; see ca-notifications.ps1. .EXAMPLE Connect-MgGraph -Identity -NoWelcome ./ca-snapshot-cycle.ps1 -OutRoot /mnt/snapshots -TeamsWebhookUrl $env:TEAMS_WEBHOOK -FailOnRiskRelevantChange .EXAMPLE ./ca-snapshot-cycle.ps1 -OutRoot ~/tenantkeep/evidence -EmailTo secops@contoso.example -EmailFrom ca-monitor@contoso.example Emails through Graph as ca-monitor@contoso.example when a risk-relevant change appears. The identity needs Mail.Send. .EXAMPLE ./ca-snapshot-cycle.ps1 -OutRoot ~/tenantkeep/evidence -EmailTo secops@contoso.example -EmailFrom ca-monitor@contoso.example -EmailMethod Smtp -SmtpServer smtp.contoso.example -SmtpCredential $cred -EmailAlways Daily digest through the customer's SMTP relay, sent even when nothing is risk-relevant. #> [CmdletBinding()] param( [string] $OutRoot = (Join-Path $HOME 'tenantkeep' 'evidence'), [string] $Brand, [string[]] $BreakGlass, [string] $NamePattern, [string] $Baseline = 'standard', [Alias('Profile')] [string] $ProfilePath, [string] $Exceptions, [switch] $IncludeMembers, [string] $TeamsWebhookUrl, [string[]] $EmailTo, [string] $EmailFrom, [ValidateSet('Graph', 'Smtp')] [string] $EmailMethod = 'Graph', [string] $SmtpServer, [int] $SmtpPort = 587, [pscredential] $SmtpCredential, [bool] $SmtpUseTls = $true, [switch] $EmailAlways, [ValidateRange(0, 10000)] [int] $KeepRuns = 0, [switch] $FailOnRiskRelevantChange ) $ErrorActionPreference = 'Stop' Set-StrictMode -Version Latest if (-not (Get-Module -Name TenantKeep.Posture)) { Import-Module TenantKeep.Posture -ErrorAction Stop } . (Join-Path $PSScriptRoot 'ca-notifications.ps1') if ($EmailTo -and -not $EmailFrom) { throw '-EmailFrom is required with -EmailTo.' } $optional = @{} if ($Brand) { $optional.Brand = $Brand } $checkInputs = @{ Baseline = $Baseline } if ($ProfilePath) { $checkInputs.ProfilePath = $ProfilePath } if ($Exceptions) { $checkInputs.Exceptions = $Exceptions } # 1. Snapshot $snapshot = Export-PostureCaSnapshot -OutRoot $OutRoot -IncludeMembers:$IncludeMembers -PassThru $newFolder = $snapshot.Folder Write-Information "Snapshot: $newFolder ($($snapshot.PolicyCount) policies, $($snapshot.Errors) error(s))" -InformationAction Continue # 2. Document $docParams = @{ Snapshot = $newFolder } + $optional + $checkInputs if ($NamePattern) { $docParams.NamePattern = $NamePattern } $documents = @(New-PostureCaDocument @docParams) $checks = Invoke-PostureChecks -Evidence $newFolder -Domain ca @checkInputs -PassThru Write-Information "Checks: pass $($checks.counts.pass), fail $($checks.counts.fail), not evaluated $($checks.counts.notEvaluated)" -InformationAction Continue # 3. Compare with the previous run $previous = Get-ChildItem -Path $OutRoot -Directory | Where-Object { $_.Name -match '^\d{8}-\d{4}-ca$' -and $_.FullName -ne $newFolder } | Sort-Object Name | Select-Object -Last 1 $comparison = $null if ($previous) { $cmpParams = @{ Before = $previous.FullName; After = $newFolder; PassThru = $true } + $optional if ($BreakGlass) { $cmpParams.BreakGlass = $BreakGlass } $comparison = Compare-PostureCaSnapshot @cmpParams Write-Information "Compared with $($previous.Name): $($comparison.RiskRelevantCount) risk-relevant change(s)" -InformationAction Continue } else { Write-Information 'No earlier snapshot under OutRoot; nothing to compare. The next run will diff against this one.' -InformationAction Continue } # 4. Notify $notified = @() if ($comparison) { $risky = $comparison.HasRiskRelevantChanges $beforeName = $previous.Name $afterName = Split-Path $newFolder -Leaf if ($risky -and $TeamsWebhookUrl) { Send-CaTeamsCard -WebhookUrl $TeamsWebhookUrl -Comparison $comparison -BeforeName $beforeName -AfterName $afterName $notified += 'teams' Write-Information 'Posted the risk-relevant changes to Teams.' -InformationAction Continue } if ($EmailTo -and ($risky -or $EmailAlways)) { $tenantLabel = [string]$comparison.Diff.after.tenantId if ($Brand) { $clientName = (Get-Content -Raw -LiteralPath $Brand | ConvertFrom-Json).client.name; if ($clientName) { $tenantLabel = $clientName } } $content = Get-CaChangeNotificationContent -Comparison $comparison -BeforeName $beforeName -AfterName $afterName -TenantLabel $tenantLabel $html = @($comparison.Files | Where-Object { $_ -like '*.html' }) $mailParams = @{ To = $EmailTo; From = $EmailFrom; Subject = $content.Subject; HtmlBody = $content.Body; AttachmentPath = $html; Method = $EmailMethod; SmtpUseTls = $SmtpUseTls; SmtpPort = $SmtpPort } if ($SmtpServer) { $mailParams.SmtpServer = $SmtpServer } if ($SmtpCredential) { $mailParams.SmtpCredential = $SmtpCredential } Send-CaChangeEmail @mailParams $notified += "email:$($EmailMethod.ToLowerInvariant())" Write-Information "Emailed $($EmailTo -join ', ') through $EmailMethod." -InformationAction Continue } } # 5. Prune $pruned = @() if ($KeepRuns -gt 0) { $runs = Get-ChildItem -Path $OutRoot -Directory | Where-Object { $_.Name -match '^\d{8}-\d{4}-ca$' } | Sort-Object Name $excess = $runs.Count - $KeepRuns if ($excess -gt 0) { foreach ($old in ($runs | Select-Object -First $excess)) { Remove-Item -LiteralPath $old.FullName -Recurse -Force $pruned += $old.Name } } } $result = [pscustomobject]@{ Snapshot = $newFolder Previous = $(if ($previous) { $previous.FullName } else { $null }) Documents = $documents Checks = (Join-Path $newFolder 'checks.json') CheckCounts = $checks.counts ChangeReports = $(if ($comparison) { $comparison.Files } else { @() }) RiskRelevantCount = $(if ($comparison) { $comparison.RiskRelevantCount } else { 0 }) HasRiskRelevantChanges = [bool]($comparison -and $comparison.HasRiskRelevantChanges) Notified = $notified Pruned = $pruned } if ($FailOnRiskRelevantChange -and $result.HasRiskRelevantChanges) { $result | Format-List | Out-String | Write-Information -InformationAction Continue throw "$($result.RiskRelevantCount) risk-relevant Conditional Access change(s). See $($result.ChangeReports -join ', ')" } return $result |