Share via

Exchange Server AMSI integration

APPLIES TO: yes-img-162016 yes-img-192019 yes-img-seSubscription Edition

Overview

The Windows Antimalware Scan Interface (AMSI) is a versatile interface standard that allows your applications and services to integrate with any anti-malware product that's present on a Windows Server. AMSI is vendor agnostic and designed to allow for the most common malware scanning and protection techniques provided by today's products to be integrated into applications. It was introduced with Windows Server 2016.

AMSI supports a calling structure allowing for file and memory or stream scanning, content source URL/IP reputation checks, and other techniques. It also supports the notion of a session so that anti-malware vendors can correlate different scan requests. For instance, the different fragments of a malicious payload can be associated to reach a more informed decision. This would be harder to reach just by looking at those fragments in isolation.

AMSI integration in Exchange Server provides the ability for an AMSI-capable antivirus/anti-malware solution to scan content in HTTP requests sent to Exchange Server and block a malicious request before it is handled by Exchange Server. The scan is performed in real-time by any AMSI-capable antivirus/anti-malware (AV) solution that runs on the Exchange server as the server begins to process the request. This feature provides automatic mitigation and protection that compliments the existing anti-malware protection in Exchange Server to help make your Exchange servers more secure.

Starting with the Exchange Server November 2024 Security Update (SU), AMSI integration is taken to the next level as it provides new capabilities for scanning the HTTP message body. This feature is disabled by default and can be enabled by following the steps mentioned in the Enable Exchange Server AMSI Body scanning section.

Prerequisites

To benefit from the AMSI integration in Exchange Server, the following prerequisites must be fulfilled:

  • Windows Server 2016, or higher
  • Partial functionality (no AMSI body scanning):
    • Exchange Server 2016 CU21 / Exchange Server 2019 CU10
  • Full functionality (with AMSI body scanning):
  • Microsoft Defender with AV engine version at or higher than 1.1.18300.4 or, a compatible AMSI capable third-party AV provider - check with your vendor

Make sure to always install the latest Exchange Server update to benefit from bug fixes and the latest improvements.

How to verify the Exchange Server AMSI integration

In this section, we provide information to help you check if Exchange Server AMSI integration is configured correctly. Exchange Server AMSI integration is enabled by default, except for the Exchange Server AMSI body scanning feature.

Find your installed AMSI provider

To confirm that you have an AMSI provider installed on your Exchange Server, run the following Windows PowerShell commands and validate the output:

$AMSI = Get-ChildItem -Path "HKLM:\SOFTWARE\Microsoft\AMSI\Providers" -Recurse
$AMSI -match "[0-9A-Fa-f\-]{36}"
$Matches.Values | ForEach-Object { Get-ChildItem -Path "HKLM:\SOFTWARE\Classes\CLSID\{$_}" | Format-Table -AutoSize }

The output appears similar to this example, depending on your installed antivirus product.

Name                    Property
----                    --------
Hosts                   (default) : Scanned Hosting Applications
Implemented Categories
InprocServer32          (default) : "C:\ProgramData\Microsoft\Windows Defender\Platform\4.18.2106.6-0\MpOav.dll"
                        ThreadingModel : Both

The results indicate that the only provider installed is located at C:\ProgramData\Microsoft\Windows Defender\Platform\4.18.2106.6-0\MpOav.dll, which corresponds to Microsoft Windows Defender. Windows Server 2016 or later operating systems recognize our AMSI Provider installation, as confirmed by this information.

Validate AMSI IIS configuration

One of the core components of the Exchange Server AMSI integration is the HttpRequestFilteringModule. This module is configured in the web.config file for most services, which are located in the FrontEnd and ClientAccess directories. If you regularly replace or modify web.config files, ensure that this module is included. Otherwise, the AMSI integration doesn't work correctly. The configuration line looks like this:

<add name="HttpRequestFilteringModule" type="Microsoft.Exchange.HttpRequestFiltering.HttpRequestFilteringModule, Microsoft.Exchange.HttpRequestFiltering, Version=15.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />

Validate Windows Defender version

To validate the signatures using Microsoft Windows Defender, open the Command Prompt and use the MpCmdRun tool, which checks for the latest definitions and display your current engine version

  • Launch cmd.exe as administrator
  • Navigate to %programdata%\Microsoft\Windows Defender\Platform\<antimalware platform version>
  • Run mpcmdrun.exe -SignatureUpdate

The output should look similar to this example:

Microsoft Windows Command Prompt
Copyright (C) Microsoft Corporation. All rights reserved.

C:\ProgramData\Microsoft\Windows Defender\Platform\4.18.2105.5-0>MpCmdRun.exe -SignatureUpdate

Signature update started . . .
Service Version: 4.18.2106.6
Engine Version: 1.1.18300.4
AntiSpyware Signature Version: 1.343.1364.0
AntiVirus Signature Version: 1.343.1364.0
Signature update finished. No updates needed

