Destinatari per sviluppatori e codice di esempio

L'interfaccia di analisi antimalware è progettata per l'uso da parte di due gruppi di sviluppatori.

• Sviluppatori di applicazioni che vogliono effettuare richieste ai prodotti antimalware dall'interno delle app.
• Creatori di terze parti di prodotti antimalware che vogliono che i loro prodotti offrano le migliori funzionalità alle applicazioni.

Sviluppatori di applicazioni

AMSI è progettato in particolare per combattere il "malware senza file". I tipi di applicazione che possono sfruttare in modo ottimale la tecnologia AMSI includono motori di script, applicazioni che necessitano di buffer di memoria da analizzare prima di usarli e applicazioni che elaborano file che possono contenere codice eseguibile non PE (ad esempio macro di Microsoft Word ed Excel o documenti PDF). Tuttavia, l'utilità della tecnologia AMSI non è limitata a tali esempi.

Esistono due modi in cui è possibile interfacciarsi con AMSI nell'applicazione.

• Usando le API Win32 AMSI. Vedere Funzioni AMSI (Antimalware Scan Interface).
• Usando le interfacce COM AMSI. Vedere Interfaccia IAmsiStream.

Per il codice di esempio che illustra come usare AMSI all'interno dell'applicazione COM, vedere l'applicazione di esempio di interfaccia IAmsiStream.

Creatori di terze parti di prodotti antimalware

Come creatore di prodotti antimalware, è possibile scegliere di creare e registrare il proprio server COM in-process (una DLL) per funzionare come provider AMSI. Tale provider AMSI deve implementare l'interfaccia IAntimalwareProvider e deve essere eseguita in-process.

Tieni presente che, dopo Windows 10, versione 1709 (Fall 2017 Creators' Update), la DLL del provider AMSI potrebbe non funzionare se dipende da altre DLL nel percorso da caricare contemporaneamente. Per evitare il hijack delle DLL, è consigliabile che la DLL del provider carichi in modo esplicito le relative dipendenze (con un percorso completo) usando chiamate LoadLibrary sicure o equivalenti. È consigliabile invece di basarsi sul comportamento di ricerca LoadLibrary .

La sezione seguente illustra come registrare il provider AMSI. Per il codice di esempio completo che mostra come creare una DLL del provider AMSI personalizzata, vedere l'applicazione di esempio di interfaccia IAntimalwareProvider.

Registrare la DLL del provider con AMSI

Per iniziare, è necessario assicurarsi che queste chiavi del Registro di sistema di Windows esistano.

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

Un provider AMSI è un server COM in-process. Di conseguenza, deve registrarsi con COM. Le classi COM vengono registrate in HKLM\SOFTWARE\Classes\CLSID.

Il codice seguente illustra come registrare un provider AMSI, il cui GUID (per questo esempio) si presuppone che sia 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 la DLL implementa la funzione DllRegisterServer, come nell'esempio precedente, è possibile registrarla usando l'eseguibile regsvr32.exefornito da Windows . Da un prompt dei comandi con privilegi elevati eseguire un comando di questo modulo.

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

In questo esempio il comando crea le voci seguenti.

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

    (Impostazione predefinita) implementazione del provider AMSI di esempio REG_SZ

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

    (Impostazione predefinita) REG_EXPAND_SZ %ProgramFiles%\TestProvider\SampleAmsiProvider.dll

    ThreadingModel REG_SZ entrambi

Oltre alla regolare registrazione COM, è anche necessario registrare il provider con AMSI. A tale scopo, aggiungere una voce alla chiave seguente.

HKLM\SOFTWARE\Microsoft\AMSI\Providers

ad esempio:

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