Private/ConvertTo-PostureReportMarkdown.ps1
|
# Copyright (c) 2026 Kainor LLC. Source-available, see LICENSE.md. function ConvertTo-PostureReportMarkdown { <# .SYNOPSIS Renders the report model as Markdown: cover, executive summary, scorecards, admins, recommendations, CA, appendix. #> [CmdletBinding()] [OutputType([string])] param( [Parameter(Mandatory)] [System.Collections.IDictionary] $Report ) $ErrorActionPreference = 'Stop' $sb = [System.Text.StringBuilder]::new() $line = { param([string] $Text = '') $null = $sb.AppendLine($Text) } $esc = { param([object] $Text) ([string]$Text).Replace('|', '\|').Replace("`r", '').Replace("`n", ' ') } $fmtDate = { param($Value) $u = ConvertTo-PostureUtcDateTime $Value; if ($u) { $u.ToString('yyyy-MM-dd HH:mm') + ' UTC' } else { 'unknown' } } $table = { param([string[]] $Headers, [object[]] $Rows) & $line "| $($Headers -join ' | ') |" & $line "|$(@($Headers | ForEach-Object { '---' }) -join '|')|" foreach ($r in $Rows) { & $line "| $(@($r | ForEach-Object { & $esc $_ }) -join ' | ') |" } & $line } $statusLabel = @{ pass = 'Pass'; fail = 'Fail'; notEvaluated = 'Not evaluated'; notApplicable = 'Not applicable'; acceptedRisk = 'Accepted risk'; coveredBy = 'Covered by' } $num = { param($x, [string] $suffix = '') if ($null -eq $x) { 'not collected yet' } else { "$x$suffix" } } $r = $Report; $b = $r.brand; $exec = ($r.template -eq 'Executive') & $line "# $($r.title)" & $line $prepared = [string]$b.preparedBy.name if ($b.client.name) { $prepared += " for $($b.client.name)" } & $line "Prepared by $prepared. Tenant $(if ($r.tenantName) { "$($r.tenantName) " })``$($r.tenantId)``. Evidence collected $(& $fmtDate $r.collectedUtc). Report generated $(& $fmtDate $r.generatedUtc) with TenantKeep.Posture $($r.appendix.moduleVersion), catalog $($r.appendix.catalogVersion), baseline $($r.appendix.baseline). $($r.template) template.$(if ($r.licence -and $r.licence.licensed) { " Licensed to $($r.licence.customer), $($r.licence.tier) tier, until $(& $fmtDate $r.licence.expiresUtc)." })$(if ($r.build) { " $($r.build.detail)" })" if ($r.licence -and -not ($r.licence.licensed -and $r.licence.tier -eq 'full')) { & $line ''; & $line "**Licence:** $(if ($r.licence.reason) { $r.licence.reason } else { 'not licensed' })" } if ($r.build -and $r.build.state -eq 'modified') { & $line ''; & $line "**Build:** $($r.build.detail) This report was not produced by an intact TenantKeep release." } if ($b.confidentiality) { & $line; & $line "*$($b.confidentiality)*" } & $line & $line '## Executive summary' & $line & $line "**Posture score $(& $num $r.score.value) ($($r.score.grade)).** $($r.score.method) $($r.score.evaluated) checks scored." & $line $h = $r.headline & $table @('MFA registered', 'Admins on phishing-resistant auth', 'Permanent Global Admins', 'Intune compliance', 'External sharing exposure', 'Copilot readiness') @(, @((& $num $h.mfaRegisteredPct '%'), (& $num $h.adminsPhishingResistantPct '%'), (& $num $h.permanentGlobalAdmins), (& $num $h.intuneCompliancePct '%'), (& $num $h.externalExposure), $(if ($h.copilotBlocked) { 'Blocked' } else { & $num $h.copilotReadinessPct '%' }))) $c = $r.counts & $line "Checks: $($c.pass) pass, $($c.fail) fail, $($c.acceptedRisk) accepted risk, $($c.coveredBy) covered by a third party, $($c.notEvaluated) not evaluated, $($c.notApplicable) not applicable." & $line if ($r.copilot -and $r.copilot.present) { $cp = $r.copilot & $line '### Copilot readiness' & $line if ($cp.blocked) { & $line "**Blocked.** $(@($cp.blockedBy).Count) hard gate(s) not passed: $(@($cp.blockedBy | ForEach-Object { "$($_.code) $(& $esc $_.title) ($($_.status))" }) -join '; ')." } else { & $line "**Readiness $(& $num $cp.readinessPct '%').** Every hard gate passes; $($cp.passed) of $($cp.evaluated) evaluated gates pass." } & $line & $table @('Gate', 'Hard', 'Status', 'Title') @($cp.gates | ForEach-Object { , @($_.code, $(if ($_.hard) { 'yes' } else { '' }), $_.status, (& $esc $_.title)) }) if (@($cp.notEvaluated).Count -gt 0) { & $line "Not evaluated: $(@($cp.notEvaluated | ForEach-Object { "$($_.code) ($(& $esc $_.reason))" }) -join '; ')."; & $line } & $line (& $esc $cp.narrative) & $line } & $line '### Top risks' & $line if (@($r.topRisks).Count -eq 0) { & $line 'No failed checks.'; & $line } else { $i = 0; foreach ($t in $r.topRisks) { $i++; & $line "$i. **$($t.id) $(& $esc $t.title)** ($($t.severity)$(if ($t.affectedCount -gt 0) { ", $($t.affectedCount) affected" })). $(& $esc $t.narrative)"; & $line } } & $line '### What we recommend this quarter' & $line foreach ($bucket in $r.recommendations.Keys) { $items = @($r.recommendations[$bucket]) if ($items.Count -eq 0) { continue } & $line "- **$bucket**: $(@($items | ForEach-Object { "$($_.id) $(& $esc $_.title)" }) -join '; ')" } & $line if ($r.trend) { $tr = $r.trend & $line "## Trend since $(& $fmtDate $tr.previousCheckedUtc)" & $line $signed = { param($d) if ($null -eq $d) { 'n/a' } elseif ($d -ge 0) { "+$d" } else { "$d" } } & $line "Score $(& $num $tr.scoreBefore) to $(& $num $tr.scoreAfter) ($(& $signed $tr.scoreDelta)). $(@($tr.newFailures).Count) check(s) started failing, $(@($tr.resolved).Count) resolved, $(@($tr.affectedMoved).Count) moved." & $line if (@($tr.newFailures).Count -gt 0) { & $line ('**Started failing:** ' + (@($tr.newFailures | ForEach-Object { "$($_.id) $(& $esc $_.title) ($($_.detail))" }) -join '; ')); & $line } if (@($tr.resolved).Count -gt 0) { & $line ('**Resolved:** ' + (@($tr.resolved | ForEach-Object { "$($_.id) $(& $esc $_.title)" }) -join '; ')); & $line } if (@($tr.affectedMoved).Count -gt 0) { & $line ('**Affected counts moved:** ' + (@($tr.affectedMoved | ForEach-Object { "$($_.id) $($_.before) to $($_.after)" }) -join '; ')); & $line } & $table @('Domain', 'Before', 'After', 'Delta') @($tr.domains | ForEach-Object { , @((& $esc $_.label), (& $num $_.before), (& $num $_.after), (& $signed $_.delta)) }) } & $line '## Domain scorecards' & $line foreach ($d in $r.domains) { & $line "### $($d.label)" & $line & $line "Score $(& $num $d.score). $($d.narrative) Pass $($d.counts.pass), fail $($d.counts.fail), accepted risk $($d.counts.acceptedRisk), covered $($d.counts.coveredBy), not evaluated $($d.counts.notEvaluated), not applicable $($d.counts.notApplicable)." & $line $rows = foreach ($x in $d.checks) { $detail = if ($x.affectedCount -gt 0) { (@($x.affected | Select-Object -First 5 | ForEach-Object { $_.name }) -join ', ') + $(if ($x.affectedCount -gt 5) { " and $($x.affectedCount - 5) more" }) } elseif ($x.reason) { $x.reason } else { '' } if ($exec) { , @($x.id, $x.title, $statusLabel[$x.status], $x.severity) } else { , @($x.id, $x.title, $statusLabel[$x.status], $x.severity, (@($r.catalogText[$x.id].license) -join ', '), $detail) } } if ($exec) { & $table @('Check', 'Title', 'Status', 'Severity') @($rows) } else { & $table @('Check', 'Title', 'Status', 'Severity', 'License', 'Detail') @($rows) } } if (@($r.domainsNotCollected).Count -gt 0) { & $line "Not collected yet: $(@($r.domainsNotCollected | ForEach-Object { $_.label }) -join ', ')." & $line } & $line '## Who are your admins' & $line if (@($r.admins).Count -eq 0) { & $line 'Role assignments were not collected.'; & $line } else { & $table @('Name', 'Type', 'Permanent roles', 'Eligible roles', 'Strongest MFA method', 'Last sign-in', 'Synced from AD', 'Licenses') @($r.admins | ForEach-Object { , @($_.name, $_.type, ($_.permanent -join ', '), ($_.eligible -join ', '), $_.strongestMethod, $(if ($_.lastSignIn) { $_.lastSignIn } else { 'unknown' }), $(if ($_.synced) { 'yes' } else { 'no' }), $(if ($null -ne $_.licenses) { $_.licenses } else { '' })) }) } & $line '## Recommendations' & $line foreach ($bucket in $r.recommendations.Keys) { $items = @($r.recommendations[$bucket]) & $line "### $bucket" & $line if ($items.Count -eq 0) { & $line 'Nothing in this bucket.'; & $line; continue } foreach ($x in $items) { & $line "**$($x.id) $(& $esc $x.title)** ($($x.severity), $($x.domain)$(if ($x.license.Count -gt 0) { ", needs $($x.license -join ' or ')" }))" & $line & $line "$(& $esc $x.remediation) [Learn]($($x.learn))$(if ($x.deepLink) { " [Portal]($($x.deepLink))" })" & $line } } & $line '## Conditional Access' & $line if (-not $r.ca) { & $line 'No Conditional Access snapshot in the evidence folder.'; & $line } else { & $line "$(@($r.ca.policies).Count) policies, $($r.ca.flagCount) health flag(s). The full documentation is in ca-document.html next to the snapshot." & $line $cols = @($r.ca.matrix.columns) & $table (@('Policy') + @($cols | ForEach-Object { $_.label })) @($r.ca.matrix.rows | ForEach-Object { $row = $_; , (@($row.name) + @($cols | ForEach-Object { $row.cells[$_.key] })) }) if (-not $exec) { foreach ($p in $r.ca.policies) { & $line "- **$(& $esc $p.name)** [$($p.stateLabel)]: $(& $esc $p.summary)$(if (@($p.healthFlags).Count -gt 0) { " Flags: $(@($p.healthFlags | ForEach-Object { $_.code }) -join ', ')." })" } & $line } } if ($r.crosswalk) { & $line "## Framework crosswalk: $($r.crosswalk.baseline) ($($r.crosswalk.framework))" & $line & $line 'Reference numbers only; the framework text is not reproduced. Each row lists the checks that map to the group or control, with their results.' & $line foreach ($e in $r.crosswalk.entries) { & $line "### $(& $esc $e.name) ($($e.pass) pass, $($e.fail) fail)" & $line if (@($e.checks).Count -eq 0) { & $line 'No check maps here yet.'; & $line; continue } & $table @('Reference', 'Check', 'Status', 'Severity') @($e.checks | ForEach-Object { , @($_.reference, "$($_.id) $(& $esc $_.title)", $_.status, $_.severity) }) } } & $line '## Appendix' & $line $a = $r.appendix & $table @('Field', 'Value') @(, @('Catalog version', $a.catalogVersion), @('Baseline', $a.baseline), @('Profile', $a.profile), @('Evidence folder', $a.evidence), @('Collectors', ($r.collectors -join ', ')), @('Scopes', ($a.scopes -join ', ')), @('Graph API versions', ($a.graphApiVersions -join ', ')), @('Module version', $a.moduleVersion), @('Build', $a.build), @('Licence', $a.licence)) if ($a.profileAnswers) { & $line '### Profile' & $line & $table @('Answer', 'Value') @($a.profileAnswers.Keys | ForEach-Object { $k = $_; $val = $a.profileAnswers[$k]; , @($k, $(if ($val -is [System.Collections.IDictionary]) { (@($val.Keys | ForEach-Object { "$_=$($val[$_])" }) -join '; ') } elseif ($val -is [array]) { $val -join ', ' } else { [string]$val })) }) } & $line '### Exceptions' & $line if (@($a.exceptions).Count -eq 0) { & $line 'None.'; & $line } else { & $table @('Check', 'Object', 'Justification', 'Owner', 'Approver', 'Expires', 'Expired') @($a.exceptions | ForEach-Object { , @($_.check, $_.object, $_.justification, $_.owner, $_.approver, $(if ($_.expires) { $_.expires.ToString('yyyy-MM-dd') } else { '' }), $(if ($_.expired) { 'yes' } else { 'no' })) }) } & $line '### Checks not evaluated' & $line if (@($a.notEvaluated).Count -eq 0) { & $line 'None.'; & $line } else { & $table @('Check', 'Title', 'Status', 'Why') @($a.notEvaluated | ForEach-Object { , @($_.id, $_.title, $statusLabel[$_.status], $_.reason) }) } & $line '### Evidence index' & $line & $line (($a.evidenceFiles | ForEach-Object { "``$_``" }) -join ', ') & $line if (@($a.errors).Count -gt 0) { & $line '### Collection errors'; & $line; foreach ($e in $a.errors) { & $line "- $(& $esc $e)" }; & $line } if ($b.footer) { & $line '---'; & $line; & $line $b.footer } return $sb.ToString() } |