Edit

Share via

Get started with troubleshooting mode in Microsoft Defender for Endpoint

Applies to:

Troubleshooting mode in Microsoft Defender for Endpoint enables administrators to troubleshoot various Microsoft Defender Antivirus features, even if devices are managed by organizational policies. For example, if tamper protection is enabled, certain settings can't be modified or turned off, but you can use troubleshooting mode on a device to edit those settings temporarily.

Troubleshooting mode is disabled by default, and requires you to turn it on for a device (and/or group of devices) for a limited time. Troubleshooting mode is exclusively an enterprise-only feature, and requires Microsoft Defender portal access.

This article describes troubleshooting mode for Windows devices. For information about troubleshooting mode on Mac, see Troubleshooting mode in Microsoft Defender for Endpoint on macOS.

Tip

What do you need to know before you begin?

During troubleshooting mode, you can use the PowerShell command Set-MPPreference -DisableTamperProtection $true or, on client operating systems, the Security Center app to temporarily disable tamper protection on your device and make your necessary configuration changes.

You can use troubleshooting mode to troubleshoot or check application compatibility with Microsoft Defender Antivirus, such as when false positives occur with application blocks.

With appropriate permissions, local administrators can change configuration on individual devices that are usually locked by policy. Having a device in troubleshooting mode can be helpful when diagnosing Microsoft Defender Antivirus performance and compatibility scenarios. Local administrators can't turn off Microsoft Defender Antivirus, or uninstall it. Local administrators can configure all other security settings in the Microsoft Defender Antivirus suite (for example, cloud protection, tamper protection).

Administrators must have "Manage Security settings" permissions to turn on troubleshooting mode.

Defender for Endpoint collects logs and investigation data throughout the troubleshooting process.

  • A snapshot of MpPreference is taken before troubleshooting mode begins.
  • A second snapshot is taken just before troubleshooting mode expires.
  • Operational logs from during troubleshooting mode are also collected.
  • Logs and snapshots are collected and are available for an administrator to collect using the Collect investigation package feature on the device page. Microsoft doesn't remove this data from the device until an administrator has collected it.

Administrators can also review the changes in settings that take place during troubleshooting mode in Event Viewer on the device itself.

Troubleshooting mode automatically turns off after reaching its expiration time (it lasts for 4 hours). When troubleshooting mode has expired, all policy-managed configurations become read-only again and revert to how the device was configured before enabling troubleshooting mode.

It can take up to 15 minutes from the time the command is sent from Microsoft Defender XDR to when it becomes active on the device.

Notifications are sent to the user when troubleshooting mode begins and when troubleshooting mode ends. A warning is also sent to indicate that troubleshooting mode is ending soon. The beginning and end of troubleshooting mode is also identified in the Microsoft Defender portal, in the Device Timeline on the device page.

You can query all troubleshooting mode events in advanced hunting.

Note

Policy management changes are applied to the device when it's actively in troubleshooting mode. However, the changes don't take effect until troubleshooting mode expires. Additionally, Microsoft Defender Antivirus Platform updates aren't applied during Troubleshooting mode. Platform updates are applied when troubleshooting mode ends with a Windows update.

Prerequisites

Enable troubleshooting mode

  1. Go to the Microsoft Defender portal, and sign in.

  2. Navigate to the device page/machine page for the device you would like to turn on troubleshooting mode. Select Turn on troubleshooting mode. You must have "Manage security settings in Security Center" permissions for Microsoft Defender for Endpoint.

    Turn on troubleshooting mode

    Note

    The Turn on troubleshooting mode option is available on all devices, even if the device doesn't meet the prerequisites for troubleshooting mode.

  3. Confirm you want to turn on troubleshooting mode for the device.

    The configuration flyout

  4. The device page shows the device is now in troubleshooting mode.

    The device is now in troubleshooting mode

Advanced hunting queries

Here are some prebuilt advanced hunting queries to give you visibility into the troubleshooting events that are occurring in your environment. You can also use these queries to create detection rules to generate alerts when devices are in troubleshooting mode.

Get troubleshooting events for a particular device

Search by deviceId or deviceName by commenting out the respective lines.

//let deviceName = "<deviceName>";   // update with device name
let deviceId = "<deviceID>";   // update with device id
DeviceEvents
| where DeviceId == deviceId
//| where DeviceName  == deviceName
| where ActionType == "AntivirusTroubleshootModeEvent"
| extend _tsmodeproperties = parse_json(AdditionalFields)
| project Timestamp,DeviceId, DeviceName, _tsmodeproperties,
 _tsmodeproperties.TroubleshootingState, _tsmodeproperties.TroubleshootingPreviousState, _tsmodeproperties.TroubleshootingStartTime,
 _tsmodeproperties.TroubleshootingStateExpiry, _tsmodeproperties.TroubleshootingStateRemainingMinutes,
 _tsmodeproperties.TroubleshootingStateChangeReason, _tsmodeproperties.TroubleshootingStateChangeSource

Devices currently in troubleshooting mode

DeviceEvents
| where Timestamp > ago(3h) // troubleshooting mode automatically disables after 4 hours 
| where ActionType == "AntivirusTroubleshootModeEvent"
| extend _tsmodeproperties = parse_json(AdditionalFields)
| where _tsmodeproperties.TroubleshootingStateChangeReason contains "started"
|summarize (Timestamp, ReportId)=arg_max(Timestamp, ReportId), count() by DeviceId
| order by Timestamp desc

Count of troubleshooting mode instances by device

DeviceEvents
| where ActionType == "AntivirusTroubleshootModeEvent"
| extend _tsmodeproperties = parse_json(AdditionalFields)
| where Timestamp > ago(30d)  // choose the date range you want
| where _tsmodeproperties.TroubleshootingStateChangeReason contains "started"
| summarize (Timestamp, ReportId)=arg_max(Timestamp, ReportId), count() by DeviceId
| sort by count_

Total count

DeviceEvents
| where ActionType == "AntivirusTroubleshootModeEvent"
| extend _tsmodeproperties = parse_json(AdditionalFields)
| where Timestamp > ago(2d) //beginning of time range
| where Timestamp < ago(1d) //end of time range
| where _tsmodeproperties.TroubleshootingStateChangeReason contains "started"
| summarize (Timestamp, ReportId)=arg_max(Timestamp, ReportId), count()
| where count_ > 5          // choose your max # of TS mode instances for your time range

Tip

Do you want to learn more? Engage with the Microsoft Security community in our Tech Community: Microsoft Defender for Endpoint Tech Community.