POWERSHELL COMMAND
Invoke-XdrEndpointDeviceAction
Invokes response actions on an endpoint device in Microsoft Defender XDR.
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.
Syntax
Invoke-XdrEndpointDeviceAction -DeviceId <string> -Scan <string> [-Comment <string>] [-WhatIf] [-Confirm] [<CommonParameters>]
Invoke-XdrEndpointDeviceAction -DeviceId <string> -Isolate <string> [-Comment <string>] [-WhatIf] [-Confirm] [<CommonParameters>]
Invoke-XdrEndpointDeviceAction -DeviceId <string> -ReleaseFromIsolation [-Comment <string>] [-WhatIf] [-Confirm] [<CommonParameters>]
Invoke-XdrEndpointDeviceAction -DeviceId <string> -RestrictAppExecution [-Comment <string>] [-WhatIf] [-Confirm] [<CommonParameters>]
Invoke-XdrEndpointDeviceAction -DeviceId <string> -RemoveAppExecutionRestriction [-Comment <string>] [-WhatIf] [-Confirm] [<CommonParameters>]
Invoke-XdrEndpointDeviceAction -DeviceId <string> -CollectInvestigationPackage [-Comment <string>] [-WhatIf] [-Confirm] [<CommonParameters>]
Invoke-XdrEndpointDeviceAction -DeviceId <string> -CollectSupportLogs [-Comment <string>] [-WhatIf] [-Confirm] [<CommonParameters>]
Invoke-XdrEndpointDeviceAction -DeviceId <string> -StartTroubleshoot [-Comment <string>] [-TroubleshootDurationHours <int>] [-WhatIf] [-Confirm] [<CommonParameters>]
Invoke-XdrEndpointDeviceAction -DeviceId <string> -StopTroubleshoot [-Comment <string>] [-WhatIf] [-Confirm] [<CommonParameters>]
Invoke-XdrEndpointDeviceAction -DeviceId <string> -SetTags <string[]> [-Comment <string>] [-WhatIf] [-Confirm] [<CommonParameters>]
Invoke-XdrEndpointDeviceAction -DeviceId <string> -SetAssetValue <string> [-Comment <string>] [-WhatIf] [-Confirm] [<CommonParameters>]
Invoke-XdrEndpointDeviceAction -DeviceId <string> -SetCriticalityLevel <string> [-Comment <string>] [-WhatIf] [-Confirm] [<CommonParameters>]
Invoke-XdrEndpointDeviceAction -DeviceId <string> -SetExclusionState <string> [-Comment <string>] [-Justification <string>] [-Notes <string>] [-WhatIf] [-Confirm] [<CommonParameters>]
Invoke-XdrEndpointDeviceAction -DeviceId <string> -ForceSync [-Comment <string>] [-WhatIf] [-Confirm] [<CommonParameters>]
Invoke-XdrEndpointDeviceAction -DeviceId <string> -StartInvestigation [-Comment <string>] [-WhatIf] [-Confirm] [<CommonParameters>]
Invoke-XdrEndpointDeviceAction -DeviceId <string> -LiveResponse [-Comment <string>] [-WhatIf] [-Confirm] [<CommonParameters>]
Parameters
-DeviceId
| Property | Value |
|---|---|
| Type | String |
| Required | Yes |
| Position | named |
| Pipeline input | true (ByPropertyName) |
| Default | Not documented |
The device ID (SenseMachineId) of the target device. Required for all actions.
-Comment
| Property | Value |
|---|---|
| Type | String |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | Not documented |
A comment describing the reason for the action. Used as RequestorComment for API calls.
-Scan
| Property | Value |
|---|---|
| Type | String |
| Required | Yes |
| Position | named |
| Pipeline input | No |
| Default | Not documented |
Runs an antivirus scan on the device. Valid values: Quick, Full.
-Isolate
| Property | Value |
|---|---|
| Type | String |
| Required | Yes |
| Position | named |
| Pipeline input | No |
| Default | Not documented |
Isolates the device from the network. Valid values: Full, Selective.
-ReleaseFromIsolation
| Property | Value |
|---|---|
| Type | SwitchParameter |
| Required | Yes |
| Position | named |
| Pipeline input | No |
| Default | False |
Releases the device from network isolation.
-RestrictAppExecution
| Property | Value |
|---|---|
| Type | SwitchParameter |
| Required | Yes |
| Position | named |
| Pipeline input | No |
| Default | False |
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.
-RemoveAppExecutionRestriction
| Property | Value |
|---|---|
| Type | SwitchParameter |
| Required | Yes |
| Position | named |
| Pipeline input | No |
| Default | False |
Removes application execution restriction from the device. macOS note: this action is currently unsupported and should be attempted only for capability detection/documentation.
-CollectInvestigationPackage
| Property | Value |
|---|---|
| Type | SwitchParameter |
| Required | Yes |
| Position | named |
| Pipeline input | No |
| Default | False |
Collects a forensic investigation package from the device.
-CollectSupportLogs
| Property | Value |
|---|---|
| Type | SwitchParameter |
| Required | Yes |
| Position | named |
| Pipeline input | No |
| Default | False |
Collects support diagnostic logs from the device.
-StartTroubleshoot
| Property | Value |
|---|---|
| Type | SwitchParameter |
| Required | Yes |
| Position | named |
| Pipeline input | No |
| Default | False |
Enables troubleshooting mode on the device.
-TroubleshootDurationHours
| Property | Value |
|---|---|
| Type | Int32 |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | 4 |
Duration in hours for troubleshooting mode. Defaults to 4. Maximum 12.
-StopTroubleshoot
| Property | Value |
|---|---|
| Type | SwitchParameter |
| Required | Yes |
| Position | named |
| Pipeline input | No |
| Default | False |
Disables troubleshooting mode on the device.
-SetTags
| Property | Value |
|---|---|
| Type | String[] |
| Required | Yes |
| Position | named |
| Pipeline input | No |
| Default | Not documented |
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.
-SetAssetValue
| Property | Value |
|---|---|
| Type | String |
| Required | Yes |
| Position | named |
| Pipeline input | No |
| Default | Not documented |
Sets the asset value of the device. Valid values: Low, Normal, High. Wraps Set-XdrEndpointDeviceAssetValue.
-SetCriticalityLevel
| Property | Value |
|---|---|
| Type | String |
| Required | Yes |
| Position | named |
| Pipeline input | No |
| Default | Not documented |
Sets the criticality level. Valid values: VeryHigh, High, Medium, Low, Reset. Reset removes the criticality level. Wraps Set-XdrEndpointDeviceCriticalityLevel.
-SetExclusionState
| Property | Value |
|---|---|
| Type | String |
| Required | Yes |
| Position | named |
| Pipeline input | No |
| Default | Not documented |
Sets the exclusion state. Valid values: Excluded, Included. Wraps Set-XdrEndpointDeviceExclusionState.
-Justification
| Property | Value |
|---|---|
| Type | String |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | Not documented |
Justification for exclusion state change.
-Notes
| Property | Value |
|---|---|
| Type | String |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | Not documented |
Additional notes for the exclusion state change.
-ForceSync
| Property | Value |
|---|---|
| Type | SwitchParameter |
| Required | Yes |
| Position | named |
| Pipeline input | No |
| Default | False |
Forces a policy sync on the device. Wraps Invoke-XdrEndpointDevicePolicySync.
-StartInvestigation
| Property | Value |
|---|---|
| Type | SwitchParameter |
| Required | Yes |
| Position | named |
| Pipeline input | No |
| Default | False |
Starts an automated investigation. Wraps Invoke-XdrEndpointDeviceAutomatedInvestigation. macOS note: this action is currently unsupported and should be attempted only for capability detection/documentation.
-LiveResponse
| Property | Value |
|---|---|
| Type | SwitchParameter |
| Required | Yes |
| Position | named |
| Pipeline input | No |
| Default | False |
Starts an interactive Live Response session. Wraps Connect-XdrEndpointDeviceLiveResponse.
-WhatIf
| Property | Value |
|---|---|
| Type | SwitchParameter |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | Not documented |
Shows what would happen if the cmdlet runs without actually performing the action.
-Confirm
| Property | Value |
|---|---|
| Type | SwitchParameter |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | Not documented |
Prompts for confirmation before executing the operation.
Examples
Invoke-XdrEndpointDeviceAction -DeviceId "980dddb7036eae7e38d30dee7f11b51e573a6fc2" -Scan Quick
Runs a quick antivirus scan on the specified device.
Invoke-XdrEndpointDeviceAction -DeviceId "980dddb7036eae7e38d30dee7f11b51e573a6fc2" -Scan Full -Comment "macOS validation full scan"
Runs a full antivirus scan with a comment.
Invoke-XdrEndpointDeviceAction -DeviceId "980dddb7036eae7e38d30dee7f11b51e573a6fc2" -Isolate Full -Comment "macOS containment test"
Fully isolates the device from the network.
Invoke-XdrEndpointDeviceAction -DeviceId "980dddb7036eae7e38d30dee7f11b51e573a6fc2" -ReleaseFromIsolation -Comment "macOS containment test rollback"
Releases the device from isolation.
Invoke-XdrEndpointDeviceAction -DeviceId "980dddb7036eae7e38d30dee7f11b51e573a6fc2" -CollectInvestigationPackage -Comment "macOS evidence collection"
Collects a forensic investigation package from the device.
Invoke-XdrEndpointDeviceAction -DeviceId "980dddb7036eae7e38d30dee7f11b51e573a6fc2" -LiveResponse
Opens an interactive Live Response session to the device.
Invoke-XdrEndpointDeviceAction -DeviceId "980dddb7036eae7e38d30dee7f11b51e573a6fc2" -SetAssetValue High
Sets the asset value to High.
Invoke-XdrEndpointDeviceAction -DeviceId "980dddb7036eae7e38d30dee7f11b51e573a6fc2" -ForceSync -Comment "macOS policy sync validation"
Forces a policy sync on the device.
Output
Type: PSCustomObject
Returns the API response from the action. For Live Response, enters an interactive session.