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 : IDisposableExample
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
| Name | Description |
|---|---|
| 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.csCreates a new AMSI context for the specified application.
public static AmsiContext Create(string applicationName)Parameters
applicationNamestring- 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.csCreates 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.
Dispose()
AmsiContext.cspublic void Dispose()No documentation is available.
GetRegisteredProviders()
AmsiContext.csGets 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.csScans a byte buffer for malware using the Windows antimalware provider.
Parameters
payloadbyte[]- The byte buffer to scan.
contentNamestring- 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.csScans a string for malware using the Windows antimalware provider.
Parameters
payloadstring- The string content to scan.
contentNamestring- 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.csDetermines 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.csScans a byte buffer for malware using the Windows antimalware provider.
public AmsiResult Scan(byte[] payload, string contentName)Parameters
payloadbyte[]- The byte buffer to scan.
contentNamestring- 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.csScans a string for malware using the Windows antimalware provider.
public AmsiResult Scan(string payload, string contentName)Parameters
payloadstring- The string content to scan.
contentNamestring- 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.