Blog Post

Exchange Team Blog

6 MIN READ

More about AMSI integration with Exchange Server

Microsoft

Jul 22, 2021

The Windows Antimalware Scan Interface (AMSI) is a versatile standard that allows applications and services to integrate with any antimalware product present on a machine. 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.

Seeing that Exchange administrators might not be familiar with AMSI, we wanted to provide an overview of various components that make this work, because…

Exchange Server integration arrives

As of the June 2021 quarterly updates, Exchange Server supports integration with AMSI. This provides the ability for an AMSI-capable antivirus/antimalware solution to scan content in HTTP requests sent to the Exchange Server and block a malicious request before it is handled by Exchange. The scan is performed in real-time as the server begins to process the request. AMSI, as implemented in June 2021 Cumulative Updates (CUs), only scans the HTTP protocol, and is not meant to be a replacement to existing server-level or message hygiene protections.

There is no observed performance impact from AMSI scanning when tested with Microsoft Defender and no changes to be made to the existing documented Exchange Sever antivirus exclusions. Each antivirus provider develops their own definitions that utilize AMSI technology, therefore your level of protection remains dependent on how quickly your specific solution can be dynamically updated to detect the latest threats.

The following steps will help you understand a bit more about what is needed on each of the Exchange servers to ensure that AMSI Integration is enabled and working:

AMSI integration with Exchange Server prerequisites

To start let’s make sure our Exchange Server can even support AMSI integration. Check the following prerequisites on each server:

Windows Server 2016, or higher
Exchange Server 2016 CU21 / Exchange Server 2019 CU10, or higher
Microsoft Defender with AV engine version at or higher than 1.1.18300.4 (alternatively, a compatible AMSI capable third-party AV provider – please check with your vendor)

How to find your installed AMSI provider

Now that you have met the prerequisites let’s confirm that you have an AMSI provider installed on the server. To do so you will need to run the following Windows PowerShell commands and review the output:

Get-ChildItem 'HKLM:\SOFTWARE\Microsoft\AMSI\Providers' -recurse
Get-ChildItem 'HKLM:\SOFTWARE\Classes\CLSID\{GUID obtained from previous command}'

For example, you can set a variable and then search for the RegEx Results of all AMSI Providers installed by running:

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

For example:

Windows PowerShell
Copyright (C) Microsoft Corporation. All rights reserved.
C:\PowerShell> $AMSI = Get-ChildItem 'HKLM:\SOFTWARE\Microsoft\AMSI\Providers' -Recurse
C:\PowerShell> $AMSI -match '[0-9A-Fa-f\-]{36}'
C:\PowerShell> $Matches.Values | ForEach-Object {Get-ChildItem "HKLM:\SOFTWARE\Classes\CLSID\{$_}" | Format-Table -AutoSize}

Hive: HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID\{2781761E-28E0-4109-99FE-B9D127C57AFE}

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 show us that the only provider we have installed is in C:\ProgramData\Microsoft\Windows Defender\Platform\4.18.2106.6-0\MpOav.dll which is Microsoft Windows Defender. So now we know that the Windows 2016 operating system or higher sees our AMSI Provider installation.

Web.config files

Next for AMSI Integration to work correctly we need to make sure that the HttpRequestFilteringModule line below is present in the <Modules> section of the FrontEnd and ClientAccess web.config files:

If you make a habit of replacing web.config files, you need to make sure that you have this line or AMSI will not work properly.

Confirm your Windows Defender version via the command line

If you are using Microsoft Windows Defender jump into the command line and make sure you have updated the signatures to the latest version.

Launch Command Prompt as an administrator
Navigate to C:\ProgramData\Microsoft\Windows Defender\Platform\<antimalware platform version>
Run mpcmdrun.exe -SignatureUpdate. This will check for the latest definitions and report your current engine version.

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
C:\ProgramData\Microsoft\Windows Defender\Platform\4.18.2105.5-0>

Confirm that AMSI integration is working

If any request is detected to be malicious by the AMSI module it is logged in the %ExchangeInstallPath%\Logging\HttpRequestFiltering folder and the value for ScanResult is “Detected”. This module does not create logs for safe calls so, if a log is present then a malicious call was seen at some point. When a request get blocked IIS will issues return code 400 / Bad Request back to the requestor.

Once a malicious connection is detected the log will look something like this:

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,,

How to disable AMSI integration with Exchange Server

If for some reason you need to temporarily disable the AMSI integration for testing or troubleshooting purposes. You can do so by opening Exchange Management Shell and create a new server override:

Welcome to the Exchange Management Shell!
[PS] C:\PowerShell> New-SettingOverride -Name "DisablingAMSIScan" -Server ServerName -Component Cafe -Section HttpRequestFiltering -Parameters ("Enabled=False") -Reason "Testing"
[PS] C:\PowerShell> Get-ExchangeDiagnosticInfo -Process Microsoft.Exchange.Directory.TopologyService -Component VariantConfiguration -Argument Refresh
[PS] C:\PowerShell> Restart-Service -Name W3SVC, WAS -Force

Note: If you set the override without using the -Server parameter, the override applies to all Exchange 2016/2019 servers in the forest.

Once your testing is complete, re-enable the AMSI integration by removing the setting override:

