MDEAutomator is a modular, serverless solution for endpoint management and incident response in Microsoft Defender for Endpoint (MDE) environments. It leverages Azure Function Apps and a custom PowerShell module to orchestrate large MDE deployments, automate response actions, and manage threat indicators at scale.
-
MDEAutomator PowerShell Module
Provides cmdlets for authentication, device management, live response, response actions, and threat indicator management in MDE. -
Azure Function Apps
- MDEDispatcher: Automates bulk management of response actions delivered to endpoints.
- MDEOrchestrator: Automates bulk management of Live Response commands delivered to endpoints.
- MDEProfiles: Automates bulk delivery of custom PowerShell scripts to configure policy on MDE endpoints.
- MDETIManager: Automates the management of Threat Indicators in MDE.
- Portable PowerShell module
- Bulk automation of MDE response actions and live response actions
- Bulk management of MDE threat indicators (IOCs)
- Designed for multi-tenant use cases
- Azure Key Vault secret management + manual
$SPNSECRETflexibility - Ability to deliver key configuration settings via PowerShell that are not available in Endpoint Security Profiles.
- Convenient upload of endpoint packages/files to Azure Storage
- Application Insights
- Azure Function
- App Service Plan (EP1)
- Azure Storage
- Azure Key Vault
- User Managed Identity
MDEAutomator Estimated Monthly Azure Cost: ~$180 USD
-
Create Entra ID Service Principal (App Registration)
Note: Select Multitenant if you plan to leverage this to service multiple tenants.
-
Add required API permissions to the Service Principal
Required WindowsDefenderATP API Permissions:
- Library.Manage
- Machine.CollectForensics
- Machine.Isolate
- Machine.LiveResponse
- Machine.ReadWrite.All
- Machine.RestrictExecution
- Machine.Scan
- Ti.ReadWrite
-
Generate SPN Secret (securely store for post-deployment configuration)
-
Enable Unsigned Script Execution & Live Response for Servers and Workstations in MDE Advanced Settings. (See Security Notes section of this README)
-
Click the "Deploy to Azure" button below.
Note: After deployment, you may need to restart the Azure Function for the Function Apps to load properly.
-
Add "SPNSECRET" to Azure Key Vault
Create a secret named "SPNSECRET" with the value generated during SPN provisioning
-
Configure your front-end application to call the Function Apps
- Use the PowerShell module locally for bulk automation and investigation tasks.
- Use the PowerShell module in Azure Functions.
- Use the PowerShell module in Azure Automation.
Below are example usage patterns for the MDEAutomator PowerShell module.
# Import MDEAutomator module from source repo
Import-Module -Name ./function/MDEAutomator -ErrorAction Stop -Force
# Install & Import from PowerShell Gallery
Install-Module -Name MDEAutomator -AllowClobber -Force
Import-Module -Name MDEAutomator -ErrorAction Stop -Force
# Upload a file to the Live Response library (limit: 250 MB)
Invoke-UploadLR -token $token -filePath "C:\MDEAutomator\tester.txt"
# Push a Live Response Library file to endpoint devices
Invoke-PutFile -token $token -fileName "Active.ps1" -DeviceIds @("<DeviceId>")
# Run a full disk scan on all onboarded and active devices
$DeviceIds = Get-Machines -token $token | Select-Object -ExpandProperty Id
Invoke-FullDiskScan -token $token -DeviceIds $DeviceIds
# Run a script via Live Response on a single device and print the transcript in JSON
$DeviceId = "<DeviceId>"
$result = Invoke-LRScript -DeviceIds @($DeviceId) -scriptName 'Active.ps1' -token $token
$result | ConvertTo-Json -Depth 5 | Write-Host
# Download the file locally
$result = Invoke-GetFile -token $token -filePath "C:\Temp\test.msi" -DeviceIds @("<DeviceId>")
$downloadPath = "C:\Your\Desired\Path\test.msi.gz"
Invoke-WebRequest -Uri $result.FileUrl -OutFile $downloadPath
# Run Script on every device
$DeviceIds = Get-Machines -token $token | Select-Object -ExpandProperty Id
Invoke-LRScript -DeviceIds $DeviceIds -scriptName 'Active.ps1' -token $token
# Get all onboarded and active Windows machines
Get-Machines -token $token -filter "contains(osPlatform, 'Windows')"
# Get recent machine actions (last 90 days)
Get-Actions -token $token
# Cancel all current pending machine actions
Undo-Actions -token $token
# Retrieve all devices with a specific tag
$taggedDevices = Get-Machines -token $token -filter "contains(machineTags, 'Critical')"
# Restrict application execution on all endpoints with a high risk score
$highRiskDevices = Get-Machines -token $token -filter "riskScore eq 'High'" | Select-Object -ExpandProperty Id
Invoke-RestrictAppExecution -token $token -DeviceIds $highRiskDevices
# Get the status of all recent machine actions and export to CSV
Get-Actions -token $token | Export-Csv -Path "C:\Temp\MDEActions.csv" -NoTypeInformation
# Upload CSV of SHA256 hash values to MDE
$hashes = Import-Csv -Path "C:\Temp\hashes.csv" | Select-Object -ExpandProperty Sha256
Invoke-TiFile -token $token -Sha256s $hashes
# Upload CSV of IP addresses to MDE as threat indicators
$ips = Import-Csv -Path "C:\Temp\ips.csv" | Select-Object -ExpandProperty IP
Invoke-TiIP -token $token -IPs $ips
# Upload CSV of URLs or domains to MDE as threat indicators
$urls = Import-Csv -Path "C:\Temp\urls.csv" | Select-Object -ExpandProperty URL
Invoke-TiURL -token $token -URLs $urls
⚠️ Warning:
MDEAutomator is a powerful tool that, if misused by a threat actor, could cause significant harm. Treat all credentials, scripts, and deployments with the highest level of security.
- Azure Key Vault is strongly recommended for storing secrets in all production scenarios.
- User-managed identity support is on the roadmap. This will require additional refactoring to support multi-tenant deployments.
- Sign all PowerShell scripts:
Clone this repository and use an Azure Trusted Signing account to sign every PowerShell script with your own signing key. - A signing script (
signscripts.ps1) is included in thepayloadssubfolder to assist with this process. - After signing, redeploy the zip package containing the signed scripts to your Azure Function.
- This allows you to disable unsigned script execution in MDE Advanced Settings without losing any functionality.
Note:
Azure Trusted Signing is currently available only to organizations based in the USA and Canada with a verifiable history of three years or more.
This software is provided "as is", without warranty of any kind, express or implied. The author and contributors are not responsible for any damages, losses, or issues arising from the use of this software. Use at your own risk.
We welcome contributions! Please open an issue or submit a pull request on GitHub.
Made possible by the BlueVoyant Digital Forensics & Incident Response team. For assistance, contact incident@bluevoyant.com.
- VS Code Deployment Guide
- Azure CLI Deployment Guide
- Azure PowerShell Deployment Guide
- Azure Cloud Shell Deployment Guide
- GitHub Actions Deployment Guide
Description:
Authenticates to Microsoft Defender for Endpoint (MDE) using a Service Principal, optionally retrieving secrets from Azure Key Vault.
The -SpnId parameter is the Application (client) ID of your Azure Service Principal. This value uniquely identifies the app registration in Entra ID (Azure AD) that will be used for authentication. You can find this value in the Azure portal under your App Registration's overview page.
The -SpnSecret parameter is the client secret associated with your Service Principal. This should be provided as a secure string. Use this parameter if you are not retrieving the secret from Azure Key Vault. Always store and handle this secret securely.
The -keyVaultName parameter specifies the name of the Azure Key Vault where your Service Principal secret is stored. If you use this parameter, the module will attempt to retrieve the secret from the specified Key Vault at runtime. The currently logged-in user or managed identity must have appropriate permissions (such as Key Vault Secrets User) to access the secret.
The -TenantId parameter is the Entra ID (Azure AD) tenant ID where your Service Principal is registered. This is typically a GUID. If not specified, the module will use the tenant associated with your current Azure context.
Parameters:
-SpnId(string, required): Service Principal App ID.-SpnSecret(securestring, optional): Service Principal secret (use if not using Key Vault).-keyVaultName(string, optional): Azure Key Vault name (if retrieving secret from Key Vault).-TenantId(string, optional): Entra ID Tenant ID or default to home tenant.
Example:
# Using Key Vault
$token = Connect-MDE -SpnId "<appId>" -keyVaultName "<vaultName>"
# Using direct secret
$secureSecret = Read-Host "Enter Secret" -AsSecureString
$token = Connect-MDE -SpnId "<appId>" -SpnSecret $secureSecret -TenantId "<tenantId>"Description:
Get-Machines retrieves a collection of devices that have communicated with Microsoft Defender for Endpoint. It supports OData V4 queries, allowing you to filter, sort, and page results.
Parameters:
The $token parameter is the OAuth2 access token you receive from the Connect-MDE function. You must call Connect-MDE first and use its output as the -token value for Get-Machines and all other API functions. These tokens typically expire every 60 minutes.
- The
-filterparameter lets you use OData$filterexpressions on properties such as:computerDnsName,id,version,deviceValue,aadDeviceId,machineTags,lastSeen,exposureLevel,onboardingStatus,lastIpAddress,healthStatus,osPlatform,riskScore, andrbacGroupId. You can also use$top(up to 10,000) and$skipfor paging results.
Example:
$machines = Get-Machines -token $token
$machines | Format-Table ComputerDnsName, Id, OsPlatformDescription:
Retrieves recent MDE machine actions from the last (60) days performed in MDE.
Parameters:
The $token parameter is the OAuth2 access token you receive from the Connect-MDE function. You must call Connect-MDE first and use its output as the -token value for Get-Actions and all other API functions. These tokens typically expire every 60 minutes.
Example:
$actions = Get-Actions -token $token
$actions | Format-Table Id, Type, Status, ComputerDnsNameDescription:
Undo-Actions cancels all pending machine actions in Microsoft Defender for Endpoint. This is useful for stopping actions that are queued but not yet executed.
Parameters:
The $token parameter is the OAuth2 access token you receive from the Connect-MDE function. You must call Connect-MDE first and use its output as the -token value for Undo-Actions and all other API functions. These tokens typically expire every 60 minutes.
-token(string, required): OAuth2 access token.
Example:
Undo-Actions -token $tokenDescription:
Invoke-MachineIsolation isolates one or more devices from the network, except for connections required for Defender for Endpoint service communication. This always uses Selective isolation and respects Isolation exclusion rules.
Undo-MachineIsolation removes isolation from specified devices, restoring their normal network connectivity.
Parameters:
The $token parameter is the OAuth2 access token you receive from the Connect-MDE function. You must call Connect-MDE first and use its output as the -token value for these functions. These tokens typically expire every 60 minutes.
The -DeviceIds parameter is an array of device IDs that uniquely identify the target devices in Microsoft Defender for Endpoint. You can obtain these IDs by running the Get-Machines function and referencing the Id property in the results. Pass one or more device IDs as a string array (e.g., @("deviceId1", "deviceId2")) to target multiple devices in a single operation.
-token(string, required): OAuth2 access token.-DeviceIds(string[], required): Array of device IDs to isolate or unisolate.
Example:
Invoke-MachineIsolation -token $token -DeviceIds @("<deviceId1>", "<deviceId2>")
Undo-MachineIsolation -token $token -DeviceIds @("<deviceId1>")Description:
Invoke-ContainDevice contains one or more unmanaged devices in Microsoft Defender for Endpoint, restricting their network connectivity to prevent lateral movement.
Undo-ContainDevice removes containment from specified unmanaged devices, restoring their normal network connectivity.
Parameters:
The $token parameter is the OAuth2 access token you receive from the Connect-MDE function. You must call Connect-MDE first and use its output as the -token value for these functions. These tokens typically expire every 60 minutes.
The -DeviceIds parameter is an array of device IDs that uniquely identify the target devices in Microsoft Defender for Endpoint. Indentify the DeviceId of Unmanaged device you wish to Contain.
-token(string, required): OAuth2 access token.-DeviceIds(string[], required): Array of device IDs to contain or uncontain.
Example:
Invoke-ContainDevice -token $token -DeviceIds @("<deviceId>")
Undo-ContainDevice -token $token -DeviceIds @("<deviceId>")Description:
Invoke-RestrictAppExecution restricts application execution on one or more devices, allowing only Microsoft-signed binaries to run.
Undo-RestrictAppExecution removes this restriction, allowing normal application execution.
Parameters:
The $token parameter is the OAuth2 access token you receive from the Connect-MDE function. You must call Connect-MDE first and use its output as the -token value for these functions. These tokens typically expire every 60 minutes.
The -DeviceIds parameter is an array of device IDs that uniquely identify the target devices in Microsoft Defender for Endpoint. You can obtain these IDs by running the Get-Machines function and referencing the Id property in the results. Pass one or more device IDs as a string array (e.g., @("deviceId1", "deviceId2")) to target multiple devices in a single operation.
-token(string, required): OAuth2 access token.-DeviceIds(string[], required): Array of device IDs to restrict or unrestrict.
Example:
Invoke-RestrictAppExecution -token $token -DeviceIds @("<deviceId>")
Undo-RestrictAppExecution -token $token -DeviceIds @("<deviceId>")Description:
Invoke-CollectInvestigationPackage collects an investigation package from one or more specified devices. The package contains forensic artifacts for further analysis.
Parameters:
The $token parameter is the OAuth2 access token you receive from the Connect-MDE function. You must call Connect-MDE first and use its output as the -token value for these functions. These tokens typically expire every 60 minutes.
The -DeviceIds parameter is an array of device IDs that uniquely identify the target devices in Microsoft Defender for Endpoint. You can obtain these IDs by running the Get-Machines function and referencing the Id property in the results. Pass one or more device IDs as a string array (e.g., @("deviceId1", "deviceId2")) to target multiple devices in a single operation.
-token(string, required): OAuth2 access token.-DeviceIds(string[], required): Array of device IDs to collect packages from.
Example:
Invoke-CollectInvestigationPackage -token $token -DeviceIds @("<deviceId>")Description:
Invoke-TiFile creates file hash-based custom threat indicators in Microsoft Defender for Endpoint.
Undo-TiFile deletes file hash-based custom threat indicators.
Parameters:
The $token parameter is the OAuth2 access token you receive from the Connect-MDE function. You must call Connect-MDE first and use its output as the -token value for these functions. These tokens typically expire every 60 minutes.
The -Sha1s and -Sha256s parameters are arrays of file hashes that you want to add or remove as custom threat indicators in Microsoft Defender for Endpoint. Each entry should be a valid SHA-1 or SHA-256 hash string. You can specify values for either or both parameters at the same time, and the function will process all provided hashes in a single operation. This allows you to efficiently manage multiple file-based indicators in one call.
-token(string, required): OAuth2 access token.-Sha1s(string[], optional): Array of SHA1 hashes.-Sha256s(string[], optional): Array of SHA256 hashes.
Example:
Invoke-TiFile -token $token -Sha1s @("<sha1>")
Undo-TiFile -token $token -Sha256s @("<sha256>")Description:
Invoke-TiCert creates certificate thumbprint-based custom threat indicators in Microsoft Defender for Endpoint.
Undo-TiCert deletes certificate thumbprint-based custom threat indicators.
Parameters:
The $token parameter is the OAuth2 access token you receive from the Connect-MDE function. You must call Connect-MDE first and use its output as the -token value for these functions. These tokens typically expire every 60 minutes.
The -Sha1s parameter is an array of certificate thumbprints that you want to add or remove as custom threat indicators in Microsoft Defender for Endpoint. Each entry must be a valid SHA-1 certificate thumbprint string. Note that MDE only accepts SHA-1 values for certificate thumbprints—other hash types are not supported.
-token(string, required): OAuth2 access token.-Sha1s(string[], required): Array of certificate thumbprints.
Example:
Invoke-TiCert -token $token -Sha1s @("<thumbprint>")
Undo-TiCert -token $token -Sha1s @("<thumbprint>")Description:
Invoke-TiIP creates IP address-based custom threat indicators in Microsoft Defender for Endpoint.
Undo-TiIP deletes IP address-based custom threat indicators.
Parameters:
The $token parameter is the OAuth2 access token you receive from the Connect-MDE function. You must call Connect-MDE first and use its output as the -token value for these functions. These tokens typically expire every 60 minutes.
The -IPs parameter is an array of IP addresses that you want to add or remove as custom threat indicators in Microsoft Defender for Endpoint. Each entry should be a valid public IPv4 or IPv6 address (e.g., "8.8.8.8" or "2001:4860:4860::8888"). Private or reserved IP ranges are not supported. You can specify one or more IP addresses as a string array (e.g., @("8.8.8.8", "1.1.1.1")) to target multiple indicators in a single operation.
-token(string, required): OAuth2 access token.-IPs(string[], required): Array of IP addresses.
Example:
Invoke-TiIP -token $token -IPs @("8.8.8.8")
Undo-TiIP -token $token -IPs @("8.8.8.8")Description:
Invoke-TiURL creates URL or domain-based custom threat indicators in Microsoft Defender for Endpoint.
Undo-TiURL deletes URL or domain-based custom threat indicators.
Parameters:
The $token parameter is the OAuth2 access token you receive from the Connect-MDE function. You must call Connect-MDE first and use its output as the -token value for these functions. These tokens typically expire every 60 minutes.
The -URLs parameter is an array of URLs or domain names that you want to add or remove as custom threat indicators in Microsoft Defender for Endpoint. Each entry should be a valid URL or domain string (e.g., "malicious.example.com"). You can specify one or more URLs or domains as a string array (e.g., @("malicious.example.com", "phishing.example.net")) to target multiple indicators in a single operation.
-token(string, required): OAuth2 access token.-URLs(string[], required): Array of URLs or domains.
Example:
Invoke-TiURL -token $token -URLs @("malicious.example.com")
Undo-TiURL -token $token -URLs @("malicious.example.com")Description:
Invoke-UploadLR uploads a script file to the Microsoft Defender for Endpoint Live Response library for later use in automated investigations or manual response.
Parameters:
The $token parameter is the OAuth2 access token you receive from the Connect-MDE function. You must call Connect-MDE first and use its output as the -token value for these functions. These tokens typically expire every 60 minutes.
The -filePath parameter specifies the full path to the script or file you want to upload or retrieve. For upload operations, provide the local path to the file on your system (e.g., "C:\Scripts\MyScript.ps1").
-token(string, required): OAuth2 access token.-filePath(string, required): Path to the script file to upload.
Example:
Invoke-UploadLR -token $token -filePath "C:\Scripts\MyScript.ps1"Description:
Invoke-PutFile pushes a file from the Live Response library to one or more specified devices.
Parameters:
The $token parameter is the OAuth2 access token you receive from the Connect-MDE function. You must call Connect-MDE first and use its output as the -token value for these functions. These tokens typically expire every 60 minutes.
The
6DB6
-fileName parameter specifies the name of the file in the Live Response library that you want to push to devices. This should match the exact file name as it appears in the library, including the file extension (e.g., "MyScript.ps1"). Ensure the file has already been uploaded to the library using the appropriate upload function before referencing it here.
The -DeviceIds parameter is an array of device IDs that uniquely identify the target devices in Microsoft Defender for Endpoint. You can obtain these IDs by running the Get-Machines function and referencing the Id property in the results. Pass one or more device IDs as a string array (e.g., @("deviceId1", "deviceId2")) to target multiple devices in a single operation.
-token(string, required): OAuth2 access token.-fileName(string, required): Name of the file in the library.-DeviceIds(string[], required): Array of device IDs to receive the file.
Example:
Invoke-PutFile -token $token -fileName "MyScript.ps1" -DeviceIds @("<deviceId>")Description:
Invoke-GetFile retrieves a file from one or more specified devices using Live Response.
Parameters:
The $token parameter is the OAuth2 access token you receive from the Connect-MDE function. You must call Connect-MDE first and use its output as the -token value for these functions. These tokens typically expire every 60 minutes.
The -filePath parameter specifies the full path to the script or file you want to upload or retrieve. For upload operations, provide the path to the file on the MDE endpoint. (e.g., "C:\Temp\error.log")
The -DeviceIds parameter is an array of device IDs that uniquely identify the target devices in Microsoft Defender for Endpoint. You can obtain these IDs by running the Get-Machines function and referencing the Id property in the results. Pass one or more device IDs as a string array (e.g., @("deviceId1", "deviceId2")) to target multiple devices in a single operation.
-token(string, required): OAuth2 access token.-filePath(string, required): Path to the file on the device.-DeviceIds(string[], required): Array of device IDs to retrieve the file from.
Example:
Invoke-GetFile -token $token -filePath "C:\Windows\Temp\test.txt" -DeviceIds @("<deviceId>")Description:
Invoke-LRScript executes a Live Response script from the library on one or more specified devices.
Parameters:
The $token parameter is the OAuth2 access token you receive from the Connect-MDE function. You must call Connect-MDE first and use its output as the -token value for these functions. These tokens typically expire every 60 minutes.
The -scriptName parameter specifies the name of the file in the Live Response library that you want to push to devices. This should match the exact file name as it appears in the library, including the file extension (e.g., "MyScript.ps1"). Ensure the file has already been uploaded to the library using the appropriate upload function before referencing it here.
The -DeviceIds parameter is an array of device IDs that uniquely identify the target devices in Microsoft Defender for Endpoint. You can obtain these IDs by running the Get-Machines function and referencing the Id property in the results. Pass one or more device IDs as a string array (e.g., @("deviceId1", "deviceId2")) to target multiple devices in a single operation.
-DeviceIds(string[], required): Array of device IDs to run the script on.-scriptName(string, required): Name of the script in the library.-token(string, required): OAuth2 access token.
Example:
Invoke-LRScript -DeviceIds @("<deviceId>") -scriptName "MyScript.ps1" -token $tokenDescription:
Get-MachineActionStatus checks the status of a machine action by its action ID.
Parameters:
The $token parameter is the OAuth2 access token you receive from the Connect-MDE function. You must call Connect-MDE first and use its output as the -token value for these functions. These tokens typically expire every 60 minutes.
The -machineActionId parameter is the unique identifier for a specific machine action in Microsoft Defender for Endpoint. You can obtain this value from the output of functions such as Get-Actions or after initiating an action (e.g., isolation, investigation package collection) and waiting for the response. Use this ID to query the status or retrieve the output of that particular action.
-machineActionId(string, required): The machineActionId to check.-token(string, required): OAuth2 access token.
Example:
Get-MachineActionStatus -machineActionId "<machineActionId>" -token $tokenDescription:
Get-LiveResponseOutput downloads and parses the output of a Live Response script for a given machine action.
Parameters:
The $token parameter is the OAuth2 access token you receive from the Connect-MDE function. You must call Connect-MDE first and use its output as the -token value for these functions. These tokens typically expire every 60 minutes.
The -machineActionId parameter is the unique identifier for a specific machine action in Microsoft Defender for Endpoint. You can obtain this value from the output of functions such as Get-Actions or after initiating an action (e.g., isolation, investigation package collection) and waiting for the response. Use this ID to query the status or retrieve the output of that particular action.
-machineActionId(string, required): The machineActionId for the Live Response script.-token(string, required): OAuth2 access token.
Example:
Get-LiveResponseOutput -machineActionId "<machineActionId>" -token $tokenTip:
For all functions, ensure you have a valid$tokenfromConnect-MDEand the required permissions in Azure/MDE.