Private/Get-PostureEmailFact.ps1

# Copyright (c) 2026 Kainor LLC. Source-available, see LICENSE.md.
function Get-PostureEmailFact {
    <#
    .SYNOPSIS
        Fact provider for the email domain (spec 4.10) from the A.2 Exchange Online files: preset policies, anti-phish,
        Safe Links and Attachments, ZAP, quarantine, forwarding, connection filter, SCL bypass rules, Enhanced
        Filtering, DKIM, SPF, DMARC, MTA-STS and TLS-RPT, legacy protocols, shared mailbox sign-in, auditing, attack
        simulation and ARC.
    .DESCRIPTION
        Thresholds read: minDmarcPolicy (quarantine or reject), spfRequireHardFail, maxDaysSinceSimulation.
        Profile read: licenses (E5 or MDE2 make Safe Documents expected).
    #>

    [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 = @{ minDmarcPolicy = 'reject'; spfRequireHardFail = $true; maxDaysSinceSimulation = 90 }
    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 { $_ }) }
    $facts = [ordered]@{}; $affected = [ordered]@{}; $notEvaluated = @{}
    $missing = { param([string[]] $Ids, [string] $File) foreach ($id in $Ids) { $notEvaluated[$id] = "$File.json was not collected (Invoke-PostureCollection -Collector Exchange; check errors.txt)." } }

    if (@(Get-ChildItem -LiteralPath $Evidence -Filter 'exo-*.json' -ErrorAction SilentlyContinue).Count -eq 0) {
        return @{ available = $false; reason = 'No Exchange Online evidence in the folder (Invoke-PostureCollection -Collector Exchange needs a Connect-ExchangeOnline session).' }
    }

    # Accepted domains: the custom authoritative ones are what DKIM and the DNS checks cover.
    $accepted = & $load 'exo-02-accepted-domains'
    $acceptedNames = @(& $rows $accepted | ForEach-Object { ([string]$_.DomainName).ToLowerInvariant() })
    $custom = @(& $rows $accepted | Where-Object { [string]$_.DomainType -eq 'Authoritative' -and [string]$_.DomainName -notmatch '(?i)\.onmicrosoft\.com$' } | ForEach-Object { ([string]$_.DomainName).ToLowerInvariant() })
    $facts.customDomains = $custom.Count

    # Preset security policies (EM-001, EM-002)
    foreach ($pair in @(@('exo-04-preset-rules-eop', 'Eop', 'EM-001'), @('exo-04-preset-rules-mdo', 'Mdo', 'EM-002'))) {
        $file, $kind, $id = $pair
        $r = & $load $file
        if ($null -eq $r) { & $missing @($id) $file; continue }
        $enabled = @(& $rows $r | Where-Object { [string]$_.State -eq 'Enabled' -and [string]$_.Name -match '(?i)standard|strict' })
        $all = @($enabled | Where-Object { @($_.SentTo | Where-Object { $_ }).Count -eq 0 -and @($_.SentToMemberOf | Where-Object { $_ }).Count -eq 0 -and @($_.RecipientDomainIs | Where-Object { $_ }).Count -eq 0 })
        $facts["preset${kind}Enabled"] = $enabled.Count -gt 0
        $facts["preset${kind}AllUsers"] = $all.Count -gt 0
        $facts["preset${kind}Names"] = @($enabled | ForEach-Object { [string]$_.Name })
    }

    # Anti-phish (EM-003 spoof, EM-004 impersonation)
    $ap = & $load 'exo-04-antiphish'
    if ($null -eq $ap) { & $missing @('EM-003', 'EM-004') 'exo-04-antiphish' }
    else {
        $pol = @(& $rows $ap | Where-Object { $_.Enabled -ne $false })
        $facts.antiPhishPolicies = $pol.Count
        $spoofGaps = @($pol | Where-Object { $_.EnableSpoofIntelligence -ne $true -or $_.HonorDmarcPolicy -ne $true })
        $facts.antiPhishSpoofGaps = $spoofGaps.Count
        $affected.antiPhishSpoofGaps = @($spoofGaps | ForEach-Object { [ordered]@{ name = [string]$_.Name; detail = "spoof intelligence $($_.EnableSpoofIntelligence), DMARC honoured $($_.HonorDmarcPolicy)" } })
        $impGaps = @($pol | Where-Object { $_.EnableTargetedUserProtection -ne $true -or @($_.TargetedUsersToProtect | Where-Object { $_ }).Count -eq 0 -or $_.EnableOrganizationDomainsProtection -ne $true -or $_.EnableMailboxIntelligence -ne $true })
        $facts.antiPhishImpersonationGaps = $impGaps.Count
        $affected.antiPhishImpersonationGaps = @($impGaps | ForEach-Object { [ordered]@{ name = [string]$_.Name; detail = "targeted users $(@($_.TargetedUsersToProtect | Where-Object { $_ }).Count), org domains $($_.EnableOrganizationDomainsProtection), mailbox intelligence $($_.EnableMailboxIntelligence)" } })
    }

    # Safe Links, Safe Attachments, global MDO settings (EM-005)
    $sl = & $load 'exo-05-mdo-safelinks'; $sa = & $load 'exo-05-mdo-safeattachments'; $g = & $load 'exo-05-mdo-global'
    if ($null -eq $sl -or $null -eq $sa -or $null -eq $g) { & $missing @('EM-005') 'exo-05-mdo-*' }
    else {
        $facts.safeLinksComplete = @(& $rows $sl | Where-Object { $_.EnableSafeLinksForEmail -eq $true -and $_.EnableSafeLinksForTeams -eq $true -and $_.EnableSafeLinksForOffice -eq $true }).Count -gt 0
        $facts.safeAttachmentsEnabled = @(& $rows $sa | Where-Object { $_.Enable -eq $true -and [string]$_.Action -in @('Block', 'DynamicDelivery') }).Count -gt 0
        $g1 = @(& $rows $g | Select-Object -First 1)
        $facts.safeAttachmentsSpoEnabled = [bool]($g1.Count -gt 0 -and (& $v $g1[0] 'EnableATPForSPOTeamsODB') -eq $true)
        $facts.safeDocumentsEnabled = [bool]($g1.Count -gt 0 -and (& $v $g1[0] 'EnableSafeDocs') -eq $true)
        $lic = @($OrgProfile['licenses'] | Where-Object { $_ })
        $facts.safeDocumentsExpected = [bool](@($lic | Where-Object { $_ -in @('E5', 'MDE2') }).Count -gt 0)
    }

    # ZAP (EM-006) and quarantine (EM-007) from the content filter and malware policies
    $cf = & $load 'exo-04-eop-content-filter'; $mw = & $load 'exo-04-eop-malware'
    if ($null -eq $cf) { & $missing @('EM-006', 'EM-007') 'exo-04-eop-content-filter' }
    else {
        $cfRows = @(& $rows $cf)
        $zapGaps = @(@($cfRows | Where-Object { $_.ZapEnabled -ne $true -or $_.SpamZapEnabled -ne $true -or $_.PhishZapEnabled -ne $true } | ForEach-Object { [ordered]@{ name = [string]$_.Name; detail = "content filter: ZAP $($_.ZapEnabled), spam $($_.SpamZapEnabled), phish $($_.PhishZapEnabled)" } }) +
            @($(if ($null -ne $mw) { @(& $rows $mw | Where-Object { $_.ZapEnabled -ne $true } | ForEach-Object { [ordered]@{ name = [string]$_.Name; detail = 'malware filter: ZAP off' } }) })))
        $facts.zapGaps = $zapGaps.Count
        $affected.zapGaps = $zapGaps
        $facts.highConfidencePhishAdminOnly = @($cfRows | Where-Object { [string]$_.HighConfidencePhishQuarantineTag -ne 'AdminOnlyAccessPolicy' }).Count -eq 0 -and $cfRows.Count -gt 0
        $affected.highConfidencePhishReleasable = @($cfRows | Where-Object { [string]$_.HighConfidencePhishQuarantineTag -ne 'AdminOnlyAccessPolicy' } | ForEach-Object { [ordered]@{ name = [string]$_.Name; detail = "high-confidence phish quarantine tag $($_.HighConfidencePhishQuarantineTag)" } })
        $q = & $load 'exo-05-quarantine-policies'
        $facts.quarantineNotificationsEnabled = [bool]($null -ne $q -and @(& $rows $q | Where-Object { $_.ESNEnabled -eq $true }).Count -gt 0)
    }

    # Automatic external forwarding (EM-008)
    $os = & $load 'exo-04-outbound-spam'
    if ($null -eq $os) { & $missing @('EM-008') 'exo-04-outbound-spam' }
    else {
        $open = @(& $rows $os | Where-Object { [string]$_.AutoForwardingMode -ne 'Off' })
        $facts.outboundPoliciesAllowingAutoForward = $open.Count
        $affected.outboundPoliciesAllowingAutoForward = @($open | ForEach-Object { [ordered]@{ name = [string]$_.Name; detail = "AutoForwardingMode $($_.AutoForwardingMode)" } })
    }

    # Connection filter allow list (EM-009)
    $conn = & $load 'exo-04-eop-connection-filter'
    if ($null -eq $conn) { & $missing @('EM-009') 'exo-04-eop-connection-filter' }
    else {
        $entries = @(& $rows $conn | ForEach-Object { $p = $_; @($p.IPAllowList | Where-Object { $_ }) | ForEach-Object { [ordered]@{ name = [string]$_; detail = "allow listed in $($p.Name)" } } })
        $facts.connectionFilterAllowListEntries = $entries.Count
        $affected.connectionFilterAllowListEntries = $entries
    }

    # SCL -1 transport rules (EM-010)
    $tr = & $load 'exo-03-transport-rules'
    if ($null -eq $tr) { & $missing @('EM-010') 'exo-03-transport-rules' }
    else {
        $bypass = @(& $rows $tr | Where-Object { [string]$_.State -eq 'Enabled' -and [string]$_.SetSCL -eq '-1' })
        $unscoped = @($bypass | Where-Object { @($_.SenderIpRanges | Where-Object { $_ }).Count -eq 0 -and @($_.HeaderContainsMessageHeader | Where-Object { $_ }).Count -eq 0 })
        $facts.sclBypassRules = $bypass.Count
        $facts.sclBypassRulesUnscoped = $unscoped.Count
        $affected.sclBypassRulesUnscoped = @($unscoped | ForEach-Object { [ordered]@{ name = [string]$_.Name; detail = "SCL -1 with no sender IP range or header condition (from scope $($_.FromScope))" } })
    }

    # Inbound connectors: Enhanced Filtering (EM-011) and ARC (EM-021)
    $ic = & $load 'exo-03-inbound-connectors'
    if ($null -eq $ic) { & $missing @('EM-011', 'EM-021') 'exo-03-inbound-connectors' }
    else {
        $partner = @(& $rows $ic | Where-Object { $_.Enabled -ne $false -and [string]$_.ConnectorType -eq 'Partner' })
        $noEf = @($partner | Where-Object { $_.EFSkipLastIP -ne $true -and @($_.EFSkipIPs | Where-Object { $_ }).Count -eq 0 })
        $facts.partnerInboundConnectors = $partner.Count
        $facts.partnerConnectorsWithoutEnhancedFiltering = $noEf.Count
        $affected.partnerConnectorsWithoutEnhancedFiltering = @($noEf | ForEach-Object { [ordered]@{ name = [string]$_.Name; detail = "partner connector, Enhanced Filtering off, senders $(@($_.SenderIPAddresses) -join ' ')" } })
    }
    $org = & $load 'exo-01-orgconfig'
    if ($null -eq $org) { & $missing @('EM-019', 'EM-021') 'exo-01-orgconfig' }
    else {
        $facts.arcTrustedSealers = @((& $v $org 'ArcTrustedSealers') | Where-Object { $_ }).Count
        $facts.mailboxAuditDisabledOrgWide = [bool]((& $v $org 'AuditDisabled') -eq $true)
    }

    # DKIM (EM-012)
    $dk = & $load 'exo-02-dkim'
    if ($null -eq $dk) { & $missing @('EM-012') 'exo-02-dkim' }
    else {
        $signed = @{}; foreach ($d in @(& $rows $dk)) { $signed[([string]$d.Domain).ToLowerInvariant()] = ($d.Enabled -eq $true) }
        $gaps = @($custom | Where-Object { -not ($signed.ContainsKey($_) -and $signed[$_]) })
        $facts.dkimDomainsWithoutSigning = $gaps.Count
        $affected.dkimDomainsWithoutSigning = @($gaps | ForEach-Object { [ordered]@{ name = $_; detail = $(if ($signed.ContainsKey($_)) { 'DKIM signing config present but disabled' } else { 'no DKIM signing config' }) } })
    }

    # Mail DNS (EM-013 DMARC, EM-014 SPF, EM-015 MTA-STS and TLS-RPT)
    $dns = & $load 'dns-01-mail-records'
    if ($null -eq $dns) { & $missing @('EM-013', 'EM-014', 'EM-015') 'dns-01-mail-records' }
    else {
        $dnsRows = @(& $rows $dns)
        $rank = @{ none = 0; quarantine = 1; reject = 2 }
        $minRank = $(if ($rank.ContainsKey([string]$t.minDmarcPolicy)) { $rank[[string]$t.minDmarcPolicy] } else { 2 })
        $dmarcGaps = @(); $spfGaps = @(); $stsGaps = @()
        foreach ($r in $dnsRows) {
            $d = [string]$r.Domain
            $dmarc = [string]$r.DMARC
            if (-not $dmarc) { $dmarcGaps += , [ordered]@{ name = $d; detail = 'no DMARC record' } }
            else {
                $p = $(if ($dmarc -match '(?i)(?:^|;)\s*p\s*=\s*([a-z]+)') { $Matches[1].ToLowerInvariant() } else { 'none' })
                $rua = $dmarc -match '(?i)(?:^|;)\s*rua\s*='
                $pr = $(if ($rank.ContainsKey($p)) { $rank[$p] } else { 0 })
                if ($pr -lt $minRank) { $dmarcGaps += , [ordered]@{ name = $d; detail = "p=$p, target $($t.minDmarcPolicy)" } }
                elseif (-not $rua) { $dmarcGaps += , [ordered]@{ name = $d; detail = "p=$p but no rua reporting address" } }
            }
            $spf = [string]$r.SPF
            if (-not $spf) { $spfGaps += , [ordered]@{ name = $d; detail = 'no SPF record' } }
            else {
                $lookups = @([regex]::Matches($spf, '(?i)(?:^|\s)(?:include:|a(?=[\s:/]|$)|mx(?=[\s:/]|$)|ptr|exists:|redirect=)')).Count
                $allTerm = $(if ($spf -match '(?i)([-~?+]?)all\s*$') { $Matches[1] } else { $null })
                if ($lookups -gt 10) { $spfGaps += , [ordered]@{ name = $d; detail = "$lookups lookup mechanisms in the record (limit 10, nested includes not counted)" } }
                elseif ($null -eq $allTerm) { $spfGaps += , [ordered]@{ name = $d; detail = 'no all mechanism' } }
                elseif ([bool]$t.spfRequireHardFail -and $allTerm -ne '-') { $spfGaps += , [ordered]@{ name = $d; detail = "ends with ${allTerm}all, not -all" } }
                elseif ($allTerm -in @('+', '?')) { $spfGaps += , [ordered]@{ name = $d; detail = "ends with ${allTerm}all" } }
            }
            if (-not [string]$r.MTASTS -or -not [string]$r.TLSRPT) { $stsGaps += , [ordered]@{ name = $d; detail = "MTA-STS $(if ($r.MTASTS) { 'published' } else { 'missing' }), TLS-RPT $(if ($r.TLSRPT) { 'published' } else { 'missing' })" } }
        }
        $facts.dnsDomains = $dnsRows.Count
        $facts.dmarcGaps = $dmarcGaps.Count; $affected.dmarcGaps = @($dmarcGaps)
        $facts.spfGaps = $spfGaps.Count; $affected.spfGaps = @($spfGaps)
        $facts.mtaStsGaps = $stsGaps.Count; $affected.mtaStsGaps = @($stsGaps)
    }

    # Mailboxes (EM-016 forwarding, EM-018 shared mailbox sign-in, EM-019 auditing)
    $mbx = & $load 'exo-09-mailboxes'
    if ($null -eq $mbx) { & $missing @('EM-016', 'EM-018') 'exo-09-mailboxes' }
    else {
        $m = @(& $rows $mbx)
        $facts.mailboxes = $m.Count
        $fwd = @($m | Where-Object { $_.ForwardingSmtpAddress -or $_.ForwardingAddress } | ForEach-Object {
                $smtp = ([string]$_.ForwardingSmtpAddress) -replace '^smtp:', ''
                $dom = $(if ($smtp -match '@(.+)$') { $Matches[1].ToLowerInvariant() } else { '' })
                $external = $smtp -and ($dom -notin $acceptedNames)
                if ($external) { [ordered]@{ name = [string]$_.UserPrincipalName; detail = "forwards to $smtp (external)" } }
                elseif (-not $smtp -and $_.ForwardingAddress) { [ordered]@{ name = [string]$_.UserPrincipalName; detail = "forwards to recipient $($_.ForwardingAddress) (verify it is internal)" } }
            })
        $facts.mailboxesForwardingExternally = $fwd.Count
        $affected.mailboxesForwardingExternally = $fwd

        $shared = @($m | Where-Object { [string]$_.RecipientTypeDetails -eq 'SharedMailbox' })
        $facts.sharedMailboxes = $shared.Count
        $users = & $load '06-users'
        if ($null -eq $users) { $notEvaluated['EM-018'] = '06-users.json was not collected (Entra collector); the shared mailbox sign-in state needs it.' }
        else {
            $enabledIds = @{}; foreach ($u in @(& $rows $users | Where-Object { $_.AccountEnabled -eq $true })) { $enabledIds[[string]$u.Id] = $true }
            $signIn = @($shared | Where-Object { $_.ExternalDirectoryObjectId -and $enabledIds.ContainsKey([string]$_.ExternalDirectoryObjectId) })
            $facts.sharedMailboxesSignInEnabled = $signIn.Count
            $affected.sharedMailboxesSignInEnabled = @($signIn | ForEach-Object { [ordered]@{ name = [string]$_.UserPrincipalName; detail = 'shared mailbox whose account is enabled for sign-in' } })
        }
    }

    # Protocols (EM-017)
    $tc = & $load 'exo-01-transport-config'; $cas = & $load 'exo-10-cas-summary'
    if ($null -eq $tc -or $null -eq $cas) { & $missing @('EM-017') 'exo-01-transport-config, exo-10-cas-summary' }
    else {
        $facts.smtpClientAuthDisabled = [bool]((& $v $tc 'SmtpClientAuthenticationDisabled') -eq $true)
        $facts.mailboxesWithPop = [int](& $v $cas 'PopEnabled'); $facts.mailboxesWithImap = [int](& $v $cas 'ImapEnabled'); $facts.mailboxesWithSmtpAuthOverride = [int](& $v $cas 'SmtpAuthExplicitlyEnabled')
        $casRows = & $load 'exo-10-cas-mailboxes'
        $affected.legacyProtocolMailboxes = @(& $rows $casRows | Where-Object { $_.PopEnabled -eq $true -or $_.ImapEnabled -eq $true -or $_.SmtpClientAuthenticationDisabled -eq $false } | ForEach-Object { [ordered]@{ name = [string]$_.PrimarySmtpAddress; detail = (@($(if ($_.PopEnabled) { 'POP' }), $(if ($_.ImapEnabled) { 'IMAP' }), $(if ($_.SmtpClientAuthenticationDisabled -eq $false) { 'SMTP AUTH override' })) | Where-Object { $_ }) -join ', ' } })
    }

    # Audit (EM-019)
    $audit = & $load 'exo-01-audit-config'
    if ($null -eq $audit) { & $missing @('EM-019') 'exo-01-audit-config' }
    else { $facts.unifiedAuditLogEnabled = [bool]((& $v $audit 'UnifiedAuditLogIngestionEnabled') -eq $true) }

    # Attack simulation (EM-020)
    $sim = & $load 'exo-11-attack-simulations'
    if ($null -eq $sim) { & $missing @('EM-020') 'exo-11-attack-simulations' }
    else {
        $window = $AsOf.AddDays(-[int]$t.maxDaysSinceSimulation)
        $recent = @(& $rows $sim | Where-Object { $d = ConvertTo-PostureUtcDateTime $(if ($_.CompletionDateTime) { $_.CompletionDateTime } else { $_.LaunchDateTime }); $d -and $d -ge $window })
        $facts.attackSimulations = @(& $rows $sim).Count
        $facts.attackSimulationsInWindow = $recent.Count
    }

    return @{ available = $true; facts = $facts; affected = $affected; notEvaluated = $notEvaluated; evidence = @('exo-01-orgconfig.json', 'dns-01-mail-records.json') }
}