Confirm that AMSI integration works

If the AMSI module detects a malicious request, it is logged in the %ExchangeInstallPath%\Logging\HttpRequestFiltering folder with a ScanResult value of Detected. The module does not log safe calls; therefore, the presence of a log indicates that a malicious call was detected. When a request is blocked, Internet Information Service (IIS) returns a 400 (Bad Request) status code to the requester.

The following output is an example of a log file, which contains HTTP POST requests that AMSI helped block:

DateTime,MajorVersion,MinorVersion,BuildVersion,RevisionVersion,ServerHostName,SharedCacheLatency,TotalLatency,HttpMethod,UrlHost,UrlStem,UrlQuery,ServerIP,Protocol,HeaderNames,CookieNames,ScanResult,GenericInfo,GenericErrors
#Software: Microsoft Exchange Server
#Version: 15.01.build
#Log-type: Http Request Filtering Logs
#Date: 2021-06-30T10:03:57.573Z
#Fields:
DateTime,MajorVersion,MinorVersion,BuildVersion,RevisionVersion,ServerHostName,SharedCacheLatency,TotalLatency,HttpMethod,UrlHost,UrlStem,UrlQuery,ServerIP,Protocol,HeaderNames,CookieNames,ScanResult,GenericInfo,GenericErrors
6/30/2021 10:03:57 AM,15,1,2334,0,SERVER01,,,POST,localhost,/ecp/x.js,,::1,FrontEnd.Ecp,Content-Length;Cookie;Host,X-BEResource,Detected,,
6/30/2021 10:09:41 AM,15,1,2334,0,SERVER01,,,POST,SERVER01.contoso.com,/ecp/x.js,,192.168.10.52,FrontEnd.Ecp,Content-Length;Cookie;Host,X-BEResource,Detected,,
6/30/2021 10:09:43 AM,15,1,2334,0,SERVER01,,,POST,SERVER01.contoso.com,/ecp/x.js,,192.168.10.52,FrontEnd.Ecp,Content-Length;Cookie;Host,X-BEResource,Detected,,

You can use the Test-AMSI script to verify if the AMSI integration functions as expected. The script sends a crafted HTTP request to trigger the anti-malware scanner, and you can check the log files on the Exchange Server for Detected entries after execution. Additionally, the script can be used to check your AMSI Providers on the system and to enable or disable AMSI integration.

If Exchange Server AMSI body scanning is enabled, you can run the following command from the Exchange Management Shell (EMS):

 Get-Mailbox -Anr "amsiscantest:x5opap4pzx54p7cc7$eicar-standard-antivirus-test-fileh+h*"

The command should fail to run, and if you open Microsoft Defender or run Get-MpThreat via PowerShell, you should see the threat Exploit:Script/ExchangeEicar.A being blocked.

Enable Exchange Server AMSI body scanning

The Exchange AMSI body scanning feature, which was introduced with the Exchange Server November 2024 Security Update (SU), is disabled by default. It can be enabled and configured by creating a setting override via the New-SettingOverride cmdlet. The feature can be enabled on a per-protocol base or for all protocols. The New-SettingOverride commands in this section create a Global override, which configures the feature across all Exchange servers within the organization. It's possible to enable it on just a subset of servers. To do so, add the -Server parameter as described in the New-SettingOverride documentation.

Important

We recommend starting to enable this feature for a subset of services first, as it is possible that it could lead to performance issues. Additionally, we ask that you reach out to us if you experience any issues after enabling Exchange Server AMSI body scanning. You can contact us by sending an email to ExchOnPremFeedback[at]microsoft.com.

To enable the AMSI body scanning feature for a specific protocol, you can select from a predefined set of protocols. Exchange Server AMSI body scanning supports all protocols except RPC over HTTP:

  • EnabledAll
  • EnabledApi
  • EnabledAutoD
  • EnabledEcp
  • EnabledEws
  • EnabledMapi
  • EnabledEas
  • EnabledOab
  • EnabledOwa
  • EnabledPowerShell
  • EnabledOthers

The next step is to create an override for the protocols that you want to enable. You can create one override, which contains all of the protocols for which AMSI body scanning should be enabled. Make sure to run all commands from an elevated Exchange Management Shell (EMS):

New-SettingOverride -Name "EnableAMSIBodyScanForEcpEwsOwa" -Component Cafe -Section AmsiRequestBodyScanning -Parameters @("EnabledEcp=True","EnabledEws=True","EnabledOwa=True") -Reason "Enabling AMSI body Scan for ECP, EWS and OWA"
Get-ExchangeDiagnosticInfo -Process Microsoft.Exchange.Directory.TopologyService -Component VariantConfiguration -Argument Refresh
Restart-Service -Name W3SVC, WAS -Force

It's possible to create multiple overrides, for example, one for each protocol:

