MDEAutomator

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.

Core Components

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

Key Features

• 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 $SPNSECRET flexibility
• 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

Azure Resources Deployed

• Application Insights
• Azure Function
• App Service Plan (EP1)
• Azure Storage
• Azure Key Vault
• User Managed Identity

MDEAutomator Estimated Monthly Azure Cost: ~$180 USD

Prerequisites

1. Create Entra ID Service Principal (App Registration)
   

   Note: Select Multitenant if you plan to leverage this to service multiple tenants.

2. Add required API permissions to the Service Principal
   

   Required WindowsDefenderATP API Permissions:

   • AdvancedQuery.Read.All
   • Alert.Read.All
   • File.Read.All
   • Ip.Read.All
   • Library.Manage
   • Machine.CollectForensics
   • Machine.Isolate
   • Machine.LiveResponse
   • Machine.Offboard
   • Machine.ReadWrite.All
   • Machine.RestrictExecution
   • Machine.Scan
   • Ti.ReadWrite

3. Generate SPN Secret (securely store for post-deployment configuration)
   

4. Enable Unsigned Script Execution & Live Response for Servers and Workstations in MDE Advanced Settings. (See Security Notes section of this README)
   

Deployment

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

2. Add "SPNSECRET" to Azure Key Vault

   Create a secret named "SPNSECRET" with the value generated during SPN provisioning
   

3. Configure your front-end application to call the Function Apps

Integration

• Calling Azure Functions via HTTP
• Example Requests
• How to customize and republish

Use Cases

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

Usage

Below are example usage patterns for the MDEAutomator PowerShell module.

Installing & Importing

# 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

Authentication Examples

# Option 1: Using SecureString for SPN Secret and specifying TenantId
$token = Connect-MDE -SpnId "<AppId>" -SpnSecret (Read-Host -AsSecureString) -TenantId "<TenantId>"

# Option 2: Using SecureString for SPN Secret (defaults to home tenant)
$token = Connect-MDE -SpnId "<AppId>" -SpnSecret (Read-Host -AsSecureString)

# Option 3: Retrieving SPNSECRET from Azure Key Vault (requires Key Vault access)
$token = Connect-MDE -SpnId "<AppId>" -keyVaultName "<KeyVaultName>"

# Option 4: Retrieving SPNSECRET from Azure Key Vault and specifying TenantId
$token = Connect-MDE -SpnId "<AppId>" -keyVaultName "<KeyVaultName>" -TenantId "<TenantId>"

Common Operations

# 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

Response Actions

# Isolate endpoints from the network
Invoke-MachineIsolation -token $token -DeviceIds @("<DeviceId>")

# Release endpoints from isolation
Undo-MachineIsolation -token $token -DeviceIds @("<DeviceId>")

# Contain unmanaged endpoints
Invoke-ContainDevice -token $token -DeviceIds @("<DeviceId>")

# Release endpoints from containment
Undo-ContainDevice -token $token -DeviceIds @("<DeviceId>")

# Restrict application/code execution on a device
Invoke-RestrictAppExecution -token $token -DeviceIds "<DeviceId>"

# Remove application/code execution restriction
Undo-RestrictAppExecution -token $token -DeviceIds @("<DeviceId>")

Threat Indicator Management

# Block a file hash (SHA256) as a custom threat indicator
Invoke-TiFile -token $token -Sha256s @("<SHA256>")

# Remove a file hash threat indicator
Undo-TiFile -token $token -Sha256s @("<SHA256>")

# Block a file hash (SHA1) as a custom threat indicator
Invoke-TiFile -token $token -Sha1s @("<SHA1>")

# Remove a file hash threat indicator
Undo-TiFile -token $token -Sha1s @("<SHA1>")

# Block an IP address as a threat indicator
Invoke-TiIP -token $token -IPs @("<IPAddress>")

# Remove an IP address threat indicator
Undo-TiIP -token $token -IPs @("<IPAddress>")

# Block a domain or URL as a threat indicator
Invoke-TiURL -token $token -URLs @("<DomainOrUrl>")

# Remove a domain or URL threat indicator
Undo-TiURL -token $token -URLs @("<DomainOrUrl>")

# Block a certificate thumbprint as a threat indicator
Invoke-TiCert -token $token -Sha1s @("<SHA1Thumbprint>")

# Remove a certificate thumbprint threat indicator
Undo-TiCert -token $token -Sha1s @("<SHA1Thumbprint>")

Security Notes

⚠️ 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.

Secret Management

• Azure Key Vault is strongly recommended for storing secrets in all production scenarios.

Managed Identities

• User-managed identity support is on the roadmap. This will require additional refactoring to support multi-tenant deployments.

PowerShell Security Hygiene

• 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 the payloads subfolder 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.

---

---

Disclaimer

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.

---

Contributing

We welcome contributions! Please open an issue or submit a pull request on GitHub.

---

Acknowledgements

Made possible by the BlueVoyant Digital Forensics & Incident Response team. For assistance, contact incident@bluevoyant.com.

References

• VS Code Deployment Guide
• Azure CLI Deployment Guide
• Azure PowerShell Deployment Guide
• Azure Cloud Shell Deployment Guide
• GitHub Actions Deployment Guide