<#
.TITLE
    FileVault Key Storage Checker

.SYNOPSIS
    Monitor and verify that FileVault recovery keys for macOS devices are properly stored in Intune.

.DESCRIPTION
    This script connects to Microsoft Graph API, retrieves all macOS devices from Intune,
    and checks if each device has FileVault recovery keys stored in Intune. The script
    provides detailed reporting on compliance status, identifies devices without stored keys,
    and exports comprehensive results to CSV format for further analysis. This helps ensure
    proper FileVault key escrow for data recovery scenarios.

.TAGS
    Monitoring,Security

.MINROLE
    Intune Administrator

.PERMISSIONS
    DeviceManagementManagedDevices.PrivilegedOperations.All,DeviceManagementManagedDevices.Read.All

.AUTHOR
    Ugur Koc

.VERSION
    1.4

.CHANGELOG
    1.4 - Added Azure Automation contract validation, portal-safe boolean parameters, beta Graph endpoints, and terminating paging errors
    1.3 - Azure Automation now records script progress, outcomes, and summaries in job history
    1.2 - Key checks get a per-device delay and 429 retry; guarded last sync date parsing; device list selects only needed fields; pagination helper keeps single-item results as arrays
    1.1 - Local runs now use MgGraphCommunity for WAM-free interactive sign-in (auto-installed if missing); added DeviceManagementManagedDevices.PrivilegedOperations.All scope required by the Graph action (calls previously always failed with 403)
    1.0 - Initial release

.LASTUPDATE
    2026-07-30

.EXAMPLE
    .\check-filevault-keys.ps1
    Generates FileVault key storage report for all macOS devices in Intune

.EXAMPLE
    .\check-filevault-keys.ps1 -OutputPath "C:\Reports" -OnlyShowMissing "true"
    Saves report to specified directory and shows only devices missing FileVault keys

.EXAMPLE
    .\check-filevault-keys.ps1 -IncludeLastSync "true" -ExportJson "true"
    Includes last sync information and exports results in JSON format as well

.NOTES
    - Requires Microsoft.Graph.Authentication module: Install-Module Microsoft.Graph.Authentication
    - FileVault keys are automatically escrowed to Intune when properly configured
    - Devices must be enrolled in Intune and have FileVault policy applied
    - Consider configuring FileVault policies to enforce key escrow
    - Regular monitoring helps ensure compliance with data protection requirements
    - Local interactive sign-in uses the MgGraphCommunity module to avoid the Graph SDK's mandatory WAM broker on Windows
#>

[CmdletBinding()]
param(
    [Parameter(Mandatory = $false, HelpMessage = "Directory path to save reports")]
    [ValidateNotNullOrEmpty()]
    [string]$OutputPath = ".",

    [Parameter(Mandatory = $false, HelpMessage = "Only show devices missing FileVault keys")]
    [ValidateSet("true", "false", "1", "0", '$true', '$false')]
    [string]$OnlyShowMissing,

    [Parameter(Mandatory = $false, HelpMessage = "Include last sync date information")]
    [ValidateSet("true", "false", "1", "0", '$true', '$false')]
    [string]$IncludeLastSync,

    [Parameter(Mandatory = $false, HelpMessage = "Export results in JSON format as well")]
    [ValidateSet("true", "false", "1", "0", '$true', '$false')]
    [string]$ExportJson,

    [Parameter(Mandatory = $false, HelpMessage = "Show progress during processing")]
    [ValidateSet("true", "false", "1", "0", '$true', '$false')]
    [string]$ShowProgress,

    [Parameter(Mandatory = $false, HelpMessage = "Force module installation without prompting")]
    [ValidateSet("true", "false", "1", "0", '$true', '$false')]
    [string]$ForceModuleInstall
)

