Public/Start-PostureRun.ps1
|
# Copyright (c) 2026 Kainor LLC. Source-available, see LICENSE.md. function Start-PostureRun { <# .SYNOPSIS One sign-in, one command: collects every domain, builds the profile, writes the report and opens it. .DESCRIPTION Signs the admin in once (Connect-PostureSession), then runs the whole posture cycle from that sign-in: 1. Graph-based collectors (Entra, Intune, Defender when the token carries ThreatHunting.Read.All) and Azure when the profile does not say azure: none and the Az modules are installed. 2. SharePoint and Teams in this process, with tokens from the broker. 3. Exchange and Purview in a fresh process, tokens handed over standard input (the Exchange and PnP modules do not share a process well on macOS). Purview is the one service with a sign-in of its own: Security & Compliance PowerShell issues no delegated token to a third-party app, so a second window opens for the same admin (a device code with -DeviceCode or -NoBrowser). 4. Hybrid: the client folder's hybrid/ad-* files, from the Windows collector, are copied into the run. 5. The profile: created from the evidence on the first run, discovered keys refreshed on later runs, every answer the wizard would ask left to the report's Settings view. 6. The report, with the trend against the newest earlier run, and findings.csv merged with the register. 7. The report opens in the browser. A collector whose module is not installed, or whose session fails, is skipped with a note and the report says what was not collected. A module older than the version the collectors were tested with gets a warning (Get-PostureRequirement lists them); the versions used are recorded in collection.json. The run folder keeps everything that was collected. Read-only throughout. Nothing leaves the machine: evidence under -OutRoot, client files under -Client. .PARAMETER TenantId Pin the run to one tenant: a sign-in to any other is refused before anything is read. .PARAMETER Client The client folder (profile.json, exceptions.json, findings.csv, tenantkeep.lic, imports/, hybrid/). Default: ~/tenantkeep/clients/<tenant display name, lower case, spaces to dashes>/, created on first run. .PARAMETER OutRoot Where run folders go. Default ~/tenantkeep/evidence. .PARAMETER Collector Which collectors to run. Default: all of them. .PARAMETER DeviceCode Sign in with a device code instead of a browser window. .PARAMETER NoBrowser Print the sign-in address instead of opening the browser, and do not open the report. .PARAMETER SkipReport Collect only. .PARAMETER PassThru Return a summary object: Folder, Client, Report, Skipped, Errors. .EXAMPLE Start-PostureRun .EXAMPLE Start-PostureRun -TenantId contoso.onmicrosoft.com -Collector Entra, Intune, Exchange #> [CmdletBinding(SupportsShouldProcess)] [OutputType([string], [pscustomobject])] [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingWriteHost', '', Justification = 'Progress lines for the admin at the console.')] param( [ValidatePattern('^([0-9a-fA-F-]{36}|[A-Za-z0-9.-]+\.[A-Za-z]{2,})$')] [string] $TenantId, [string] $Client, [ValidateNotNullOrEmpty()] [string] $OutRoot = (Join-Path $HOME 'tenantkeep' 'evidence'), [ValidateSet('Entra', 'Intune', 'Exchange', 'SharePoint', 'Teams', 'Defender', 'Purview', 'Azure')] [string[]] $Collector = @('Entra', 'Intune', 'Exchange', 'SharePoint', 'Teams', 'Defender', 'Purview', 'Azure'), [switch] $DeviceCode, [switch] $NoBrowser, [switch] $SkipReport, [switch] $PassThru ) $ErrorActionPreference = 'Stop' Set-StrictMode -Version Latest if (-not $PSCmdlet.ShouldProcess($(if ($TenantId) { $TenantId } else { 'the tenant you sign in to' }), 'Sign in, collect read-only evidence, write the report')) { return } $skipped = [ordered]@{} $step = { param([string] $Text) Write-Host "> $Text" -ForegroundColor Cyan } # Module versions against the tested ones (Get-PostureRequirement): missing skips the collector, older warns once. $warned = [System.Collections.Generic.HashSet[string]]::new() $usable = { param([string] $Module) $check = Test-PostureModuleRequirement -Name $Module if ($check.status -eq 'older' -and $warned.Add($Module)) { Write-Warning $check.message } $check } # 1. One sign-in. $connect = @{} if ($TenantId) { $connect.TenantId = $TenantId } if ($DeviceCode) { $connect.DeviceCode = $true } elseif ($NoBrowser) { $connect.NoBrowser = $true } $session = Connect-PostureSession @connect $context = Assert-PostureGraphScope -RequiredScope @('Policy.Read.All', 'Directory.Read.All', 'Group.Read.All') # 2. The client folder. if (-not $Client) { $slug = (([string]$session.tenantDisplayName).ToLowerInvariant() -replace '[^a-z0-9]+', '-').Trim('-') if (-not $slug) { $slug = [string]$session.tenantId } $Client = Join-Path $HOME 'tenantkeep' 'clients' $slug } $Client = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($Client) New-Item -ItemType Directory -Path $Client, (Join-Path $Client 'imports'), (Join-Path $Client 'hybrid') -Force | Out-Null $OutRoot = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($OutRoot) New-Item -ItemType Directory -Path $OutRoot -Force | Out-Null $profilePath = Join-Path $Client 'profile.json' $profileParam = @{} if (Test-Path -LiteralPath $profilePath) { $existing = Get-Content -Raw -LiteralPath $profilePath | ConvertFrom-Json -AsHashtable -Depth 10 $expected = [string]$(if ($existing.Contains('tenantId')) { $existing['tenantId'] }) if ($expected -and $expected -ne [string]$session.tenantId) { throw "$profilePath belongs to tenant $expected, but the sign-in is to $($session.tenantId). Pass -Client for this tenant's folder." } $profileParam.ProfilePath = $profilePath if ($existing.Contains('azure') -and [string]$existing['azure'] -eq 'none' -and 'Azure' -in $Collector) { $Collector = @($Collector | Where-Object { $_ -ne 'Azure' }) $skipped['Azure'] = 'Profile says azure: none; the Azure domain is not applicable to this tenant.' } } Write-Host "Client folder: $Client" # 3. Graph-based collectors and Azure in this process. $main = @($Collector | Where-Object { $_ -in 'Entra', 'Intune' }) if ('Defender' -in $Collector) { if ('ThreatHunting.Read.All' -in @($context.Scopes)) { $main += 'Defender' } else { $skipped['Defender'] = 'ThreatHunting.Read.All is not on the token; the tenant consented without it.' } } if ('Azure' -in $Collector) { $az = @('Az.Accounts', 'Az.ResourceGraph' | ForEach-Object { & $usable $_ }) if (@($az | Where-Object { $_.status -eq 'missing' }).Count -eq 0) { try { Connect-PostureService -Name azure; $main += 'Azure' } catch { $skipped['Azure'] = "Azure sign-in failed: $($_.Exception.Message)" } } else { $skipped['Azure'] = 'Az.Accounts and Az.ResourceGraph are not installed; the Azure domain was not collected. Set azure: none in the profile if there is nothing in Azure.' } } if ($main.Count -eq 0) { $main = @('Entra') } & $step "Collecting $($main -join ', ')" $collection = Invoke-PostureCollection -OutRoot $OutRoot -Collector $main -PassThru @profileParam $folder = [string]$collection.Folder $errorCount = @($collection.Errors).Count # 4. SharePoint and Teams here, after every Graph read above (PnP.PowerShell loads an older Microsoft.Graph.Core). $local = [System.Collections.Generic.List[string]]::new() $need = @{ SharePoint = 'PnP.PowerShell'; Teams = 'MicrosoftTeams' } foreach ($name in 'SharePoint', 'Teams') { if ($name -notin $Collector) { continue } $check = & $usable $need[$name] if ($check.status -eq 'missing') { $skipped[$name] = $check.message; continue } try { Connect-PostureService -Name $name.ToLowerInvariant(); $local.Add($name) } catch { $skipped[$name] = "$name sign-in failed: $($_.Exception.Message)" } } if ($local.Count -gt 0) { & $step "Collecting $($local -join ', ')" try { Invoke-PostureCollection -Collector @($local) -SkipCaSnapshot -OutputFolder $folder @profileParam | Out-Null } catch { foreach ($n in $local) { $skipped[$n] = $_.Exception.Message } } } # 5. Exchange and Purview in their own process, tokens over standard input. $child = @($Collector | Where-Object { $_ -in 'Exchange', 'Purview' }) if ($child.Count -gt 0) { $exo = & $usable 'ExchangeOnlineManagement' if ($exo.status -eq 'missing') { foreach ($n in $child) { $skipped[$n] = $exo.message } } else { & $step "Collecting $($child -join ', ') in a second process$(if ('Purview' -in $child) { ' (Purview opens a sign-in of its own)' })" $tokens = @{} foreach ($name in @('graph') + @($child | Where-Object { $_ -eq 'Exchange' } | ForEach-Object { 'exchange' })) { $null = Get-PostureToken -Resource $name -Force $tokens[$name] = @{ accessToken = $script:PostureSession['tokens'][$name]['accessToken']; expiresUtc = $script:PostureSession['tokens'][$name]['expiresUtc'].ToString('o') } } $request = @{ clientId = $session.clientId; tenantId = $session.tenantId; tenantName = $session.tenantName; account = $session.account; folder = $folder; profilePath = $(if ($profileParam.Count -gt 0) { $profilePath } else { '' }); collectors = $child; tokens = $tokens; purviewSignIn = $(if ($DeviceCode -or $NoBrowser) { 'device' } else { 'browser' }) } $exit = Start-PostureChildCollection -Request $request if ($exit -ne 0) { $skipped['Exchange or Purview'] = "The second process reported $exit failed collector(s); see errors.txt in the run folder." } } } # 6. Hybrid files from the Windows collector. $hybrid = Join-Path $Client 'hybrid' $adFiles = @(Get-ChildItem -LiteralPath $hybrid -Filter 'ad-*' -File -ErrorAction SilentlyContinue) if ($adFiles.Count -gt 0) { $adFiles | Copy-Item -Destination $folder -Force; Write-Host "Hybrid: $($adFiles.Count) ad-* files copied in" } # 7. Profile: discovered from the evidence, the rest left to the report's Settings view. & $step 'Profile' $profileArgs = @{ Path = $profilePath; Evidence = $folder; NonInteractive = $true; TenantId = $session.tenantId } if (-not (Test-Path -LiteralPath $profilePath)) { $profileArgs.ClientName = [string]$session.tenantDisplayName } $null = New-PostureProfile @profileArgs $reportFile = $null if (-not $SkipReport) { # 8. Report, with the trend against the newest earlier run that has checks.json. & $step 'Report' $previous = @(Get-ChildItem -LiteralPath $OutRoot -Directory | Where-Object { $_.Name -match '^\d{8}-\d{4}$' -and $_.FullName -ne $folder -and (Test-Path (Join-Path $_.FullName 'checks.json')) } | Sort-Object Name | Select-Object -Last 1) $reportArgs = @{ Evidence = $folder; Client = $Client; PassThru = $true } if ($previous.Count -gt 0) { $reportArgs.Previous = $previous[0].FullName } $report = New-PostureReport @reportArgs $reportFile = @($report.Files | Where-Object { $_ -like '*.html' })[0] $findingsArgs = @{ Path = $folder; OutputPath = (Join-Path $folder 'findings.csv') } if (Test-Path -LiteralPath (Join-Path $Client 'findings.csv')) { $findingsArgs.Merge = Join-Path $Client 'findings.csv' } $null = Export-PostureFindings @findingsArgs if ($reportFile -and -not $NoBrowser) { try { Start-Process $reportFile } catch { Write-Verbose "Report did not open: $($_.Exception.Message)" } } } # errors.txt is appended by every process that wrote into the folder, so it is the count to report. $errorsFile = Join-Path $folder 'errors.txt' if (Test-Path -LiteralPath $errorsFile) { $errorCount = @(Get-Content -LiteralPath $errorsFile | Where-Object { $_.Trim() }).Count } Write-Host '' Write-Host "Run folder: $folder" $versions = Get-PostureModuleVersionUsed Write-Host "PowerShell $($PSVersionTable.PSVersion); modules: $(@($versions.Keys | ForEach-Object { "$_ $(if ($versions[$_]) { $versions[$_] } else { 'not installed' })" }) -join ', ')" if ($reportFile) { Write-Host "Report: $reportFile" } if ($errorCount -gt 0) { Write-Host "$errorCount step(s) logged in errors.txt" -ForegroundColor Yellow } foreach ($k in $skipped.Keys) { Write-Host "Skipped $($k): $($skipped[$k])" -ForegroundColor Yellow } if ($PassThru) { return [pscustomobject]@{ Folder = $folder; Client = $Client; Report = $reportFile; Skipped = $skipped; Errors = $errorCount } } return $folder } |