Público-alvo de desenvolvedores e código de exemplo

Artigo
03/13/2025

A interface de verificação antimalware foi projetada para uso por dois grupos de desenvolvedores.

Desenvolvedores de aplicativos que desejam fazer solicitações para produtos antimalware de dentro de seus aplicativos.
Criadores de produtos antimalware de terceiros que desejam que seus produtos ofereçam os melhores recursos aos aplicativos.

Desenvolvedores de aplicativos

O AMSI foi projetado em particular para combater o "malware sem arquivo". Os tipos de aplicativos que podem aproveitar a tecnologia AMSI de maneira ideal incluem mecanismos de script, aplicativos que precisam que buffers de memória sejam verificados antes de usá-los e aplicativos que processam arquivos que podem conter código executável não PE (como macros do Microsoft Word e Excel ou documentos PDF). No entanto, a utilidade da tecnologia AMSI não se limita a esses exemplos.

Há duas maneiras de interagir com o AMSI em seu aplicativo.

Usando as APIs AMSI Win32. Consulte Funções da Interface de Verificação Antimalware (AMSI).
Usando as interfaces AMSI COM. Consulte Interface IAmsiStream .

Para obter um código de exemplo que mostra como consumir AMSI em seu aplicativo COM, consulte o aplicativo de exemplo de interface IAmsiStream .

Criadores terceirizados de produtos antimalware

Como criador de produtos antimalware, você pode optar por criar e registrar seu próprio servidor COM em processo (uma DLL) para funcionar como um provedor AMSI. Esse provedor AMSI deve implementar a interface IAntimalwareProvider e deve ser executado em processo.

Observe que, após Windows 10, versão 1709 (a Atualização dos Criadores do outono de 2017), a DLL do provedor AMSI pode não funcionar se depender de outras DLLs em seu caminho para serem carregadas ao mesmo tempo. Para evitar o sequestro de DLL, recomendamos que a DLL do provedor carregue suas dependências explicitamente (com um caminho completo) usando chamadas LoadLibrary seguras ou equivalente. Recomendamos isso em vez de depender do comportamento de pesquisa LoadLibrary.

A seção abaixo mostra como registrar seu provedor AMSI. Para obter o código de exemplo completo mostrando como criar sua própria DLL do provedor AMSI, consulte o aplicativo de exemplo de interface IAntimalwareProvider.

Registre a DLL do seu provedor com AMSI

Para começar, você precisa garantir que essas chaves do Registro do Windows existam.

HKLM\SOFTWARE\Microsoft\AMSI\Providers
HKLM\SOFTWARE\Classes\CLSID

Um provedor AMSI é um servidor COM em processo. Consequentemente, ele precisa se registrar no COM. As classes COM são registradas no HKLM\SOFTWARE\Classes\CLSID.

O código abaixo mostra como registrar um provedor AMSI, cujo GUID (para este exemplo) vamos supor que seja 2E5D8A62-77F9-4F7B-A90C-2744820139B2.

#include <strsafe.h>
...
HRESULT SetKeyStringValue(_In_ HKEY key, _In_opt_ PCWSTR subkey, _In_opt_ PCWSTR valueName, _In_ PCWSTR stringValue)
{
    LONG status = RegSetKeyValue(key, subkey, valueName, REG_SZ, stringValue, (wcslen(stringValue) + 1) * sizeof(wchar_t));
    return HRESULT_FROM_WIN32(status);
}

STDAPI DllRegisterServer()
{
    wchar_t modulePath[MAX_PATH];
    if (GetModuleFileName(g_currentModule, modulePath, ARRAYSIZE(modulePath)) >= ARRAYSIZE(modulePath))
    {
        return E_UNEXPECTED;
    }

    // Create a standard COM registration for our CLSID.
    // The class must be registered as "Both" threading model,
    // and support multithreaded access.
    wchar_t clsidString[40];
    if (StringFromGUID2(__uuidof(SampleAmsiProvider), clsidString, ARRAYSIZE(clsidString)) == 0)
    {
        return E_UNEXPECTED;
    }

    wchar_t keyPath[200];
    HRESULT hr = StringCchPrintf(keyPath, ARRAYSIZE(keyPath), L"Software\\Classes\\CLSID\\%ls", clsidString);
    if (FAILED(hr)) return hr;

    hr = SetKeyStringValue(HKEY_LOCAL_MACHINE, keyPath, nullptr, L"SampleAmsiProvider");
    if (FAILED(hr)) return hr;

    hr = StringCchPrintf(keyPath, ARRAYSIZE(keyPath), L"Software\\Classes\\CLSID\\%ls\\InProcServer32", clsidString);
    if (FAILED(hr)) return hr;

    hr = SetKeyStringValue(HKEY_LOCAL_MACHINE, keyPath, nullptr, modulePath);
    if (FAILED(hr)) return hr;

    hr = SetKeyStringValue(HKEY_LOCAL_MACHINE, keyPath, L"ThreadingModel", L"Both");
    if (FAILED(hr)) return hr;

    // Register this CLSID as an anti-malware provider.
    hr = StringCchPrintf(keyPath, ARRAYSIZE(keyPath), L"Software\\Microsoft\\AMSI\\Providers\\%ls", clsidString);
    if (FAILED(hr)) return hr;

    hr = SetKeyStringValue(HKEY_LOCAL_MACHINE, keyPath, nullptr, L"SampleAmsiProvider");
    if (FAILED(hr)) return hr;

    return S_OK;
}