# Normalize the local module-install override for Azure Automation parameter binding.
$forceModuleInstallRaw = [string]$ForceModuleInstall
Remove-Variable -Name ForceModuleInstall
if ([string]::IsNullOrWhiteSpace($forceModuleInstallRaw)) {
    $ForceModuleInstall = $false
}
elseif ($forceModuleInstallRaw.Trim().ToLowerInvariant() -in @("true", "1", '$true')) {
    $ForceModuleInstall = $true
}
elseif ($forceModuleInstallRaw.Trim().ToLowerInvariant() -in @("false", "0", '$false')) {
    $ForceModuleInstall = $false
}
else {
    throw "Parameter 'ForceModuleInstall' accepts only true, false, 1, 0, $true, or $false."
}

# Azure Automation supplies portal parameter values as strings. Normalize the
# public boolean parameters once so local and runbook execution use real booleans.
foreach ($runbookBooleanParameter in @('OnlyShowMissing', 'IncludeLastSync', 'ExportJson', 'ShowProgress')) {
    $runbookBooleanRaw = [string](Get-Variable -Name $runbookBooleanParameter -ValueOnly)
    Remove-Variable -Name $runbookBooleanParameter

    if ([string]::IsNullOrWhiteSpace($runbookBooleanRaw)) {
        Set-Variable -Name $runbookBooleanParameter -Value $false
        continue
    }

    switch ($runbookBooleanRaw.Trim().ToLowerInvariant()) {
        { $_ -in @("true", "1", '$true') } {
            Set-Variable -Name $runbookBooleanParameter -Value $true
        }
        { $_ -in @("false", "0", '$false') } {
            Set-Variable -Name $runbookBooleanParameter -Value $false
        }
        default {
            throw "Parameter '$runbookBooleanParameter' accepts only true, false, 1, 0, $true, or $false."
        }
    }
}

# ============================================================================
# ENVIRONMENT DETECTION AND SETUP
# ============================================================================

function Initialize-RequiredModule {
    <#
    .SYNOPSIS
    Ensures required modules are available and loaded
    #>
    param(
        [string[]]$ModuleNames,
        [bool]$IsAutomationEnvironment,
        [bool]$ForceInstall = $false
    )

    foreach ($ModuleName in $ModuleNames) {
        Write-Verbose "Checking module: $ModuleName"

        # Check if module is available
        $module = Get-Module -ListAvailable -Name $ModuleName | Select-Object -First 1

        if (-not $module) {
            if ($IsAutomationEnvironment) {
                $errorMessage = @"
Module '$ModuleName' is not available in this Azure Automation Account.

To resolve this issue:
1. Go to Azure Portal
2. Navigate to your Automation Account
3. Go to 'Modules' > 'Browse Gallery'
4. Search for '$ModuleName'
5. Click 'Import' and wait for installation to complete

Alternative: Use PowerShell to import the module:
Import-Module Az.Automation
Import-AzAutomationModule -AutomationAccountName "YourAccount" -ResourceGroupName "YourRG" -Name "$ModuleName"
"@
                throw $errorMessage
            }
            else {
                # Local environment - attempt to install
                Write-Information "Module '$ModuleName' not found. Attempting to install..." -InformationAction Continue

                if (-not $ForceInstall) {
                    $response = Read-Host "Install module '$ModuleName'? (Y/N)"
                    if ($response -notmatch '^[Yy]') {
                        throw "Module '$ModuleName' is required but installation was declined."
                    }
                }

                try {
                    # Check if running as administrator for AllUsers scope
                    $isAdmin = ([Security.Principal.WindowsPrincipal] [Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole] "Administrator")
                    $scope = if ($isAdmin) { "AllUsers" } else { "CurrentUser" }

                    Write-Information "Installing '$ModuleName' in scope '$scope'..." -InformationAction Continue
                    Install-Module -Name $ModuleName -Scope $scope -Force -AllowClobber -Repository PSGallery
                    Write-Information "✓ Successfully installed '$ModuleName'" -InformationAction Continue
                }
                catch {
                    throw "Failed to install module '$ModuleName': $($_.Exception.Message)"
                }
            }
        }

        # Import the module
        try {
            Write-Verbose "Importing module: $ModuleName"
            Import-Module -Name $ModuleName -Force -ErrorAction Stop
            Write-Verbose "✓ Successfully imported '$ModuleName'"
        }
        catch {
            throw "Failed to import module '$ModuleName': $($_.Exception.Message)"
        }
    }
}

