MDEAutomator is designed to support incident response activities in Microsoft Defender for Endpoint (MDE) environments. It leverages Azure serverless componets in a private virtual network and Federated App Registration + UMI (FIC/Workload Identity) authentication for enhanced security.
-
MDEAutomator PowerShell Module
A comprehensive PowerShell module providing cmdlets for Microsoft Defender for Endpoint operations, including advanced authentication, profile management, live response automation, response action orchestration, custom detection management, advanced hunting query execution, and threat indicator lifecycle management. -
MDEAutomator
A serverless orchestration platform for large-scale response action automation, distributed Live Response command execution across endpoint fleets, and programmatic deployment of PowerShell configuration scripts to Microsoft Defender for Endpoint managed devices.Dispatcher- Isolate Device, Collect Investigation Package, Run Antivirus Scan, Restrict App Execution, Stop & Quarantine File
Orchestator- Run Live Response Script, Collect File, Put File, Upload file to Live Response Library
Profiles- Active & Passive
-
Threat Intelligence Manager
A threat indicator orchestration system providing automated lifecycle management for diverse indicator types including hashes, network infrastructure indicators (IPs, URLs, domains), and code signing certificates within Microsoft Defender for Endpoint. Features streamlined Custom Detection authoring and management, automated backup of existing Custom Detections, and a content library. -
Action Manager
Provides comprehensive reporting on MDE machine actions and includes a safety switch to cancel all pending actions in the tenant. -
Hunt Manager
An advanced threat hunting automation engine supporting both on-demand and scheduled hunting operations, with sophisticated query management, automated result processing, and native Azure Blob Storage integration. -
Incident Manager
A streamlined incident portal for managing Microsoft Defender XDR incidents, featuring integrated comment tracking and downloadable incident summaries powered by Azure OpenAI.
- 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
- Secretless App Registration/UMI auth + manual
$SPNSECRETflexibility - Ability to deliver key configuration settings via PowerShell that are not available in Endpoint Security Profiles
- Custom Detection syncronization with Azure Storage & simplified authoring experience
- Hunt Manager offers on-demand & programatic Threat Hunting via Graph
- Convenient upload of endpoint forensic packages/files to Azure Storage
- Simplified management of Defender incidents
-
Application Insights
-
Azure Function (PowerShell)
-
Azure App Service
-
App Service Plan(s)
-
Azure Storage Account
-
Azure OpenAI
-
User Managed Identity
-
Log Analytics Workspace
-
Azure Monitor Private Link Scope
-
Virtual Network
-
Private DNS Zone(s)
-
Network Security Group(s)
MDEAutomator Estimated Monthly Azure Cost: ~$220 USD
-
Click the "Deploy to Azure" button below.
Note: You must specify a
envparameter to make the deployment globally unique. Example: "dev", "test", etc. -
Note the name of the User-Managed Identity that is created by the deployment.
-
Provision the App Registration (Service Principal) in Entra ID.
Note: Select Multitenant if you plan to leverage this App Registration to service multiple tenants.
-
Configure & Consent to the required API permissions
Required WindowsDefenderATP API Permissions:
- AdvancedQuery.Read.All
- Alert.Read.All
- File.Read.All
- Ip.Read.All
- Library.Manage
- Machine.CollectForensics
- Machine.Isolate
- Machine.StopAndQuarantine
- Machine.LiveResponse
- Machine.Offboard
- Machine.ReadWrite.All
- Machine.RestrictExecution
- Machine.Scan
- Ti.ReadWrite.All
- User.Read.All
Required Graph API Permissions:
- CustomDetection.ReadWrite.All
- ThreatHunting.Read.All
- ThreatIndicators.ReadWrite.OwnedBy
- SecurityIncident.ReadWrite.All
-
Link the User Managed Identity to the App Registration.
Add MDEAutomator's user-managed identity as a Federated Credential of the App Registration.
-
Save the App Registration Client ID in the
SPNIDAzure Function App Setting. -
Enable Unsigned Script Execution & Live Response for Servers and Workstations in MDE Advanced Settings. (See Security Notes section of this README)
Below are example usage patterns for the MDEAutomator PowerShell module.
# Import MDEAutomator module from Git repo source
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# Using direct secret to authenticate
$secureSecret = Read-Host "Enter Secret" -AsSecureString
$token = Connect-MDE -SpnId "<appId>" -SpnSecret $secureSecret
# 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.
Critical! Configure Authentication on the Azure App Service so Entra ID auth is required before MDEAutomator's control panel.
- 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.
MDEAutomator leverages a Azure Storage Account to save investigation packages zips & file gzips collected from MDE endpoints, AutoHunt JSON output, and Custom Detection JSON's.
Azure Portal:
Azure Storage Explorer
Download Azure Storage Explorer
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/UMI Federation or $SpnSecret.
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. Always store and handle this secret securely.
The -ManagedIdentityId parameter specifies the Client ID of the User Managed Identity associated with MDEAutomator.
The -TenantId parameter is the Entra ID 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.-ManagedIdentityId(string, optional): The Client ID of the MDEAutomator User-Managed Identity.-TenantId(string, optional): Entra ID Tenant ID or default to home tenant.
Example:
# Using UMI + Federated App Registration
$token = Connect-MDE -SpnId "<SPNappId>" -ManagedIdentityId "<UMIappId>"
# 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(securestring, required): OAuth2 access token. Obtain this fromConnect-MDE.
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(securestring, required): OAuth2 access token. Obtain this fromConnect-MDE.-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(securestring, required): OAuth2 access token. Obtain this fromConnect-MDE.-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(securestring, required): OAuth2 access token. Obtain this fromConnect-MDE.-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(securestring, required): OAuth2 access token. Obtain this fromConnect-MDE.-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(securestring, required): OAuth2 access token. Obtain this fromConnect-MDE.-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(securestring, required): OAuth2 access token. Obtain this fromConnect-MDE.-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(securestring, required): OAuth2 access token. Obtain this fromConnect-MDE.-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(securestring, required): OAuth2 access token. Obtain this fromConnect-MDE.-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").
The -fileContent parameter can be leverage to upload files as a byte array. When this option is used -TargetFileName is always required.
The -TargetFileName parameter specifies the name of the file that will be uploaded to the Live Response Library.
-token(securestring, required): OAuth2 access token. Obtain this fromConnect-MDE.-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 -fileName parameter specifies the name of the file in the Live Response library that you want to push to devices. This should match the
F438
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(securestring, required): OAuth2 access token. Obtain this fromConnect-MDE.-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(securestring, required): OAuth2 access token. Obtain this fromConnect-MDE.-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(securestring, required): OAuth2 access token. Obtain this fromConnect-MDE.
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(securestring, required): OAuth2 access token. Obtain this fromConnect-MDE.
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(securestring, required): OAuth2 access token. Obtain this fromConnect-MDE.
Example:
Get-LiveResponseOutput -machineActionId "<machineActionId>" -token $tokenDescription:
Invoke-StopAndQuarantineFile issues a Stop and Quarantine File action on one or more devices in Microsoft Defender for Endpoint. This action attempts to stop the specified file (by SHA1 hash) on all Active and onboarded devices.
Parameters:
-token(securestring, required): OAuth2 access token. Obtain this fromConnect-MDE.-Sha1(string, required): The SHA1 hash of the file to stop and quarantine.
Example:
Invoke-StopAndQuarantineFile -token $token -Sha1 "<sha1hash>"Description:
Get-Indicators retrieves all custom threat indicators (IOCs) from Microsoft Defender for Endpoint, including file hashes, IPs, URLs, and certificates.
Parameters:
-token(securestring, required): OAuth2 access token. Obtain this fromConnect-MDE.
Example:
$indicators = Get-Indicators -token $token
$indicators | Format-Table Id, IndicatorValue, IndicatorType, ActionDescription:
Get-FileInfo retrieves detailed information about one or more files in Microsoft Defender for Endpoint using their SHA1 hashes. For each hash, it returns file metadata, related alerts, machines, and statistics.
Parameters:
-token(securestring, required): OAuth2 access token. Obtain this fromConnect-MDE.-Sha1s(string[], required): Array of SHA1 hashes to query.
Example:
$fileInfo = Get-FileInfo -token $token -Sha1s @("<sha1hash1>", "<sha1hash2>")
$fileInfo | ConvertTo-Json -Depth 5Description:
Get-IPInfo retrieves information about one or more IP addresses from Microsoft Defender for Endpoint. For each IP, it returns related alerts, statistics, and advanced hunting results.
Parameters:
-token(securestring, required): OAuth2 access token. Obtain this fromConnect-MDE.-IPs(string[], required): Array of IP addresses to query.
Example:
$ipInfo = Get-IPInfo -token $token -IPs @("8.8.8.8", "1.2.3.4")
$ipInfo | ConvertTo-Json -Depth 5Description:
Get-URLInfo retrieves information about one or more URLs or domains from Microsoft Defender for Endpoint. For each URL or domain, it returns related alerts, statistics, machines, and advanced hunting results.
Parameters:
-token(securestring, required): OAuth2 access token. Obtain this fromConnect-MDE.-URLs(string[], required): Array of URLs or domains to query.
Example:
$urlInfo = Get-URLInfo -token $token -URLs @("malicious.example.com", "phishing.example.net")
$urlInfo | ConvertTo-Json -Depth 5Description:
Get-LoggedInUsers retrieves the list of users currently or recently logged in to one or more devices in Microsoft Defender for Endpoint. For each device, it returns details such as account name, domain, logon type, session info, and last seen time.
Parameters:
-token(securestring, required): OAuth2 access token. Obtain this fromConnect-MDE.-DeviceIds(string[], required): Array of device IDs to query. UseGet-Machinesto obtain IDs.
Example:
$deviceIds = Get-Machines -token $token | Select-Object -ExpandProperty Id
$users = Get-LoggedInUsers -token $token -DeviceIds $deviceIds
$users | Format-Table DeviceId, AccountName, LogonTime, LastSeenTip:
For most functions, ensure you have a valid$tokenfromConnect-MDEand the required permissions in Azure/MDE.
Description:
Invoke-AdvancedHunting runs one or more KQL queries against Microsoft Defender for Endpoint’s Advanced Hunting API using Microsoft Graph. It returns the raw results for each query.
It leverages a randomization technique to load balance between the v1.0 & Beta API endpoint.
Requirements:
You must be connected to Microsoft Graph using Connect-MDE before running this command.
Parameters:
-Queries(string[], required): String Array of KQL queries to execute. Each query string should be valid KQL syntax.
Example:
$queries = @(
"DeviceEvents | take 5",
"AlertInfo | where Severity == 'High'"
)
$results = Invoke-AdvancedHunting -Queries $queries
$results | ConvertTo-Json -Depth 5Description:
Invoke-MachineOffboard offboards one or more devices from Microsoft Defender for Endpoint. This action removes the device from active management and monitoring in MDE. Offboarding is typically used when a device is being decommissioned or is no longer required to be managed by Defender for Endpoint.
Warning:
The action is permanant.
Parameters:
-token(securestring, required): OAuth2 access token. Obtain this fromConnect-MDE.-DeviceIds(string[], required): Array of device IDs to offboard. UseGet-Machinesto obtain IDs.
Example:
$deviceIds = Get-Machines -token $token | Select-Object -ExpandProperty Id
Invoke-MachineOffboard -token $token -DeviceIds $deviceIdsDescription:
Get-DetectionRules retrieves all Microsoft Defender Custom Detection rules via Microsoft Graph API as objects.
Requirements:
You must be connected to Microsoft Graph using Connect-MDE before running this command.
Parameters:
None.
Example:
$rules = Get-DetectionRules
$rules | ConvertTo-Json -Depth 50
Write-Host $rules Description:
Install-DetectionRule installs a new Custom Detection rule in Microsoft Defender via Microsoft Graph API. Accepts a PowerShell object representing the rule definition.
Requirements:
You must be connected to Microsoft Graph using Connect-MDE before running this command.
Parameters:
-jsonContent(PSCustomObject, required): The Custom Detection rule definition as a PowerShell object.
Example:
$jsonContent = Get-Content .\MyDetectionRule.json | ConvertFrom-Json
Install-DetectionRule -jsonContent $jsonContentDescription:
Update-DetectionRule updates an existing Custom Detection rule in Microsoft Defender via Microsoft Graph API. Accepts the rule ID and the updated rule definition.
Requirements:
You must be connected to Microsoft Graph using Connect-MDE before running this command.
Parameters:
-RuleId(string, required): The ID of the Custom Detection rule to update.-jsonContent(PSCustomObject, required): The updated Custom Detection rule definition as a PowerShell object.
Example:
$jsonContent = Get-Content .\UpdatedDetectionRule.json | ConvertFrom-Json
Update-DetectionRule -RuleId $ruleId -jsonContent $jsonContentDescription:
Undo-DetectionRule deletes an existing Custom Detection rule in Microsoft Defender via Microsoft Graph API. Accepts the rule ID of the detection rule to remove.
Requirements:
You must be connected to Microsoft Graph using Connect-MDE before running this command.
Parameters:
-RuleId(string, required): The ID of the Custom Detection rule to delete.
Example:
Undo-DetectionRule -RuleId $ruleIdDescription:
Get-Incidents retrieves security incidents from Microsoft Defender for Endpoint via Microsoft Graph API. Returns up to 500 of the most recent incidents, filtering out informational severity incidents. Uses pagination with a 10-page limit for performance.
Requirements:
You must be connected to Microsoft Graph using Connect-MDE before running this command.
Parameters:
None.
Example:
$incidents = Get-Incidents
$incidents | Format-Table Id, DisplayName, Status, Severity, CreatedDateTimeDescription:
Get-Incident retrieves detailed information about a specific security incident from Microsoft Defender for Endpoint via Microsoft Graph API. Returns comprehensive incident details including all associated alerts and their evidence objects (device, file, process, registry, IP, URL, user, mailbox, and cloud application evidence).
Requirements:
You must be connected to Microsoft Graph using Connect-MDE before running this command.
Parameters:
-IncidentId(string, required): The ID of the incident to retrieve detailed information for.
Example:
$incident = Get-Incident -IncidentId "881109"
$incident | ConvertTo-Json -Depth 10Description:
Get-IncidentAlerts retrieves all alerts associated with a specific security incident from Microsoft Defender for Endpoint via Microsoft Graph API. Returns detailed alert information including evidence and related entities.
Requirements:
You must be connected to Microsoft Graph using Connect-MDE before running this command.
Parameters:
-IncidentId(string, required): The ID of the incident to retrieve alerts for.
Example:
$alerts = Get-IncidentAlerts -IncidentId "881109"
$alerts | Format-Table Id, Title, Severity, Status, CreatedDateTimeDescription:
Update-Incident updates the properties of a security incident in Microsoft Defender for Endpoint via Microsoft Graph API. Allows modification of incident status, assignment, classification, determination, custom tags, description, display name, severity, summary, and resolving comments.
Requirements:
You must be connected to Microsoft Graph using Connect-MDE before running this command.
Parameters:
-IncidentId(string, required): The ID of the incident to update.-Status(string, optional): The status of the incident. Valid values:active,resolved,redirected.-AssignedTo(string, optional): Owner of the incident (free editable text).-Classification(string, optional): The classification of the incident. Valid values:unknown,falsePositive,truePositive,informationalExpectedActivity.-Determination(string, optional): The determination of the incident. Valid values:unknown,apt,malware,securityPersonnel,securityTesting,unwantedSoftware,other,multiStagedAttack,compromisedAccount,phishing,maliciousUserActivity,notMalicious,notEnoughDataToValidate,confirmedUserActivity,lineOfBusinessApplication.-CustomTags(string[], optional): Array of custom tags associated with the incident.-Description(string, optional): Description of the incident.-DisplayName(string, optional): The incident name.-Severity(string, optional): The severity of the incident. Valid values:unknown,informational,low,medium,high.-ResolvingComment(string, optional): User input that explains the resolution of the incident and the classification choice.-Summary(string, optional): The overview of an attack with details of what occurred, impacted assets, and the type of attack.
Example:
Update-Incident -IncidentId "881109" -Status "resolved" -Classification "truePositive" -Determination "malware" -ResolvingComment "Malware detected and quarantined successfully"Description:
Update-IncidentComment adds a comment to a security incident in Microsoft Defender for Endpoint via Microsoft Graph API. Useful for documenting investigation progress and findings.
Requirements:
You must be connected to Microsoft Graph using Connect-MDE before running this command.
Parameters:
-IncidentId(string, required): The ID of the incident to add a comment to.-Comment(string, required): The comment text to add to the incident.
Example:
Update-IncidentComment -IncidentId "881109" -Comment "Investigation completed. No further action required."