Público do desenvolvedor e código de exemplo

Artigo
12/19/2024

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

Programadores de aplicações que pretendam fazer pedidos a produtos antimalware a partir das suas aplicações.
Criadores terceirizados de produtos antimalware que querem que seus produtos ofereçam os melhores recursos para aplicativos.

Programadores de aplicações

AMSI é projetado em particular para combater "malware sem arquivo". Os tipos de aplicativos que podem aproveitar a tecnologia AMSI de forma ideal incluem mecanismos de script, aplicativos que precisam de buffers de memória para serem 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 pelas quais você pode interagir com o AMSI em seu aplicativo.

Ao usar as APIs AMSI Win32. Consulte funções Antimalware Scan Interface (AMSI) .
Usando as interfaces AMSI COM. Consulte a interface IAmsiStream.

Para obter um código de exemplo que mostre como consumir AMSI na sua aplicação COM, consulte o exemplo de aplicação da 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 o IAntimalwareProvider interfacee deve ser executado no processo.

Tenha em conta que, após o Windows 10, versão 1709 (a Atualização para Criadores de Outono de 2017), a DLL do fornecedor AMSI pode não funcionar se depender de outras DLLs no seu caminho a serem carregadas ao mesmo tempo. Para evitar o sequestro de DLL, recomendamos que a DLL do seu provedor carregue suas dependências explicitamente (com um caminho completo) usando chamadas seguras LoadLibrary ou equivalente. Recomendamos isso em vez de confiar no comportamento de pesquisa do 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 .

Registe-se a DLL do seu fornecedor com o AMSI

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

HKLM\SOFTWARE\Microsoft\AMSI\Provedores
HKLM\SOFTWARE\Classes\CLSID

Um provedor AMSI é um servidor COM em processo. Por conseguinte, deve registar-se na COM. As classes COM são registradas em HKLM\SOFTWARE\Classes\CLSID.

O código abaixo mostra como registrar um provedor AMSI, cujo GUID (para este exemplo) assumiremos ser 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 sua DLL implementa a função DllRegisterServer, como o exemplo acima faz, então você pode registrá-lo usando o regsvr32.exeexecutável fornecido pelo Windows . Em um prompt de comando elevado, emita um comando deste tipo.

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 Implementação do Provedor AMSI de Exemplo

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 registrar o provedor com AMSI. Para fazer isso, adicione uma entrada à seguinte chave.

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 atendeu aos requisitos de nível de assinatura

Se você tiver um serviço antimalware que não seja da Microsoft PPL (Windows Protected Process Light) ou Antimalware Protected Process Light (PPL antimalware) que tente carregar em um provedor AMSI, poderá ver as seguintes informações no log de eventos de integridade do 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 de código, execute estas etapas:

Abra o Visualizador de Eventos.
No painel de navegação, expanda Logs de Aplicações e Serviços>Microsoft>Windows>Code Integritye selecione Operacional.

Ou, se tiver a auditoria de integridade 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 são projetadas para trabalhar com processos não protegidos. Os ISVs não conseguem assinar suas DLL's registadas no AMSI para poderem ser carregadas em processos protegidos por ELAM/PPL. Nesses casos, poderá ver as seguintes informações no registo 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 visualizar o registo de eventos de Segurança do Windows, siga estes passos:

Abra o Visualizador de Eventos.
No painel de Navegação, expanda Logs do Windowse, em seguida, selecione Segurança.

Solução alternativa:

Você pode filtrar eventos seguindo estas etapas:

Para filtrar um evento, como a ID de Evento 3033 ou 5038, abra o Visualizador de Eventos.
No painel de navegação, expanda Registos de Aplicações e Serviços>Microsoft>Windows>Code Integritye, em seguida, selecione Operacional.
Clique com o botão direito do rato Operacional e, em seguida, selecione Filtrar Registo Atual....
Na caixa <Todos os IDs de Evento>, digite -3033 (ou -5038) e selecione OK.

Ou, no Visualizador de Eventos, pode expandir Registos do Windows, clicar com o botão direito do rato em Segurança, selecionar Filtrar Registo Atual...e, em seguida, especificar -3033 ou -5038.

Dica

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

Filtre os Eventos 3033 e 5038 para o seu SIEM

Se sua organização estiver usando um servidor SIEM, certifique-se de filtrar a ID de Evento 3033 e/ou a ID de Evento 5038 específicas para AMSI para que você não ingira informações que não sejam úteis para seus analistas do Security Operations Center (SOC). Para obter mais informações, consulte Usar o Encaminhamento de Eventos do Windows para ajudar com a deteção de intrusões.

Partilhar via