Part 1: Core AMSI APIs

Now that we have a basic understanding of AMSI, let’s jump into how AMSI actually does this under the hood.

When a PowerShell process is instantiated, the Windows loader automatically loads numerous Dynamic Link Libraries (DLLs) into the process address space. Amongst these DLLs one is the amsi.dll as shown in the image below.

The amsi.dll library exposes several Win32 APIs. Relevant information captured by these APIs is forwarded to the registered anti-malware provider through an interprocess communication mechanism called Remote Procedure Call. After the anti-malware provider analyzes the data, the result is sent back to amsi.dll inside the PowerShell process. Note that while Windows Defender is the default provider on Windows systems, any anti-malware vendor can register as an AMSI provider.

There are four core functions that are used…

AmsiInitialize

When PowerShell is launched, it loads amsi.dll and calls AmsiInitialize(). Thus, AmsiInitialize() is called even before you Invoke any command and hence it can’t be manipulated. There are two inputs to this function, one is the name of application (for example, powershell) and another one is amsicontext structure which is used by the subsequent calls.

1
HRESULT AmsiInitialize(
2
 [in]  LPCWSTR      appName,
3
 [out] HAMSICONTEXT *a
4
);

AmsiOpenSession

AmsiOpenSession() accepts the amsiContext structure and creates a session structure to be used in all calls within that session.

1
HRESULT AmsiOpenSession(
2
 [in]  HAMSICONTEXT amsiContext,
3
 [out] HAMSISESSION *amsiSession
4
);

AmsiScanString

AmsiScanString() is a function within AmsiScanBuffer() and calls it ultimately. Below is a image showing disassmbled graph of AmsiScanString() function.

1
 HRESULT AmsiScanString(
2
  [in]           HAMSICONTEXT amsiContext,
3
  [in]           LPCWSTR      string,
4
  [in]           LPCWSTR      contentName,
5
  [in, optional] HAMSISESSION amsiSession,
6
  [out]          AMSI_RESULT  *result
7
);

AmsiScanBuffer

AmsiScanBuffer() is the core scanning function that accepts a buffer containing the string/script to be scanned and sends it to the registered anti-malware provider. It returns two values.

• HRESULT: S_OK if the API call is successful and if not and if not it returns an HRESULT error code. Microsoft documentation shows a various errors and their respective codes. E_INVALIDARG (0x80070057), indicating one or more arguments are not valid, is one of the important error codes.

AMSI_RESULT

1
HRESULT AmsiScanBuffer(
2
  [in]           HAMSICONTEXT amsiContext,
3
  [in]           PVOID        buffer,
4
  [in]           ULONG        length,
5
  [in]           LPCWSTR      contentName,
6
  [in, optional] HAMSISESSION amsiSession,
7
  [out]          AMSI_RESULT  *result
8
);

As mentioned earlier, AmsiScanBuffer() returns an AMSI_RESULT value through its output parameter. The most important results are:

• AMSI_RESULT_CLEAN: Content is not malicious, execution can proceed
• AMSI_RESULT_DETECTED: Malware detected, content should be blocked

Based on the AMSI_RESULT returned, the calling application decides whether to continue or stop execution.

1
typedef enum AMSI_RESULT {
2
  AMSI_RESULT_CLEAN,
3
  AMSI_RESULT_NOT_DETECTED,
4
  AMSI_RESULT_BLOCKED_BY_ADMIN_START,
5
  AMSI_RESULT_BLOCKED_BY_ADMIN_END,
6
  AMSI_RESULT_DETECTED
7
} ;