# Detect execution environment
if ($PSPrivateMetadata.JobId.Guid) {
    Write-Output "Running inside Azure Automation Runbook"
    $IsAzureAutomation = $true
}
else {
    Write-Output "Running locally in IDE or terminal"
    $IsAzureAutomation = $false
}

# Initialize required modules
$RequiredModuleList = @(
    "Microsoft.Graph.Authentication"
)

# MgGraphCommunity gives WAM-free interactive sign-in for local runs
if (-not $IsAzureAutomation) {
    $RequiredModuleList += "MgGraphCommunity"
}

try {
    Initialize-RequiredModule -ModuleNames $RequiredModuleList -IsAutomationEnvironment $IsAzureAutomation -ForceInstall $ForceModuleInstall
    Write-Verbose "✓ All required modules are available"
}
catch {
    Write-Error "Module initialization failed: $_"
    exit 1
}

# ============================================================================
# AUTHENTICATION
# ============================================================================

try {
    if ($IsAzureAutomation) {
        # Azure Automation - Use Managed Identity
        Write-Output "Connecting to Microsoft Graph using Managed Identity..."
        Connect-MgGraph -Identity -NoWelcome -ErrorAction Stop
        Write-Output "✓ Successfully connected to Microsoft Graph using Managed Identity"
    }
    else {
        # Local execution - WAM-free interactive sign-in via MgGraphCommunity
        Write-Output "Connecting to Microsoft Graph with interactive authentication..."
        $Scopes = @(
            "DeviceManagementManagedDevices.PrivilegedOperations.All",
            "DeviceManagementManagedDevices.Read.All"
        )
        Connect-MgGraphCommunity -Scopes $Scopes -NoWelcome -ErrorAction Stop
        Write-Output "✓ Successfully connected to Microsoft Graph"
    }
}
catch {
    Write-Error "Failed to connect to Microsoft Graph: $($_.Exception.Message)"
    exit 1
}

# ============================================================================
# HELPER FUNCTIONS
# ============================================================================

# Function to get all pages of results from Graph API
function Get-MgGraphPaginatedData {
    param(
        [Parameter(Mandatory = $true)]
        [string]$Uri,
        [int]$DelayMs = 100
    )

    $AllResult = @()
    $NextLink = $Uri
    $RequestCount = 0

    do {
        try {
            # Add delay to respect rate limits
            if ($RequestCount -gt 0) {
                Start-Sleep -Milliseconds $DelayMs
            }

            $Response = Invoke-MgGraphRequest -Uri $NextLink -Method GET
            $RequestCount++

            if ($null -ne $Response.value) {
                $AllResult += $Response.value
            }
            else {
                $AllResult += $Response
            }

            $NextLink = $Response.'@odata.nextLink'
        }
        catch {
            if ($_.Exception.Message -like "*429*" -or $_.Exception.Message -like "*throttled*") {
                Write-Information "`nRate limit hit, waiting 60 seconds..." -InformationAction Continue
                Start-Sleep -Seconds 60
                continue
            }
            throw "Error fetching data from $NextLink : $($_.Exception.Message)"
        }
    } while ($NextLink)

    # Comma prevents unrolling so single-element results stay arrays
    return , $AllResult
}

