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.