136 lines
5.6 KiB
Markdown
136 lines
5.6 KiB
Markdown
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 as well as other OSs (macOS, Linux...) 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.
|