Welcome to the Exchange Management Shell!
[PS] C:\PowerShell> Remove-SettingOverride -Name "DisablingAMSIScan" -Component Cafe -Section HttpRequestFiltering -Parameters ("Enabled=False") -Reason "Testing"
[PS] C:\PowerShell> Get-ExchangeDiagnosticInfo -Process Microsoft.Exchange.Directory.TopologyService -Component VariantConfiguration -Argument Refresh
[PS] C:\PowerShell> Restart-Service -Name W3SVC, WAS -Force

You will have to restart the Internet Information Services (IIS) on the machine which will disrupt connectivity so make sure to do this when there will be no impact to the server or under a maintenance period.

Self-service test script

The new script we have created will let you test your Exchange Server AMSI integration with Microsoft Defender. The script can send a crafted HTTP request that will trigger the anti-malware scanner and once run you can check the \HttpRequestFiltering folder for a log. The script can also check your AMSI Providers on the system and even enable and disable AMSI integration. The script is available at the CSS-Exchange Repo on GitHub [Test-AMSI]. Please see GitHub for script usage tips / documentation!

Angélique Conde, Rob Whaley

Updated Sep 01, 2021

Version 3.0

Microsoft

Joined April 19, 2019

View Profile

Exchange Team Blog

You Had Me at EHLO..

RobWhaley-MSFT
Microsoft
Jul 22, 2021
Test-RRR Are you sure that you are in ProgramData not Program Files? I have checked all my labs and all of them have the Platform folder.
justsomeadmin
Copper Contributor
Jul 23, 2021
Great Info, thanks.
Now its not a complete black box anymore.
I will extend our monitoring to include those logs!

If you have sccm and using endpoint protection on your exchange servers gives great visibility into amsi.
Very nice!

Johnny_Yao_Taiwan

Brass Contributor

Jul 23, 2021

Hi Sir
I've ran .\Test-AMSI.ps1 on Exchange 2016 CU21 but get below SSL/TLS connection error. Any idea?

I'm sure AMSI is running and functional since CU21 upgrade on end of June. I'm keep follow related articles posted by Exchange Team.

Test-AMSI : The underlying connection was closed: Could not establish trust relationship for the SSL/TLS secure channel.
At C:\Batch\AMSI\Test-AMSI.ps1:124 char:1
+ Test-AMSI
+ ~~~~~~~~~
+ CategoryInfo : NotSpecified: (:) [Write-Error], WriteErrorException
+ FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException,Test-AMSI

If you are using Microsoft Defender then AMSI may be disabled or you are using a AntiVirus Product that may not be AMSI capable (Please Check with your AntiVirus Provider for Exchange AMSI Support)

Updated how to fixed.
Add below script in front Function Test-AMSI section.

function Test-AMSI {


if (-not ([System.Management.Automation.PSTypeName]'ServerCertificateValidationCallback').Type)
{
$certCallback = @"
    using System;
    using System.Net;
    using System.Net.Security;
    using System.Security.Cryptography.X509Certificates;
    public class ServerCertificateValidationCallback
    {
        public static void Ignore()
        {
            if(ServicePointManager.ServerCertificateValidationCallback ==null)
            {
                ServicePointManager.ServerCertificateValidationCallback += 
                    delegate
                    (
                        Object obj, 
                        X509Certificate certificate, 
                        X509Chain chain, 
                        SslPolicyErrors errors
                    )
                    {
                        return true;
                    };
            }
        }
    }
"@
    Add-Type $certCallback
 }
[ServerCertificateValidationCallback]::Ignore()

Test-RRR
Brass Contributor
Jul 22, 2021
On Windows 2016 I dont have a folder "Platform". I have one on Windows 2019. Is it a differnt Path with Windows 2016?
Test-RRR
Brass Contributor
Jul 23, 2021
RobWhaley-MSFT: Thanks for your answer. Since we use a 3trd part virus scanner in production I tested on Window 2016 in my lab. The updates where missing - after updating Windows the folder "Platform" is where.
Pamor
Copper Contributor
Jul 28, 2021
Thanks for the Info!

Running the Test-AMSI script on an Exchange server that has a different OS language than English (German in my case) will lead to the warning message that AMSI may be disabled, as the script checks for the English error message of the code 400 / Bad Request that is returned. The test is working fine despite of this, code 400 is returned and the detection is logged. And a Microsoft 365 Defender alert was triggered, as we've onboarded the Exchange servers to Defender for Endpoint. Of course you can change the script and add the error message in the OS language if you want it to display the correct result.
RobWhaley-MSFT
Microsoft
Jul 28, 2021
Johnny_Yao_Taiwan and Pamor Thanks for your feedback I have added these issues over on GitHub.
JMaletzky
Brass Contributor
Jul 29, 2021
Thank you for the information.

Is the real-time AMSI scanning of HTTP traffic also working, if the real-time protection of Windows Defender is disabled per
Set-MpPreference -DisableRealtimeMonitoring $true
?

Thank you in advance.
Jörg Maletzky
RobWhaley-MSFT
Microsoft
Jul 30, 2021
JMaletzky When real time monitoring is disabled in Microsoft Defender AMSI scanning of traffic will also be disabled. I would suggest that you leave real time monitoring enabled and follow the documentation here: Running Windows antivirus software on Exchange servers | Microsoft Docs to set the proper exclusions.
DBoro1250
Copper Contributor
Aug 04, 2021
I suspect that Sophos and AMSI on our EX2016 server was giving performance issues so I uninstalled Sophos to fully confirm my suspicions. Message transfer completely broken after the uninstall so Sophos re-installed and all functional again. Will try the Sophos AMSI disable approach but rather surprised that the uninstall leaves it broken.