Private/Get-PostureGovernanceFact.ps1
|
# Copyright (c) 2026 Kainor LLC. Source-available, see LICENSE.md. function Get-PostureGovernanceFact { <# .SYNOPSIS Fact provider for the governance domain (spec 4.8): inactive members, access reviews on roles and guests, access packages, lifecycle workflows, PIM for Groups, the SSO protocol mix, SAML certificate expiry, administrative units, application owners and an HR-driven provisioning connector. .DESCRIPTION Reads 06-users-summary, 07-groups, 10-service-principals and the gov-* files. Thresholds read: maxInactiveMemberPct, maxPasswordSsoPct, samlCertWarningDays, adminUnitScaleUsers. The interview items in the spec (deprovisioning SLA, orphan accounts against an HR extract, SCIM error review) are not checks yet. #> [CmdletBinding()] [OutputType([hashtable])] param( [Parameter(Mandatory)] [string] $Evidence, [Parameter()] [System.Collections.IDictionary] $OrgProfile = @{}, [Parameter()] [System.Collections.IDictionary] $Thresholds = @{}, [datetime] $AsOf = [datetime]::UtcNow ) $ErrorActionPreference = 'Stop' $t = @{ maxInactiveMemberPct = 5; maxPasswordSsoPct = 10; samlCertWarningDays = 90; adminUnitScaleUsers = 1000 } foreach ($k in @($Thresholds.Keys)) { $t[$k] = $Thresholds[$k] } $load = { param([string] $Name) $f = Join-Path $Evidence "$Name.json" if (-not (Test-Path -LiteralPath $f)) { return $null } $text = Get-Content -Raw -LiteralPath $f if ([string]::IsNullOrWhiteSpace($text)) { return , @() } $parsed = ConvertFrom-Json -InputObject $text -AsHashtable -Depth 20 if ($null -eq $parsed) { return , @() } return $parsed } $v = { param($o, [string] $p) Get-PostureValue $o $p } $rows = { param($o) @($o | Where-Object { $_ }) } $pct = { param([double] $n, [double] $d) if ($d -le 0) { 0 } else { [Math]::Round(100.0 * $n / $d, 1) } } $facts = [ordered]@{}; $affected = [ordered]@{}; $notEvaluated = @{} $missing = { param([string[]] $Ids, [string] $File, [string] $Scope) foreach ($id in $Ids) { $notEvaluated[$id] = "$File.json was not collected (Entra collector; needs $Scope; check errors.txt)." } } $users = & $load '06-users-summary' if ($null -eq $users) { return @{ available = $false; reason = 'No identity evidence in the folder (Invoke-PostureCollection -Collector Entra).' } } $facts.members = [int](& $v $users 'Members') $facts.guests = [int](& $v $users 'Guests') $facts.enabledInactiveMembers = [int](& $v $users 'EnabledInactiveMembers') $facts.inactiveMemberPct = & $pct $facts.enabledInactiveMembers $facts.members if ((& $v $users 'SignInActivityAvailable') -eq $false) { $notEvaluated['GV-001'] = 'Sign-in activity was not collected (AuditLog.Read.All); inactive members cannot be counted.' } $facts.staleDays = & $v $users 'StaleDays' # Access reviews (GV-002, GV-003) $reviews = & $load 'gov-01-access-reviews' if ($null -eq $reviews) { & $missing @('GV-002', 'GV-003') 'gov-01-access-reviews' 'AccessReview.Read.All' } else { $active = @(& $rows $reviews | Where-Object { $_.Recurring -eq $true -and [string]$_.Status -notin @('Completed', 'Canceled') }) $facts.accessReviewDefinitions = @(& $rows $reviews).Count # (verify) the scope query shapes: role reviews point at roleManagement/directory or privilegedAccess; guest reviews filter userType eq 'Guest' $facts.privilegedRoleReviews = @($active | Where-Object { [string]$_.ScopeQuery -match 'roleManagement/directory|privilegedAccess|roleAssignment' }).Count $facts.guestReviews = @($active | Where-Object { [string]$_.ScopeQuery -match "userType eq 'Guest'|userType eq ''Guest''|/guest" }).Count } # Access packages (GV-004) $ap = & $load 'gov-02-access-packages-summary' if ($null -eq $ap) { & $missing @('GV-004') 'gov-02-access-packages-summary' 'EntitlementManagement.Read.All' } else { $facts.accessPackages = [int](& $v $ap 'Packages'); $facts.accessPackageCatalogs = [int](& $v $ap 'Catalogs'); $facts.connectedOrganizations = [int](& $v $ap 'ConnectedOrganizations') } # Lifecycle workflows (GV-005) $wf = & $load 'gov-03-lifecycle-workflows' if ($null -eq $wf) { & $missing @('GV-005') 'gov-03-lifecycle-workflows' 'LifecycleWorkflows.Read.All' } else { $enabled = @(& $rows $wf | Where-Object { $_.IsEnabled -eq $true }) $facts.lifecycleWorkflowsEnabled = $enabled.Count $facts.joinerWorkflow = @($enabled | Where-Object { [string]$_.Category -match '(?i)joiner' }).Count -gt 0 $facts.leaverWorkflow = @($enabled | Where-Object { [string]$_.Category -match '(?i)leaver' }).Count -gt 0 } # PIM for Groups (GV-006) $groups = & $load '07-groups'; $pim = & $load 'gov-04-pim-groups-summary' if ($null -eq $groups) { & $missing @('GV-006') '07-groups' 'Group.Read.All' } elseif ($null -eq $pim) { & $missing @('GV-006') 'gov-04-pim-groups-summary' 'PrivilegedEligibilitySchedule.Read.AzureADGroup' } else { $facts.roleAssignableGroups = @(& $rows $groups | Where-Object { $_.IsAssignableToRole -eq $true }).Count $facts.pimManagedGroups = [int](& $v $pim 'Groups') $facts.pimEligibleGroupAssignments = [int](& $v $pim 'EligibleAssignments') } # Service principals: SSO mix (GV-007), SAML certificates (GV-008), owners (GV-010), HR connector (GV-011) $sps = & $load '10-service-principals' if ($null -eq $sps) { & $missing @('GV-007', 'GV-008', 'GV-010', 'GV-011') '10-service-principals' 'Directory.Read.All' } else { $apps = @(& $rows $sps | Where-Object { $_.IsEnterpriseAppListed -eq $true -and $_.AccountEnabled -ne $false }) $facts.enterpriseApps = $apps.Count $byMode = @{} foreach ($a in $apps) { $m = [string]$a.PreferredSingleSignOnMode; if (-not $m) { $m = 'none' }; $byMode[$m] = 1 + $(if ($byMode.ContainsKey($m)) { $byMode[$m] } else { 0 }) } $facts.ssoByMode = [ordered]@{}; foreach ($k in ($byMode.Keys | Sort-Object)) { $facts.ssoByMode[$k] = $byMode[$k] } $federated = @($apps | Where-Object { [string]$_.PreferredSingleSignOnMode -in @('saml', 'oidc') }).Count $password = @($apps | Where-Object { [string]$_.PreferredSingleSignOnMode -eq 'password' }) $facts.ssoFederatedApps = $federated $facts.ssoPasswordApps = $password.Count $facts.passwordSsoPct = & $pct $password.Count ($federated + $password.Count) $affected.passwordSsoApps = @($password | ForEach-Object { [ordered]@{ name = [string]$_.DisplayName; detail = 'password-based single sign-on' } }) $warn = $AsOf.AddDays([int]$t.samlCertWarningDays) # Only applications signed in through SAML: every service principal can carry a Verify key, including first-party and retired apps. $expiring = @($apps | Where-Object { [string]$_.PreferredSingleSignOnMode -eq 'saml' -and $_.SamlCertExpiry } | Where-Object { $d = ConvertTo-PostureUtcDateTime $_.SamlCertExpiry; $d -and $d -lt $warn }) $facts.samlCertsExpiringSoon = $expiring.Count $affected.samlCertsExpiringSoon = @($expiring | ForEach-Object { [ordered]@{ name = [string]$_.DisplayName; detail = "SAML signing certificate expires $((ConvertTo-PostureUtcDateTime $_.SamlCertExpiry).ToString('yyyy-MM-dd'))" } }) if (@($apps | Where-Object { $_.Contains('OwnerCount') }).Count -eq 0 -and $apps.Count -gt 0) { $notEvaluated['GV-010'] = '10-service-principals.json predates the owner count; collect again.' } else { $ownerless = @($apps | Where-Object { [int]$_.OwnerCount -eq 0 }) $facts.enterpriseAppsWithoutOwner = $ownerless.Count $affected.enterpriseAppsWithoutOwner = @($ownerless | ForEach-Object { [ordered]@{ name = [string]$_.DisplayName; detail = 'enterprise application with no owner' } }) } # (verify) HR connector detection by name; API-driven inbound provisioning apps carry the template name $hr = @(& $rows $sps | Where-Object { [string]$_.DisplayName -match '(?i)workday|successfactors|api-driven|oracle hcm|oracle fusion|\bukg\b|bamboohr|\badp\b' }) $facts.hrProvisioningConnectors = $hr.Count } # Administrative units (GV-009) $aus = & $load 'gov-05-administrative-units' if ($null -eq $aus) { & $missing @('GV-009') 'gov-05-administrative-units' 'AdministrativeUnit.Read.All' } else { $facts.administrativeUnits = @(& $rows $aus).Count } return @{ available = $true; facts = $facts; affected = $affected; notEvaluated = $notEvaluated; evidence = @('06-users-summary.json', '10-service-principals.json') } } |