Public/New-PostureReport.ps1
|
# Copyright (c) 2026 Kainor LLC. Source-available, see LICENSE.md. function New-PostureReport { <# .SYNOPSIS Renders the posture report (spec 3 and 7) from an evidence folder: runs the catalog, writes checks.json, and writes the report as a self-contained interactive HTML file and as Markdown. PDF prints the HTML through a headless Edge or Chrome. .DESCRIPTION Reads only local files. The report carries the posture score with its method, the headline numbers, one scorecard per domain, the top risks, recommendations in the audit plan's four buckets, the administrators table, the Conditional Access matrix and policy summaries, and an appendix with the baseline, profile, exceptions, scopes, API versions and the evidence index. Domains whose evidence is not collected yet are listed as such. -Client points at a client folder (spec 10.5) holding brand.json, profile.json and exceptions.json; explicit -Brand, -Profile and -Exceptions override the folder's files. .PARAMETER Evidence A collection folder from Invoke-PostureCollection (a bare Export-PostureCaSnapshot folder works for the CA domain alone). .PARAMETER Client Client folder with brand.json, profile.json and exceptions.json. .PARAMETER Template Executive (cover, summary, scorecards, recommendations) or Full. Default Full. .PARAMETER Format One or more of Html, Markdown, Pdf. Default: Html and Markdown. Pdf always writes the HTML too. .PARAMETER LicensePath TenantKeep licence file. Default: TENANTKEEP_LICENSE, <Client>/tenantkeep.lic, then ~/tenantkeep/tenantkeep.lic. Without a valid Full licence only the Conditional Access domain is evaluated and the report says so (docs/licensing.md). .PARAMETER Previous An earlier run's checks.json, or the folder holding one, for the Trend view: score and domain deltas, checks that started or stopped failing, affected counts that moved. .PARAMETER OutputPath Folder for report.<ext> and checks.json. Default: the evidence folder. .PARAMETER PassThru Return the report model and the written file paths. .EXAMPLE New-PostureReport -Evidence ~/tenantkeep/evidence/20261013-2350 -Client ~/tenantkeep/clients/contoso .EXAMPLE New-PostureReport -Evidence ./evidence/run -Profile ./profile.json -Template Executive -PassThru .OUTPUTS System.String, written file paths. With -PassThru, an object with Files and Report. .LINK docs/posture-spec.md sections 3 and 7 #> [CmdletBinding(SupportsShouldProcess)] [OutputType([string], [pscustomobject])] param( [Parameter(Mandatory, Position = 0)] [ValidateNotNullOrEmpty()] [string] $Evidence, [string] $Client, [string] $Brand, [Alias('Profile')] [string] $ProfilePath, [string] $Exceptions, [string] $Baseline = 'standard', [string[]] $CustomChecks = @(), [ValidateSet('Executive', 'Full')] [string] $Template = 'Full', [ValidateSet('Html', 'Markdown', 'Pdf')] [string[]] $Format = @('Html', 'Markdown'), [string] $Previous, [string] $OutputPath, [string] $LicensePath, [switch] $PassThru ) $ErrorActionPreference = 'Stop' Set-StrictMode -Version Latest if (-not (Test-Path -LiteralPath $Evidence -PathType Container)) { throw "Evidence folder not found: $Evidence" } $evidencePath = (Resolve-Path -LiteralPath $Evidence).Path if ($Client) { if (-not (Test-Path -LiteralPath $Client -PathType Container)) { throw "Client folder not found: $Client" } foreach ($pair in @(@('Brand', 'brand.json'), @('ProfilePath', 'profile.json'), @('Exceptions', 'exceptions.json'))) { $candidate = Join-Path $Client $pair[1] if (-not (Get-Variable -Name $pair[0] -ValueOnly) -and (Test-Path -LiteralPath $candidate -PathType Leaf)) { Set-Variable -Name $pair[0] -Value $candidate } } } $catalog = Import-PostureCheckCatalog -CustomPath $CustomChecks $baselineModel = Import-PostureBaseline -Baseline $Baseline $profileModel = Import-PostureProfile -Path $ProfilePath $exceptionList = @(Import-PostureException -Path $Exceptions) $brandModel = Import-PostureBrand -Path $Brand $entitlement = Get-PostureEntitlement -Evidence $evidencePath -LicensePath $LicensePath -ClientFolder $Client $run = Invoke-PostureCheckEvaluation -Catalog $catalog -Baseline $baselineModel -OrgProfile $profileModel -Exception $exceptionList -Evidence $evidencePath -Entitlement $entitlement $run.entitlement = ConvertTo-PostureEntitlementRecord -Entitlement $entitlement $run.moduleVersion = $script:ModuleVersion $previousRun = $null if ($Previous) { $prevPath = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($Previous) if (Test-Path -LiteralPath $prevPath -PathType Container) { $prevPath = Join-Path $prevPath 'checks.json' } if (-not (Test-Path -LiteralPath $prevPath -PathType Leaf)) { throw "Previous checks.json not found: $prevPath" } $previousRun = Get-Content -Raw -LiteralPath $prevPath | ConvertFrom-Json -AsHashtable -Depth 20 } # The register the client folder already holds (owners, statuses, effort) rides into the page so the browser can keep them. $register = @() if ($Client) { $registerPath = Join-Path $Client 'findings.csv'; if (Test-Path -LiteralPath $registerPath -PathType Leaf) { $register = @(Import-Csv -LiteralPath $registerPath | ForEach-Object { $h = [ordered]@{}; foreach ($prop in $_.PSObject.Properties) { $h[$prop.Name] = [string]$prop.Value }; $h }) } } $report = ConvertTo-PostureReportModel -Run $run -Catalog $catalog -Evidence $evidencePath -OrgProfile $profileModel -Brand $brandModel -Exception $exceptionList -Template $Template -Previous $previousRun -BaselineModel $baselineModel -Entitlement $entitlement -Register $register $outFolder = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($(if ($OutputPath) { $OutputPath } else { $evidencePath })) # expands ~ too $written = [System.Collections.Generic.List[string]]::new() $checksPath = Join-Path $outFolder 'checks.json' if ($PSCmdlet.ShouldProcess($checksPath, 'Write checks.json')) { if (-not (Test-Path -LiteralPath $outFolder)) { New-Item -ItemType Directory -Path $outFolder -Force -WhatIf:$false | Out-Null } [System.IO.File]::WriteAllText($checksPath, (ConvertTo-Json -InputObject $run -Depth 20), [System.Text.UTF8Encoding]::new($false)) $written.Add($checksPath) } $formats = [System.Collections.Generic.List[string]]::new([string[]]$Format) if ($formats -contains 'Pdf' -and $formats -notcontains 'Html') { $formats.Insert(0, 'Html') } $htmlPath = $null foreach ($f in @('Html', 'Markdown')) { if ($formats -notcontains $f) { continue } $ext, $content = switch ($f) { 'Html' { 'html', (ConvertTo-PostureReportHtml -Report $report) } 'Markdown' { 'md', (ConvertTo-PostureReportMarkdown -Report $report) } } $path = Join-Path $outFolder "report.$ext" if ($PSCmdlet.ShouldProcess($path, "Write $f report")) { [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 'report.pdf' if ($PSCmdlet.ShouldProcess($pdfPath, 'Print HTML to PDF with a headless browser')) { $written.Add((Export-PostureHtmlToPdf -HtmlPath $htmlPath -PdfPath $pdfPath)) } } Write-Verbose "Score $($report.score.value) ($($report.score.grade)); $($run.counts.fail) failed check(s)" if ($PassThru) { return [pscustomobject]@{ Files = $written.ToArray(); Report = $report; Run = $run } } return $written.ToArray() } |