From b9df4c29e9f50826df7782bc393d882e3699e423 Mon Sep 17 00:00:00 2001 From: Jahziel Villasana-Espinoza Date: Thu, 14 Nov 2024 19:45:01 -0500 Subject: [PATCH] fix: update guide on lock/unlock/wipe (#23788) > Related issue: #22753 # Checklist for submitter If some of the following don't apply, delete the relevant line. - [x] Manual QA for all new/changed functionality --- articles/lock-wipe-hosts.md | 67 ++++++++++ articles/sysadmin-diaries-lost-device.md | 155 ----------------------- website/config/routes.js | 1 + 3 files changed, 68 insertions(+), 155 deletions(-) create mode 100644 articles/lock-wipe-hosts.md delete mode 100644 articles/sysadmin-diaries-lost-device.md diff --git a/articles/lock-wipe-hosts.md b/articles/lock-wipe-hosts.md new file mode 100644 index 000000000000..519640b173e1 --- /dev/null +++ b/articles/lock-wipe-hosts.md @@ -0,0 +1,67 @@ +# Lock and wipe hosts + +![Lock and wipe hosts](../website/assets/images/articles/sysadmin-diaries-1600x900@2x.png) + +_Available in Fleet Premium_ + +In Fleet, you can lock and wipe macOS, Windows, and Linux hosts remotely. This allows you to easily deal with situations +where a host might have been lost or stolen, or to remotely prepare a device to be re-deployed to another end user. + +**Note**: lock/unlock and wipe commands are queued and will run when the device next comes online. + +## 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 Overview** 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". + +## 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 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 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". + +## Unlocking a host + +**Note**: When a macOS host is locked, Fleet generates a 6 digit security PIN. This PIN must be physically input into the host in order to unlock it. + +To unlock a locked 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 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 and Linux**: The command to unlock the host will be queued and the host will unlock once it receives the command (no PIN needed). +5. When you click **Unlock**, the host 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. + + +## 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. + +**Note**: for macOS hosts, the `mdm unlock` command will return the security PIN, which must be typed into the device in order to finish unlocking it. + + + + + + + diff --git a/articles/sysadmin-diaries-lost-device.md b/articles/sysadmin-diaries-lost-device.md deleted file mode 100644 index 914eceb09607..000000000000 --- a/articles/sysadmin-diaries-lost-device.md +++ /dev/null @@ -1,155 +0,0 @@ -# Sysadmin diaries: lost device - -![Sysadmin diaries: lost device](../website/assets/images/articles/sysadmin-diaries-1600x900@2x.png) - -Picture this: an employee calls you in a panic from an airport halfway across the country. They have just realized they left their company-issued laptop on the plane. Cue the sinking feeling. The device contains sensitive company data, and the thought of it falling into the wrong hands is enough to induce a cold sweat. But fear not! With Fleet's Mobile Device Management (MDM) capabilities, you can handle this situation swiftly and securely. Let us walk through how to lock or wipe a lost device using Fleet remotely. - - -## The scenario: a lost device - -Imagine you receive a call from Jamie, a sales executive who has just landed in Chicago for a crucial client meeting. In their rush to deplane, they accidentally leave their laptop in the seatback pocket. Realizing the mistake after reaching the terminal, Jamie calls you, anxious and stressed about the potential data breach. - - -## Keep calm and use Fleet - -First, take a deep breath. Fleet has got you covered using MDM. You can remotely lock and wipe the lost device to ensure your company’s data remains secure. - - -### Step 1: identify the device - -Start by identifying the device in Fleet. Navigate to the **Hosts** page in the Fleet web UI. Use the search functionality to quickly find Jamie’s laptop by entering the hostname or any other relevant identifier. - - -### Step 2: remote lock - - -#### Using the Fleet web UI - -1. Once you have located the device, click on it to open the **Host Overview** page. - -2. In the **Actions** menu, select **Lock**. - -3. A confirmation dialog will appear. Confirm that you want to lock the device. - - -#### Using the Fleet API - -Alternatively, you can use the Fleet REST API to lock the device. Here is the API call you need to make: - -``` bash - -POST /api/v1/fleet/hosts/:id/lock - -``` - -Replace `:id` with Jamie’s laptop's actual ID. This command sends a signal to lock the device as soon as it comes online. For macOS, this requires MDM to be enabled. For Windows and Linux, scripts need to be enabled. - -If you wanted to call this from the command line, you could use `curl` with a command like this: - -```bash - -curl -X GET https://fleet.company.com/api/v1/fleet/hosts/123/lock -H "Authorization: Bearer " - -``` - - -#### Optional steps for macOS - -You can customize the locking message for macOS devices and set a PIN using an XML payload. Here is how: - -1. Create a file named `command-lock-macos-host.xml` with the following content: - - ```xml - - - - - - Command - - Message - This device has been locked. Contact IT on (123) 456-7890. - PIN - 123456 - RequestType - DeviceLock - - - - - ``` - -2. Customize the message and PIN as needed. - -3. Safely store the recovery PIN using a secure method like 1Password. - -4. Run the following command using the Fleet CLI tool, replacing `hostname` with the actual hostname in Fleet and the payload path with the file’s location: - - ```bash - - fleetctl mdm run-command --hosts=hostname --payload=command-lock-macos-host.xml - - ``` - - -### Step 3: remote wipe (if necessary) - -If you determine the device is at a high risk of being compromised, you may decide to wipe it. This is a more drastic step, but sometimes, it is necessary to protect sensitive information. - - -#### Using the Fleet web UI - -1. On the same **Host Overview** page, go to the **Actions** menu and select **Wipe**. - -2. Confirm the wipe action that appears in the dialog. - - -#### Using the Fleet API - -To wipe the device via the API, use the following call: - -```bash - -POST /api/v1/fleet/hosts/:id/wipe - -``` - -Again, replace `:id` with the device’s ID. The wipe command will be executed once the device is online. MDM must be enabled for macOS and Windows, and scripts must be enabled for Linux. - - -### Step 4: confirm and reassure - -After you have locked and potentially wiped the device, inform Jamie of the steps actioned. Reassure them that the company’s data is now secure and provide any further instructions they may need, such as getting a replacement device. - - -### Unlocking macOS - -If the device is found and needs to be unlocked: - - - -1. Enter the security PIN (stored in Fleet, returned from the API call, or the XML file) in the device's input field. -2. The device will open to the regular login screen and ask for a password. -3. If the password is unavailable, select the option to enter the recovery key/disk encryption key (this option might be behind a ? icon). -4. Retrieve the disk encryption key from Fleet’s web UI. -5. Enter the disk encryption key on the laptop, which should prompt you to create a new password. -6. You will then be logged into the default device profile, which allows you to complete any needed actions (e.g., wiping or recovering data). - - -## Conclusion - -Losing a device is stressful, but Fleet’s MDM capabilities can help you manage it effectively. You can protect sensitive data and prevent unauthorized access by remotely locking or wiping the lost device. Remember, stay calm, and rely on Fleet to secure your endpoints. - -Fleet’s MDM features ensure that your data remains protected even if a device is lost. So, the next time you get that dreaded call, you will know exactly what to do. - - - - - - - - - - - - diff --git a/website/config/routes.js b/website/config/routes.js index ca7c27023fa2..9e9d7005ed6f 100644 --- a/website/config/routes.js +++ b/website/config/routes.js @@ -488,6 +488,7 @@ module.exports.routes = { 'GET /docs/using-fleet/mdm-commands': (req,res)=> { return res.redirect(301, '/guides/mdm-commands');}, 'GET /docs/using-fleet/log-destinations': (req,res)=> { return res.redirect(301, '/guides/log-destinations');}, 'GET /guides/how-to-uninstall-osquery': (req,res)=> { return res.redirect(301, '/guides/how-to-uninstall-fleetd');}, + 'GET /guides/sysadmin-diaries-lost-device': (req,res)=> { return res.redirect(301, '/guides/lock-wipe-hosts');}, // ╔╦╗╦╔═╗╔═╗ ╦═╗╔═╗╔╦╗╦╦═╗╔═╗╔═╗╔╦╗╔═╗ ┬ ╔╦╗╔═╗╦ ╦╔╗╔╦ ╔═╗╔═╗╔╦╗╔═╗ // ║║║║╚═╗║ ╠╦╝║╣ ║║║╠╦╝║╣ ║ ║ ╚═╗ ┌┼─ ║║║ ║║║║║║║║ ║ ║╠═╣ ║║╚═╗