Private/Invoke-PostureExoCommand.ps1
|
# Copyright (c) 2026 Kainor LLC. Source-available, see LICENSE.md. function Test-PostureExoSession { <# .SYNOPSIS True when an Exchange Online PowerShell session (ExchangeOnlineManagement 3.x) is connected. Never connects. #> [CmdletBinding()] [OutputType([bool])] param() $ErrorActionPreference = 'Stop' if (-not (Get-Command -Name Get-ConnectionInformation -ErrorAction SilentlyContinue)) { return $false } $info = @(Get-ConnectionInformation -ErrorAction SilentlyContinue | Where-Object { $_.State -eq 'Connected' -and $_.ConnectionUri -notmatch 'compliance' }) return $info.Count -gt 0 } function Test-PosturePurviewSession { <# .SYNOPSIS True when a Security and Compliance PowerShell session (Connect-IPPSSession) is connected. Never connects. #> [CmdletBinding()] [OutputType([bool])] param() $ErrorActionPreference = 'Stop' if (-not (Get-Command -Name Get-ConnectionInformation -ErrorAction SilentlyContinue)) { return $false } $info = @(Get-ConnectionInformation -ErrorAction SilentlyContinue | Where-Object { $_.State -eq 'Connected' -and $_.ConnectionUri -match 'compliance' }) return $info.Count -gt 0 } function Invoke-PostureExoCommand { <# .SYNOPSIS The single entry point for Exchange Online and Security and Compliance cmdlets: Get-* only, by name, so tests can mock one function. #> [CmdletBinding()] [OutputType([object[]])] param( [Parameter(Mandatory)] [ValidatePattern('^Get-[A-Za-z0-9]+$')] [string] $Name, [hashtable] $Parameters = @{} ) $ErrorActionPreference = 'Stop' if (-not (Get-Command -Name $Name -ErrorAction SilentlyContinue)) { # A connected session loads only the cmdlets the signed-in roles and the tenant's licences expose (seen live on # Business Premium, 2026-10-23: no Get-AutoSensitivityLabelPolicy, no Get-InformationBarrierPolicy). if ((Test-PostureExoSession) -or (Test-PosturePurviewSession)) { throw "$Name is not in this session: the signed-in roles or the tenant's licences do not expose it." } throw "$Name is not available; import ExchangeOnlineManagement and connect first." } return @(& $Name @Parameters) } function ConvertTo-PostureFlatObject { <# .SYNOPSIS Projects a rich cmdlet object to an ordered dictionary of scalar and scalar-list properties, so evidence stays small and predictable. -Property limits the set; otherwise every scalar property is kept. #> [CmdletBinding()] [OutputType([System.Collections.Specialized.OrderedDictionary])] param( [Parameter(Mandatory, ValueFromPipeline)] [object] $InputObject, [string[]] $Property ) process { $ErrorActionPreference = 'Stop' $out = [ordered]@{} $names = if ($Property) { $Property } else { @($InputObject.PSObject.Properties | Where-Object { $_.MemberType -in 'Property', 'NoteProperty', 'AliasProperty' } | ForEach-Object { $_.Name }) } foreach ($n in $names) { $prop = $InputObject.PSObject.Properties[$n] if (-not $prop) { $out[$n] = $null; continue } $val = $prop.Value if ($null -eq $val) { $out[$n] = $null } elseif ($val -is [string] -or $val -is [bool] -or $val -is [int] -or $val -is [long] -or $val -is [double] -or $val -is [datetime] -or $val -is [enum] -or $val -is [guid]) { $out[$n] = $(if ($val -is [enum] -or $val -is [guid]) { [string]$val } else { $val }) } elseif ($val -is [System.Collections.IEnumerable] -and $val -isnot [System.Collections.IDictionary]) { $out[$n] = @($val | ForEach-Object { [string]$_ }) } else { $out[$n] = [string]$val } } $out } } function Resolve-PostureDnsRecord { <# .SYNOPSIS Returns the TXT or MX record strings for a name, through dig on macOS and Linux and Resolve-DnsName on Windows. Empty array when nothing is published. Tests mock this function. #> [CmdletBinding()] [OutputType([string[]])] param( [Parameter(Mandatory)] [string] $Name, [ValidateSet('TXT', 'MX')] [string] $Type = 'TXT' ) $ErrorActionPreference = 'Stop' if ($IsWindows) { # The answer can carry extra records of other types (CNAME, A); only the requested type has the fields read below. $r = @(Resolve-DnsName -Name $Name -Type $Type -ErrorAction SilentlyContinue | Where-Object { [string]$_.Type -eq $Type }) if ($Type -eq 'TXT') { return @($r | ForEach-Object { (@($_.Strings) -join '') } | Where-Object { $_ }) } return @($r | ForEach-Object { "$($_.Preference) $($_.NameExchange)" } | Where-Object { $_ }) } $dig = Get-Command -Name dig -ErrorAction SilentlyContinue if (-not $dig) { throw 'dig is not available; install bind tools or run the DNS step on Windows.' } $lines = @(& $dig.Source +short +time=3 +tries=1 $Type $Name 2>$null | Where-Object { $_ }) if ($Type -eq 'TXT') { return @($lines | ForEach-Object { ($_ -replace '"\s+"', '') -replace '^"|"$', '' }) } return @($lines | ForEach-Object { ($_ -replace '\.$', '').Trim() }) } |