MDE Offboarding script

2025-11-12 12:45:29 +01:00
commit 224f191e9c
4 changed files with 594 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,135 @@
+Collection of M365 scripts
+# M365-Scripts
+
+This repository contains administrative and automation scripts for managing Microsoft 365 services, with a focus on Microsoft Defender for Endpoint (MDE) device lifecycle management.
+
+---
+
+## 🔧 Script: MDE Offboard Devices by Tag
+
+**Script name:** `MDE\MDE_OffboardDevices.ps1`  
+**Purpose:** Identify and offboard Microsoft Defender for Endpoint devices based on a specific device tag.
+
+The script connects to the Defender for Endpoint API, finds devices tagged with a defined value (e.g. `offboard`), and issues an offboarding request for each one. This is typically used during device decommissioning or cleanup processes.
+
+---
+
+## 🚀 How to Use
+
+### 1. Requirements
+- PowerShell 7.0 or newer  
+- An Entra ID App Registration with the following **API permissions** under “APIs my organization uses → WindowsDefenderATP”:
+  - `Machine.Read.All` (minimum to list devices)  
+  - `Machine.ReadWrite.All` (required if you want the script to remove the source tag and apply `CompletedTag`)  
+  - `Machine.Offboard`
+- These permissions appear under the WindowsDefenderATP API in the Azure portal and require admin consent to be granted.  
+- Offboarding via the Defender API is only supported for Windows 10/11 and Windows Server 2019 (or later) endpoints. Earlier OS versions must be offboarded through other supported methods.
+- Correct Defender API base URL for your tenant:
+  - Global: `https://api.securitycenter.microsoft.com`
+  - EU: `https://eu.api.security.microsoft.com`
+  - US: `https://us.api.security.microsoft.com`
+
+---
+
+### 2. Example usage
+
+```powershell
+.\MDE_OffboardDevices.ps1 `
+  -TenantId "<tenant-id>" `
+  -ClientId "<client-id>" `
+  -ClientSecret "<client-secret>" `
+  -Tag "offboard" `          # devices currently tagged with this value will be targeted
+  -CompletedTag "offboarded" ` # optional: tag applied after successful offboard (defaults to offboarded)
+  -ApiBase "https://eu.api.security.microsoft.com"
+```
+
+The script runs in dry-run mode unless you add `-Offboard`. Use this switch only when you're ready to send the requests:
+```powershell
+.\Offboard-ByTag.ps1 -TenantId "<tenant>" -ClientId "<id>" -ClientSecret "<secret>" -Tag "offboard" -Offboard
+```
+
+### 3. Use a parameter file
+
+Store frequently reused values in a JSON or `.psd1` file so you don't have to pass them on every run. By default, the script looks for `MDE_OffboardDevices.parameters.json` or `MDE_OffboardDevices.parameters.psd1` in the same folder, but you can also pass a custom path through `-ParametersPath`.
+
+Example JSON file:
+
+```json
+{
+  "TenantId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
+  "ClientId": "ffffffff-1111-2222-3333-444444444444",
+  "ClientSecret": "super-secret-value",
+  "Tag": "offboard",
+  "CompletedTag": "offboarded",
+  "ApiBase": "https://eu.api.security.microsoft.com",
+  "StartsWith": true,
+  "Offboard": false,
+  "DelayBetweenCallsSec": 2,
+  "MaxRetries": 5,
+  "RetryDelaySec": 10
+}
+```
+
+Run the script and let the file supply the values:
+
+```powershell
+.\Offboard-ByTag.ps1 -ParametersPath .\MDE_OffboardDevices.parameters.json
+```
+
+Any CLI arguments you pass will override the values loaded from the file, so you can mix and match (e.g., keep secrets in the file but override `-Tag` for specific runs). Set `"Offboard": true` (or pass `-Offboard`) only when you want to send the offboard requests. Once an offboard succeeds, the script removes the original `Tag` value and applies `CompletedTag` (default `offboarded`) so you can track completed machines (requires the app to have `Machine.ReadWrite.All` permission). The script also queries Defender's Machine Actions API before each run so it can report and skip devices that already have an offboarding action in progress.
+
+---
+
+## 🏷️ Tagging Devices
+
+Before running the script, ensure target devices are tagged appropriately.
+
+### Add the tag manually
+1. Go to [https://security.microsoft.com](https://security.microsoft.com)
+2. Navigate to **Assets → Devices**
+3. Select devices to manage
+4. Choose **Manage tags → Add tag**
+5. Add the tag `offboard`
+
+### Add the tag via API
+```http
+POST /api/machines/{machineId}/tags
+{
+  "Value": "offboard",
+  "Action": "Add"
+}
+```
+
+Devices with this tag will be detected automatically when you run the script.
+
+---
+
+## ⚙️ What Happens When You Offboard
+
+- The Defender for Endpoint sensor on the machine stops sending telemetry.  
+- The device will appear as **Inactive** or **Offboarded** in the MDE portal.  
+- Devices stay in an **Active** state for up to ~7 days after the offboarding request before flipping to **Inactive**, so rewriting the tag to `CompletedTag` provides immediate tracking you can rely on during that transition window.  
+- The device timeline should eventually show an event titled **`Event of type [OffboardDevice] observed on device`**; this is the final confirmation that the service observed the offboarding command. Verify this manually in the Defender portal (Device timeline) after running the script, especially for high-value machines.  
+- The agent is not uninstalled; re-onboarding will be required to bring the device back.  
+- The action is irreversible once executed.
+
+---
+
+## 🧭 Tips
+
+- Always run a dry run (omit `-Offboard`) before production to verify the device list.  
+- Use a unique tag (like `offboard`) to avoid affecting unintended devices.  
+- Logs and API responses are printed to the console for transparency.  
+
+---
+
+## 🧾 License
+
+MIT License  
+Copyright © 2025
+
+---
+
+## 📬 Feedback & Contributions
+
+Feel free to open issues or submit pull requests to expand the collection of M365 automation scripts.