Public/Invoke-PostureChecks.ps1

# Copyright (c) 2026 Kainor LLC. Source-available, see LICENSE.md.
function Invoke-PostureChecks {
    <#
    .SYNOPSIS
        Runs the check catalog against an evidence folder and writes checks.json (spec 6, 10).
    .DESCRIPTION
        Checks are data in checks/*.json; this cmdlet evaluates them. Scope and targets come from -Baseline
        (a shipped name such as standard, or a path), facts about the tenant from -Profile (profile.json), and
        accepted risk from -Exceptions (exceptions.json). Each result carries pass, fail, notEvaluated with the
        reason, notApplicable, acceptedRisk or coveredBy, plus the affected objects and the evidence files used.

        Reads only local files. No Graph session is needed.
    .PARAMETER Evidence
        Evidence folder. For the Conditional Access domain this is an Export-PostureCaSnapshot folder.
    .PARAMETER Baseline
        Baseline name under baselines/ or a path to a baseline JSON. Default: standard.
    .PARAMETER ProfilePath
        Path to profile.json (alias -Profile). Without it every check is evaluated and license gating is off.
    .PARAMETER Exceptions
        Path to exceptions.json.
    .PARAMETER CustomChecks
        Folders with org-specific checks in the catalog schema, rendered alongside and tagged custom.
    .PARAMETER Domain
        Limit to these domains, for example ca.
    .PARAMETER LicensePath
        TenantKeep licence file. Default: TENANTKEEP_LICENSE, the profile's folder, then ~/tenantkeep/tenantkeep.lic. Without a valid Full licence only the Conditional Access domain is evaluated (docs/licensing.md).
    .PARAMETER OutputPath
        Folder for checks.json. Default: the evidence folder.
    .PARAMETER PassThru
        Return the full result object instead of the checks.json path.
    .EXAMPLE
        Invoke-PostureChecks -Evidence ~/tenantkeep/evidence/20261013-2231-ca -Domain ca

        Evaluates the Conditional Access checks against that snapshot with the standard baseline.
    .EXAMPLE
        Invoke-PostureChecks -Evidence ./snap -Baseline cisa-scuba -Profile ~/tenantkeep/clients/contoso/profile.json -Exceptions ~/tenantkeep/clients/contoso/exceptions.json -PassThru

        Full result object for a client folder.
    .OUTPUTS
        System.String, the checks.json path. With -PassThru, the result object.
    .LINK
        docs/posture-spec.md sections 6 and 10
    #>

    [CmdletBinding()]
    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseSingularNouns', '', Justification = 'Spec section 6 names the cmdlet Invoke-PostureChecks.')]
    [OutputType([string], [System.Collections.Specialized.OrderedDictionary])]
    param(
        [Parameter(Mandatory, Position = 0)] [ValidateNotNullOrEmpty()] [string] $Evidence,
        [string] $Baseline = 'standard',
        [Alias('Profile')] [string] $ProfilePath,
        [string] $Exceptions,
        [string[]] $CustomChecks = @(),
        [string[]] $Domain,
        [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

    $catalog = Import-PostureCheckCatalog -CustomPath $CustomChecks
    $baselineModel = Import-PostureBaseline -Baseline $Baseline
    $profileModel = Import-PostureProfile -Path $ProfilePath
    $exceptionList = @(Import-PostureException -Path $Exceptions)

    $entitlement = Get-PostureEntitlement -Evidence $evidencePath -LicensePath $LicensePath -ClientFolder $(if ($ProfilePath) { Split-Path -Parent $ProfilePath })
    $params = @{ Catalog = $catalog; Baseline = $baselineModel; OrgProfile = $profileModel; Exception = $exceptionList; Evidence = $evidencePath; Entitlement = $entitlement }
    if ($Domain) { $params.Domain = $Domain }
    $run = Invoke-PostureCheckEvaluation @params
    $run.entitlement = ConvertTo-PostureEntitlementRecord -Entitlement $entitlement
    $run.exceptionsFile = $(if ($Exceptions) { (Resolve-Path -LiteralPath $Exceptions).Path } else { $null })
    $run.moduleVersion = $script:ModuleVersion

    $outFolder = if ($OutputPath) { $OutputPath } else { $evidencePath }
    if (-not (Test-Path -LiteralPath $outFolder)) { New-Item -ItemType Directory -Path $outFolder -Force | Out-Null }
    $path = Join-Path (Resolve-Path -LiteralPath $outFolder).Path 'checks.json'
    [System.IO.File]::WriteAllText($path, (ConvertTo-Json -InputObject $run -Depth 20), [System.Text.UTF8Encoding]::new($false))

    $c = $run.counts
    Write-Verbose "checks.json: pass $($c.pass), fail $($c.fail), not evaluated $($c.notEvaluated), not applicable $($c.notApplicable), accepted risk $($c.acceptedRisk), covered $($c.coveredBy)"
    if ($PassThru) { return $run }
    return $path
}