Using the Microsoft Defender for Endpoint Files API to Validate Malware Hashes
Introduction Security advisories frequently include file hashes (SHA-1 or SHA-256) as indicators of compromise (IoCs). Microsoft Defender for Endpoint (MDE) exposes a Files API that lets SecOps quickly look up Microsoft’s verdict and metadata for a given hash. This enables rapid assessment—whether a file is classified as Malicious, Suspicious, Clean, or Unknown—and helps analysts decide the next response action without needing to download or execute the sample. What is the Files API in MDE and why is it used in Security Operations? The Files API is part of the Defender for Endpoint REST APIs that returns a file profile by hash identifier. Analysts use it to: • Validate whether Microsoft has a global verdict for a hash named in an advisory. • Retrieve telemetry such as global prevalence and first/last observed times to gauge risk and spread. • Pivot to related alerts and devices when needed. This lookup shortens triage time and avoids unnecessary handling of potentially dangerous samples. Prerequisites To call the Files API using application (client credentials) context, you need: A Microsoft Entra ID App Registration (Web app / service). API permissions on the WindowsDefenderATP resource (Microsoft Defender for Endpoint). Minimum: File.Read.All (Application). Admin consent granted for the permissions. Network access to the MDE API endpoint (region-based base URL) and the Microsoft identity platform (OAuth 2.0). Tip: For interactive testing, you can also use the API Explorer in the Microsoft Defender portal under Partners & APIs, which runs requests under your user context and RBAC scope. How to use the Files API via PowerShell 1) Acquire an OAuth token from the Microsoft identity platform using your app’s client ID and secret with the .default scope for the Defender API. 2) Send an HTTP GET request to the Files endpoint with the hash (SHA-1 or SHA-256) as the identifier. 3) Inspect the JSON response field "fileClassification" and other metadata (globalPrevalence, first/last observed). 4) Use the verdict to decide next actions (e.g., create an Indicator to block, hunt in Advanced Hunting, or open related alerts). Actual Script ===== STEP 1: Get OAuth Token (MDE v1) ===== $tenantId = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" $appId = "xxxxxxxxxxxxxxxxxxxxxxxxxxx" $appSecret = "xxxxxxxxxxxxxxxxxxxxxxxxxxx" # update with your tenant and app values $tokenUri = "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token" $body = @{ client_id = $appId scope = "https://api.securitycenter.microsoft.com/.default" client_secret = $appSecret grant_type = "client_credentials" } $tokenResponse = Invoke-RestMethod -Uri $tokenUri -Method Post -Body $body -ContentType "application/x-www-form-urlencoded" $token = $tokenResponse.access_token # ===== STEP 2: Call MDE v1 Files API ===== $hash = "97bf5e1a903a978b2281496e0a897688e9d8e6f981238cf91e39bae20390defe" # Replace with your actual hash values. $uri = "https://api.securitycenter.microsoft.com/api/v1.0/files/$hash" try { $response = Invoke-RestMethod -Uri $uri -Headers @{ Authorization = "Bearer $token" Accept = "application/json" } -Method Get } catch { Write-Error "API call failed: $($_.Exception.Message)" if ($_.ErrorDetails.Message) { Write-Host $_.ErrorDetails.Message } return } switch ($response.fileClassification) { "Malicious" { Write-Host "MDE recognises this hash as MALICIOUS. Threat Name: $($response.threatName)" -ForegroundColor Red } "Suspicious" { Write-Host "MDE recognises this hash as SUSPICIOUS." -ForegroundColor Yellow } "Clean" { Write-Host "MDE recognises this hash as CLEAN." -ForegroundColor Green } default { Write-Host "MDE does NOT have a signature for this hash (Unknown)." -ForegroundColor Gray } } $response | ConvertTo-Json -Depth 5 Script Explanation Token acquisition: Uses OAuth 2.0 client credentials flow to obtain an access token; scope targets Defender for Endpoint API. Endpoint call: Builds a GET request to the Files endpoint with the hash identifier. Error handling: Catches HTTP errors and prints server-provided details if available. Verdict mapping: Reads the fileClassification field and prints a color-coded verdict (Malicious, Suspicious, Clean, Unknown). Response output: Prints the full JSON for deeper analysis and logging. Recommended Inputs The Files endpoint accepts SHA-1 or SHA-256 identifiers; ensure you pass the correct hash type. Consider using certificate credentials or managed identity instead of client secrets for production automation. Sample Output API Explorer - Other Option to query File API The Microsoft Defender for Endpoint API Explorer is a tool that helps you explore various Defender for Endpoint APIs interactively. The API Explorer makes it easy to construct and do API queries, test, and send requests for any available Defender for Endpoint API endpoint. Use the API Explorer to take actions or find data that might not yet be available through the user interface. The tool is useful during app development. It allows you to perform API queries that respect your user access settings, reducing the need to generate access tokens. You can also use the tool to explore the gallery of sample queries, copy result code samples, and generate debug information. With the API Explorer, you can: Run requests for any method and see responses in real-time. Quickly browse through the API samples and learn what parameters they support. Make API calls with ease; no need to authenticate beyond the management portal signin. Access API Explorer From the left navigation menu, select Partners & APIs > API Explorer. Supported APIs API Explorer supports all the APIs offered by Defender for Endpoint. The list of supported APIs is available in the APIs documentation. Get started with the API Explorer In the left pane, there's a list of sample requests that you can use. Follow the links and click Run query. Some of the samples may require specifying a parameter in the URL, for example, {File Hash}. Permissions Required You need to log in with an account that has appropriate RBAC roles in Microsoft Defender for Endpoint. API Explorer enforces the same role-based access control (RBAC) as the portal: Security Administrator or Global Administrator for high-privilege actions (e.g., offboarding a device, submitting indicators). Lower roles (e.g., Security Reader) can only run read-only queries like Get file information or Get alerts. No additional API permissions or app registration are needed because requests run under your user context. Conclusion The MDE Files API gives SecOps an immediate way to validate hashes from advisories and threat feeds, reducing time-to-triage and enabling consistent response. When a hash is classified as Malicious or Suspicious, teams can move directly to containment (e.g., creating an Indicator to block). When it is Clean or Unknown, analysts can pivot to hunting, sandboxing, or further intelligence before acting. Integrating this lookup into runbooks helps security operations quickly and safely respond to emerging threats. References Get file information API: https://learn.microsoft.com/en-us/defender-endpoint/api/get-file-information Supported MDE APIs (Endpoint URI & versioning): https://learn.microsoft.com/en-us/defender-endpoint/api/exposed-apis-list Access the Microsoft Defender for Endpoint APIs (intro & app context): https://learn.microsoft.com/en-us/defender-endpoint/api/apis-intro Create an app to access MDE without a user (app registration & permissions): https://learn.microsoft.com/en-us/defender-endpoint/api/exposed-apis-create-app-webapp API Explorer: https://learn.microsoft.com/en-us/defender-endpoint/api/api-explorerMDE for Non‑Persistent VDI — Implementation Guide & Best Practices.
1. Overview: Microsoft Defender for Endpoint (MDE) for Non‑Persistent VDI Non‑persistent VDI instances are reset or reprovisioned frequently. To ensure immediate protection and clean device inventory, MDE provides a dedicated onboarding path that calculates a persistent device ID and onboard early in the boot process. Key considerations: Use the VDI onboarding package and choose the single‑entry method (recommended) to avoid duplicate devices when hosts are recreated with the same name. Place the onboarding script in the golden image but ensure it executes only on child VMs (first boot) after the final hostname is assigned and the last reboot completes. Never fully onboard or boot the golden/template/replica image into production; if it happens, offboard and clean registry artifacts before resealing. Consider enabling the portal feature “Hide potential duplicate device records” to reduce inventory noise during transition periods. 2. Stage the scripts in the Golden Image (do NOT onboard the image) Goal: Ensure early, reliable onboarding of pooled VDI instances without tattooing the master image. Download the Windows onboarding package (Deployment method: VDI onboarding scripts for non‑persistent endpoints). Extract and copy the files to: C\Windows\System32\GroupPolicy\Machine\Scripts\Startup Configure Local/Domain GPO to run the PowerShell script at startup (SYSTEM, highest privileges). For single‑entry, add Onboard-NonPersistentMachine.ps1 on the PowerShell Scripts tab. Ensure the script runs only after final hostname and the last reboot in your provisioning flow to prevent duplicate objects. Example (Domain GPO scheduled task at startup as SYSTEM): Program/Script: C\Windows\System32\WindowsPowerShell\v1.0\powershell.exe Arguments: -ExecutionPolicy Bypass -File \srvshare\onboard\Onboard-NonPersistentMachine.ps1 3. Never Onboard the Golden/Template/Replica VM If the golden image was accidentally onboarded (Sense service started), you must offboard and clean before resealing: sc query sense del "C:\ProgramData\Microsoft\Windows Defender Advanced Threat Protection\Cyber\*.*" /f /s /q reg delete "HKLM\SOFTWARE\Microsoft\Windows Advanced Threat Protection" /v senseGuid /f Run the official offboarding script for your tenant before cleanup, when available. 4. (Optional) Tag Devices Automatically from the Image Tags simplify scoping of device groups and policies. Add a DeviceTagging registry value during image build: reg add "HKLM\SOFTWARE\Policies\Microsoft\Windows Advanced Threat Protection\DeviceTagging" /v Group /t REG_SZ /d "VDI-NonPersistent" /f Tag appears after device info refresh; a reboot accelerates reporting. 5. Performance & AV Configuration for VDI (Important) 5.1 Shared Security Intelligence & Cache Maintenance Purpose: Reduce CPU and disk spikes at sign‑in by offloading unpackaging of definitions to a shared source and by pre‑running cache maintenance on the master image. Step‑by‑step GPO configuration: Create a secure UNC share for definition packages (e.g., \srvshare\WDAV-Update) and grant read to VDI computer accounts. GPO → Computer Configuration → Administrative Templates → Windows Components → Microsoft Defender Antivirus → Security Intelligence Updates → Enable “Define security intelligence location for VDI clients” and set \srvshare\WDAV-Update. In the same node, set update cadence (daily time) and enable randomization to avoid I/O storms. PowerShell examples: Set-MpPreference -SignatureUpdateInterval 4 Set-MpPreference -SignatureFallbackOrder "InternalDefinitionUpdateServer|MicrosoftUpdateServer" Run Windows Defender Cache Maintenance on the golden image before sealing: schtasks /Run /TN "\Microsoft\Windows\Windows Defender\Windows Defender Cache Maintenance" 5.2 FSLogix Exclusions Why exclusions matter: FSLogix mounts user profiles as VHD/VHDX files. Scanning these at attach/detach causes logon delays, black screens, and app launch slowness. Paths and extensions to exclude: %TEMP%\*.VHD %TEMP%\*.VHDX %Windir%\TEMP\*.VHD %Windir%\TEMP\*.VHDX \\<storage>\<share>\*.VHD \\<storage>\<share>\*.VHDX \\<storage>\<share>\*.VHD.lock \\<storage>\<share>\*.VHD.meta \\<storage>\<share>\*.VHD.metadata \\<storage>\<share>\*.VHDX.lock \\<storage>\<share>\*.VHDX.meta \\<storage>\<share>\*.VHDX.metadata GPO: Computer Configuration → Administrative Templates → Windows Components → Microsoft Defender Antivirus → Exclusions (File/Folder and Extension). PowerShell examples: Add-MpPreference -ExclusionExtension VHD,VHDX Add-MpPreference -ExclusionPath "C:\ProgramData\FSLogix","\\storage\fslogix-share\*.VHD*" 5.3 General Scan Posture Real‑time & cloud‑delivered protection (GPO): Enable Real‑time protection, Cloud‑delivered protection, Join MAPS, and “Block at first sight.” Scheduled scans (GPO): Daily Quick Scan (e.g., 02:00) with randomization window. Weekly Full Scan (e.g., Sunday 03:00). Consider “Start the scheduled scan only when computer is on but not in use” to reduce user impact. CPU throttling settings: Set-MpPreference -ScanAvgCPULoadFactor 30 # 5..100 (0 = no throttling) Additional scheduling/throttling options (Intune/Policy CSP as applicable): ScanOnlyIfIdleEnabled = True DisableCpuThrottleOnIdleScans = True ThrottleForScheduledScanOnly = True EnableLowCPUPriority = True Validation commands: Get-MpPreference | fl ScanAvgCPULoadFactor,ScanScheduleQuickScanTime,SignatureUpdateInterval Get-MpComputerStatus | fl AMServiceEnabled,AntivirusSignatureVersion,RealTimeProtectionEnabled 6. Validate Onboarding After first boot of a pooled VM, verify device appears in Defender portal (Assets → Devices). For single‑entry method, reboot/redeploy a few instances with the same hostname and confirm one device object is reused. Optionally enable “Hide potential duplicate device records” (Settings → Endpoints → Advanced features). This is like only filtering the view of Devices list does actual remove the records from the MDE portal. Run a detection test if needed (per Microsoft guidance) to verify sensor connectivity. 7. Quick Checklist — Build Step Download VDI onboarding package from Defender portal. Copy scripts to Startup folder in golden image; configure GPO/Task to run PS1 at boot as SYSTEM. Do NOT onboard/boot the golden image into production; if it happens, offboard + clean senseGuid & Cyber cache. (Optional) Set DeviceTagging registry value for scoping (e.g., VDI-NonPersistent). Configure Shared Security Intelligence path; schedule updates; run Cache Maintenance on master image. Apply FSLogix AV exclusions (paths + extensions). Set scan posture (RTP + cloud, schedules, CPU throttling). Validate onboarding behavior and inventory cleanliness. 8. Summary & Best Practices Checklist for golden image: Script staged, not executed on master; executes only on child VMs at final boot stage. Shared Security Intelligence path configured; cache maintenance pre-run. FSLogix exclusions present prior to first user logon. RTP and cloud protection enabled; scans scheduled with randomization; CPU load factor tuned. Common pitfalls & fixes: Golden image onboarded → Offboard + clean registry/cache; reseal. Script runs before final hostname → Duplicate device records. Delay script until last reboot/final rename. No exclusions for FSLogix → Long logons/black screens. Add VHD/VHDX exclusions and share paths. Simultaneous scans across hosts → Enable randomization; schedule during off‑hours. References Onboard non‑persistent VDI devices: https://learn.microsoft.com/en-us/defender-endpoint/configure-endpoints-vdi Onboard Windows devices in Azure Virtual Desktop: https://learn.microsoft.com/en-us/defender-endpoint/onboard-windows-multi-session-device Configure Microsoft Defender Antivirus on RDS/VDI: https://learn.microsoft.com/en-us/defender-endpoint/deployment-vdi-microsoft-defender-antivirus FSLogix prerequisites (AV exclusions): https://learn.microsoft.com/en-us/fslogix/overview-prerequisites Configure AV exclusions (file/extension/folder): https://learn.microsoft.com/en-us/defender-endpoint/configure-extension-file-exclusions-microsoft-defender-antivirus Create and manage device tags: https://learn.microsoft.com/en-us/defender-endpoint/machine-tags Advanced features (hide duplicate records): https://learn.microsoft.com/en-us/defender-endpoint/advanced-features Schedule antivirus scans using Group Policy: https://learn.microsoft.com/en-us/defender-endpoint/schedule-antivirus-scans-group-policy Troubleshoot MDAV scan issues (CPU throttling, idle scans): https://learn.microsoft.com/en-us/defender-endpoint/troubleshoot-mdav-scan-issuesUpdate Coverage Workbook in Microsoft Defender for Cloud to Include Defender for AI Plan status
Option 1: Update the Existing Coverage Workbook Enhance the current workbook by adding a query that checks Defender for AI plan enablement across subscriptions. Steps Open the Coverage Workbook in Defender for Cloud. Edit the workbook and update the query section to include the line below. AIServices = defenderPlans.AI Display the results in a table or chart alongside other Defender plans. Save and publish the updated workbook for organization-wide visibility. Pros Single pane of glass for all Defender coverage. Easy for SOC teams already using the workbook. Cons Requires manual customization and maintenance. Updates may be overwritten during workbook template refresh. Option 2: Use Azure Resource Graph Explorer Run a Resource Graph query to check Defender for AI enablement status across multiple subscriptions without modifying the workbook. Steps Go to Azure Resource Graph Explorer in the Azure portal. Run the following query: __________________________________________________________________________________ securityresources | where type =~ "microsoft.security/pricings" | extend pricingTier = properties.pricingTier, subPlan = properties.subPlan | extend planSet = pack(name, level = case(isnotempty(subPlan),subPlan,pricingTier)) | summarize defenderPlans = make_bag(planSet) by subscriptionId | project subscriptionId, CloudPosture = defenderPlans.CloudPosture, VirtualMachines = defenderPlans.VirtualMachines, AppServices = defenderPlans.AppServices, AIServices = defenderPlans.AI, SqlServers = defenderPlans.SqlServers, SqlServerVirtualMachines = defenderPlans.SqlServerVirtualMachines, OpenSourceRelationalDatabases = defenderPlans.OpenSourceRelationalDatabases, CosmosDB = defenderPlans.CosmosDbs, StorageAccounts = defenderPlans.StorageAccounts, Containers = defenderPlans.Containers, KeyVaults = defenderPlans.KeyVaults, Arm = defenderPlans.Arm, DNS = defenderPlans.Dns, KubernetesService = defenderPlans.KubernetesService, ContainerRegistry = defenderPlans.ContainerRegistry The output appears as shown below. Export results to CSV or Power BI for reporting. Optionally, schedule the query using Azure Automation or Logic Apps for periodic checks. Pros No dependency on workbook customization. Flexible for ad hoc queries and automation. Cons Separate reporting interface from the Coverage Workbook. Requires manual execution or automation setup. Recommendation If your organization prefers a centralized dashboard, choose Option 1 and update the Coverage Workbook. For quick checks or automation, Option 2 using Resource Graph Explorer is simpler and more scalable.End of Windows 10 Support: What Defender Customers Need to Know
As of today, October 14, 2025, Microsoft is officially ending support for Windows 10. This means that Windows 10 devices will no longer receive security or feature updates, nor technical support from Microsoft. While these devices will continue to operate, the lack of regular security updates increases vulnerability to cyber threats, including malware and viruses. Applications running on Windows 10 may also lose support as the platform stops receiving updates. Will Defender continue to protect Windows 10 devices? Defender supports a range of legacy systems, including Windows 10. (See here for a full list of supported operating systems.) Microsoft Defender will continue to provide detection and protection capabilities to the extent possible on Windows 10 and other legacy systems. Keep in mind that security solutions on legacy systems are inherently less secure and may not be able to receive all new features, so please review the next section for important actions you can take. For Windows 10 customers without Defender, Microsoft will continue to provide security intelligence updates for the built-in Microsoft Defender Antivirus protection through October 2028. Of course, Defender Antivirus alone isn't a comprehensive risk mitigation posture without Microsoft Defender detection and response deployed across your digital estate. What should customers do to protect their Windows 10 devices? Upgrade to Windows 11: Moving to Windows 11 is strongly recommended for PCs eligible to upgrade. Windows 11 delivers the latest security features, improved performance, and ongoing support at no additional cost. This is the best way to ensure your endpoints remain protected and compliant. Devices running Windows 10 will be more vulnerable, even with ongoing security intelligence updates (SIUs). Extended security update (ESU) program: If upgrading isn’t immediately possible, Microsoft offers an ESU program for Windows 10. The ESU program provides critical and important security updates but does not include new Windows features or technical support. Enterprise customers can purchase ESU for up to three years or receive it at no additional cost with a Windows 365 subscription. Cloud and virtual environments: Windows 10 devices accessing Windows 11 Cloud PCs via Windows 365 or Virtual Machines are entitled to ESU at no extra cost, with automatic updates. Consumer customers have options to enroll for one year of ESU, including free enrollment methods in certain regions. For further guidance, check out the posts below or connect with your Microsoft account team. End of support for Windows 10, Windows 8.1, and Windows 7 | Microsoft Windows How to prepare for Windows 10 end of support by moving to Windows 11 today | Windows Experience Blog Extended Security Updates (ESU) program for Windows 10 | Microsoft Learn To learn more about Microsoft Security solutions, visit our website. Bookmark the Security blog to keep up with our expert coverage on security matters. Also, follow us on LinkedIn (Microsoft Security) and X (@MSFTSecurity) for the latest news and updates on cybersecurity.Multi-tenant endpoint security policies distribution is now in Public Preview
We’re excited to announce a key milestone in Defender’s multi-tenant management journey—Microsoft Defender for Endpoint security policies can now be distributed across multiple tenants from the Defender multi-tenant portal. This capability empowers security teams to manage policies at scale, ensuring consistency and saving valuable time. What is content distribution? Content distribution is a powerful Defender feature that enables scalable management of content across tenants. With this capability, you can create content distribution profiles in the multi-tenant portal that allow you to seamlessly replicate existing content—such as custom detection rules and now, endpoint security policies—from a source tenant to designated target tenants. Once distributed, the content runs on the target tenant, enabling centralized control with localized execution. How it works Security policies are now a selectable content type when creating a distribution profile. Simply choose existing policies from your home tenant and add them to the distribution profile. You can also decide which Microsoft Entra group(s) will be applied as scope. Policy targeting will be based on the Entra device groups that exist in every tenant, and you select the relevant groups for each tenant. Upon completion, policies are automatically distributed to the selected tenants and are applied on the targeted machines. Distributed policies also appear in a hierarchical view, with the original policy serving as the parent. You can find the policies that were distributed from the tenant under the original policy. This appears on the endpoint security policies page within multi-tenant management. The last distribution status for the original policy reflects the overall status of its distributed copies, and the tenants and tenant groups sections indicate the recipients of the policy. At any time, you can update the policies, tenants, scope or any other settings, and sync to apply these changes. This new capability enables consistency (maintaining uniform security posture across tenants), efficiency (eliminating manual duplication and reducing operational overhead), and scalability (easily expanding coverage as the tenant landscape grows). FAQ What pre-requisites are required? Access to more than one tenant with Microsoft Defender for Endpoint, with delegated access via Azure B2B or GDAP (CSP Partners only), using the multi-tenant management capability. A subscription to Microsoft 365 E5 or Office E5. What permissions are needed to distribute MDE security policies? To access endpoint security policies, users require the security administrator role in each relevant tenant. To distribute content using multi-tenant management content distribution, the Security settings (manage) or Security Data Basic (read) permission is required. Both roles are assigned to the Security Administrator and Security Reader Microsoft Entra built-in roles by default. Can I update or expand distribution profiles later? Yes. You can add more content, include additional tenants, or modify scopes as needed. Learn more For more information, see Content distribution in multitenant management. To get started, navigate to the Content distribution page. To learn more about Microsoft Defender's endpoint protection, check out our website and video. To learn more about Microsoft Security solutions, visit our website. Bookmark the Security blog to keep up with our expert coverage on security matters. Follow us on LinkedIn (Microsoft Security) and X (@MSFTSecurity) for the latest news and updates on cybersecurity.
