mirror of
https://github.com/fleetdm/fleet
synced 2026-04-21 13:37:30 +00:00
5a660613db
Add fallback wipe script for Windows hosts (#34994) When Fleet's built-in Windows wipe action fails (MDM command returns status 500, device not wiped), there is no documented fallback. This PR adds a script that can be run via Fleet to wipe the device when the native wipe fails. ## Changes - `docs/solutions/windows/scripts/wipe-windows-device.ps1` - Fallback wipe script - `articles/lock-wipe-hosts.md` - Reference to fallback script added under Windows wipe section ## What the script does 1. Validates and repairs WinRE if disabled (confirmed root cause of wipe failures in #34994) 2. Checks Component Store integrity via DISM 3. Suspends BitLocker for one reboot cycle 4. Triggers wipe via WMI-to-CSP bridge (`doWipeProtected`, falls back to `doWipe`), bypassing the MDM command queue Fully unattended. No user interaction required. Exits 0 on success, 1 on failure. ## Context Every fully unattended Windows wipe method uses the same RemoteWipe CSP. There is no alternative Windows API. This script adds value by fixing the root causes before calling the wipe, and by bypassing the MDM command queue where server-side failures (DB timeouts, auth errors) can occur. Closes #34994 <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Added an administrator-only Windows device wipe utility that performs staged system checks (recovery environment, system health, and disk protection), attempts to suspend drive protection for a reboot, invokes multiple local wipe triggers with fallbacks, creates a timestamped audit log of actions, and provides clear success/failure summaries with likely causes and suggested next steps. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Marko Lisica <83164494+marko-lisica@users.noreply.github.com> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> Co-authored-by: CodeRabbit <noreply@coderabbit.ai>
109 lines
8.5 KiB
Markdown
109 lines
8.5 KiB
Markdown
# Lock and wipe hosts
|
|
|
|
|
|
|
|
_Available in Fleet Premium_
|
|
|
|
In Fleet, you can lock and wipe macOS, Windows, Linux, iOS and iPadOS hosts remotely when a host might have been lost or stolen, or to remotely prepare a device to be re-deployed to another end user.
|
|
|
|
Restricting wipe for iPhones and iPads to only company-owned iPhones and iPads is coming soon.
|
|
|
|
## Lock a host
|
|
|
|
1. Navigate to the **Hosts** page by clicking the "Hosts" tab in the main navigation header. Find the device you want to lock. You can search by name, hostname, UUID, serial number, or private IP address in the search box in the upper right corner.
|
|
2. Click the host to open the **Host details** page.
|
|
3. Click the **Actions** dropdown, then click **Lock**.
|
|
4. A confirmation dialog will appear. Confirm that you want to lock the device. The host will now be marked with a "Lock pending" badge. Once the lock command is acknowledged by the host, the badge will update to "Locked".*
|
|
|
|
Currently, for Windows hosts that are [Microsoft Entra joined](https://learn.microsoft.com/en-us/entra/identity/devices/concept-directory-join), the best practice is to disable the end user's account in Entra and then lock the host in Fleet. This applies to all Windows hosts that [automatically enroll](https://fleetdm.com/guides/windows-mdm-setup#automatic-enrollment). These hosts are Entra joined.
|
|
|
|
> **iOS and iPadOS**: Lock action is only available for company-owned ([supervised](https://support.apple.com/en-gb/guide/deployment/dep1d89f0bff/web)) hosts.
|
|
As part of locking an iOS or iPadOS host, Fleet collects the device's location data. Fleet will not consider the device fully locked until the location data is collected.
|
|
|
|
> **Linux hosts**: The system may automatically reboot after approximately 10 seconds to complete the lock process.
|
|
|
|
### Get location of locked iOS/iPadOS host
|
|
|
|
1. Navigate to the **Hosts** page by clicking the "Hosts" tab in the main navigation header. Find the locked device. You can search by name, hostname, UUID, serial number, or private IP address in the search box in the upper right corner.
|
|
2. Click the host to open the **Host details** page
|
|
3. Under **Vitals**, click **Show location**, then click **Open in Google Maps**. This will open a new tab with the device's location shown in Google Maps.
|
|
4. While the device is locked, you can refetch device location data by clicking **Refetch**.
|
|
|
|
You can also manually send the [`DeviceLocation`](https://developer.apple.com/documentation/devicemanagement/device-location-command) command using a [custom command](https://fleetdm.com/guides/mdm-commands). This command will only work if the device is locked and in [Lost Mode](https://support.apple.com/en-gb/guide/security/secc46f3562c/web#sec49d5c5c50).
|
|
|
|
To view the location on Google Maps, use the latitude and longitude values from the command response in the following URL: `https://google.com/maps?q={latitude},{longitude}`
|
|
|
|
Example response:
|
|
```xml
|
|
<key>Latitude</key>
|
|
<real>37.33385013244351</real>
|
|
<key>Longitude</key>
|
|
<real>-122.01079213269968</real>
|
|
```
|
|
|
|
Example URL:
|
|
`https://google.com/maps?q=37.33385013244351,-122.01079213269968`
|
|
|
|
## Wipe a host
|
|
|
|
1. Navigate to the **Hosts** page by clicking the "Hosts" tab in the main navigation header. Find the device you want to wipe. You can search by name, hostname, UUID, serial number, or private IP address in the search box in the upper right corner.
|
|
2. Click the host to open the **Host Overview** page.
|
|
3. Click the **Actions** dropdown, then click **Wipe**.
|
|
4. Confirm that you want to wipe the device in the dialog. The host will now be marked with a "Wipe pending" badge. Once the wipe command is acknowledged by the host, the badge will update to "Wiped".
|
|
|
|
When wiping and re-installing the operating system (OS) on a host, delete the host from Fleet before you re-enroll it. If you re-enroll without deleting, Fleet won't escrow a new disk encryption key.
|
|
|
|
If you're gifting a company-owned macOS host or you want to prevent the host from automatically re-enrolling to Fleet for some other reason, first release the host from Apple Business Manager (ABM) and then delete the host in Fleet.
|
|
|
|
For Windows hosts, Fleet uses the [doWipeProtected](https://learn.microsoft.com/en-us/windows/client-management/mdm/remotewipe-csp#dowipeprotected) command by default. According to Microsoft, this leaves the host [unable to boot](https://learn.microsoft.com/en-us/windows/client-management/mdm/remotewipe-csp#:~:text=In%20some%20device%20configurations%2C%20this%20command%20may%20leave%20the%20device%20unable%20to%20boot.). However, it is possible to use the [doWipe command via the API](https://fleetdm.com/docs/rest-api/rest-api#parameters57).
|
|
|
|
If the wipe command fails (MDM protocol returns 500 in [MDM command results](https://fleetdm.com/docs/rest-api/rest-api#list-mdm-commands)), you can run a [fallback wipe script](https://github.com/fleetdm/fleet/blob/main/docs/solutions/windows/scripts/wipe-windows-device.ps1) via Fleet. This script validates and repairs WinRE (the most common cause of wipe failure), suspends BitLocker, and triggers the wipe locally via the WMI-to-CSP bridge, bypassing the MDM command queue.
|
|
For macOS hosts, Fleet uses Erase All Content and Settings (EACS) with the [default fallback behavior documented by Apple](https://developer.apple.com/documentation/devicemanagement/erasedevicecommand/command-data.dictionary#:~:text=devices%20always%20obliterate.-,Default,-%3A%20If%20EACS%20preflight).
|
|
|
|
## Unlock a host
|
|
|
|
1. Navigate to the **Hosts** page by clicking the "Hosts" tab in the main navigation header. Find the device you want to unlock. You can search by name, hostname, UUID, serial number, or private IP address in the search box in the upper right corner.
|
|
2. Click the host to open the **Host Overview** page.
|
|
3. Click the **Actions** menu, then click **Unlock**.
|
|
- **macOS**: A dialog with the PIN will appear. Type the PIN into the device to unlock it.
|
|
- **Windows, Linux, iOS and iPadOS**: The command to unlock the host will be queued and the host will unlock once it receives the command (no PIN needed).*
|
|
4. When you click **Unlock**, Windows, Linux, iOS and iPadOS hosts will be marked with an "Unlock pending" badge. Once the host is unlocked and checks back in with Fleet, the "Unlock pending" badge will be removed. macOS hosts do not have an "Unlock pending" badge as they cannot be remotely unlocked (the PIN has to be typed into the device).
|
|
|
|
> **Linux hosts**: The system will automatically reboot after approximately 10 seconds to complete the unlock process and ensure the user interface is properly restored. If the host loses connection to Fleet, the unlock process may run again, causing the host to reboot again.
|
|
|
|
### How to unlock offline iOS and iPadOS hosts
|
|
|
|
If an iPhone/iPad is turned off or restarted while locked, it will disconnect from Wi-Fi and can't be unlocked remotely. Connect your iPhone/iPad to your Mac with a USB and [share the network](https://support.apple.com/en-gb/guide/mac-help/mchlp1540/mac). After connecting your iPhone/iPad to the internet, in Fleet, head to the **Host details** page and select **Actions > Unlock**.
|
|
|
|
## Lock and wipe using `fleetctl`
|
|
|
|
You can lock, unlock, and wipe hosts using Fleet's command-line tool `fleetctl`:
|
|
|
|
```shell
|
|
fleetctl mdm lock --host $HOST_IDENTIFIER
|
|
```
|
|
|
|
```shell
|
|
fleetctl mdm unlock --host $HOST_IDENTIFIER
|
|
```
|
|
|
|
```shell
|
|
fleetctl mdm wipe --host $HOST_IDENTIFIER
|
|
```
|
|
|
|
`$HOST_IDENTIFIER` can be any of the host identifiers: hostname, UUID, or serial number.
|
|
|
|
Add the `--help` flag to any command to learn more about how to use it.
|
|
|
|
For macOS hosts, the `mdm unlock` command will return the six-digit PIN, which must be typed into the device in order to finish unlocking it.
|
|
|
|
*For Windows and Linux hosts, a script will run as part of the lock and unlock actions. Details for each script can be found in GitHub for [Windows](https://github.com/fleetdm/fleet/tree/main/ee/server/service/embedded_scripts/windows_lock.ps1) and [Linux](https://github.com/fleetdm/fleet/tree/main/ee/server/service/embedded_scripts/linux_lock.sh) hosts.
|
|
|
|
** Fleet is currently tracking a [known Apple bug](https://github.com/fleetdm/fleet/issues/34208), which results in Lost mode being cleared after reboot on iOS/iPadOS 26.
|
|
|
|
<meta name="articleTitle" value="Lock and wipe hosts">
|
|
<meta name="authorFullName" value="JD Strong">
|
|
<meta name="authorGitHubUsername" value="spokanemac">
|
|
<meta name="category" value="guides">
|
|
<meta name="publishedOn" value="2024-07-09">
|
|
<meta name="articleImageUrl" value="../website/assets/images/articles/sysadmin-diaries-1600x900@2x.png">
|