New-SettingOverride -Name "EnableAMSIBodyScanForEcp" -Component Cafe -Section AmsiRequestBodyScanning -Parameters ("EnabledEcp=True") -Reason "Enabling AMSI body Scan for ECP"
New-SettingOverride -Name "EnableAMSIBodyScanForEws" -Component Cafe -Section AmsiRequestBodyScanning -Parameters ("EnabledEws=True") -Reason "Enabling AMSI body Scan for EWS"
New-SettingOverride -Name "EnableAMSIBodyScanForOwa" -Component Cafe -Section AmsiRequestBodyScanning -Parameters ("EnabledOwa=True") -Reason "Enabling AMSI body Scan for OWA"
Get-ExchangeDiagnosticInfo -Process Microsoft.Exchange.Directory.TopologyService -Component VariantConfiguration -Argument Refresh
Restart-Service -Name W3SVC, WAS -Force

To enable the AMSI body scanning for all protocols on all Exchange Servers in your environment:

New-SettingOverride -Name "EnableAMSIBodyScanAllProtocols" -Component Cafe -Section AmsiRequestBodyScanning -Parameters ("EnabledAll=True") -Reason "Enabling AMSI body Scan for all protocols"
Get-ExchangeDiagnosticInfo -Process Microsoft.Exchange.Directory.TopologyService -Component VariantConfiguration -Argument Refresh
Restart-Service -Name W3SVC, WAS -Force

By default, the feature passes the first 4096 bytes of the body to the anti-malware scanner. It is possible to adjust the number of bytes that should be scanned. The maximum possible value is 1048576 bytes (1 MB). We recommend starting with the default configuration and adjusting the size if you experience performance issues. This setting can be configured by running the following commands. Make sure to replace BodyScanSizeInBytes=8192 with the new byte size that should be processed:

New-SettingOverride -Name "ConfigureCustomAMSIBodyScanSize" -Component Cafe -Section AmsiRequestBodyScanning -Parameters ("BodyScanSizeInBytes=8192") -Reason "Adjusting AMSI body Scan size to 8192 bytes"
Get-ExchangeDiagnosticInfo -Process Microsoft.Exchange.Directory.TopologyService -Component VariantConfiguration -Argument Refresh
Restart-Service -Name W3SVC, WAS -Force

Warning

The configuration mentioned in the following section should not be enabled unless explicitly advised by Microsoft.

It's possible to block any request whose HTTP message body exceeds the maximum possible scannable size of 1048576 bytes (1 MB). This feature can be enabled for a subset of protocols (for example, OWA, ECP, EWS) or for all protocols. The supported protocols are listed in the previous section. The following example blocks requests where the body size exceeds the maximum scannable size for the Outlook on the Web (OWA) protocol:

New-SettingOverride -Name "BlockRequestBodyGreaterThanMaxScanSizeOWA" -Component Cafe -Section BlockRequestBodyGreaterThanMaxScanSize -Parameters ("EnabledOwa=True") -Reason "Block requests with body size greater than 1 MB for OWA"
Get-ExchangeDiagnosticInfo -Process Microsoft.Exchange.Directory.TopologyService -Component VariantConfiguration -Argument Refresh
Restart-Service -Name W3SVC, WAS -Force

Disable Exchange Server AMSI integration

If you encounter issues with the Exchange Server AMSI integration or need to temporarily disable it for research or troubleshooting, you can create an override to disable the integration. The following commands must be executed from an elevated Exchange Management Shell (EMS).

To disable AMSI integration on a specific Exchange Server, run these commands. Replace <ServerName> with the name of your Exchange Server:

New-SettingOverride -Name "DisablingAMSIScan" -Server <ServerName> -Component Cafe -Section HttpRequestFiltering -Parameters ("Enabled=False") -Reason "Troubleshooting AMSI"
Get-ExchangeDiagnosticInfo -Process Microsoft.Exchange.Directory.TopologyService -Component VariantConfiguration -Argument Refresh
Restart-Service -Name W3SVC, WAS -Force

To disable AMSI integration on all Exchange Servers within your organization, you can run these commands:

New-SettingOverride -Name "DisablingAMSIScan" -Component Cafe -Section HttpRequestFiltering -Parameters ("Enabled=False") -Reason "Troubleshooting AMSI"
Get-ExchangeDiagnosticInfo -Process Microsoft.Exchange.Directory.TopologyService -Component VariantConfiguration -Argument Refresh
Restart-Service -Name W3SVC, WAS -Force

To enable AMSI integration back, you can run these commands to remove the override:

Get-SettingOverride | Where-Object {($_.SectionName -eq "HttpRequestFiltering") -and ($_.Parameters -eq "Enabled=False")} | Remove-SettingOverride
Get-ExchangeDiagnosticInfo -Process Microsoft.Exchange.Directory.TopologyService -Component VariantConfiguration -Argument Refresh
Restart-Service -Name W3SVC, WAS -Force