Private/Invoke-PostureCheckEvaluation.ps1
|
# Copyright (c) 2026 Kainor LLC. Source-available, see LICENSE.md. function Invoke-PostureCheckEvaluation { <# .SYNOPSIS The check engine: runs a catalog against evidence with a baseline, a profile and exceptions, one result per check in scope. .DESCRIPTION Facts come from one provider per domain, Get-Posture<Domain>Fact, called once per domain as -Evidence <folder> -OrgProfile <profile> -Thresholds <merged domain thresholds>. -FactProvider overrides providers by domain (tests). Statuses: pass, fail, notEvaluated (reason: license, data missing, provider failed), notApplicable (profile), acceptedRisk (exception), coveredBy (third-party control in the profile). Threshold precedence: catalog default, then profile.thresholds by key, then baseline.thresholds[check id]. #> [CmdletBinding()] [OutputType([System.Collections.Specialized.OrderedDictionary])] param( [Parameter(Mandatory)] [System.Collections.IDictionary] $Catalog, [Parameter(Mandatory)] [System.Collections.IDictionary] $Baseline, [Parameter(Mandatory)] [System.Collections.IDictionary] $OrgProfile, [AllowEmptyCollection()] [object[]] $Exception = @(), [Parameter(Mandatory)] [string] $Evidence, [string[]] $Domain, [hashtable] $FactProvider = @{}, [datetime] $AsOf = [datetime]::UtcNow, [System.Collections.IDictionary] $Entitlement ) $ErrorActionPreference = 'Stop' # 1. Scope from the baseline, then the optional domain filter. $all = @($Catalog.checks) # Selection entries: '*', a check id, 'domain:<slug>', or 'framework:<key>' (every check that carries a reference for that framework). $selectors = @($Baseline.checks | ForEach-Object { [string]$_ }) $selected = if ($selectors -contains '*') { $all } else { @($all | Where-Object { $c = $_ ($c['id'] -in $selectors) -or (@($selectors | Where-Object { $_ -like 'domain:*' } | ForEach-Object { $_.Substring(7) }) -contains [string]$c['domain']) -or (@($selectors | Where-Object { $_ -like 'framework:*' } | ForEach-Object { $_.Substring(10) } | Where-Object { $c['frameworks'] -and $c['frameworks'].Contains($_) -and [string]$c['frameworks'][$_] }).Count -gt 0) }) } $selected = @($selected | Where-Object { $_['id'] -notin @($Baseline.exclude) }) if ($Domain) { $selected = @($selected | Where-Object { [string]$_['domain'] -in $Domain }) } # 2. Effective thresholds per check, and merged per domain for the providers. $effective = @{} $domainThresholds = @{} foreach ($c in $selected) { $t = [ordered]@{} foreach ($k in @($c['thresholds'].Keys)) { $t[$k] = $c['thresholds'][$k] } foreach ($k in @($t.Keys)) { if ($OrgProfile.thresholds -and $OrgProfile.thresholds.Contains($k)) { $t[$k] = $OrgProfile.thresholds[$k] } } $override = $Baseline.thresholds[$c['id']] if ($override) { foreach ($k in @($override.Keys)) { $t[$k] = $override[$k] } } $effective[$c['id']] = $t $d = [string]$c['domain'] if (-not $domainThresholds.ContainsKey($d)) { $domainThresholds[$d] = @{} } foreach ($k in @($t.Keys)) { $domainThresholds[$d][$k] = $t[$k] } } # 3. Facts per domain. $domainFacts = @{} # Entitlement (Get-PostureEntitlement): domains outside the licensed set get no facts, so their checks read as not evaluated with the licence reason. $licensedDomains = $null; $unlicensedReason = $null if ($Entitlement -and $Entitlement.Contains('domains') -and -not ($Entitlement['domains'] -is [string] -and $Entitlement['domains'] -eq '*')) { $licensedDomains = @($Entitlement['domains']); $unlicensedReason = "Not licensed. $($Entitlement['reason'])" } foreach ($d in @($domainThresholds.Keys)) { if ($null -ne $licensedDomains -and $d -notin $licensedDomains) { $domainFacts[$d] = @{ available = $false; reason = $unlicensedReason }; continue } $provider = $FactProvider[$d] if (-not $provider) { $name = "Get-Posture$($d.Substring(0, 1).ToUpperInvariant() + $d.Substring(1))Fact" $cmd = Get-Command -Name $name -ErrorAction SilentlyContinue if ($cmd) { $provider = $cmd } } if (-not $provider) { $domainFacts[$d] = @{ available = $false; reason = "No fact provider for domain '$d'." }; continue } try { $r = & $provider -Evidence $Evidence -OrgProfile $OrgProfile -Thresholds $domainThresholds[$d] if (-not $r.Contains('available')) { $r['available'] = $true } if (-not $r.Contains('affected')) { $r['affected'] = @{} } if (-not $r.Contains('evidence')) { $r['evidence'] = @() } $domainFacts[$d] = $r } catch { $domainFacts[$d] = @{ available = $false; reason = "Fact provider for '$d' failed: $($_.Exception.Message)" } } } # 4. Evaluate. $results = foreach ($c in $selected) { $id = [string]$c['id']; $d = [string]$c['domain'] $thresholds = $effective[$id] $severity = if ($Baseline.severity -and $Baseline.severity[$id]) { [string]$Baseline.severity[$id] } else { [string]$c['severityDefault'] } $result = [ordered]@{ id = $id; domain = $d; title = [string]$c['title']; status = $null; severity = $severity; reason = $null thresholds = $thresholds; affected = @(); affectedCount = 0; evidence = @($c['evidence']); exception = $null coveredBy = $null; custom = [bool]$c['custom']; checkedUtc = $AsOf.ToString('o') } # Applicability against the profile: a key the profile knows with no overlap means not applicable. $na = $null foreach ($k in @($c['applicableWhen'].Keys)) { $wanted = @($c['applicableWhen'][$k]) if ($wanted.Count -eq 0 -or -not $OrgProfile.Contains($k)) { continue } $have = @(@($OrgProfile[$k]) | Where-Object { $null -ne $_ -and $_ -ne '' }) if ($have.Count -eq 0) { continue } if (@($wanted | Where-Object { $_ -in $have }).Count -eq 0) { $na = "Profile: $k is $($have -join ', '), check applies to $($wanted -join ', ')."; break } } if ($na) { $result.status = 'notApplicable'; $result.reason = $na; $result; continue } # Third-party coverage. $covered = $null foreach ($cb in @($c['coveredBy'])) { $cat, $vendor = ([string]$cb).Split(':', 2) if ($OrgProfile.thirdParty -and $OrgProfile.thirdParty.Contains($cat)) { $have = [string]$OrgProfile.thirdParty[$cat] if ($have -and $have -ne 'none' -and ($vendor -eq '*' -or $vendor -eq $have)) { $covered = "$cat`:$have"; break } } } if ($covered) { $result.status = 'coveredBy'; $result.coveredBy = $covered; $result.reason = "Covered by $($covered.Split(':')[1]) per the profile; verify there."; $result; continue } # License gate, only when the profile states licenses. $needs = @($c['license']) if ($OrgProfile.present -and $needs.Count -gt 0 -and @($OrgProfile.licenses).Count -gt 0 -and @($needs | Where-Object { $_ -in @($OrgProfile.licenses) }).Count -eq 0) { $result.status = 'notEvaluated'; $result.reason = "Requires $($needs -join ' or ')."; $result; continue } # Facts. $df = $domainFacts[$d] if (-not $df -or -not $df['available']) { $result.status = 'notEvaluated'; $result.reason = $(if ($df) { [string]$df['reason'] } else { 'No facts for this domain.' }); $result; continue } $result.evidence = @(@($c['evidence']) + @($df['evidence']) | Select-Object -Unique) # A provider may rule a specific check out with a reason (for example: no naming pattern configured). if ($df.Contains('notEvaluated') -and $df['notEvaluated'] -and $df['notEvaluated'].Contains($id)) { $result.status = 'notEvaluated'; $result.reason = [string]$df['notEvaluated'][$id]; $result; continue } try { $passed = Invoke-PostureExpression -Expression ([string]$c['pass']) -Context @{ facts = $df['facts']; thresholds = $thresholds } } catch { $result.status = 'notEvaluated'; $result.reason = "Data missing: $($_.Exception.Message)"; $result; continue } if ($c.Contains('affected') -and $c['affected']) { $key = ([string]$c['affected']) -replace '^facts\.', '' if ($df['affected'].Contains($key)) { $result.affected = @($df['affected'][$key]) } } $result.status = if ($passed) { 'pass' } else { 'fail' } # Exceptions. $mine = @($Exception | Where-Object { $_.check -eq $id }) $active = @($mine | Where-Object { -not $_.expired }) $expiredOnes = @($mine | Where-Object { $_.expired }) if ($result.status -eq 'fail' -and $active.Count -gt 0) { $checkLevel = @($active | Where-Object { -not $_.object }) $objectLevel = @($active | Where-Object { $_.object }) if ($checkLevel.Count -gt 0) { $e = $checkLevel[0] $result.status = 'acceptedRisk'; $result.exception = $e $result.reason = "Accepted risk: $($e.justification) (owner $($e.owner), approver $($e.approver), until $(if ($e.expires) { $e.expires.ToString('yyyy-MM-dd') } else { 'no expiry' }))." } elseif ($result.affected.Count -gt 0) { $names = @($objectLevel | ForEach-Object { $_.object }) $label = { param($o) if ($o -is [System.Collections.IDictionary]) { [string]$o['name'] } elseif ($o.PSObject.Properties['name']) { [string]$o.name } else { [string]$o } } $remaining = @($result.affected | Where-Object { (& $label $_) -notin $names }) $excepted = @($result.affected | Where-Object { (& $label $_) -in $names }) if ($excepted.Count -gt 0) { $result.affected = $remaining if ($remaining.Count -eq 0) { $result.status = 'acceptedRisk'; $result.exception = $objectLevel $result.reason = "Accepted risk for $($excepted.Count) object(s): $(@($objectLevel | ForEach-Object { "$($_.object): $($_.justification)" }) -join '; ')." } else { $result.reason = "$($excepted.Count) object(s) accepted by exception; $($remaining.Count) remain." } } } } if ($expiredOnes.Count -gt 0 -and $result.status -ne 'acceptedRisk') { $result.reason = (@($result.reason, "$($expiredOnes.Count) expired exception(s) ignored.") | Where-Object { $_ }) -join ' ' } $result.affectedCount = @($result.affected).Count $result } $counts = [ordered]@{} foreach ($s in 'pass', 'fail', 'notEvaluated', 'notApplicable', 'acceptedRisk', 'coveredBy') { $counts[$s] = @($results | Where-Object { $_.status -eq $s }).Count } # Per-domain facts travel with the run so a report can show headline numbers from the same evaluation. $domains = [ordered]@{} foreach ($d in ($domainFacts.Keys | Sort-Object)) { $df = $domainFacts[$d] $domains[$d] = [ordered]@{ available = [bool]$df['available'] reason = $(if ($df.Contains('reason')) { [string]$df['reason'] } else { $null }) facts = $(if ($df['available']) { $df['facts'] } else { @{} }) evidence = @($(if ($df.Contains('evidence')) { $df['evidence'] } else { @() })) } } return [ordered]@{ catalogVersion = $Catalog.version baseline = $Baseline.name profile = $(if ($OrgProfile.present) { $OrgProfile.path } else { 'none (license gating off)' }) evidence = $Evidence evaluatedUtc = $AsOf.ToString('o') counts = $counts domains = $domains results = @($results) } } |