Se a DLL implementar a função DllRegisterServer, como o exemplo acima, você poderá registrá-la usando o executável regsvr32.exefornecido pelo Windows. Em um prompt de comando com privilégios elevados, emita um comando deste formulário.

C:>C:\Windows\System32\regsvr32.exe SampleAmsiProvider.dll

Neste exemplo, o comando cria as seguintes entradas.

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID\{2E5D8A62-77F9-4F7B-A90C-2744820139B2}

(Padrão) REG_SZ Exemplo de implementação do provedor AMSI

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID\{2E5D8A62-77F9-4F7B-A90C-2744820139B2}\InprocServer32

(Padrão) REG_EXPAND_SZ %ProgramFiles%\TestProvider\SampleAmsiProvider.dll

ThreadingModel REG_SZ ambos

Além do registro COM regular, você também precisa inscrever o provedor na AMSI. Você faz isso adicionando uma entrada à chave a seguir.

HKLM\SOFTWARE\Microsoft\AMSI\Providers

Por exemplo,

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\AMSI\Providers\{2E5D8A62-77F9-4F7B-A90C-2744820139B2}

Problemas conhecidos

O processo não atendia aos requisitos de nível de assinatura

Se você tiver um serviço antimalware que não seja da Microsoft que seja Windows PPL (Protected Process Light) ou PPL (Antimalware Protected Process Light) que tenta carregar em um provedor AMSI, poderá ver as seguintes informações no log de eventos de Integridade de Código:

 
Log Name: Microsoft-Windows-CodeIntegrity/Operational 

Source: Microsoft-Windows-CodeIntegrity 

Event ID: 3033 

Description: 

Code Integrity determined that a process (\Device\HarddiskVolume3\<Folder>\<Folder w/ the ISV name>\<Folder w/ the product name>\<ProcessName>.exe) attempted to load \Device\HarddiskVolume3\<Folder>\<Folder w/ the ISV name>\<Folder w/ the product name>\<Your Amsi Provider>.dll that did not meet the Custom 3 / Antimalware signing level requirements.

Para exibir o log de eventos de integridade do código, siga estas etapas:

Abra o Visualizador de Eventos.
No painel de navegação, expanda Logs>de Aplicativos e Serviços Integridade>>e selecione Operacional.

Ou, se você tiver a auditoria de integridade da auditoria do sistema habilitada, procure o seguinte:

Nome do log: Segurança
Fonte: Segurança do Microsoft Windows
ID do evento: 5038

Um hash de arquivo não é válido

As APIs amsi foram projetadas para trabalhar com processos não protegidos. IsV's não podem assinar suas DLLs registradas amsi para poder carregar em processos protegidos por ELAM/PPL. Nesses casos, você pode ver as seguintes informações no log de eventos de Segurança do Windows:


Description: 

Code integrity determined that the image hash of a file is not valid.  The file could be corrupt due to unauthorized modification, or the invalid hash could indicate a potential disk device error. 

File Name: \Device\HarddiskVolume3\<Folder> \<Folder w/ the ISV name> \<Folder w/ the product name>\<Your Amsi Provider>.dll

Para exibir o log de eventos de Segurança do Windows, siga estas etapas:

Abra o Visualizador de Eventos.
No painel Navegação, expanda de Logs do Windows e selecione Segurança.

Solução alternativa:

Você pode filtrar eventos seguindo estas etapas:

Para filtrar um evento, como a ID do Evento 3033 ou 5038, abra o Visualizador de Eventos.
No painel de navegação, expanda Logs>de Aplicativos e Serviços Integridade>>e selecione Operacional.
Clique com o botão direito do mouse Operacional e selecione Filtrar Log Atual....
Na caixa>Todas as IDs de Evento<, digite -3033 (ou -5038) e selecione OK.

Ou, no Visualizador de Eventos, você pode expandir logs do Windows, clicar com o botão direito do mouse em Segurança, selecionar Filtrar Log Atual...e especificar -3033 ou -5038.

Ponta

Se você estiver usando o WEF (Encaminhamento de Eventos do Windows), poderá filtrar detalhes de quais IDs de evento ou descrições são encaminhadas. Para obter mais informações, consulte Blog da Tech Community: Filtragem XML avançada no Visualizador de Eventos do Windows

Filtrar eventos 3033 e 5038 para seu SIEM

Se sua organização estiver usando um servidor SIEM, filtre a ID do Evento 3033 e/ou a ID de Evento 5038 específica para AMSI para que você não ingera informações que não sejam úteis para seus analistas do SOC (Centro de Operações de Segurança). Para obter mais informações, consulte Usar o Encaminhamento de Eventos do Windows para ajudar na detecção de intrusão.

Compartilhar via