# Function to check FileVault key availability for a device
function Test-FileVaultKeyAvailability {
    param (
        [Parameter(Mandatory = $true)]
        [string]$DeviceId,
        [Parameter(Mandatory = $false)]
        [string]$DeviceName = "Unknown",
        [Parameter(Mandatory = $false)]
        [string]$OwnerType = "unknown"
    )

    if ([string]::IsNullOrWhiteSpace($DeviceId)) {
        Write-Verbose "Device $DeviceName has no Device ID"
        return @{
            HasKey   = $false
            KeyAvailable = $false
            Status   = "No Device ID"
            ErrorDetails = $null
        }
    }

    $maxRetries = 2
    $retryCount = 0
    while ($true) {
        try {
            # Use the getFileVaultKey endpoint
            $keyUri = "https://graph.microsoft.com/beta/deviceManagement/managedDevices('$DeviceId')/getFileVaultKey"
            $keyResponse = Invoke-MgGraphRequest -Uri $keyUri -Method GET

            # Check if response contains a recovery key
            if ($keyResponse -and $keyResponse.value) {
                return @{
                    HasKey   = $true
                    KeyAvailable = $true
                    Status   = "Key Available"
                    ErrorDetails = $null
                }
            }
            else {
                return @{
                    HasKey   = $false
                    KeyAvailable = $false
                    Status   = "No Key Found"
                    ErrorDetails = $null
                }
            }
        }
        catch {
            $errorMessage = $_.Exception.Message

            # Retry on throttling instead of reporting a false "Error Checking"
            if (($errorMessage -like "*429*" -or $errorMessage -like "*throttled*") -and $retryCount -lt $maxRetries) {
                $retryCount++
                Write-Information "Rate limit hit checking device $DeviceName, waiting 60 seconds (retry $retryCount of $maxRetries)..." -InformationAction Continue
                Start-Sleep -Seconds 60
                continue
            }

            # Handle specific error cases
            if ($errorMessage -like "*404*" -or $errorMessage -like "*Not Found*") {
                return @{
                    HasKey   = $false
                    KeyAvailable = $false
                    Status   = "No Key Stored"
                    ErrorDetails = "FileVault key not found in Intune"
                }
            }
            elseif ($errorMessage -like "*403*" -or $errorMessage -like "*Forbidden*") {
                return @{
                    HasKey   = $false
                    KeyAvailable = $false
                    Status   = "Access Denied"
                    ErrorDetails = "Insufficient permissions"
                }
            }
            elseif ($errorMessage -like "*BadRequest*" -or $errorMessage -like "*400*") {
                # BadRequest typically indicates personal device or unsupported operation
                if ($OwnerType -eq "personal") {
                    return @{
                        HasKey   = $false
                        KeyAvailable = $false
                        Status   = "Personal Device"
                        ErrorDetails = "FileVault keys not accessible for personal devices"
                    }
                }
                else {
                    return @{
                        HasKey   = $false
                        KeyAvailable = $false
                        Status   = "Not Supported"
                        ErrorDetails = "FileVault key retrieval not supported for this device"
                    }
                }
            }
            elseif ($errorMessage -like "*Personal*") {
                return @{
                    HasKey   = $false
                    KeyAvailable = $false
                    Status   = "Personal Device"
                    ErrorDetails = "Cannot retrieve key for personal device"
                }
            }
            else {
                Write-Verbose "Error checking FileVault key for device $DeviceName : $errorMessage"
                return @{
                    HasKey   = $false
                    KeyAvailable = $false
                    Status   = "Error Checking"
                    ErrorDetails = $errorMessage
                }
            }
        }
    }
}

# Function to format device last sync date
function Format-LastSyncDate {
    param([datetime]$LastSyncDateTime)

    if ($LastSyncDateTime -eq [datetime]::MinValue) {
        return "Never"
    }

    $daysSinceSync = (Get-Date) - $LastSyncDateTime

    if ($daysSinceSync.TotalDays -lt 1) {
        return "Today"
    }
    elseif ($daysSinceSync.TotalDays -lt 2) {
        return "Yesterday"
    }
    else {
        return "$([math]::Round($daysSinceSync.TotalDays)) days ago"
    }
}

# ============================================================================
# MAIN SCRIPT LOGIC
# ============================================================================

