Public/New-PostureCaDocument.ps1
|
# Copyright (c) 2026 Kainor LLC. Source-available, see LICENSE.md. function New-PostureCaDocument { <# .SYNOPSIS Renders Conditional Access documentation from an Export-PostureCaSnapshot folder (spec 5.2). .DESCRIPTION Reads the snapshot, resolves every id to a name, and writes a document with one section per policy (plain-English summary, assignments, targets, conditions, grant and session controls, health flags) plus the tenant-level pages: health flag table, policy matrix, naming convention report, named locations, authentication strengths and contexts, and a snapshot appendix. Reads only the snapshot folder. Never touches the tenant and needs no Graph session. .PARAMETER Snapshot Path to a snapshot folder written by Export-PostureCaSnapshot. .PARAMETER OutputPath Folder for the output files. Default: the snapshot folder. Files are named ca-document.<ext>. .PARAMETER Format One or more of Markdown, Html, Pdf. Default: Markdown and Html. Pdf prints the HTML through a headless Microsoft Edge or Google Chrome (spec 6) and always writes the HTML file too. .PARAMETER NamePattern Regex the policy names must match for the naming report. Falls back to caNamePattern in brand.json. .PARAMETER Brand Path to brand.json (spec 7.5) for prepared-by, client name, confidentiality line and footer. .PARAMETER ExclusionGroupThreshold Excluded groups larger than this raise a health flag. Default 25. .PARAMETER ReportOnlyDays Policies in report-only longer than this raise a health flag. Default 90. .PARAMETER DisabledDays Policies disabled longer than this raise a health flag. Default 90. .PARAMETER ProposedNameFormat Template for proposed names in the naming report. Tokens: {seq}, {persona}, {action}, {name}. .PARAMETER MatrixColumn Subset of matrix columns: allUsers, adminRoles, guests, workloadIdentities, allApps, office365, adminPortals, registerSecurityInfo. .PARAMETER Baseline Baseline for the Coverage findings page (name under baselines/ or a path). Default: standard. .PARAMETER ProfilePath profile.json for the Coverage findings page (alias -Profile): licenses, platforms, break-glass accounts, thresholds. .PARAMETER Exceptions exceptions.json for the Coverage findings page: accepted risk per check or per object. .PARAMETER SkipChecks Leave the Coverage findings page out instead of running the Conditional Access checks on the snapshot. .PARAMETER PassThru Return the document model and the written file paths instead of the file paths alone. .EXAMPLE New-PostureCaDocument -Snapshot ~/tenantkeep/evidence/20261013-0905-ca Writes ca-document.md and ca-document.html into the snapshot folder and returns their paths. .EXAMPLE New-PostureCaDocument -Snapshot ./snap -OutputPath ./out -Brand ~/tenantkeep/clients/contoso/brand.json -NamePattern '^CA-\d{3}-' Branded document with a naming report, written to ./out. .OUTPUTS System.String. Written file paths. With -PassThru, an object with Files and Document. .LINK docs/posture-spec.md section 5.2 #> [CmdletBinding(SupportsShouldProcess)] [OutputType([string], [pscustomobject])] param( [Parameter(Mandatory, Position = 0)] [ValidateNotNullOrEmpty()] [string] $Snapshot, [string] $OutputPath, [ValidateSet('Markdown', 'Html', 'Pdf')] [string[]] $Format = @('Markdown', 'Html'), [string] $NamePattern, [string] $Brand, [ValidateRange(0, 100000)] [int] $ExclusionGroupThreshold = 25, [ValidateRange(0, 3650)] [int] $ReportOnlyDays = 90, [ValidateRange(0, 3650)] [int] $DisabledDays = 90, [string] $ProposedNameFormat = 'CA-{seq}-{persona}-{action}', [string[]] $MatrixColumn, [string] $Baseline = 'standard', [Alias('Profile')] [string] $ProfilePath, [string] $Exceptions, [switch] $SkipChecks, [switch] $PassThru ) $ErrorActionPreference = 'Stop' Set-StrictMode -Version Latest $snap = Import-PostureCaSnapshot -Path $Snapshot $brandModel = Import-PostureBrand -Path $Brand if (-not $NamePattern -and $brandModel.caNamePattern) { $NamePattern = [string]$brandModel.caNamePattern } $modelParams = @{ Snapshot = $snap; ExclusionGroupThreshold = $ExclusionGroupThreshold ReportOnlyDays = $ReportOnlyDays; DisabledDays = $DisabledDays } if ($NamePattern) { $modelParams.NamePattern = $NamePattern } $policies = @(ConvertTo-PostureCaPolicyModel @modelParams) $matrixParams = @{ Policy = $policies } if ($MatrixColumn) { $matrixParams.Column = $MatrixColumn } $matrix = Get-PostureCaMatrix @matrixParams $naming = if ($NamePattern) { Get-PostureCaNamingReport -Policy $policies -NamePattern $NamePattern -ProposedNameFormat $ProposedNameFormat } else { $null } $allFlags = @($policies | ForEach-Object { @($_.healthFlags) }) $stats = [ordered]@{ total = $policies.Count enabled = @($policies | Where-Object state -eq 'enabled').Count reportOnly = @($policies | Where-Object state -eq 'reportOnly').Count disabled = @($policies | Where-Object state -eq 'disabled').Count flagsError = @($allFlags | Where-Object severity -eq 'error').Count flagsWarning = @($allFlags | Where-Object severity -eq 'warning').Count flagsInfo = @($allFlags | Where-Object severity -eq 'info').Count } $clientName = if ($brandModel.client.name) { [string]$brandModel.client.name } else { [string](Get-PostureValue $snap.Metadata 'tenantId') } $document = [ordered]@{ title = "Conditional Access documentation: $clientName" brand = $brandModel generatedUtc = [datetime]::UtcNow snapshot = [ordered]@{ path = $snap.Path tenantId = Get-PostureValue $snap.Metadata 'tenantId' account = Get-PostureValue $snap.Metadata 'account' timestampUtc = Get-PostureValue $snap.Metadata 'timestampUtc' moduleVersion = Get-PostureValue $snap.Metadata 'moduleVersion' scopes = @(Get-PostureValue $snap.Metadata 'scopes') graphApiVersions = @(Get-PostureValue $snap.Metadata 'graphApiVersions') errors = @($snap.Errors) } options = [ordered]@{ namePattern = $NamePattern; exclusionGroupThreshold = $ExclusionGroupThreshold reportOnlyDays = $ReportOnlyDays; disabledDays = $DisabledDays; matrixColumns = @($matrix.columns | ForEach-Object { $_.key }) } stats = $stats policies = $policies matrix = $matrix naming = $naming namedLocations = @($snap.NamedLocations) authStrengths = @($snap.AuthStrengths) authContexts = @($snap.AuthContexts) } # Coverage findings: the spec 4.3 checks, evaluated by the engine with the same thresholds this document uses. $document.coverage = $null if (-not $SkipChecks) { $profileModel = Import-PostureProfile -Path $ProfilePath if (-not $profileModel.thresholds) { $profileModel.thresholds = @{} } foreach ($pair in @(@('maxExclusionGroupMembers', $ExclusionGroupThreshold), @('reportOnlyMaxDays', $ReportOnlyDays), @('disabledMaxDays', $DisabledDays))) { if (-not $profileModel.thresholds.Contains($pair[0])) { $profileModel.thresholds[$pair[0]] = $pair[1] } } if ($NamePattern -and -not $profileModel.thresholds.Contains('namePattern')) { $profileModel.thresholds['namePattern'] = $NamePattern } $catalog = Import-PostureCheckCatalog $run = Invoke-PostureCheckEvaluation -Catalog $catalog -Baseline (Import-PostureBaseline -Baseline $Baseline) -OrgProfile $profileModel -Exception @(Import-PostureException -Path $Exceptions) -Evidence $snap.Path -Domain @('ca') $text = @{} foreach ($c in $catalog.checks) { $text[[string]$c['id']] = @{ narrative = [string]$c['narrative']; remediation = [string]$c['remediation']; learn = [string]$c['learn'] } } $document.coverage = [ordered]@{ run = $run; text = $text } } $outFolder = if ($OutputPath) { $OutputPath } else { $snap.Path } if (-not (Test-Path -LiteralPath $outFolder)) { New-Item -ItemType Directory -Path $outFolder -Force | Out-Null } $outFolder = (Resolve-Path -LiteralPath $outFolder).Path $formats = [System.Collections.Generic.List[string]]::new([string[]]$Format) if ($formats -contains 'Pdf' -and $formats -notcontains 'Html') { $formats.Insert(0, 'Html') } $written = [System.Collections.Generic.List[string]]::new() $htmlPath = $null foreach ($f in @('Markdown', 'Html')) { if ($formats -notcontains $f) { continue } $ext, $content = switch ($f) { 'Markdown' { 'md', (ConvertTo-PostureCaMarkdown -Document $document) } 'Html' { 'html', (ConvertTo-PostureCaHtml -Document $document) } } $path = Join-Path $outFolder "ca-document.$ext" if ($PSCmdlet.ShouldProcess($path, "Write $f document")) { [System.IO.File]::WriteAllText($path, $content, [System.Text.UTF8Encoding]::new($false)) $written.Add($path) if ($f -eq 'Html') { $htmlPath = $path } } } if ($formats -contains 'Pdf' -and $htmlPath) { $pdfPath = Join-Path $outFolder 'ca-document.pdf' if ($PSCmdlet.ShouldProcess($pdfPath, 'Print HTML to PDF with a headless browser')) { $written.Add((Export-PostureHtmlToPdf -HtmlPath $htmlPath -PdfPath $pdfPath)) } } if ($PassThru) { return [pscustomobject]@{ Files = $written.ToArray(); Document = $document } } return $written.ToArray() } |