Edit

IAntimalwareProvider interface (amsi.h)

  • Article

Represents the provider of the antimalware product. For a code example, see the IAntimalwareProvider interface sample.

The IAntimalwareProvider interface inherits from the IUnknown interface.

Inheritance

The IAntimalwareProvider interface inherits from the IUnknown interface.

Methods

The IAntimalwareProvider interface has these methods.

 
IAntimalwareProvider::CloseSession

Closes the session. (IAntimalwareProvider.CloseSession)
IAntimalwareProvider::DisplayName

The name of the antimalware provider to be displayed.
IAntimalwareProvider::Scan

Scan a stream of content. (IAntimalwareProvider.Scan)

Remarks

As of Windows 10, version 1903, Windows has added a way to enable Authenticode signing checks for providers. The feature is disabled by default, for both 32-bit and 64-bit processes. If you are creating a provider for test purposes, then you can enable or disable sign checks by setting the following Windows Registry value appropriately. The value is a DWORD.

Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\AMSI\FeatureBits

Value Behavior
0x1 The signing check is disabled. This is the default behavior. You can also use this value, temporarily, while testing.
0x2 The check for Authenticode signing is enabled.

Deleting the registry value altogether behaves as if the value 0x1 were present.

Note

As a provider, you must use the /ac switch (with the SignTool) to cross-sign with an Authenticode certificate. Once you've signed your binary, you can then verify it by using the SignTool and the /kp option. If the SignTool returns no error, then your binary is properly signed.

Important

Even though the Windows Registry value is not protected by the operating system, your computer's antivirus provider might protect the value, thus making it write-protected.

To check whether or not your provider is loading, you can view code integrity events. Be sure to enable verbose logging of code integrity diagnostic events. The event IDs to look for are 3040 and 3041. Here are some examples.

Log Name:      Microsoft-Windows-CodeIntegrity/Verbose
Source:        Microsoft-Windows-CodeIntegrity
Date:          M/DD/YYYY H:MM:SS PM
Event ID:      3040
Task Category: (14)
Level:         Verbose
Keywords:      
User:          [DOMAIN_NAME]\Administrator
Computer:      [COMPUTER_NAME]
Description:
Code Integrity started retrieving the cached data of [PATH_AND_FILENAME] file.
Event Xml:
<Event xmlns="http://schemas.microsoft.com/win/2004/08/events/event">
  <System>
    <Provider Name="Microsoft-Windows-CodeIntegrity" Guid="{4ee76bd8-3cf4-44a0-a0ac-3937643e37a3}" />
    <EventID>3040</EventID>
    <Version>0</Version>
    <Level>5</Level>
    <Task>14</Task>
    <Opcode>1</Opcode>
    <Keywords>0x4000000000000000</Keywords>
    <TimeCreated SystemTime="YYYY-MM-DDT02:26:48.875954700Z" />
    <EventRecordID>7</EventRecordID>
    <Correlation />
    <Execution ProcessID="4972" ThreadID="7752" ProcessorID="1" KernelTime="14" UserTime="2" />
    <Channel>Microsoft-Windows-CodeIntegrity/Verbose</Channel>
    <Computer>[COMPUTER_NAME]</Computer>
    <Security UserID="[USER_SID]" />
  </System>
  <EventData>
    <Data Name="FileNameLength">40</Data>
    <Data Name="FileNameBuffer">[PATH_AND_FILENAME]</Data>
  </EventData>
</Event>

Log Name:      Microsoft-Windows-CodeIntegrity/Verbose
Source:        Microsoft-Windows-CodeIntegrity
Date:          M/DD/YYYY H:MM:SS PM
Event ID:      3041
Task Category: (14)
Level:         Verbose
Keywords:      
User:          [DOMAIN_NAME]\Administrator
Computer:      [COMPUTER_NAME]
Description:
Code Integrity completed retrieval of file cache. Status 0xC0000225.
Event Xml:
<Event xmlns="http://schemas.microsoft.com/win/2004/08/events/event">
  <System>
    <Provider Name="Microsoft-Windows-CodeIntegrity" Guid="{4ee76bd8-3cf4-44a0-a0ac-3937643e37a3}" />
    <EventID>3041</EventID>
    <Version>2</Version>
    <Level>5</Level>
    <Task>14</Task>
    <Opcode>2</Opcode>
    <Keywords>0x4000000000000000</Keywords>
    <TimeCreated SystemTime="YYYY-MM-DDT02:26:48.875964700Z" />
    <EventRecordID>8</EventRecordID>
    <Correlation />
    <Execution ProcessID="4972" ThreadID="7752" ProcessorID="1" KernelTime="14" UserTime="2" />
    <Channel>Microsoft-Windows-CodeIntegrity/Verbose</Channel>
    <Computer>[COMPUTER_NAME]</Computer>
    <Security UserID="[USER_SID]" />
  </System>
  <EventData>
    <Data Name="Status">0xc0000225</Data>
    <Data Name="CachedFlags">0x0</Data>
    <Data Name="CacheSource">0</Data>
    <Data Name="CachedPolicy">0</Data>
  </EventData>
</Event>

Requirements

Requirement Value
Minimum supported client Windows 10 [desktop apps only]
Minimum supported server Windows Server 2016 [desktop apps only]
Target Platform Windows
Header amsi.h

See also

IAntimalwareProvider interface sample

SignTool

How AMSI helps