Private/Get-PostureEntitlement.ps1
|
# Copyright (c) 2026 Kainor LLC. Source-available, see LICENSE.md. function Get-PostureEntitlement { <# .SYNOPSIS What this run is allowed to evaluate. The Conditional Access domain and the three CA cmdlets are free (spec 5.5); every other domain needs a Full licence bound to the evidence's tenant. .DESCRIPTION The licence file is looked for in this order: -LicensePath, the TENANTKEEP_LICENSE environment variable, the client folder's tenantkeep.lic, then ~/tenantkeep/tenantkeep.lic. The tenant id comes from the evidence (collection.json, else metadata.json). Evidence without a tenant id gets the free tier: the module cannot bind a licence to it. The test suite sets $script:PostureEntitlementOverride inside the module scope to run the catalog against fixtures without a licence. Nothing outside the module can set it; editing the module files is the only way, and the licence terms cover that. #> [CmdletBinding()] [OutputType([hashtable])] param( [Parameter(Mandatory)] [string] $Evidence, [string] $LicensePath, [string] $ClientFolder ) $ErrorActionPreference = 'Stop' $override = Get-Variable -Name PostureEntitlementOverride -Scope Script -ValueOnly -ErrorAction SilentlyContinue if ($override) { return @{ licensed = $true; tier = [string]$override.tier; domains = '*'; reason = "Entitlement override: $($override.source)"; source = 'override'; licence = $null } } $read = { param([string] $Name) $f = Join-Path $Evidence "$Name.json"; if (Test-Path -LiteralPath $f) { try { Get-Content -Raw -LiteralPath $f | ConvertFrom-Json -AsHashtable -Depth 10 } catch { $null } } } $meta = & $read 'collection'; if (-not $meta) { $meta = & $read 'metadata' } $tenantId = [string]$(if ($meta -and $meta.Contains('tenantId')) { $meta['tenantId'] }) $collected = $(if ($meta -and $meta.Contains('timestampUtc') -and $meta['timestampUtc']) { ConvertTo-PostureUtcDateTime $meta['timestampUtc'] }) $asOf = [datetime]::UtcNow; if ($collected -and $collected -gt $asOf) { $asOf = $collected } $free = { param([string] $why) @{ licensed = $false; tier = 'none'; domains = @('ca'); reason = $why; source = $null; licence = $null; tenantId = $tenantId } } if (-not $tenantId) { return & $free 'The evidence folder has no collection.json or metadata.json with a tenant id, so no licence can be bound to it. Collect with Invoke-PostureCollection to get the full report.' } $candidates = [System.Collections.Generic.List[string]]::new() if ($LicensePath) { $candidates.Add($LicensePath) } if ($env:TENANTKEEP_LICENSE) { $candidates.Add($env:TENANTKEEP_LICENSE) } if ($ClientFolder) { $candidates.Add((Join-Path $ClientFolder 'tenantkeep.lic')) } $candidates.Add((Join-Path $HOME 'tenantkeep' 'tenantkeep.lic')) $path = $null foreach ($c in $candidates) { $p = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($c); if (Test-Path -LiteralPath $p -PathType Leaf) { $path = $p; break } } if (-not $path) { return & $free "No licence file found (looked for $($candidates -join ', ')). The Conditional Access domain is evaluated; the other domains need a TenantKeep Posture licence (docs/licensing.md)." } $check = Test-PostureLicense -Path $path -TenantId $tenantId -AsOfUtc $asOf if (-not $check.valid) { return & $free "$($check.reason) The Conditional Access domain is evaluated; the other domains need a valid licence (docs/licensing.md)." } $domains = $(if ($check.tier -eq 'full') { '*' } else { @('ca') }) $reason = $(if ($check.tier -eq 'full') { $null } else { 'TenantKeep CA licence: the Conditional Access domain and the scheduled CA cycle. The other domains need the Posture (full) tier.' }) return @{ licensed = $true; tier = $check.tier; domains = $domains; reason = $reason; source = $path; licence = $check.licence; tenantId = $tenantId } } function ConvertTo-PostureEntitlementRecord { <# .SYNOPSIS What checks.json and the report record about the licence: tier, customer, expiry, reason. Never the file contents. #> [CmdletBinding()] [OutputType([System.Collections.Specialized.OrderedDictionary])] param([Parameter(Mandatory)] [System.Collections.IDictionary] $Entitlement) $lic = $Entitlement['licence'] return [ordered]@{ licensed = [bool]$Entitlement['licensed'] tier = [string]$Entitlement['tier'] customer = $(if ($lic) { [string]$lic['customer'] } else { $null }) expiresUtc = $(if ($lic) { [string]$lic['expiresUtc'] } else { $null }) licenceId = $(if ($lic) { [string]$lic['licenceId'] } else { $null }) reason = $(if ($Entitlement['reason']) { [string]$Entitlement['reason'] } else { $null }) } } function Confirm-PostureEntitlement { <# .SYNOPSIS Re-verifies an entitlement where it is consumed (the report model, the findings export) rather than trusting the record the engine made. A licensed entitlement must still verify from its file; anything else is the free tier. #> [CmdletBinding()] [OutputType([hashtable])] param([Parameter(Mandatory)] [System.Collections.IDictionary] $Entitlement) $ErrorActionPreference = 'Stop' if ([string]$Entitlement['source'] -eq 'override') { $override = Get-Variable -Name PostureEntitlementOverride -Scope Script -ValueOnly -ErrorAction SilentlyContinue if ($override) { return $Entitlement } return @{ licensed = $false; tier = 'none'; domains = @('ca'); reason = 'Entitlement override claimed but not set.'; source = $null; licence = $null } } if (-not $Entitlement['licensed']) { return $Entitlement } $path = [string]$Entitlement['source']; $tenantId = [string]$(if ($Entitlement.Contains('tenantId')) { $Entitlement['tenantId'] }) if (-not $path -or -not $tenantId) { return @{ licensed = $false; tier = 'none'; domains = @('ca'); reason = 'Licence could not be re-verified (no file or tenant id). The Conditional Access domain is evaluated.'; source = $null; licence = $null; tenantId = $tenantId } } $check = Test-PostureLicense -Path $path -TenantId $tenantId if (-not $check.valid) { return @{ licensed = $false; tier = 'none'; domains = @('ca'); reason = "$($check.reason) The Conditional Access domain is evaluated."; source = $null; licence = $null; tenantId = $tenantId } } $domains = $(if ($check.tier -eq 'full') { '*' } else { @('ca') }) return @{ licensed = $true; tier = $check.tier; domains = $domains; reason = $Entitlement['reason']; source = $path; licence = $check.licence; tenantId = $tenantId } } function Limit-PostureResultsToEntitlement { <# .SYNOPSIS Applies an entitlement to a result list: checks outside the licensed domains become not evaluated with the licence reason. #> [CmdletBinding()] [OutputType([object[]])] param([Parameter(Mandatory)] [AllowEmptyCollection()] [object[]] $Results, [Parameter(Mandatory)] [System.Collections.IDictionary] $Entitlement) $domains = $Entitlement['domains'] if ($domains -is [string] -and $domains -eq '*') { return , $Results } $allowed = @($domains); $reason = "Not licensed. $($Entitlement['reason'])" return , @($Results | ForEach-Object { if ([string]$_['domain'] -in $allowed -or [string]$_['status'] -in @('notApplicable', 'notEvaluated')) { $_ } else { $x = [ordered]@{}; foreach ($k in $_.Keys) { $x[$k] = $_[$k] }; $x['status'] = 'notEvaluated'; $x['reason'] = $reason; $x['affected'] = @(); $x['affectedCount'] = 0; $x } }) } |