Invoke-XdrEndpointDeviceAction
SYNOPSIS
Invokes response actions on an endpoint device in Microsoft Defender XDR.
SYNTAX
Scan (Default)
Invoke-XdrEndpointDeviceAction -DeviceId <String> [-Comment <String>] -Scan <String>
[-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm] [<CommonParameters>]
Isolate
Invoke-XdrEndpointDeviceAction -DeviceId <String> [-Comment <String>] -Isolate <String>
[-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm] [<CommonParameters>]
ReleaseFromIsolation
Invoke-XdrEndpointDeviceAction -DeviceId <String> [-Comment <String>] [-ReleaseFromIsolation]
[-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm] [<CommonParameters>]
RestrictAppExecution
Invoke-XdrEndpointDeviceAction -DeviceId <String> [-Comment <String>] [-RestrictAppExecution]
[-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm] [<CommonParameters>]
RemoveAppExecutionRestriction
Invoke-XdrEndpointDeviceAction -DeviceId <String> [-Comment <String>] [-RemoveAppExecutionRestriction]
[-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm] [<CommonParameters>]
CollectInvestigationPackage
Invoke-XdrEndpointDeviceAction -DeviceId <String> [-Comment <String>] [-CollectInvestigationPackage]
[-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm] [<CommonParameters>]
CollectSupportLogs
Invoke-XdrEndpointDeviceAction -DeviceId <String> [-Comment <String>] [-CollectSupportLogs]
[-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm] [<CommonParameters>]
StartTroubleshoot
Invoke-XdrEndpointDeviceAction -DeviceId <String> [-Comment <String>] [-StartTroubleshoot]
[-TroubleshootDurationHours <Int32>] [-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm]
[<CommonParameters>]
StopTroubleshoot
Invoke-XdrEndpointDeviceAction -DeviceId <String> [-Comment <String>] [-StopTroubleshoot]
[-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm] [<CommonParameters>]
SetTags
Invoke-XdrEndpointDeviceAction -DeviceId <String> [-Comment <String>] -SetTags <String[]>
[-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm] [<CommonParameters>]
SetAssetValue
Invoke-XdrEndpointDeviceAction -DeviceId <String> [-Comment <String>] -SetAssetValue <String>
[-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm] [<CommonParameters>]
SetCriticalityLevel
Invoke-XdrEndpointDeviceAction -DeviceId <String> [-Comment <String>] -SetCriticalityLevel <String>
[-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm] [<CommonParameters>]
SetExclusionState
Invoke-XdrEndpointDeviceAction -DeviceId <String> [-Comment <String>] -SetExclusionState <String>
[-Justification <String>] [-Notes <String>] [-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm]
[<CommonParameters>]
ForceSync
Invoke-XdrEndpointDeviceAction -DeviceId <String> [-Comment <String>] [-ForceSync]
[-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm] [<CommonParameters>]
StartInvestigation
Invoke-XdrEndpointDeviceAction -DeviceId <String> [-Comment <String>] [-StartInvestigation]
[-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm] [<CommonParameters>]
LiveResponse
Invoke-XdrEndpointDeviceAction -DeviceId <String> [-Comment <String>] [-LiveResponse]
[-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm] [<CommonParameters>]
DESCRIPTION
Unified cmdlet for executing device response actions including antivirus scans, device isolation, app execution restriction, investigation package collection, support log collection, troubleshooting mode, tag management, asset value, criticality level, exclusion state, policy sync, automated investigation, and live response sessions.
For responseApiPortal actions (Scan, Isolate, Restrict, etc.), the cmdlet auto-fetches OsPlatform and SenseClientVersion from the device.
For other actions, the cmdlet wraps dedicated cmdlets like Set-XdrEndpointDeviceTag, Set-XdrEndpointDeviceAssetValue, etc.
EXAMPLES
EXAMPLE 1
Invoke-XdrEndpointDeviceAction -DeviceId "980dddb7036eae7e38d30dee7f11b51e573a6fc2" -Scan Quick
Runs a quick antivirus scan on the specified device.
EXAMPLE 2
Invoke-XdrEndpointDeviceAction -DeviceId "980dddb7036eae7e38d30dee7f11b51e573a6fc2" -Scan Full -Comment "macOS validation full scan"
Runs a full antivirus scan with a comment.
EXAMPLE 3
Invoke-XdrEndpointDeviceAction -DeviceId "980dddb7036eae7e38d30dee7f11b51e573a6fc2" -Isolate Full -Comment "macOS containment test"
Fully isolates the device from the network.
EXAMPLE 4
Invoke-XdrEndpointDeviceAction -DeviceId "980dddb7036eae7e38d30dee7f11b51e573a6fc2" -ReleaseFromIsolation -Comment "macOS containment test rollback"
Releases the device from isolation.
EXAMPLE 5
Invoke-XdrEndpointDeviceAction -DeviceId "980dddb7036eae7e38d30dee7f11b51e573a6fc2" -CollectInvestigationPackage -Comment "macOS evidence collection"
Collects a forensic investigation package from the device.
EXAMPLE 6
Invoke-XdrEndpointDeviceAction -DeviceId "980dddb7036eae7e38d30dee7f11b51e573a6fc2" -LiveResponse
Opens an interactive Live Response session to the device.
EXAMPLE 7
Invoke-XdrEndpointDeviceAction -DeviceId "980dddb7036eae7e38d30dee7f11b51e573a6fc2" -SetAssetValue High
Sets the asset value to High.
EXAMPLE 8
Invoke-XdrEndpointDeviceAction -DeviceId "980dddb7036eae7e38d30dee7f11b51e573a6fc2" -ForceSync -Comment "macOS policy sync validation"
Forces a policy sync on the device.
PARAMETERS
-DeviceId
The device ID (SenseMachineId) of the target device. Required for all actions.
Type: String
Parameter Sets: (All)
Aliases: MachineId, SenseMachineId
Required: True
Position: Named
Default value: None
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False
-Comment
A comment describing the reason for the action. Used as RequestorComment for API calls.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Scan
Runs an antivirus scan on the device. Valid values: Quick, Full.
Type: String
Parameter Sets: Scan
Aliases:
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Isolate
Isolates the device from the network. Valid values: Full, Selective.
Type: String
Parameter Sets: Isolate
Aliases:
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-ReleaseFromIsolation
Releases the device from network isolation.
Type: SwitchParameter
Parameter Sets: ReleaseFromIsolation
Aliases:
Required: True
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-RestrictAppExecution
Restricts application execution on the device to Microsoft-signed binaries only. macOS note: this action is currently unsupported and should be attempted only for capability detection/documentation.
Type: SwitchParameter
Parameter Sets: RestrictAppExecution
Aliases:
Required: True
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-RemoveAppExecutionRestriction
Removes application execution restriction from the device. macOS note: this action is currently unsupported and should be attempted only for capability detection/documentation.
Type: SwitchParameter
Parameter Sets: RemoveAppExecutionRestriction
Aliases:
Required: True
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-CollectInvestigationPackage
Collects a forensic investigation package from the device.
Type: SwitchParameter
Parameter Sets: CollectInvestigationPackage
Aliases:
Required: True
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-CollectSupportLogs
Collects support diagnostic logs from the device.
Type: SwitchParameter
Parameter Sets: CollectSupportLogs
Aliases:
Required: True
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-StartTroubleshoot
Enables troubleshooting mode on the device.
Type: SwitchParameter
Parameter Sets: StartTroubleshoot
Aliases:
Required: True
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-TroubleshootDurationHours
Duration in hours for troubleshooting mode. Defaults to 4. Maximum 12.
Type: Int32
Parameter Sets: StartTroubleshoot
Aliases:
Required: False
Position: Named
Default value: 4
Accept pipeline input: False
Accept wildcard characters: False
-StopTroubleshoot
Disables troubleshooting mode on the device.
Type: SwitchParameter
Parameter Sets: StopTroubleshoot
Aliases:
Required: True
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-SetTags
Array of tag strings to set on the device. Replaces all existing user-defined tags. Wraps Set-XdrEndpointDeviceTag. For add/remove semantics, use Set-XdrEndpointDeviceTag -Add or -Remove directly.
Type: String[]
Parameter Sets: SetTags
Aliases:
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-SetAssetValue
Sets the asset value of the device. Valid values: Low, Normal, High. Wraps Set-XdrEndpointDeviceAssetValue.
Type: String
Parameter Sets: SetAssetValue
Aliases:
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-SetCriticalityLevel
Sets the criticality level. Valid values: VeryHigh, High, Medium, Low, Reset. Reset removes the criticality level. Wraps Set-XdrEndpointDeviceCriticalityLevel.
Type: String
Parameter Sets: SetCriticalityLevel
Aliases:
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-SetExclusionState
Sets the exclusion state. Valid values: Excluded, Included. Wraps Set-XdrEndpointDeviceExclusionState.
Type: String
Parameter Sets: SetExclusionState
Aliases:
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Justification
Justification for exclusion state change.
Type: String
Parameter Sets: SetExclusionState
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Notes
Additional notes for the exclusion state change.
Type: String
Parameter Sets: SetExclusionState
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-ForceSync
Forces a policy sync on the device. Wraps Invoke-XdrEndpointDevicePolicySync.
Type: SwitchParameter
Parameter Sets: ForceSync
Aliases:
Required: True
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-StartInvestigation
Starts an automated investigation. Wraps Invoke-XdrEndpointDeviceAutomatedInvestigation. macOS note: this action is currently unsupported and should be attempted only for capability detection/documentation.
Type: SwitchParameter
Parameter Sets: StartInvestigation
Aliases:
Required: True
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-LiveResponse
Starts an interactive Live Response session. Wraps Connect-XdrEndpointDeviceLiveResponse.
Type: SwitchParameter
Parameter Sets: LiveResponse
Aliases:
Required: True
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-WhatIf
Shows what would happen if the cmdlet runs without actually performing the action.
Type: SwitchParameter
Parameter Sets: (All)
Aliases: wi
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Confirm
Prompts for confirmation before executing the operation.
Type: SwitchParameter
Parameter Sets: (All)
Aliases: cf
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-ProgressAction
The ProgressAction parameter is a common parameter, not a cmdlet parameter. For more information, see about_CommonParameters.
Type: ActionPreference
Parameter Sets: (All)
Aliases: proga
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
INPUTS
OUTPUTS
PSCustomObject
Returns the API response from the action. For Live Response, enters an interactive session.
NOTES
macOS validation baseline: February 24, 2026.
Validated on macOS: Scan (Quick, Full), Isolate (Full, Selective), ReleaseFromIsolation, CollectInvestigationPackage, StartTroubleshoot, StopTroubleshoot, SetTags, SetAssetValue, SetCriticalityLevel, SetExclusionState, ForceSync, LiveResponse.
Service-dependent on macOS: CollectSupportLogs (may return transient backend InternalServerError).
Not currently supported on macOS: RestrictAppExecution, RemoveAppExecutionRestriction, StartInvestigation.