IntuneOperator.psm1
|
[CmdletBinding()] param() $baseName = [System.IO.Path]::GetFileNameWithoutExtension($PSCommandPath) $script:PSModuleInfo = Import-PowerShellDataFile -Path "$PSScriptRoot\$baseName.psd1" $script:PSModuleInfo | Format-List | Out-String -Stream | ForEach-Object { Write-Debug $_ } $scriptName = $script:PSModuleInfo.Name Write-Debug "[$scriptName] - Importing module" #region [functions] - [private] Write-Debug "[$scriptName] - [functions] - [private] - Processing folder" #region [functions] - [private] - [ConvertTo-IntuneDeviceSummary] Write-Debug "[$scriptName] - [functions] - [private] - [ConvertTo-IntuneDeviceSummary] - Importing" function ConvertTo-IntuneDeviceSummary { <# .SYNOPSIS Converts a managed device Graph object to the module's Intune device summary shape. .DESCRIPTION Maps selected managed device properties to a stable output object used by Get-IntuneDevice. Expects any enrichment (for example EnrolledBy resolution) to be done before conversion. .PARAMETER Device A Microsoft Graph managed device object. .EXAMPLE $device | ConvertTo-IntuneDeviceSummary Converts each input device object to the standardized output object. .INPUTS System.Object .OUTPUTS PSCustomObject #> [OutputType([PSCustomObject])] [CmdletBinding()] param( [Parameter(Mandatory = $true, ValueFromPipeline = $true)] [ValidateNotNull()] [object]$Device ) process { $lastSyncDateTime = $null # Keep output type stable even if Graph returns an unexpected timestamp format. if ($null -ne $Device.lastSyncDateTime -and -not [string]::IsNullOrWhiteSpace([string]$Device.lastSyncDateTime)) { try { $lastSyncDateTime = [datetime]$Device.lastSyncDateTime } catch { $lastSyncDateTime = $null } } # Stable output contract consumed by Get-IntuneDevice callers. [PSCustomObject]@{ DeviceName = [string]$Device.deviceName PrimaryUser = [string]$Device.userPrincipalName DeviceManufacturer = [string]$Device.manufacturer DeviceModel = [string]$Device.model OperatingSystem = [string]$Device.operatingSystem SerialNumber = [string]$Device.serialNumber Compliance = [string]$Device.complianceState LastSyncDateTime = $lastSyncDateTime } } # Process } # Cmdlet Write-Debug "[$scriptName] - [functions] - [private] - [ConvertTo-IntuneDeviceSummary] - Done" #endregion [functions] - [private] - [ConvertTo-IntuneDeviceSummary] #region [functions] - [private] - [Get-FirstPropertyValue] Write-Debug "[$scriptName] - [functions] - [private] - [Get-FirstPropertyValue] - Importing" function Get-FirstPropertyValue { <# .SYNOPSIS Returns the first non-empty property value from an object or dictionary. .DESCRIPTION Checks each property name in order against the input object, dictionary keys, and an AdditionalProperties dictionary when present. Returns the first value that is not null and not empty/whitespace when converted to string. .PARAMETER InputObject The object or dictionary to inspect. .PARAMETER PropertyNames The ordered list of property names to evaluate. .PARAMETER DefaultValue The value to return when none of the requested properties contain a value. .EXAMPLE Get-FirstPropertyValue -InputObject $Object -PropertyNames @('displayName', 'name') Returns the first populated value found in `displayName` or `name`. .INPUTS System.Object .OUTPUTS System.Object #> [OutputType([object])] [CmdletBinding()] param( [Parameter(Mandatory = $true)] [AllowNull()] [object]$InputObject, [Parameter(Mandatory = $true)] [ValidateNotNullOrEmpty()] [string[]]$PropertyNames, [Parameter(Mandatory = $false)] [AllowNull()] [object]$DefaultValue = $null ) process { if ($null -eq $InputObject) { return $DefaultValue } $additionalProperties = $InputObject.PSObject.Properties['AdditionalProperties'] $additionalPropertiesValue = $null if ($null -ne $additionalProperties -and $additionalProperties.Value -is [System.Collections.IDictionary]) { $additionalPropertiesValue = $additionalProperties.Value } foreach ($propertyName in $PropertyNames) { if ($InputObject -is [System.Collections.IDictionary] -and $InputObject.Contains($propertyName)) { $dictionaryValue = $InputObject[$propertyName] if ($null -ne $dictionaryValue -and -not [string]::IsNullOrWhiteSpace([string]$dictionaryValue)) { return $dictionaryValue } } $property = $InputObject.PSObject.Properties[$propertyName] if ($null -ne $property) { $value = $property.Value if ($null -ne $value -and -not [string]::IsNullOrWhiteSpace([string]$value)) { return $value } } if ($null -ne $additionalPropertiesValue -and $additionalPropertiesValue.Contains($propertyName)) { $apValue = $additionalPropertiesValue[$propertyName] if ($null -ne $apValue -and -not [string]::IsNullOrWhiteSpace([string]$apValue)) { return $apValue } } } return $DefaultValue } } Write-Debug "[$scriptName] - [functions] - [private] - [Get-FirstPropertyValue] - Done" #endregion [functions] - [private] - [Get-FirstPropertyValue] #region [functions] - [private] - [Invoke-GraphGet] Write-Debug "[$scriptName] - [functions] - [private] - [Invoke-GraphGet] - Importing" function Invoke-GraphGet { <# .SYNOPSIS Invokes a GET request against the Microsoft Graph API with error handling and automatic pagination. .DESCRIPTION Wrapper function for making authenticated GET requests to the Microsoft Graph API. Provides consistent error handling, verbose output, and automatic pagination handling for all Graph API calls. When the response contains a 'value' collection and '@odata.nextLink', automatically follows pagination to retrieve all results. Requires an established Microsoft Graph connection via Connect-MgGraph. .PARAMETER Uri The full URI of the Graph API endpoint to query. .EXAMPLE Invoke-GraphGet -Uri "https://graph.microsoft.com/beta/deviceManagement/managedDevices" Retrieves all managed devices from the Graph API, automatically following pagination links. .EXAMPLE Invoke-GraphGet -Uri "https://graph.microsoft.com/beta/deviceManagement/managedDevices/12345" Retrieves a single managed device by ID (no pagination applies). .INPUTS System.String .OUTPUTS PSObject .NOTES Part of the Intune Device Login helper functions. Requires Microsoft.Graph PowerShell module with active connection. Automatically handles pagination for collection responses. #> [OutputType([PSObject])] [CmdletBinding()] param( [Parameter( Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "The full URI of the Graph API endpoint" )] [ValidateNotNullOrEmpty()] [string]$Uri ) process { Write-Verbose -Message "GET $Uri" try { $splat = @{ Method = 'GET' Uri = $Uri ErrorAction = 'Stop' } $response = Invoke-MgGraphRequest @splat # Check if response has pagination (value collection with nextLink) if ($null -ne $response.value -and $null -ne $response.'@odata.nextLink') { Write-Verbose -Message "Response contains pagination, retrieving all pages" $allValues = [System.Collections.Generic.List[object]]::new() $allValues.AddRange($response.value) $nextLink = $response.'@odata.nextLink' $pageCount = 1 while ($null -ne $nextLink) { $pageCount++ Write-Verbose -Message "Following pagination link (page $pageCount, current items: $($allValues.Count))" $splat.Uri = $nextLink $nextResponse = Invoke-MgGraphRequest @splat if ($null -ne $nextResponse.value) { $allValues.AddRange($nextResponse.value) } $nextLink = $nextResponse.'@odata.nextLink' } Write-Verbose -Message "Pagination complete: retrieved $($allValues.Count) total items across $pageCount pages" # Return modified response with all values $response.value = $allValues.ToArray() $response.PSObject.Properties.Remove('@odata.nextLink') } return $response } catch { $Exception = [Exception]::new("Graph request failed for '$Uri': $($_.Exception.Message)", $_.Exception) $ErrorRecord = [System.Management.Automation.ErrorRecord]::new( $Exception, 'GraphRequestFailed', [System.Management.Automation.ErrorCategory]::NotSpecified, $Uri ) $PSCmdlet.ThrowTerminatingError($ErrorRecord) } } # Process } # Cmdlet Write-Debug "[$scriptName] - [functions] - [private] - [Invoke-GraphGet] - Done" #endregion [functions] - [private] - [Invoke-GraphGet] #region [functions] - [private] - [Resolve-EntraUserById] Write-Debug "[$scriptName] - [functions] - [private] - [Resolve-EntraUserById] - Importing" function Resolve-EntraUserById { <# .SYNOPSIS Resolves an Entra ID user by user ID to retrieve user principal name and other details. .DESCRIPTION Queries Microsoft Graph for a specific user by their user ID (object ID). Returns user object including userPrincipalName for reporting and audit purposes. Handles cases where user may no longer exist in Entra ID. .PARAMETER UserId The Entra ID user object identifier (GUID). .EXAMPLE Resolve-EntraUserById -UserId "d1e1a1d7-2d2b-4d8c-9f0a-0d2a3d1e2f3a" Returns the user object with UPN for the specified user ID. .INPUTS System.String .OUTPUTS PSObject .NOTES Part of the Intune Device Login helper functions. Uses Microsoft Graph /v1.0 endpoint. Requires User.Read.All scope. Returns a minimal user object if user cannot be found. #> [OutputType([PSObject])] [CmdletBinding()] param( [Parameter( Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "The Entra ID user object ID" )] [ValidateNotNullOrEmpty()] [string]$UserId ) begin { $baseUri = 'https://graph.microsoft.com/v1.0/users' } process { $uri = "$baseUri/$UserId" try { Invoke-GraphGet -Uri $uri } catch { Write-Verbose -Message "Could not resolve user ID '$UserId': $($_.Exception.Message)" # Return a minimal object with the ID and a placeholder UPN [PSCustomObject]@{ id = $UserId userPrincipalName = "Unknown (ID: $UserId)" } } } } Write-Debug "[$scriptName] - [functions] - [private] - [Resolve-EntraUserById] - Done" #endregion [functions] - [private] - [Resolve-EntraUserById] #region [functions] - [private] - [Resolve-IntuneDeviceByName] Write-Debug "[$scriptName] - [functions] - [private] - [Resolve-IntuneDeviceByName] - Importing" function Resolve-IntuneDeviceByName { <# .SYNOPSIS Resolves one or more Intune managed devices by device name. .DESCRIPTION Queries Intune managed devices using the device name filter. Performs case-insensitive exact match searching via OData filter. Returns all devices matching the specified name. .PARAMETER Name The device name to search for in Intune managed devices. .EXAMPLE Resolve-IntuneDeviceByName -Name "PC-001" Returns the managed device object matching the name "PC-001", if found. .INPUTS System.String .OUTPUTS PSObject[] .NOTES Part of the Intune Device Login helper functions. Uses Microsoft Graph /beta endpoint. Requires DeviceManagementManagedDevices.Read.All scope. #> [OutputType([PSCustomObject[]])] [CmdletBinding()] param( [Parameter( Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "The device name to resolve" )] [ValidateNotNullOrEmpty()] [string]$Name ) begin { $baseUri = 'https://graph.microsoft.com/beta/deviceManagement/managedDevices' } process { # Escape only the string literal content; keep OData filter syntax intact. $escapedName = $Name.Replace("'", "''") $filter = "deviceName eq '$escapedName'" $select = 'id,deviceName,userPrincipalName,manufacturer,model,operatingSystem,serialNumber,enrolledByUserId,complianceState,lastSyncDateTime' $candidateUris = @( "$baseUri`?`$filter=$filter&`$select=$select", "$baseUri`?`$filter=$filter", "$baseUri`?`$select=$select", $baseUri ) $resp = $null $lastBadRequestError = $null foreach ($candidateUri in $candidateUris) { try { $resp = Invoke-GraphGet -Uri $candidateUri break } catch { $errorMessage = $_.Exception.Message if ($errorMessage -match 'BadRequest|400') { $lastBadRequestError = $_ Write-Verbose -Message "Managed device query returned BadRequest for URI '$candidateUri'. Trying next fallback." continue } throw } } if ($null -eq $resp -and $null -ne $lastBadRequestError) { throw $lastBadRequestError } $devices = @() if ($null -ne $resp) { if ($null -ne $resp.value) { $devices = @($resp.value) } else { $devices = @($resp) } } # Keep exact name semantics even after fallback to unfiltered Graph query. $matchedDevices = @($devices | Where-Object -FilterScript { [string]$_.deviceName -ieq $Name }) if ($matchedDevices.Count -eq 0) { Write-Verbose -Message "No managed devices found with deviceName '$Name'." return [PSCustomObject[]]@() } # Return managed device objects with fields required by downstream callers. $matchedDevices | ForEach-Object -Process { [PSCustomObject]@{ id = $_.id deviceName = $_.deviceName userPrincipalName = $_.userPrincipalName manufacturer = $_.manufacturer model = $_.model operatingSystem = $_.operatingSystem serialNumber = $_.serialNumber enrolledByUserId = $_.enrolledByUserId complianceState = $_.complianceState lastSyncDateTime = $_.lastSyncDateTime } } } # Process } # Cmdlet Write-Debug "[$scriptName] - [functions] - [private] - [Resolve-IntuneDeviceByName] - Done" #endregion [functions] - [private] - [Resolve-IntuneDeviceByName] #region [functions] - [private] - [Resolve-IntuneDeviceByUser] Write-Debug "[$scriptName] - [functions] - [private] - [Resolve-IntuneDeviceByUser] - Importing" function Resolve-IntuneDeviceByUser { <# .SYNOPSIS Resolves one or more Intune managed devices by primary user UPN. .DESCRIPTION Queries Intune managed devices using the userPrincipalName filter. Performs case-insensitive exact match searching via OData filter. Returns all devices assigned to the specified user. .PARAMETER UserPrincipalName The UPN of the primary user to search for in Intune managed devices. .EXAMPLE Resolve-IntuneDeviceByUser -UserPrincipalName "jane.doe@contoso.com" Returns all managed device objects whose primary user is jane.doe@contoso.com. .INPUTS System.String .OUTPUTS PSCustomObject[] .NOTES Part of the Intune Device helper functions. Uses Microsoft Graph /beta endpoint. Requires DeviceManagementManagedDevices.Read.All scope. #> [OutputType([PSCustomObject[]])] [CmdletBinding()] param( [Parameter( Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "The UPN of the primary user to resolve" )] [ValidateNotNullOrEmpty()] [string]$UserPrincipalName ) begin { $baseUri = 'https://graph.microsoft.com/beta/deviceManagement/managedDevices' $select = 'id,deviceName,userPrincipalName,manufacturer,model,operatingSystem,serialNumber,complianceState,lastSyncDateTime' } process { # Escape only the string literal; keep OData filter syntax intact. $escapedUpn = $UserPrincipalName.Replace("'", "''") $filter = "userPrincipalName eq '$escapedUpn'" # Ordered fallback chain matching the BadRequest resilience pattern used elsewhere. $candidateUris = @( "$baseUri`?`$filter=$filter&`$select=$select", "$baseUri`?`$filter=$filter", "$baseUri`?`$select=$select", $baseUri ) $resp = $null $lastBadRequestError = $null foreach ($candidateUri in $candidateUris) { try { $resp = Invoke-GraphGet -Uri $candidateUri break } catch { $errorMessage = $_.Exception.Message if ($errorMessage -match 'BadRequest|400') { $lastBadRequestError = $_ Write-Verbose -Message "Managed device query returned BadRequest for URI '$candidateUri'. Trying next fallback." continue } # Non-BadRequest errors are fatal; re-throw immediately. throw } } # All candidates failed with BadRequest; surface the last error. if ($null -eq $resp -and $null -ne $lastBadRequestError) { throw $lastBadRequestError } # Normalise response: unwrap .value collection or treat as single object. $devices = @() if ($null -ne $resp) { if ($null -ne $resp.value) { $devices = @($resp.value) } else { $devices = @($resp) } } # Apply exact match locally to handle unfiltered fallback responses. $matchedDevices = @($devices | Where-Object -FilterScript { [string]$_.userPrincipalName -ieq $UserPrincipalName }) if ($matchedDevices.Count -eq 0) { Write-Verbose -Message "No managed devices found for userPrincipalName '$UserPrincipalName'." return [PSCustomObject[]]@() } # Return managed device objects with fields required by downstream callers. $matchedDevices | ForEach-Object -Process { [PSCustomObject]@{ id = $_.id deviceName = $_.deviceName userPrincipalName = $_.userPrincipalName manufacturer = $_.manufacturer model = $_.model operatingSystem = $_.operatingSystem serialNumber = $_.serialNumber complianceState = $_.complianceState lastSyncDateTime = $_.lastSyncDateTime } } } # Process } # Cmdlet Write-Debug "[$scriptName] - [functions] - [private] - [Resolve-IntuneDeviceByUser] - Done" #endregion [functions] - [private] - [Resolve-IntuneDeviceByUser] Write-Debug "[$scriptName] - [functions] - [private] - Done" #endregion [functions] - [private] #region [functions] - [public] Write-Debug "[$scriptName] - [functions] - [public] - Processing folder" #region [functions] - [public] - [completers] Write-Debug "[$scriptName] - [functions] - [public] - [completers] - Importing" Register-ArgumentCompleter -CommandName New-PSModuleTest -ParameterName Name -ScriptBlock { param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters) $null = $commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters 'Alice', 'Bob', 'Charlie' | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) } } Write-Debug "[$scriptName] - [functions] - [public] - [completers] - Done" #endregion [functions] - [public] - [completers] #region [functions] - [public] - [Device] Write-Debug "[$scriptName] - [functions] - [public] - [Device] - Processing folder" #region [functions] - [public] - [Device] - [Get-IntuneDevice] Write-Debug "[$scriptName] - [functions] - [public] - [Device] - [Get-IntuneDevice] - Importing" #Requires -Modules @{ ModuleName = 'Microsoft.Graph.Authentication'; ModuleVersion = '2.28.0' } function Get-IntuneDevice { <# .SYNOPSIS Retrieves Intune managed device details by DeviceId, DeviceName, or primary user UPN. .DESCRIPTION Queries Microsoft Graph (beta) for managed device details and returns a compact device summary. Supports lookup by managed device ID, by device name, or by the primary user's UPN. Requires an authenticated Graph session with appropriate scopes. Scopes (minimum): - DeviceManagementManagedDevices.Read.All .PARAMETER DeviceId The Intune managed device identifier (GUID). Parameter set: ById. .PARAMETER DeviceName One or more device names to resolve in Intune managed devices. Parameter set: ByName. If multiple devices share the same name, all matches are returned. Accepts multiple names via array or pipeline. .PARAMETER UserPrincipalName The UPN of the primary user whose devices should be returned. Parameter set: ByUser. If the user has multiple enrolled devices, all matches are returned. .EXAMPLE Connect-MgGraph -Scopes "DeviceManagementManagedDevices.Read.All","User.Read.All" Get-IntuneDevice -DeviceId "c1f5d1d7-2d2b-4d8c-9f0a-0d2a3d1e2f3a" Retrieves summary details for the specified managed device. .EXAMPLE Get-IntuneDevice -DeviceName PC-001 Resolves device by name and returns summary details for each matching managed device. .EXAMPLE Get-IntuneDevice -UserPrincipalName `jane.doe@contoso.com` Returns summary details for all managed devices whose primary user is `jane.doe@contoso.com`. .INPUTS System.String (DeviceId, DeviceName, or UserPrincipalName via pipeline/property name) .OUTPUTS PSCustomObject with the following properties - DeviceName (string) - PrimaryUser (string) - DeviceManufacturer (string) - DeviceModel (string) - OperatingSystem (string) - SerialNumber (string) - Compliance (string) - LastSyncDateTime (datetime) .NOTES Author: FHN & GitHub Copilot Uses /beta Graph endpoints for managed device properties. #> [OutputType([PSCustomObject])] [CmdletBinding(DefaultParameterSetName = 'ById', SupportsShouldProcess = $false)] param( [Parameter( ParameterSetName = 'ById', Mandatory = $true, ValueFromPipelineByPropertyName = $true )] [ValidatePattern('^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$')] [Alias('Id', 'ManagedDeviceId')] [string]$DeviceId, [Parameter( ParameterSetName = 'ByName', Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true )] [ValidateNotNullOrEmpty()] [Alias('Name', 'ComputerName')] [string[]]$DeviceName, [Parameter( ParameterSetName = 'ByUser', Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true )] [ValidateNotNullOrEmpty()] [Alias('UPN', 'PrimaryUser')] [string]$UserPrincipalName ) begin { $baseUri = 'https://graph.microsoft.com/beta/deviceManagement/managedDevices' # Request only fields needed for enrichment + output mapping. $select = 'deviceName,userPrincipalName,manufacturer,model,operatingSystem,serialNumber,complianceState,lastSyncDateTime' } process { switch ($PSCmdlet.ParameterSetName) { 'ById' { Write-Verbose -Message "Resolving managed device by id: $DeviceId" $uri = "$baseUri/$DeviceId?`$select=$select" try { $device = Invoke-GraphGet -Uri $uri } catch { $errorMessage = $_.Exception.Message # Distinguish 404 (not found) from network/auth failures. if ($errorMessage -match 'Request_ResourceNotFound|NotFound|404') { $exception = [Exception]::new("Managed device not found for id '$DeviceId': $errorMessage", $_.Exception) $errorRecord = [System.Management.Automation.ErrorRecord]::new( $exception, 'DeviceNotFound', [System.Management.Automation.ErrorCategory]::ObjectNotFound, $DeviceId ) $PSCmdlet.WriteError($errorRecord) return } $exception = [Exception]::new("Failed to resolve device id '$DeviceId': $errorMessage", $_.Exception) $errorRecord = [System.Management.Automation.ErrorRecord]::new( $exception, 'DeviceLookupFailed', [System.Management.Automation.ErrorCategory]::NotSpecified, $DeviceId ) $PSCmdlet.ThrowTerminatingError($errorRecord) } # Graph returned null; invalid or removed device. if (-not $device) { $exception = [Exception]::new("Managed device not found for id '$DeviceId'.") $errorRecord = [System.Management.Automation.ErrorRecord]::new( $exception, 'DeviceNotFound', [System.Management.Automation.ErrorCategory]::ObjectNotFound, $DeviceId ) $PSCmdlet.WriteError($errorRecord) return } # Map to public output contract. ConvertTo-IntuneDeviceSummary -Device $device } 'ByName' { # Iterate through each provided device name. foreach ($currentDeviceName in $DeviceName) { Write-Verbose -Message "Resolving managed device(s) by name: $currentDeviceName" try { $deviceSummaries = Resolve-IntuneDeviceByName -Name $currentDeviceName } catch { $errorMessage = $_.Exception.Message # Distinguish name resolution failure (no match) from actual Graph errors. if ($errorMessage -match 'Request_ResourceNotFound|NotFound|404') { $exception = [Exception]::new("Managed device not found for name '$currentDeviceName': $errorMessage", $_.Exception) $errorRecord = [System.Management.Automation.ErrorRecord]::new( $exception, 'DeviceNameNotFound', [System.Management.Automation.ErrorCategory]::ObjectNotFound, $currentDeviceName ) $PSCmdlet.WriteError($errorRecord) continue } $exception = [Exception]::new("Failed to resolve device name '$currentDeviceName': $errorMessage", $_.Exception) $errorRecord = [System.Management.Automation.ErrorRecord]::new( $exception, 'DeviceNameLookupFailed', [System.Management.Automation.ErrorCategory]::NotSpecified, $currentDeviceName ) $PSCmdlet.ThrowTerminatingError($errorRecord) } # Empty result set: name does not match any device. if ($null -eq $deviceSummaries -or $deviceSummaries.Count -eq 0) { $exception = [Exception]::new("Managed device not found for name '$currentDeviceName'.") $errorRecord = [System.Management.Automation.ErrorRecord]::new( $exception, 'DeviceNameNotFound', [System.Management.Automation.ErrorCategory]::ObjectNotFound, $currentDeviceName ) $PSCmdlet.WriteError($errorRecord) continue } # Resolve-IntuneDeviceByName already returns selected managed device fields. foreach ($device in $deviceSummaries) { if (-not $device) { continue } # Map to public output contract. ConvertTo-IntuneDeviceSummary -Device $device } } } 'ByUser' { Write-Verbose -Message "Resolving managed device(s) by user: $UserPrincipalName" try { $deviceSummaries = Resolve-IntuneDeviceByUser -UserPrincipalName $UserPrincipalName } catch { $errorMessage = $_.Exception.Message # Distinguish user not found from actual Graph errors. if ($errorMessage -match 'Request_ResourceNotFound|NotFound|404') { $exception = [Exception]::new("Managed device not found for user '$UserPrincipalName': $errorMessage", $_.Exception) $errorRecord = [System.Management.Automation.ErrorRecord]::new( $exception, 'DeviceUserNotFound', [System.Management.Automation.ErrorCategory]::ObjectNotFound, $UserPrincipalName ) $PSCmdlet.WriteError($errorRecord) return } $exception = [Exception]::new("Failed to resolve devices for user '$UserPrincipalName': $errorMessage", $_.Exception) $errorRecord = [System.Management.Automation.ErrorRecord]::new( $exception, 'DeviceUserLookupFailed', [System.Management.Automation.ErrorCategory]::NotSpecified, $UserPrincipalName ) $PSCmdlet.ThrowTerminatingError($errorRecord) } # Empty result set: user has no enrolled devices. if ($null -eq $deviceSummaries -or $deviceSummaries.Count -eq 0) { $exception = [Exception]::new("No managed devices found for user '$UserPrincipalName'.") $errorRecord = [System.Management.Automation.ErrorRecord]::new( $exception, 'DeviceUserNotFound', [System.Management.Automation.ErrorCategory]::ObjectNotFound, $UserPrincipalName ) $PSCmdlet.WriteError($errorRecord) return } # Resolve-IntuneDeviceByUser already returns selected managed device fields. foreach ($device in $deviceSummaries) { if (-not $device) { continue } # Map to public output contract. ConvertTo-IntuneDeviceSummary -Device $device } } } } # Process } # Cmdlet Write-Debug "[$scriptName] - [functions] - [public] - [Device] - [Get-IntuneDevice] - Done" #endregion [functions] - [public] - [Device] - [Get-IntuneDevice] #region [functions] - [public] - [Device] - [Get-IntuneDeviceLogin] Write-Debug "[$scriptName] - [functions] - [public] - [Device] - [Get-IntuneDeviceLogin] - Importing" #Requires -Modules @{ ModuleName = 'Microsoft.Graph.Authentication'; ModuleVersion = '2.28.0' } function Get-IntuneDeviceLogin { <# .SYNOPSIS Retrieves logged-on user info for an Intune-managed device by DeviceId, DeviceName, UserPrincipalName, or UserId. .DESCRIPTION Uses Microsoft Graph (beta) to read managed device metadata and the `usersLoggedOn` collection. When given a DeviceId, queries that specific device. When given a DeviceName, resolves one or more matching managed devices (`deviceName eq '<name>'`) and returns logon info for each match. When given a UserPrincipalName or UserId, searches all managed devices and returns only those where the specified user has logged in. Requires an authenticated Graph session with appropriate scopes. Scopes (minimum): - DeviceManagementManagedDevices.Read.All - User.Read.All .PARAMETER DeviceId The Intune managed device identifier (GUID). Parameter set: ById. .PARAMETER DeviceName The device name to resolve in Intune managed devices. Parameter set: ByName. If multiple devices share the same name, all matches are processed. .PARAMETER UserPrincipalName The user principal name (UPN) to search for across all managed devices. Parameter set: ByUserPrincipalName. Returns all devices where this user has logged in. .PARAMETER UserId The Entra ID user object identifier (GUID). Parameter set: ByUserId. Returns all devices where this user has logged in. .EXAMPLE Connect-MgGraph -Scopes "DeviceManagementManagedDevices.Read.All","User.Read.All" Get-IntuneDeviceLogin -DeviceId "c1f5d1d7-2d2b-4d8c-9f0a-0d2a3d1e2f3a" Gets logged-on user info for the specified device. .EXAMPLE Get-IntuneDeviceLogin -DeviceName PC-001 Resolves the device name and returns logged-on user info for the match. .EXAMPLE Get-IntuneDeviceLogin -UserPrincipalName "<UserPrincipalName>" Returns all devices where the specified user principal name has logged in. .EXAMPLE Get-IntuneDeviceLogin -UserId "c1f5d1d7-2d2b-4d8c-9f0a-0d2a3d1e2f3a" Returns all devices where the specified user (by ID) has logged in. .INPUTS System.String (DeviceId, DeviceName, UserPrincipalName, or UserId via pipeline/property name) .OUTPUTS PSCustomObject with the following properties - DeviceId (string) - DeviceName (string) - OperatingSystem (string) - UserId (string) - UserPrincipalName (string) - LastLogonDateTime (datetime) .NOTES Author: FHN & ChatGPT & GitHub Copilot - Uses /beta Graph endpoints because usersLoggedOn is exposed there. #> [OutputType([PSCustomObject])] [CmdletBinding(DefaultParameterSetName = 'ById', SupportsShouldProcess = $false)] param( # ById: DeviceId (GUID) [Parameter( ParameterSetName = 'ById', Mandatory = $true, ValueFromPipelineByPropertyName = $true )] [ValidatePattern('^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$')] [Alias('Id', 'ManagedDeviceId')] [string]$DeviceId, # ByName: DeviceName (string) [Parameter( ParameterSetName = 'ByName', Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true )] [ValidateNotNullOrEmpty()] [Alias('Name', 'ComputerName')] [string]$DeviceName, # ByUserPrincipalName: UserPrincipalName (string) [Parameter( ParameterSetName = 'ByUserPrincipalName', Mandatory = $true, ValueFromPipelineByPropertyName = $true )] [ValidateNotNullOrEmpty()] [Alias('UPN')] [string]$UserPrincipalName, # ByUserId: UserId (GUID) [Parameter( ParameterSetName = 'ByUserId', Mandatory = $true, ValueFromPipelineByPropertyName = $true )] [ValidatePattern('^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$')] [string]$UserId ) begin { $baseUri = 'https://graph.microsoft.com/beta/deviceManagement/managedDevices' } process { switch ($PSCmdlet.ParameterSetName) { 'ById' { Write-Verbose -Message "Resolving usersLoggedOn for device id: $DeviceId" $uri = "$baseUri/$DeviceId" try { $device = Invoke-GraphGet -Uri $uri } catch { $errorMessage = $_.Exception.Message if ($errorMessage -match 'Request_ResourceNotFound|NotFound|404') { $Exception = [Exception]::new("Managed device not found for id '$DeviceId': $errorMessage", $_.Exception) $ErrorRecord = [System.Management.Automation.ErrorRecord]::new( $Exception, 'DeviceNotFound', [System.Management.Automation.ErrorCategory]::ObjectNotFound, $DeviceId ) $PSCmdlet.WriteError($ErrorRecord) return } $Exception = [Exception]::new("Failed to resolve device id '$DeviceId': $errorMessage", $_.Exception) $ErrorRecord = [System.Management.Automation.ErrorRecord]::new( $Exception, 'DeviceLookupFailed', [System.Management.Automation.ErrorCategory]::NotSpecified, $DeviceId ) $PSCmdlet.ThrowTerminatingError($ErrorRecord) } if (-not $device) { $Exception = [Exception]::new("Managed device not found for id '$DeviceId'.") $ErrorRecord = [System.Management.Automation.ErrorRecord]::new( $Exception, 'DeviceNotFound', [System.Management.Automation.ErrorCategory]::ObjectNotFound, $DeviceId ) $PSCmdlet.WriteError($ErrorRecord) return } if (-not $device.usersLoggedOn -or $device.usersLoggedOn.Count -eq 0) { Write-Verbose -Message "No logged-on users found for device '$($device.deviceName)' ($DeviceId)." return } foreach ($entry in $device.usersLoggedOn) { $user = Resolve-EntraUserById -UserId $entry.userId [PSCustomObject]@{ DeviceName = $device.deviceName OperatingSystem = $device.operatingSystem UserPrincipalName = $user.userPrincipalName DeviceId = $device.id UserId = $entry.userId LastLogonDateTime = [datetime]$entry.lastLogOnDateTime } } } 'ByName' { Write-Verbose -Message "Resolving device(s) by name: $DeviceName" try { $deviceSummaries = Resolve-IntuneDeviceByName -Name $DeviceName } catch { $errorMessage = $_.Exception.Message if ($errorMessage -match 'Request_ResourceNotFound|NotFound|404') { $Exception = [Exception]::new("Managed device not found for name '$DeviceName': $errorMessage", $_.Exception) $ErrorRecord = [System.Management.Automation.ErrorRecord]::new( $Exception, 'DeviceNameNotFound', [System.Management.Automation.ErrorCategory]::ObjectNotFound, $DeviceName ) $PSCmdlet.WriteError($ErrorRecord) return } $Exception = [Exception]::new("Failed to resolve device name '$DeviceName': $errorMessage", $_.Exception) $ErrorRecord = [System.Management.Automation.ErrorRecord]::new( $Exception, 'DeviceNameLookupFailed', [System.Management.Automation.ErrorCategory]::NotSpecified, $DeviceName ) $PSCmdlet.ThrowTerminatingError($ErrorRecord) } if ($null -eq $deviceSummaries -or $deviceSummaries.Count -eq 0) { $Exception = [Exception]::new("Managed device not found for name '$DeviceName'.") $ErrorRecord = [System.Management.Automation.ErrorRecord]::new( $Exception, 'DeviceNameNotFound', [System.Management.Automation.ErrorCategory]::ObjectNotFound, $DeviceName ) $PSCmdlet.WriteError($ErrorRecord) return } if ($deviceSummaries.Count -gt 1) { Write-Verbose -Message "Multiple devices matched name '$DeviceName' ($($deviceSummaries.Count) matches). Returning results for all." } foreach ($summary in $deviceSummaries) { $uri = "$baseUri/$($summary.Id)" try { $device = Invoke-GraphGet -Uri $uri } catch { $errorMessage = $_.Exception.Message if ($errorMessage -match 'Request_ResourceNotFound|NotFound|404') { $Exception = [Exception]::new("Managed device not found for id '$($summary.Id)' while resolving name '$DeviceName': $errorMessage", $_.Exception) $ErrorRecord = [System.Management.Automation.ErrorRecord]::new( $Exception, 'DeviceNotFound', [System.Management.Automation.ErrorCategory]::ObjectNotFound, $summary.Id ) $PSCmdlet.WriteError($ErrorRecord) continue } $Exception = [Exception]::new("Failed to retrieve device id '$($summary.Id)' while resolving name '$DeviceName': $errorMessage", $_.Exception) $ErrorRecord = [System.Management.Automation.ErrorRecord]::new( $Exception, 'DeviceLookupFailed', [System.Management.Automation.ErrorCategory]::NotSpecified, $summary.Id ) $PSCmdlet.ThrowTerminatingError($ErrorRecord) } if (-not $device) { $Exception = [Exception]::new("Managed device not found for id '$($summary.Id)' while resolving name '$DeviceName'.") $ErrorRecord = [System.Management.Automation.ErrorRecord]::new( $Exception, 'DeviceNotFound', [System.Management.Automation.ErrorCategory]::ObjectNotFound, $summary.Id ) $PSCmdlet.WriteError($ErrorRecord) continue } if (-not $device.usersLoggedOn -or $device.usersLoggedOn.Count -eq 0) { Write-Verbose -Message "No logged-on users found for device '$($summary.DeviceName)' ($($summary.Id))." continue } foreach ($entry in $device.usersLoggedOn) { $user = Resolve-EntraUserById -UserId $entry.userId [PSCustomObject]@{ DeviceName = $device.deviceName OperatingSystem = $device.operatingSystem UserPrincipalName = $user.userPrincipalName DeviceId = $device.id UserId = $entry.userId LastLogonDateTime = [datetime]$entry.lastLogOnDateTime } } } } { $_ -in 'ByUserPrincipalName', 'ByUserId' } { # Resolve UPN to UserId if needed if ($PSCmdlet.ParameterSetName -eq 'ByUserPrincipalName') { Write-Verbose -Message "Resolving UserPrincipalName '$UserPrincipalName' to UserId" $userUri = "https://graph.microsoft.com/v1.0/users/$UserPrincipalName" try { $userObj = Invoke-GraphGet -Uri $userUri $targetUserId = $userObj.id Write-Verbose -Message "Resolved to UserId: $targetUserId" } catch { $errorMessage = $_.Exception.Message if ($errorMessage -match 'Request_ResourceNotFound|NotFound|404') { $Exception = [Exception]::new("Could not resolve UserPrincipalName '$UserPrincipalName': $errorMessage", $_.Exception) $ErrorRecord = [System.Management.Automation.ErrorRecord]::new( $Exception, 'UserResolutionFailed', [System.Management.Automation.ErrorCategory]::ObjectNotFound, $UserPrincipalName ) $PSCmdlet.WriteError($ErrorRecord) return } $Exception = [Exception]::new("Failed to resolve UserPrincipalName '$UserPrincipalName': $errorMessage", $_.Exception) $ErrorRecord = [System.Management.Automation.ErrorRecord]::new( $Exception, 'UserResolutionGraphRequestFailed', [System.Management.Automation.ErrorCategory]::NotSpecified, $UserPrincipalName ) $PSCmdlet.ThrowTerminatingError($ErrorRecord) } } else { $targetUserId = $UserId } Write-Verbose -Message "Searching for devices where user '$targetUserId' has logged in" # Get all managed devices with usersLoggedOn property. # Invoke-GraphGet already handles pagination, so we query once and filter client-side. $uri = "$baseUri`?`$select=id,deviceName,operatingSystem,usersLoggedOn" $resp = Invoke-GraphGet -Uri $uri $allDevices = @() if ($null -ne $resp) { if ($null -ne $resp.value) { $allDevices = @($resp.value) } else { $allDevices = @($resp) } } if ($allDevices.Count -eq 0) { Write-Verbose -Message "No managed devices found." return } Write-Verbose -Message "Checking $($allDevices.Count) managed devices for user logons" $matchCount = 0 $seenResults = [System.Collections.Generic.HashSet[string]]::new() foreach ($device in $allDevices) { # Check if target user is in the usersLoggedOn collection $userLogon = $device.usersLoggedOn | Where-Object -FilterScript { $_.userId -eq $targetUserId } if ($userLogon) { $latestUserLogon = $userLogon | Sort-Object -Property lastLogOnDateTime -Descending | Select-Object -First 1 $logonTimestamp = [datetime]$latestUserLogon.lastLogOnDateTime $resultKey = "{0}|{1}|{2}" -f $device.id, $targetUserId, $logonTimestamp.ToString('o') if (-not $seenResults.Add($resultKey)) { continue } $matchCount++ $user = Resolve-EntraUserById -UserId $targetUserId [PSCustomObject]@{ DeviceName = $device.deviceName OperatingSystem = $device.operatingSystem UserPrincipalName = $user.userPrincipalName DeviceId = $device.id UserId = $targetUserId LastLogonDateTime = $logonTimestamp } } } if ($matchCount -eq 0) { Write-Verbose -Message "No devices found where user '$targetUserId' has logged in." } } } } # Process } # Cmdlet Write-Debug "[$scriptName] - [functions] - [public] - [Device] - [Get-IntuneDeviceLogin] - Done" #endregion [functions] - [public] - [Device] - [Get-IntuneDeviceLogin] Write-Debug "[$scriptName] - [functions] - [public] - [Device] - Done" #endregion [functions] - [public] - [Device] #region [functions] - [public] - [Remediation] Write-Debug "[$scriptName] - [functions] - [public] - [Remediation] - Processing folder" #region [functions] - [public] - [Remediation] - [Get-IntuneRemediationDeviceStatus] Write-Debug "[$scriptName] - [functions] - [public] - [Remediation] - [Get-IntuneRemediationDeviceStatus] - Importing" function Get-IntuneRemediationDeviceStatus { <# .SYNOPSIS Retrieves per-device run state and pre/post remediation output for a specific Intune proactive remediation. .DESCRIPTION Queries Microsoft Graph (beta) for the device run states of a proactive remediation script (device health script). Returns one row per device, including the detection and remediation states and the captured pre/post-remediation detection script output. Requires an authenticated Graph session with appropriate scopes. Scopes (minimum): - DeviceManagementConfiguration.Read.All .PARAMETER Name The display name of the remediation script. Supports wildcards (*). When multiple scripts match, all are processed. Parameter set: ByName. .PARAMETER Id The ID (GUID) of the device health script (remediation) to query. Parameter set: ById. .EXAMPLE Connect-MgGraph -Scopes "DeviceManagementConfiguration.Read.All" Get-IntuneRemediationDeviceStatus -Name "BitLocker*" Returns per-device run states for all remediations whose name starts with "BitLocker". .EXAMPLE Get-IntuneRemediationDeviceStatus -Id "f1f5d1d7-2d2b-4d8c-9f0a-0d2a3d1e2f3a" Returns per-device run states for the remediation with the specified ID. .EXAMPLE Get-IntuneRemediationSummary | Where-Object WithIssues -gt 0 | Get-IntuneRemediationDeviceStatus Pipes remediations that have devices with issues into this cmdlet to get device-level detail. .INPUTS System.String (Name or Id via pipeline by property name) .OUTPUTS PSCustomObject with the following properties - RemediationName (string) : Display name of the remediation script - RemediationId (string) : GUID of the device health script - DeviceId (string) : Managed device ID - DeviceName (string) : Managed device display name - UserPrincipalName (string) : Primary user UPN of the device - LastStateUpdate (datetime / null): When the run state was last updated - DetectionState (string) : Outcome of the last detection script run - RemediationState (string) : Outcome of the last remediation script run - PreRemediationOutput (string) : stdout captured before remediation ran - PostRemediationOutput (string) : stdout captured after remediation ran - DetectionOutput (string) : Detection-only script stdout - PreRemediationError (string) : stderr captured before remediation ran - RemediationError (string) : stderr from the remediation script - DetectionError (string) : stderr from the detection script .NOTES Author: FHN & GitHub Copilot - Uses /beta Graph endpoints. - Expands managedDevice to include DeviceName and UserPrincipalName inline. #> [OutputType([PSCustomObject])] [CmdletBinding(DefaultParameterSetName = 'ByName', SupportsShouldProcess = $false)] param( [Parameter( ParameterSetName = 'ByName', Mandatory = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = 'Display name (supports wildcards) of the remediation script' )] [ValidateNotNullOrEmpty()] [Alias('RemediationName')] [string]$Name, [Parameter( ParameterSetName = 'ById', Mandatory = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = 'GUID of the device health / remediation script' )] [ValidatePattern('^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$')] [Alias('RemediationId')] [string]$Id ) begin { # Expand managedDevice so device identity fields are available in each run-state row. $expandQuery = '$expand=managedDevice($select=id,deviceName,userPrincipalName)' } process { # ------------------------------------------------------------------ # # 1. Resolve the target script(s) when called by name # # ------------------------------------------------------------------ # $targetScripts = @() if ($PSCmdlet.ParameterSetName -eq 'ById') { $targetScripts += [PSCustomObject]@{ id = $Id displayName = $Id # will be overwritten once we fetch the real name } # Resolve display name for friendlier output while still accepting direct ID input. try { $scriptDetailUri = "https://graph.microsoft.com/beta/deviceManagement/deviceHealthScripts/$($Id)?`$select=id,displayName" $scriptDetail = Invoke-GraphGet -Uri $scriptDetailUri if ($null -ne $scriptDetail -and -not [string]::IsNullOrWhiteSpace($scriptDetail.displayName)) { $targetScripts[0] = [PSCustomObject]@{ id = $Id displayName = [string]$scriptDetail.displayName } } } catch { Write-Warning -Message "Could not fetch display name for remediation '$Id': $($_.Exception.Message)" } } else { # ByName – list all scripts then filter $listUri = 'https://graph.microsoft.com/beta/deviceManagement/deviceHealthScripts?$select=id,displayName' try { $listResponse = Invoke-GraphGet -Uri $listUri } catch { if ($_.FullyQualifiedErrorId -match 'GraphRequestFailed' -and $_.Exception.Message -match 'Forbidden|403') { $Exception = [Exception]::new("Failed to list proactive remediations: access denied. Ensure your account has an Intune role with permission to read Device configurations, then reconnect and try again. Original error: $($_.Exception.Message)", $_.Exception) $ErrorRecord = [System.Management.Automation.ErrorRecord]::new( $Exception, 'RemediationListAccessDenied', [System.Management.Automation.ErrorCategory]::PermissionDenied, $listUri ) $PSCmdlet.ThrowTerminatingError($ErrorRecord) } $Exception = [Exception]::new("Failed to list proactive remediations: $($_.Exception.Message)", $_.Exception) $ErrorRecord = [System.Management.Automation.ErrorRecord]::new( $Exception, 'RemediationListFailed', [System.Management.Automation.ErrorCategory]::NotSpecified, $listUri ) $PSCmdlet.ThrowTerminatingError($ErrorRecord) } # Normalize payload shape before wildcard name matching. $allScripts = @() if ($null -ne $listResponse) { if ($null -ne $listResponse.value) { $allScripts = @($listResponse.value) } else { $allScripts = @($listResponse) } } $targetScripts = @($allScripts | Where-Object { $_.displayName -like $Name }) if ($targetScripts.Count -eq 0) { $Exception = [Exception]::new("No remediation script found matching name '$Name'.") $ErrorRecord = [System.Management.Automation.ErrorRecord]::new( $Exception, 'RemediationNotFound', [System.Management.Automation.ErrorCategory]::ObjectNotFound, $Name ) $PSCmdlet.WriteError($ErrorRecord) return } } # ------------------------------------------------------------------ # # 2. For each matched script, retrieve per-device run states # # ------------------------------------------------------------------ # foreach ($script in $targetScripts) { $remediationName = [string]$script.displayName $remediationId = [string]$script.id Write-Verbose -Message "Retrieving device run states for remediation '$remediationName' ($remediationId)" $runStatesUri = "https://graph.microsoft.com/beta/deviceManagement/deviceHealthScripts/$remediationId/deviceRunStates?$expandQuery" try { $runStatesResponse = Invoke-GraphGet -Uri $runStatesUri } catch { Write-Warning -Message "Failed to retrieve device run states for '$remediationName' ($remediationId): $($_.Exception.Message)" continue } # Normalize run-state list: handle both .value and direct response shapes. $runStates = @() if ($null -ne $runStatesResponse) { if ($null -ne $runStatesResponse.value) { $runStates = @($runStatesResponse.value) } else { $runStates = @($runStatesResponse) } } if ($runStates.Count -eq 0) { Write-Verbose -Message "No device run states found for '$remediationName'." continue } foreach ($state in $runStates) { # Resolve device fields from the expanded managedDevice object $device = $null $deviceId = $null $deviceName = $null $upn = $null if ($null -ne $state.managedDevice) { $device = $state.managedDevice $deviceId = [string]$device.id $deviceName = [string]$device.deviceName $upn = [string]$device.userPrincipalName } # Resolve last-state timestamp $lastUpdate = $null $rawDate = $state.lastStateUpdateDateTime if ($null -ne $rawDate -and -not [string]::IsNullOrWhiteSpace([string]$rawDate)) { # Guard output typing: invalid timestamps should not break object emission. try { $lastUpdate = [datetime]$rawDate } catch { $lastUpdate = $null } } # Cast Graph fields to predictable output types for downstream filtering/export. [PSCustomObject]@{ RemediationName = $remediationName RemediationId = $remediationId DeviceId = $deviceId DeviceName = $deviceName UserPrincipalName = $upn LastStateUpdate = $lastUpdate DetectionState = [string]$state.detectionState RemediationState = [string]$state.remediationState PreRemediationOutput = [string]$state.preRemediationDetectionScriptOutput PostRemediationOutput = [string]$state.postRemediationDetectionScriptOutput DetectionOutput = [string]$state.detectionScriptOutput PreRemediationError = [string]$state.preRemediationDetectionScriptError RemediationError = [string]$state.remediationScriptError DetectionError = [string]$state.detectionScriptError } } } } # Process } # Cmdlet Write-Debug "[$scriptName] - [functions] - [public] - [Remediation] - [Get-IntuneRemediationDeviceStatus] - Done" #endregion [functions] - [public] - [Remediation] - [Get-IntuneRemediationDeviceStatus] #region [functions] - [public] - [Remediation] - [Get-IntuneRemediationSummary] Write-Debug "[$scriptName] - [functions] - [public] - [Remediation] - [Get-IntuneRemediationSummary] - Importing" function Get-IntuneRemediationSummary { <# .SYNOPSIS Retrieves remediation summary statistics for all Intune proactive remediations. .DESCRIPTION Queries Microsoft Graph (beta) for all device health scripts (proactive remediations) and returns one summary row per remediation, including status and key issue counters. Requires an authenticated Graph session with appropriate scopes. Scopes (minimum): - DeviceManagementConfiguration.Read.All .EXAMPLE Connect-MgGraph -Scopes "DeviceManagementConfiguration.Read.All" Get-IntuneRemediationSummary Returns one row per remediation with status and issue/remediation counters. .OUTPUTS PSCustomObject with the following properties - Name (string) - Status (string) - WithoutIssues (int) - WithIssues (int) - IssueFixed (int) - IssueRecurred (int) - TotalRemediated (int) .NOTES Author: FHN & GitHub Copilot - Uses /beta Graph endpoints. #> [OutputType([PSCustomObject])] [CmdletBinding(SupportsShouldProcess = $false)] param() begin { # Query all proactive remediations once and process summaries per script. $listUri = 'https://graph.microsoft.com/beta/deviceManagement/deviceHealthScripts?$select=id,displayName' } process { Write-Verbose -Message 'Retrieving proactive remediations from Microsoft Graph' try { $scriptsResponse = Invoke-GraphGet -Uri $listUri } catch { if ($_.FullyQualifiedErrorId -match 'GraphRequestFailed' -and $_.Exception.Message -match 'Forbidden|403') { $Exception = [Exception]::new("Failed to retrieve proactive remediations: access denied by Intune RBAC or tenant policy. Ensure your account has an Intune role with permission to read Device configurations (Endpoint Analytics/Remediations), then reconnect and try again. Original error: $($_.Exception.Message)", $_.Exception) $ErrorRecord = [System.Management.Automation.ErrorRecord]::new( $Exception, 'RemediationListAccessDenied', [System.Management.Automation.ErrorCategory]::PermissionDenied, $listUri ) $PSCmdlet.ThrowTerminatingError($ErrorRecord) } $Exception = [Exception]::new("Failed to retrieve proactive remediations: $($_.Exception.Message)", $_.Exception) $ErrorRecord = [System.Management.Automation.ErrorRecord]::new( $Exception, 'RemediationListFailed', [System.Management.Automation.ErrorCategory]::NotSpecified, $listUri ) $PSCmdlet.ThrowTerminatingError($ErrorRecord) } # Normalize payload shape: Graph may return either an object with .value or a direct object/array. $scripts = @() if ($null -ne $scriptsResponse) { if ($null -ne $scriptsResponse.value) { $scripts = @($scriptsResponse.value) } else { $scripts = @($scriptsResponse) } } foreach ($script in $scripts) { if ($null -eq $script.id) { continue } $scriptName = [string]$script.displayName if ([string]::IsNullOrWhiteSpace($scriptName)) { $scriptName = [string](Get-FirstPropertyValue -InputObject $script -PropertyNames @('displayName', 'name') -DefaultValue $script.id) } Write-Verbose -Message "Processing remediation summary for '$scriptName'" $summaryUri = "https://graph.microsoft.com/beta/deviceManagement/deviceHealthScripts/$($script.id)/runSummary" try { $summaryResponse = Invoke-GraphGet -Uri $summaryUri } catch { Write-Warning -Message "Failed to retrieve run summary for '$scriptName' ($($script.id)): $($_.Exception.Message)" continue } # Normalize run summary root before probing nested alternatives. $summary = $summaryResponse if ($null -ne $summaryResponse.value) { if ($summaryResponse.value -is [array]) { $summary = $summaryResponse.value | Select-Object -First 1 } else { $summary = $summaryResponse.value } } if ($null -eq $summary) { $summary = $summaryResponse } # Some tenants return nested shapes for run summary payloads. # Resolve to the first object that actually contains known summary counters. $summaryCandidates = @() if ($null -ne $summary) { $summaryCandidates += $summary if ($null -ne $summary.runSummary) { $summaryCandidates += $summary.runSummary } } if ($null -ne $summaryResponse) { $summaryCandidates += $summaryResponse if ($null -ne $summaryResponse.runSummary) { $summaryCandidates += $summaryResponse.runSummary } if ($null -ne $summaryResponse.value -and $null -ne $summaryResponse.value.runSummary) { $summaryCandidates += $summaryResponse.value.runSummary } } if ($null -ne $summary.value) { $summaryCandidates += $summary.value if ($null -ne $summary.value.runSummary) { $summaryCandidates += $summary.value.runSummary } } $resolvedSummary = $null foreach ($candidate in $summaryCandidates) { if ($null -eq $candidate) { continue } $candidateNoIssue = Get-FirstPropertyValue -InputObject $candidate -PropertyNames @( 'noIssueDetectedDeviceCount', 'withoutIssues', 'noIssueCount', 'noIssueDeviceCount', 'devicesWithoutIssues' ) -DefaultValue $null $candidateWithIssue = Get-FirstPropertyValue -InputObject $candidate -PropertyNames @( 'issueDetectedDeviceCount', 'withIssues', 'issueCount', 'issueDeviceCount', 'devicesWithIssues' ) -DefaultValue $null $candidateFixed = Get-FirstPropertyValue -InputObject $candidate -PropertyNames @( 'issueRemediatedDeviceCount', 'issueFixed', 'issueFixedCount', 'issuesFixed', 'issueRemediatedCount' ) -DefaultValue $null $candidateRecurred = Get-FirstPropertyValue -InputObject $candidate -PropertyNames @( 'issueReoccurredDeviceCount', 'issueRecurred', 'issueRecurredCount', 'recurredIssueCount', 'issueRecurredDevicesCount' ) -DefaultValue $null $candidateTotalRemediated = Get-FirstPropertyValue -InputObject $candidate -PropertyNames @( 'issueRemediatedCumulativeDeviceCount', 'totalRemediated', 'remediatedCount', 'remediatedDeviceCount', 'devicesRemediated' ) -DefaultValue $null if ($null -ne $candidateNoIssue -or $null -ne $candidateWithIssue -or $null -ne $candidateFixed -or $null -ne $candidateRecurred -or $null -ne $candidateTotalRemediated) { $resolvedSummary = $candidate break } } if ($null -ne $resolvedSummary) { $summary = $resolvedSummary } # Prefer status from script metadata; fall back to summary payload when missing. $status = Get-FirstPropertyValue -InputObject $script -PropertyNames @( 'status' ) -DefaultValue $null if ([string]::IsNullOrWhiteSpace([string]$status)) { $status = Get-FirstPropertyValue -InputObject $summary -PropertyNames @( 'status', 'remediationStatus', 'scriptExecutionStatus' ) -DefaultValue $null } # Counter aliases vary by tenant/API shape, so probe multiple known names. $withoutIssues = [int](Get-FirstPropertyValue -InputObject $summary -PropertyNames @( 'noIssueDetectedDeviceCount', 'withoutIssues', 'noIssueCount', 'noIssueDeviceCount', 'devicesWithoutIssues' ) -DefaultValue 0) $withIssues = [int](Get-FirstPropertyValue -InputObject $summary -PropertyNames @( 'issueDetectedDeviceCount', 'withIssues', 'issueCount', 'issueDeviceCount', 'devicesWithIssues' ) -DefaultValue 0) $issueFixed = [int](Get-FirstPropertyValue -InputObject $summary -PropertyNames @( 'issueRemediatedDeviceCount', 'issueFixed', 'issueFixedCount', 'issuesFixed', 'issueRemediatedCount' ) -DefaultValue 0) $issueRecurred = [int](Get-FirstPropertyValue -InputObject $summary -PropertyNames @( 'issueReoccurredDeviceCount', 'issueRecurred', 'issueRecurredCount', 'recurredIssueCount', 'issueRecurredDevicesCount' ) -DefaultValue 0) $totalRemediated = [int](Get-FirstPropertyValue -InputObject $summary -PropertyNames @( 'issueRemediatedCumulativeDeviceCount', 'totalRemediated', 'remediatedCount', 'remediatedDeviceCount', 'devicesRemediated' ) -DefaultValue 0) # If summary counters are empty, derive best-effort values from remediation history. if ($withoutIssues -eq 0 -and $withIssues -eq 0 -and $issueFixed -eq 0 -and $issueRecurred -eq 0 -and $totalRemediated -eq 0) { $historyUri = "https://graph.microsoft.com/beta/deviceManagement/deviceHealthScripts/$($script.id)/getRemediationHistory" try { $historyResponse = Invoke-GraphGet -Uri $historyUri $historyRoot = $historyResponse if ($null -ne $historyResponse.value) { $historyRoot = $historyResponse.value } $historyData = @() if ($null -ne $historyRoot.historyData) { $historyData = @($historyRoot.historyData) } elseif ($historyRoot -is [array]) { $historyData = @($historyRoot) } elseif ($null -ne $historyRoot.date) { $historyData = @($historyRoot) } $latestHistory = $null if ($historyData.Count -gt 0) { $latestHistory = $historyData | Sort-Object -Property date -Descending | Select-Object -First 1 } if ($null -ne $latestHistory) { $historyNoIssue = [int](Get-FirstPropertyValue -InputObject $latestHistory -PropertyNames @('noIssueDeviceCount', 'noIssueCount', 'withoutIssues') -DefaultValue 0) $historyDetectFailed = [int](Get-FirstPropertyValue -InputObject $latestHistory -PropertyNames @('detectFailedDeviceCount', 'issueDetectedDeviceCount', 'issueCount', 'withIssues') -DefaultValue 0) $historyRemediated = [int](Get-FirstPropertyValue -InputObject $latestHistory -PropertyNames @('remediatedDeviceCount', 'issueRemediatedDeviceCount', 'issueFixedCount', 'issueFixed') -DefaultValue 0) if ($historyNoIssue -eq 0 -and $historyDetectFailed -eq 0 -and $historyRemediated -eq 0 -and $historyData.Count -gt 0) { $historyNoIssue = ($historyData | ForEach-Object { [int](Get-FirstPropertyValue -InputObject $_ -PropertyNames @('noIssueDeviceCount', 'noIssueCount', 'withoutIssues') -DefaultValue 0) } | Measure-Object -Maximum).Maximum $historyDetectFailed = ($historyData | ForEach-Object { [int](Get-FirstPropertyValue -InputObject $_ -PropertyNames @('detectFailedDeviceCount', 'issueDetectedDeviceCount', 'issueCount', 'withIssues') -DefaultValue 0) } | Measure-Object -Maximum).Maximum $historyRemediated = ($historyData | ForEach-Object { [int](Get-FirstPropertyValue -InputObject $_ -PropertyNames @('remediatedDeviceCount', 'issueRemediatedDeviceCount', 'issueFixedCount', 'issueFixed') -DefaultValue 0) } | Measure-Object -Sum).Sum } $withoutIssues = $historyNoIssue $issueFixed = $historyRemediated if ($totalRemediated -eq 0) { $totalRemediated = $historyRemediated } if ($withIssues -eq 0) { $withIssues = $historyRemediated + $historyDetectFailed } } if ($null -ne $historyRoot.lastModifiedDateTime -and [string]::IsNullOrWhiteSpace([string]$status)) { $status = 'Completed' } } catch { Write-Verbose -Message "No remediation history fallback available for '$scriptName' ($($script.id)): $($_.Exception.Message)" } } # Resolve a display-friendly status when no explicit status was returned. if ([string]::IsNullOrWhiteSpace([string]$status)) { $pendingCount = [int](Get-FirstPropertyValue -InputObject $summary -PropertyNames @( 'detectionScriptPendingDeviceCount' ) -DefaultValue 0) $lastRun = Get-FirstPropertyValue -InputObject $summary -PropertyNames @( 'lastScriptRunDateTime' ) -DefaultValue $null if ($pendingCount -gt 0) { $status = 'Pending' } elseif ($null -ne $lastRun -and -not [string]::IsNullOrWhiteSpace([string]$lastRun)) { $status = 'Completed' } else { $status = 'Unknown' } } [PSCustomObject]@{ Name = [string]$scriptName Status = [string]$status WithoutIssues = $withoutIssues WithIssues = $withIssues IssueFixed = $issueFixed IssueRecurred = $issueRecurred TotalRemediated = $totalRemediated } } } # Process } # Cmdlet Write-Debug "[$scriptName] - [functions] - [public] - [Remediation] - [Get-IntuneRemediationSummary] - Done" #endregion [functions] - [public] - [Remediation] - [Get-IntuneRemediationSummary] Write-Debug "[$scriptName] - [functions] - [public] - [Remediation] - Done" #endregion [functions] - [public] - [Remediation] Write-Debug "[$scriptName] - [functions] - [public] - Done" #endregion [functions] - [public] #region Member exporter $exports = @{ Alias = '*' Cmdlet = '' Function = @( 'Get-IntuneDevice' 'Get-IntuneDeviceLogin' 'Get-IntuneRemediationDeviceStatus' 'Get-IntuneRemediationSummary' ) Variable = '' } Export-ModuleMember @exports #endregion Member exporter |