Public/Export-PostureFindings.ps1

# Copyright (c) 2026 Kainor LLC. Source-available, see LICENSE.md.
function Export-PostureFindings {
    <#
    .SYNOPSIS
        Writes findings.csv in the audit plan's Appendix E schema from a checks.json, one row per failed or accepted
        check, keeping the owners and statuses already recorded in an earlier findings.csv.
    .DESCRIPTION
        Columns: ID, Workstream, Finding, Evidence, Likelihood 1-5, Impact 1-5, Risk, Effort S/M/L/XL, Dependency,
        Quick win, Bucket, Owner, Status. Likelihood and impact follow the severity (Critical 5, High 4, Medium 3,
        Low 2) until the catalog carries its own; risk is their product; the bucket is the report's. Rows whose ID is
        in -Merge keep that file's Owner, Status, Effort and Dependency, so the register round-trips between runs: a
        check that no longer fails is written with status Resolved, a new one with Open.
    .PARAMETER Path
        checks.json, or a folder holding one (an evidence folder after Invoke-PostureChecks or New-PostureReport).
    .PARAMETER OutputPath
        Where to write findings.csv. Default: next to the checks.json.
    .PARAMETER LicensePath
        TenantKeep licence file; the same lookup as New-PostureReport. Findings from unlicensed domains are left out and every row carries the licence id.
    .PARAMETER Merge
        An earlier findings.csv whose Owner, Status, Effort and Dependency survive for the same IDs.
    .PARAMETER IncludePassed
        Also write the passing checks, status Resolved or Pass, so the register shows the whole catalog.
    .PARAMETER PassThru
        Return the rows instead of the file path.
    .EXAMPLE
        Export-PostureFindings -Path ~/tenantkeep/evidence/20261015-0952 -Merge ~/tenantkeep/clients/contoso/findings.csv -OutputPath ~/tenantkeep/clients/contoso/findings.csv
    .OUTPUTS
        System.String, the findings.csv path. With -PassThru, the rows.
    .LINK
        docs/m365-environment-audit-plan.md Appendix E
    #>

    [CmdletBinding(SupportsShouldProcess)]
    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseSingularNouns', '', Justification = 'The spec names the cmdlet after the findings register (Appendix E).')]
    [OutputType([string], [object[]])]
    param(
        [Parameter(Mandatory, Position = 0)] [ValidateNotNullOrEmpty()] [string] $Path,
        [string] $OutputPath,
        [string] $Merge,
        [string] $LicensePath,
        [switch] $IncludePassed,
        [switch] $PassThru
    )

    $ErrorActionPreference = 'Stop'
    Set-StrictMode -Version Latest

    $checksPath = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($Path)
    if (Test-Path -LiteralPath $checksPath -PathType Container) { $checksPath = Join-Path $checksPath 'checks.json' }
    if (-not (Test-Path -LiteralPath $checksPath -PathType Leaf)) { throw "checks.json not found: $checksPath (run Invoke-PostureChecks or New-PostureReport first)" }
    $run = Get-Content -Raw -LiteralPath $checksPath | ConvertFrom-Json -AsHashtable -Depth 20
    $catalog = Import-PostureCheckCatalog
    $byId = @{}; foreach ($c in $catalog.checks) { $byId[[string]$c['id']] = $c }
    # The licence is verified here too, not read back from checks.json (docs/licensing.md, Hardening).
    $entitlement = Confirm-PostureEntitlement -Entitlement (Get-PostureEntitlement -Evidence (Split-Path $checksPath -Parent) -LicensePath $LicensePath)
    $run.results = Limit-PostureResultsToEntitlement -Results @($run.results) -Entitlement $entitlement
    $licenceLabel = $(if ($entitlement.licensed -and $entitlement.licence) { [string]$entitlement.licence.licenceId } elseif ($entitlement.licensed) { [string]$entitlement.source } else { 'unlicensed' })

    $labels = @{ identity = 'Identity and privileged access'; auth = 'Authentication methods'; ca = 'Conditional Access'; devices = 'Devices'; endpoint = 'Endpoint security'; email = 'Email security'; purview = 'Data protection'; collaboration = 'Collaboration and oversharing'; copilot = 'Copilot readiness'; governance = 'Governance and lifecycle'; operations = 'Operations and monitoring'; azure = 'Azure'; hybrid = 'Hybrid identity and on-premises AD' }
    $score = @{ Critical = 5; High = 4; Medium = 3; Low = 2 }
    $bucket = @{ Critical = 'Stop the bleeding'; High = 'Foundations'; Medium = 'Program workstreams'; Low = 'Later' }

    $previous = @{}
    if ($Merge) {
        $mergePath = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($Merge)
        if (-not (Test-Path -LiteralPath $mergePath -PathType Leaf)) { throw "findings.csv to merge not found: $mergePath" }
        foreach ($row in @(Import-Csv -LiteralPath $mergePath)) { if ($row.ID) { $previous[[string]$row.ID] = $row } }
    }

    $rows = foreach ($r in @($run.results)) {
        $status = [string]$r.status
        if ($status -notin @('fail', 'acceptedRisk') -and -not $IncludePassed) { continue }
        if ($status -in @('notEvaluated', 'notApplicable')) { continue }
        $id = [string]$r.id; $sev = [string]$r.severity; $c = $byId[$id]
        $affected = @($r.affected | ForEach-Object { if ($_ -is [System.Collections.IDictionary]) { [string]$_['name'] } else { [string]$_ } } | Where-Object { $_ })
        $finding = [string]$r.title
        if ($affected.Count -gt 0) { $finding += " ($($r.affectedCount) affected: $(@($affected | Select-Object -First 5) -join ', ')$(if ($affected.Count -gt 5) { ', ...' }))" }
        $l = $(if ($score.ContainsKey($sev)) { $score[$sev] } else { 3 })
        $old = $previous[$id]
        $newStatus = switch ($status) { 'fail' { $(if ($old -and $old.Status -and $old.Status -notin @('Resolved', 'Pass')) { $old.Status } else { 'Open' }) } 'acceptedRisk' { 'Accepted' } default { 'Resolved' } }
        [pscustomobject]@{
            'ID'             = $id
            'Workstream'     = $(if ($labels.ContainsKey([string]$r.domain)) { $labels[[string]$r.domain] } else { [string]$r.domain })
            'Finding'        = $finding
            'Evidence'       = (@($r.evidence) -join '; ')
            'Likelihood 1-5' = $l
            'Impact 1-5'     = $l
            'Risk'           = $l * $l
            'Effort S/M/L/XL' = $(if ($old -and $old.'Effort S/M/L/XL') { $old.'Effort S/M/L/XL' } else { '' })
            'Dependency'     = $(if ($old -and $old.Dependency) { $old.Dependency } else { '' })
            'Quick win'      = $(if ($status -eq 'fail' -and $r.affectedCount -le 5 -and $sev -in @('Low', 'Medium')) { 'Y' } else { '' })
            'Bucket'         = $(if ($bucket.ContainsKey($sev)) { $bucket[$sev] } else { 'Later' })
            'Owner'          = $(if ($old -and $old.Owner) { $old.Owner } else { '' })
            'Status'         = $newStatus
            'Remediation'    = $(if ($c) { [string]$c['remediation'] } else { '' })
            'Learn'          = $(if ($c) { [string]$c['learn'] } else { '' })
            'Checked'        = [string]$r.checkedUtc
            'Licence'        = $licenceLabel
        }
    }
    $rows = @($rows | Sort-Object { -[int]$_.Risk }, { $_.ID })

    $out = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($(if ($OutputPath) { $OutputPath } else { Join-Path (Split-Path $checksPath -Parent) 'findings.csv' }))
    if (Test-Path -LiteralPath $out -PathType Container) { $out = Join-Path $out 'findings.csv' }
    if ($PSCmdlet.ShouldProcess($out, 'Write findings.csv')) {
        $dir = Split-Path $out -Parent
        if ($dir -and -not (Test-Path -LiteralPath $dir)) { New-Item -ItemType Directory -Path $dir -Force | Out-Null }
        $rows | Export-Csv -LiteralPath $out -NoTypeInformation -Encoding utf8
    }
    if ($PassThru) { return $rows }
    return $out
}