schedules/posture-runbook.ps1
|
#Requires -Version 7.4 # Copyright (c) 2026 Kainor LLC. Source-available, see LICENSE.md. <# .SYNOPSIS Azure Automation runbook (PowerShell 7.4 runtime): the monthly full posture cycle with the account's managed identity. .DESCRIPTION Deployed by deploy/automation/deploy.ps1 -IncludePosture. One job does what an admin does by hand over an afternoon: 1. sign in as the managed identity: Graph and Azure first and every Graph call before PnP loads (its old Microsoft.Graph.Core breaks the Graph SDK), then Exchange, Purview (certificate app from the customer's Key Vault, when New-PosturePurviewApp.ps1 has run), then SharePoint and Teams 2. download the client container: profile.json, brand.json, exceptions.json, tenantkeep.lic, findings.csv and any ad-* files a hybrid tenant's Windows collector produced 3. Invoke-PostureCollection into a work folder (every collector whose session opened) 4. New-PostureReport against the previous run for the trend, Export-PostureFindings merged with the register 5. upload the run to the posture container, write findings.csv back to the client container, prune old runs A collector whose sign-in fails is skipped with the reason in the job output; the report says which domains were not collected. Nothing here writes to the tenant: sign-ins and reads only, storage in the customer's own subscription. Identity roles: Grant-ManagedIdentityGraphRole.ps1 -IncludePosture (Graph application roles, Exchange.ManageAsApp, SharePoint Sites.FullControl.All (verify: the least SharePoint application permission that lets Get-PnPTenant read), the Teams tenant admin API role, Global Reader), plus Reader and Security Reader on the subscriptions. Variables: TENANTKEEP_POSTURE_CONTAINER_URL, TENANTKEEP_CLIENT_CONTAINER_URL, TENANTKEEP_POSTURE_KEEP_RUNS, TENANTKEEP_ORGANIZATION, TENANTKEEP_SHAREPOINT_ADMIN_URL, TENANTKEEP_PURVIEW_APP_ID, TENANTKEEP_PURVIEW_CERT (a Key Vault secret URL, never the certificate), TEAMS_WEBHOOK, EMAIL_TO, EMAIL_FROM. #> [CmdletBinding()] param() $ErrorActionPreference = 'Stop' Set-StrictMode -Version Latest try { Write-Output "step: read variables (PowerShell $($PSVersionTable.PSVersion))" $getVar = { param([string] $Name) try { ([string](Get-AutomationVariable -Name $Name)).Trim('"') } catch { '' } } $postureUrl = & $getVar 'TENANTKEEP_POSTURE_CONTAINER_URL' $clientUrl = & $getVar 'TENANTKEEP_CLIENT_CONTAINER_URL' if (-not $postureUrl -or -not $clientUrl) { throw 'Automation variables TENANTKEEP_POSTURE_CONTAINER_URL and TENANTKEEP_CLIENT_CONTAINER_URL must be set (deploy with -IncludePosture).' } $keepRuns = [int]((& $getVar 'TENANTKEEP_POSTURE_KEEP_RUNS') -replace '[^0-9]', '0') $organization = & $getVar 'TENANTKEEP_ORGANIZATION' $spoAdmin = & $getVar 'TENANTKEEP_SHAREPOINT_ADMIN_URL' $purviewAppId = & $getVar 'TENANTKEEP_PURVIEW_APP_ID' $purviewCert = & $getVar 'TENANTKEEP_PURVIEW_CERT' $webhook = & $getVar 'TEAMS_WEBHOOK' $emailTo = @(((& $getVar 'EMAIL_TO')) -split ',' | ForEach-Object { $_.Trim() } | Where-Object { $_ }) $emailFrom = & $getVar 'EMAIL_FROM' $accountName = ([uri]$postureUrl).Host.Split('.')[0] $postureContainer = ([uri]$postureUrl).AbsolutePath.Trim('/') $clientContainer = ([uri]$clientUrl).AbsolutePath.Trim('/') $blobBase = "https://$accountName.blob.core.windows.net" # Blob storage over REST with the identity's token. Az.Storage is deliberately not used: it and ExchangeOnlineManagement # each ship a Microsoft.OData.Core, and whichever loads second fails, which costs either the mailbox reads or the upload. $blobToken = { $t = Get-AzAccessToken -ResourceUrl 'https://storage.azure.com/' -WarningAction SilentlyContinue if ($t.Token -is [securestring]) { ConvertFrom-SecureString -SecureString $t.Token -AsPlainText } else { [string]$t.Token } } $blobHeaders = { @{ Authorization = "Bearer $(& $blobToken)"; 'x-ms-version' = '2021-12-02'; 'x-ms-date' = [datetime]::UtcNow.ToString('R') } } $blobList = { param([string] $Container, [string] $Prefix = '') $names = [System.Collections.Generic.List[string]]::new(); $marker = '' do { $uri = "$blobBase/$Container`?restype=container&comp=list&prefix=$([uri]::EscapeDataString($Prefix))$(if ($marker) { "&marker=$([uri]::EscapeDataString($marker))" })" $text = [string](Invoke-WebRequest -Uri $uri -Headers (& $blobHeaders) -Method Get).Content $xml = [xml]$text.TrimStart([char]0xFEFF) # the listing starts with a byte order mark the XML parser rejects foreach ($b in @($xml.SelectNodes('/EnumerationResults/Blobs/Blob'))) { if ($b -and $b.Name) { $names.Add([string]$b.Name) } } # an empty container has a Blobs element with no children; strict mode has no .Blob on that $marker = [string]$xml.EnumerationResults.NextMarker } while ($marker) return $names.ToArray() # callers wrap in @(); a leading comma here would hand them a nested array } $blobGet = { param([string] $Container, [string] $Name, [string] $Path) Invoke-WebRequest -Uri "$blobBase/$Container/$Name" -Headers (& $blobHeaders) -Method Get -OutFile $Path | Out-Null } $blobPut = { param([string] $Container, [string] $Name, [string] $Path) $h = & $blobHeaders; $h['x-ms-blob-type'] = 'BlockBlob'; Invoke-WebRequest -Uri "$blobBase/$Container/$Name" -Headers $h -Method Put -InFile $Path -ContentType 'application/octet-stream' | Out-Null } $blobDelete = { param([string] $Container, [string] $Name) Invoke-WebRequest -Uri "$blobBase/$Container/$Name" -Headers (& $blobHeaders) -Method Delete | Out-Null } # ---- 1. Graph and Azure first. The session-bound modules are imported only after the last Graph call (see 4b). Write-Output 'step: sign in (Azure, Graph)' $null = Connect-AzAccount -Identity Connect-MgGraph -Identity -NoWelcome $ctx = Get-MgContext Write-Output "Graph tenant $($ctx.TenantId), roles: $(@($ctx.Scopes).Count)" if (-not $organization) { $org = Invoke-MgGraphRequest -Method GET -Uri 'https://graph.microsoft.com/v1.0/organization?$select=verifiedDomains' -OutputType HashTable $organization = [string](@($org.value[0].verifiedDomains | Where-Object { $_.isInitial })[0].name) Write-Output "Organization from Graph: $organization" } $skipped = [ordered]@{} # Purview: ExchangeOnlineManagement has no managed identity sign-in for Connect-IPPSSession, so the customer's setup # script (New-PosturePurviewApp.ps1) registers a certificate app with the certificate in the customer's Key Vault. The # identity reads it here, in memory, never to disk (the CLAUDE.md carve-out). Without the variables, Purview is skipped. $purviewOpen = $false if ($purviewAppId -and $purviewCert) { try { $vaultToken = Get-AzAccessToken -ResourceUrl 'https://vault.azure.net' -WarningAction SilentlyContinue $vt = $(if ($vaultToken.Token -is [securestring]) { ConvertFrom-SecureString -SecureString $vaultToken.Token -AsPlainText } else { [string]$vaultToken.Token }) $secret = Invoke-RestMethod -Uri "$purviewCert`?api-version=7.4" -Headers @{ Authorization = "Bearer $vt" } -Method Get $pfx = [Convert]::FromBase64String([string]$secret.value) $purviewCertificate = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new($pfx, [string]$null, [System.Security.Cryptography.X509Certificates.X509KeyStorageFlags]::EphemeralKeySet) Connect-IPPSSession -Certificate $purviewCertificate -AppId $purviewAppId -Organization $organization -ShowBanner:$false $purviewOpen = $true; Write-Output "Purview session open (certificate $($purviewCertificate.Thumbprint.Substring(0, 8))..., expires $($purviewCertificate.NotAfter.ToString('yyyy-MM-dd')))" } catch { $skipped['Purview'] = $_.Exception.Message; Write-Output "Purview sign-in failed; skipped: $($_.Exception.Message)" } } else { $skipped['Purview'] = 'Purview app not configured: run deploy/setup/New-PosturePurviewApp.ps1 once to collect Purview in the scheduled run.' } # Exchange signs in now, before Az.Storage loads: both carry Microsoft.OData.Core, and the mailbox cmdlets need Exchange's newer copy to be the one in memory. $exchangeOpen = $false try { Connect-ExchangeOnline -ManagedIdentity -Organization $organization -ShowBanner:$false; $exchangeOpen = $true # One REST cmdlet now, so Exchange's Microsoft.OData.Core is the copy in memory before Az.Storage brings its older one. $null = Get-EXOMailbox -ResultSize 1 -ErrorAction SilentlyContinue Write-Output 'Exchange session open' } catch { $skipped['Exchange'] = $_.Exception.Message; Write-Output "Exchange sign-in failed; skipped: $($_.Exception.Message)" } Write-Output 'step: import module' Import-Module TenantKeep.Posture Write-Output "module $((Get-Module TenantKeep.Posture).Version) build: $(& (Get-Module TenantKeep.Posture) { $script:PostureBuildState.detail })" $work = Join-Path ([System.IO.Path]::GetTempPath()) 'TenantKeep-Posture' if (Test-Path $work) { Remove-Item -LiteralPath $work -Recurse -Force } $evidenceRoot = Join-Path $work 'evidence'; $client = Join-Path $work 'client' New-Item -ItemType Directory -Path $evidenceRoot, $client -Force | Out-Null # ---- 2. Client files (profile, brand, exceptions, licence, register, hybrid ad-* files). Write-Output 'step: download client container' $clientBlobs = @(& $blobList $clientContainer) foreach ($name in $clientBlobs) { $dest = Join-Path $client ($name -replace '/', [System.IO.Path]::DirectorySeparatorChar) New-Item -ItemType Directory -Path (Split-Path $dest -Parent) -Force | Out-Null & $blobGet $clientContainer $name $dest } Write-Output "client files: $($clientBlobs.Count)" $profilePath = Join-Path $client 'profile.json' if (-not (Test-Path $profilePath)) { Write-Output 'No profile.json in the client container; the report uses discovery defaults. Upload one from New-PostureProfile for thresholds and third-party answers.' } # ---- 3. Previous run, for the trend and the register merge. Write-Output 'step: list previous runs' $blobs = @(& $blobList $postureContainer) $runNames = @($blobs | ForEach-Object { ($_ -split '/')[0] } | Where-Object { $_ -match '^\d{8}-\d{4}$' } | Sort-Object -Unique) $previous = $null if ($runNames.Count -gt 0) { $latest = $runNames[-1]; $previous = Join-Path $evidenceRoot $latest New-Item -ItemType Directory -Path $previous -Force | Out-Null if ($blobs -contains "$latest/checks.json") { & $blobGet $postureContainer "$latest/checks.json" (Join-Path $previous 'checks.json') } Write-Output "previous run $latest" } # ---- 4. Collect: Graph-based collectors and Azure first. Write-Output 'step: collect (Entra, Intune, Defender, Azure)' # Only name collectors whose roles the token carries: a named collector without its role is an error, an unnamed one a warning. $mainCollectors = @('Entra', 'Intune') if ('ThreatHunting.Read.All' -in @($ctx.Scopes)) { $mainCollectors += 'Defender' } else { $skipped['Defender'] = 'ThreatHunting.Read.All is not on the Graph token yet (roles granted recently are cached for up to a day).' } $azureWanted = $true if (Test-Path $profilePath) { try { $pj = Get-Content -Raw -LiteralPath $profilePath | ConvertFrom-Json -AsHashtable; if ($pj -and $pj.Contains('azure') -and [string]$pj['azure'] -eq 'none') { $azureWanted = $false } } catch { Write-Verbose 'profile.json unreadable; Azure stays on.' } } if (-not $azureWanted) { $skipped['Azure'] = 'Profile says azure: none; the Azure domain is not applicable to this tenant.' } elseif ((Get-AzContext -ErrorAction SilentlyContinue) -and (Get-Command Search-AzGraph -ErrorAction SilentlyContinue)) { $mainCollectors += 'Azure' } else { $skipped['Azure'] = 'No Azure context or Az.ResourceGraph not loaded.' } $collectParams = @{ OutRoot = $evidenceRoot; Collector = $mainCollectors; PassThru = $true } if (Test-Path $profilePath) { $collectParams.ProfilePath = $profilePath } $collection = Invoke-PostureCollection @collectParams $folder = [string]$collection.Folder Write-Output "evidence $folder, errors $(@($collection.Errors).Count)" # ---- 4b. Session-bound collectors, in this order and only now: the Graph SDK resolves Microsoft.Graph.Core to the # old copy PnP.PowerShell loads, so every Graph call happens above, before PnP is imported. The sandbox has no pwsh # executable (the host is a custom .NET app), so there is no child process to hide in. Each phase is its own try. $phase = { param([string] $Name, [scriptblock] $Connect, [string[]] $Collectors) try { & $Connect Invoke-PostureCollection -Collector $Collectors -SkipCaSnapshot -OutputFolder $folder @profileParam | Out-Null Write-Output "$Name collected" } catch { $skipped[$Name] = $_.Exception.Message; Write-Output "$Name failed; skipped: $($_.Exception.Message)" } } $profileParam = @{}; if (Test-Path $profilePath) { $profileParam.ProfilePath = $profilePath } Write-Output 'step: collect (Exchange)' if ($exchangeOpen) { & $phase 'Exchange' { } @('Exchange') } Write-Output 'step: collect (Purview)' if ($purviewOpen) { & $phase 'Purview' { } @('Purview') } Write-Output 'step: collect (SharePoint, Teams)' if ($spoAdmin) { & $phase 'SharePoint and Teams' { Connect-PnPOnline -Url $spoAdmin -ManagedIdentity; Connect-MicrosoftTeams -Identity | Out-Null } @('SharePoint', 'Teams') } else { $skipped['SharePoint'] = 'TENANTKEEP_SHAREPOINT_ADMIN_URL not set.' & $phase 'Teams' { Connect-MicrosoftTeams -Identity | Out-Null } @('Teams') } $hybrid = Join-Path $client 'hybrid' if (Test-Path $hybrid) { Copy-Item -Path (Join-Path $hybrid 'ad-*') -Destination $folder -Force; Write-Output 'hybrid ad-* files copied in' } Write-Output 'step: report' $reportParams = @{ Evidence = $folder; Client = $client; PassThru = $true } if ($previous -and (Test-Path (Join-Path $previous 'checks.json'))) { $reportParams.Previous = $previous } $report = New-PostureReport @reportParams Write-Output "report written: $(@($report.Files) -join ', ')" $register = Join-Path $client 'findings.csv' $findingsParams = @{ Path = $folder; OutputPath = (Join-Path $folder 'findings.csv') } if (Test-Path $register) { $findingsParams.Merge = $register } $null = Export-PostureFindings @findingsParams # ---- 5. Upload the run, write the register back, prune. Write-Output 'step: upload' $runName = Split-Path $folder -Leaf foreach ($f in (Get-ChildItem -Path $folder -File)) { & $blobPut $postureContainer "$runName/$($f.Name)" $f.FullName } & $blobPut $clientContainer 'findings.csv' (Join-Path $folder 'findings.csv') Write-Output "uploaded run $runName ($((Get-ChildItem -Path $folder -File).Count) files)" if ($keepRuns -gt 0) { $all = @(@($runNames) + @($runName) | Sort-Object -Unique) foreach ($old in ($all | Select-Object -First ([Math]::Max(0, $all.Count - $keepRuns)))) { foreach ($b in ($blobs | Where-Object { $_ -like "$old/*" })) { & $blobDelete $postureContainer $b } Write-Output "pruned run $old" } } # ---- 6. Tell someone, through the same opt-in channels as the CA cycle. $summary = "TenantKeep Posture run $runName for ${organization}: score $($report.Report.score.value) ($($report.Report.score.grade)), $($report.Report.counts.fail) failing checks. Report: $postureContainer/$runName/report.html" if ($skipped.Count -gt 0) { $summary += ". Not collected: $(@($skipped.Keys) -join ', ')" } Write-Output $summary if ($webhook) { # A plain Adaptive Card to the customer's own Teams Workflows webhook (opt-in, same channel as the CA cycle). $card = @{ type = 'message'; attachments = @(@{ contentType = 'application/vnd.microsoft.card.adaptive'; content = @{ type = 'AdaptiveCard'; version = '1.4'; '$schema' = 'http://adaptivecards.io/schemas/adaptive-card.json'; body = @(@{ type = 'TextBlock'; text = 'TenantKeep Posture monthly run'; weight = 'Bolder'; size = 'Medium' }, @{ type = 'TextBlock'; text = $summary; wrap = $true }) } }) } | ConvertTo-Json -Depth 8 try { Invoke-RestMethod -Uri $webhook -Method Post -ContentType 'application/json' -Body $card | Out-Null; Write-Output 'posted to Teams' } catch { Write-Output "Teams post failed: $($_.Exception.Message)" } } $notify = Join-Path (Split-Path (Get-Module TenantKeep.Posture).Path) 'schedules' 'ca-notifications.ps1' if ($emailTo.Count -gt 0 -and $emailFrom -and (Test-Path $notify)) { . $notify try { $null = Send-CaChangeEmail -To $emailTo -From $emailFrom -Subject "TenantKeep Posture: $runName" -HtmlBody "<p>$([System.Net.WebUtility]::HtmlEncode($summary))</p>" -AttachmentPath (Join-Path $folder 'report.html'); Write-Output 'emailed the report' } catch { Write-Output "Email failed: $($_.Exception.Message)" } } [pscustomobject]@{ Run = $runName; Score = $report.Report.score.value; Failing = $report.Report.counts.fail; Skipped = @($skipped.Keys); Container = $postureUrl } } catch { Write-Error "Runbook failed: $($_.Exception.Message)`nat $($_.InvocationInfo.ScriptLineNumber): $($_.InvocationInfo.Line.Trim())`n$($_.ScriptStackTrace)" -ErrorAction Continue throw } |