try {
    Write-Output "Starting FileVault key storage check..."

    # Validate output path
    if (-not (Test-Path $OutputPath)) {
        New-Item -Path $OutputPath -ItemType Directory -Force | Out-Null
        Write-Output "Created output directory: $OutputPath"
    }

    # Get all macOS devices from Intune
    Write-Output "Retrieving macOS devices from Intune..."
    $devicesUri = "https://graph.microsoft.com/beta/deviceManagement/managedDevices?`$filter=operatingSystem eq 'macOS'&`$select=id,deviceName,serialNumber,model,manufacturer,osVersion,complianceState,isEncrypted,managementState,ownerType,lastSyncDateTime"
    $devices = Get-MgGraphPaginatedData -Uri $devicesUri

    if ($devices.Count -eq 0) {
        Write-Warning "No macOS devices found in Intune"
        return
    }

    Write-Output "Found $($devices.Count) macOS devices. Checking FileVault key status..."

    $results = @()
    $processedCount = 0

    foreach ($device in $devices) {
        $processedCount++

        if ($ShowProgress) {
            $percentComplete = [math]::Round(($processedCount / $devices.Count) * 100, 1)
            Write-Progress -Activity "Checking FileVault Keys" -Status "Processing device: $($device.deviceName)" -PercentComplete $percentComplete
        }

        # Delay between per-device key checks to respect rate limits
        if ($processedCount -gt 1) {
            Start-Sleep -Milliseconds 100
        }

        # Check FileVault key availability
        $filevaultCheck = Test-FileVaultKeyAvailability -DeviceId $device.id -DeviceName $device.deviceName -OwnerType $device.ownerType

        # Prepare result object
        $deviceResult = [PSCustomObject]@{
            DeviceName                  = $device.deviceName
            SerialNumber                = $device.serialNumber
            Model                       = $device.model
            Manufacturer                = $device.manufacturer
            OSVersion                   = $device.osVersion
            DeviceId                    = $device.id
            "FileVault Key in Intune"   = if ($filevaultCheck.HasKey) { "Yes" } else { "No" }
            Status                      = $filevaultCheck.Status
            ComplianceState             = $device.complianceState
            EncryptionState             = $device.isEncrypted
            ManagementState             = $device.managementState
            OwnerType                   = $device.ownerType
        }

        # Add error details if present
        if ($filevaultCheck.ErrorDetails) {
            $deviceResult | Add-Member -MemberType NoteProperty -Name "Error Details" -Value $filevaultCheck.ErrorDetails
        }

        # Add last sync information if requested
        if ($IncludeLastSync) {
            # lastSyncDateTime arrives as a string from Graph; cast with a guard
            if (-not [string]::IsNullOrEmpty($device.lastSyncDateTime)) {
                $lastSyncDate = [datetime]$device.lastSyncDateTime
                $lastSyncDisplay = $lastSyncDate.ToString("yyyy-MM-dd HH:mm")
                $syncStatusDisplay = Format-LastSyncDate -LastSyncDateTime $lastSyncDate
            }
            else {
                $lastSyncDisplay = "Unknown"
                $syncStatusDisplay = "Unknown"
            }
            $deviceResult | Add-Member -MemberType NoteProperty -Name "Last Sync" -Value $lastSyncDisplay
            $deviceResult | Add-Member -MemberType NoteProperty -Name "Sync Status" -Value $syncStatusDisplay
        }

        # Add to results (filter if only showing missing keys)
        if (-not $OnlyShowMissing -or -not $filevaultCheck.HasKey) {
            $results += $deviceResult
        }
    }

    if ($ShowProgress) {
        Write-Progress -Activity "Checking FileVault Keys" -Completed
    }

    # Display results
    Write-Output "`nFileVault Key Storage Results:"
    $results | Format-Table -AutoSize

    # Calculate and display summary statistics
    $totalDevices = $devices.Count
    $devicesWithKeys = ($results | Where-Object { $_."FileVault Key in Intune" -eq "Yes" }).Count
    $devicesWithoutKeys = ($results | Where-Object { $_."FileVault Key in Intune" -eq "No" }).Count
    $personalDevices = ($results | Where-Object { $_.Status -eq "Personal Device" }).Count
    $errorDevices = ($results | Where-Object { $_.Status -eq "Error Checking" }).Count

    if ($totalDevices -gt 0) {
        $compliancePercentage = [math]::Round(($devicesWithKeys / $totalDevices) * 100, 1)
    }
    else {
        $compliancePercentage = 0
    }

    Write-Output "`n========================================"
    Write-Output "FileVault Key Storage Summary"
    Write-Output "========================================"
    Write-Output "Total macOS devices in Intune: $totalDevices"
    Write-Output "Devices with FileVault keys in Intune: $devicesWithKeys"
    Write-Output "Devices without FileVault keys: $devicesWithoutKeys"
    if ($personalDevices -gt 0) {
        Write-Output "Personal devices (keys not accessible): $personalDevices"
    }
    if ($errorDevices -gt 0) {
        Write-Output "Devices with errors: $errorDevices"
    }
    Write-Output "Compliance percentage: $compliancePercentage%"
    Write-Output "========================================"

    # Export results to CSV
    $timestamp = Get-Date -Format "yyyyMMdd-HHmmss"
    $csvPath = Join-Path $OutputPath "FileVault-Key-Storage-Report-$timestamp.csv"
    $results | Export-Csv -Path $csvPath -NoTypeInformation -Encoding utf8
    Write-Output "✓ Results exported to: $csvPath"

    # Export to JSON if requested
    if ($ExportJson) {
        $jsonPath = Join-Path $OutputPath "FileVault-Key-Storage-Report-$timestamp.json"
        $jsonData = @{
            GeneratedDate = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
            Summary       = @{
                TotalDevices         = $totalDevices
                DevicesWithKeys      = $devicesWithKeys
                DevicesWithoutKeys   = $devicesWithoutKeys
                PersonalDevices      = $personalDevices
                ErrorDevices         = $errorDevices
                CompliancePercentage = $compliancePercentage
            }
            Devices       = $results
        }
        $jsonData | ConvertTo-Json -Depth 3 | Set-Content -Path $jsonPath
        Write-Output "✓ Results exported to JSON: $jsonPath"
    }

    # Show devices without keys if any exist and not in OnlyShowMissing mode
    if ($devicesWithoutKeys -gt 0 -and -not $OnlyShowMissing) {
        Write-Output "`nDevices without FileVault keys in Intune:"
        $devicesWithoutKeysList = $results | Where-Object { $_."FileVault Key in Intune" -eq "No" } | Select-Object DeviceName, SerialNumber, Status, OwnerType
        $devicesWithoutKeysList | Format-Table -AutoSize
    }

    Write-Output "✓ FileVault key storage check completed successfully"
}
catch {
    Write-Error "Script failed: $($_.Exception.Message)"
    exit 1
}
finally {
    # Cleanup operations
    try {
        Disconnect-MgGraph -ErrorAction SilentlyContinue | Out-Null
        Write-Output "Disconnected from Microsoft Graph"
    }
    catch {
        Write-Verbose "Unable to disconnect from Microsoft Graph: $($_.Exception.Message)"
    }
}

# ============================================================================
# SCRIPT SUMMARY
# ============================================================================

Write-Output "
========================================
Script Execution Summary
========================================
Script: FileVault Key Storage Checker
Total Devices Processed: $($devices.Count)
Devices with Keys: $devicesWithKeys
Compliance Rate: $compliancePercentage%
Report Location: $OutputPath
Status: Completed
========================================
"

# Copia sin cambios de https://github.com/ugurkocde/IntuneAutomation (commit 797bb2e).
# MIT License
#
# Copyright (c) 2025 Ugur Koc | Microsoft MVP
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in all
# copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
# SOFTWARE.