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

.\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:

.\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:

{
  "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:

.\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

Go to https://security.microsoft.com
Navigate to Assets → Devices
Select devices to manage
Choose Manage tags → Add tag
Add the tag offboard

Add the tag via API

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

📬 Feedback & Contributions

Feel free to open issues or submit pull requests to expand the collection of M365 automation scripts.