AmsiContext Class

  • Supported on windows10.0.10240

Provides access to the Windows Antimalware Scan Interface (AMSI) for scanning content for malware.

[SupportedOSPlatform("windows10.0.10240")]
public sealed class AmsiContext : IDisposable

Example

using var context = AmsiContext.Create("MyApplication");

// The EICAR test file is detected as malware by every antivirus
Assert.True(context.IsMalware(@"X5O!P%@AP[4\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*", "test.txt"));
Implements

Methods

NameDescription
Create(string)Creates a new AMSI context for the specified application.
CreateSession()Creates a new AMSI session for correlating multiple scan requests.
Dispose()
GetRegisteredProviders()Gets the antimalware providers registered with AMSI, in the order AMSI loads them.
IsMalware(byte[], string)Scans a byte buffer for malware using the Windows antimalware provider.
IsMalware(string, string)Scans a string for malware using the Windows antimalware provider.
IsProviderRegistered()Determines whether at least one antimalware provider is registered with AMSI.
Scan(byte[], string)Scans a byte buffer for malware using the Windows antimalware provider.
Scan(string, string)Scans a string for malware using the Windows antimalware provider.

Create(string)

AmsiContext.cs

Creates a new AMSI context for the specified application.

public static AmsiContext Create(string applicationName)

Parameters

applicationName string
The name of the application that will use the AMSI context.

Returns

AmsiContext A new AmsiContext instance.

Exceptions

COMException
Thrown when the AMSI context cannot be initialized.

CreateSession()

AmsiContext.cs

Creates a new AMSI session for correlating multiple scan requests.

public AmsiSession CreateSession()

Returns

AmsiSession A new AmsiSession instance.

Exceptions

COMException
Thrown when the AMSI session cannot be opened.
ObjectDisposedException
Thrown when the context has been disposed.
public void Dispose()

No documentation is available.

GetRegisteredProviders()

AmsiContext.cs

Gets the antimalware providers registered with AMSI, in the order AMSI loads them.

public static IReadOnlyList<AmsiProvider> GetRegisteredProviders()

Returns

IReadOnlyList<AmsiProvider> The registered providers, or an empty list when no provider is registered.

Remarks

AMSI reads its providers from the HKLM\SOFTWARE\Microsoft\AMSI\Providers registry key. The registry view of the current process is used, as AMSI does: a 32-bit process sees the providers registered for 32-bit processes.

IsMalware overloads

IsMalware(byte[], string)

AmsiContext.cs

Scans a byte buffer for malware using the Windows antimalware provider.

public bool IsMalware(byte[] payload, string contentName)
Parameters
payload byte[]
The byte buffer to scan.
contentName string
The name or identifier of the content being scanned.
Returns

bool true if the content is detected as malware; otherwise, false.

Exceptions
COMException
Thrown when the scan operation fails.
ObjectDisposedException
Thrown when the context has been disposed.
Remarks

Content blocked by administrator policy is not reported as malware. Use AmsiContext.Scan and AmsiResultExtensions.ShouldBlock to cover that case.

IsMalware(string, string)

AmsiContext.cs

Scans a string for malware using the Windows antimalware provider.

public bool IsMalware(string payload, string contentName)
Parameters
payload string
The string content to scan.
contentName string
The name or identifier of the content being scanned.
Returns

bool true if the content is detected as malware; otherwise, false.

Exceptions
COMException
Thrown when the scan operation fails.
ObjectDisposedException
Thrown when the context has been disposed.
Remarks

Content blocked by administrator policy is not reported as malware. Use AmsiContext.Scan and AmsiResultExtensions.ShouldBlock to cover that case.

IsProviderRegistered()

AmsiContext.cs

Determines whether at least one antimalware provider is registered with AMSI.

public static bool IsProviderRegistered()

Returns

bool true when a provider is registered; otherwise, false.

Remarks

When no provider is registered, scans succeed and report every content as AmsiResult.NotDetected: a negative answer does not mean that the content is safe. A registered provider may still be unable to scan, for instance when it is disabled; scans then throw a COMException.

Example

// Without a provider, every content is reported as not detected
if (!AmsiContext.IsProviderRegistered())
    throw new InvalidOperationException("No antimalware product is registered with AMSI");

foreach (var provider in AmsiContext.GetRegisteredProviders())
{
    // e.g. {2781761E-28E0-4109-99FE-B9D127C57AFE} Windows Defender IOfficeAntiVirus implementation
    Assert.NotEqual(Guid.Empty, provider.Id);
}

Scan overloads

Scan(byte[], string)

AmsiContext.cs

Scans a byte buffer for malware using the Windows antimalware provider.

public AmsiResult Scan(byte[] payload, string contentName)
Parameters
payload byte[]
The byte buffer to scan.
contentName string
The name or identifier of the content being scanned.
Returns

AmsiResult The result reported by the antimalware provider.

Exceptions
COMException
Thrown when the scan operation fails.
ObjectDisposedException
Thrown when the context has been disposed.

Scan(string, string)

AmsiContext.cs

Scans a string for malware using the Windows antimalware provider.

public AmsiResult Scan(string payload, string contentName)
Parameters
payload string
The string content to scan.
contentName string
The name or identifier of the content being scanned.
Returns

AmsiResult The result reported by the antimalware provider.

Exceptions
COMException
Thrown when the scan operation fails.
ObjectDisposedException
Thrown when the context has been disposed.