Cílová skupina vývojářů a ukázkový kód

Článek
12/20/2024

Antimalware Scan Interface je určen pro použití dvěma skupinami vývojářů.

Vývojáři aplikací, kteří chtějí ze svých aplikací provádět požadavky na antimalwarové produkty.
Tvůrci antimalwarových produktů třetích stran, kteří chtějí, aby jejich produkty nabízely nejlepší funkce aplikacím.

Vývojáři aplikací

AMSI je navržen především pro boj proti "malwaru bez souborů". Mezi typy aplikací, které mohou optimálně využívat technologii AMSI, patří skriptovací moduly, aplikace, které před jejich použitím potřebují vyrovnávací paměť, a aplikace zpracovávající soubory, které mohou obsahovat spustitelný kód jiného typu než PE (například makra Microsoft Wordu a Excelu nebo dokumenty PDF). Užitečnost technologie AMSI ale není omezena na tyto příklady.

Existují dva způsoby, jak ve své aplikaci komunikovat s AMSI.

Pomocí rozhraní API AMSI Win32. Viz funkce Antimalware Scan Interface (AMSI).
Pomocí rozhraní AMSI COM. Viz rozhraní IAmsiStream.

Ukázkový kód ukazující, jak využívat AMSI v rámci vaší aplikace COM, najdete v ukázkové aplikaci rozhraní IAmsiStream.

Tvůrci antimalwarových produktů třetích stran

Jako tvůrce antimalwarových produktů se můžete rozhodnout, že vytvoříte a zaregistrujete vlastní procesový server COM (knihovnu DLL), který bude fungovat jako poskytovatel AMSI. Tento zprostředkovatel AMSI musí implementovat IAntimalwareProvider rozhranía musí běžet v rámci procesu.

Mějte na paměti, že po systému Windows 10, verzi 1709 (Fall 2017 Creators' Update), nemusí knihovna DLL zprostředkovatele AMSI fungovat, pokud závisí na jiných knihovnách DLL v její cestě, které se mají načíst současně. Chcete-li zabránit napadení knihovny DLL, doporučujeme, aby knihovna zprostředkovatele načítala své závislosti explicitně (s úplnou cestou) pomocí zabezpečených volání LoadLibrary nebo ekvivalentních. Doporučujeme toto místo spoléhání se na chování hledání LoadLibrary.

Následující část ukazuje, jak zaregistrovat poskytovatele AMSI. Úplný vzorový kód, který ukazuje, jak naprogramovat vlastní knihovnu DLL zprostředkovatele AMSI, najdete v ukázkové aplikaci rozhraní IAntimalwareProvider.

Zaregistrujte knihovnu DLL poskytovatele u AMSI

Abyste mohli začít, musíte zajistit, aby tyto klíče registru systému Windows existovaly.

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

Zprostředkovatel AMSI je procesový server COM. V důsledku toho se musí sám zaregistrovat u COM. Třídy COM jsou registrovány v HKLM\SOFTWARE\Classes\CLSID.

Následující kód ukazuje, jak zaregistrovat zprostředkovatele AMSI, jehož identifikátor GUID (v tomto příkladu) předpokládáme, že je 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;
}

Pokud vaše knihovna DLL implementuje funkci DllRegisterServer, jak je uvedeno výše, můžete ji zaregistrovat pomocí spustitelného souboru zadaného systémem Windows regsvr32.exe. Z příkazového řádku se zvýšenými oprávněními zadejte příkaz v tomto formátu.

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

V tomto příkladu příkaz vytvoří následující položky.

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

(výchozí) REG_SZ ukázková implementace zprostředkovatele AMSI

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

(výchozí) REG_EXPAND_SZ %ProgramFiles%\TestProvider\SampleAmsiProvider.dll

ThreadingModel REG_SZ oba

Kromě běžné registrace modelu COM je také potřeba zaregistrovat poskytovatele v AMSI. Uděláte to tak, že přidáte položku do následujícího klíče.

HKLM\SOFTWARE\Microsoft\AMSI\Providers

Například

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

Známé problémy

Proces nesplněl požadavky na úroveň podepisování

Pokud máte antimalwarovou službu, která je Windows Protected Process Light (PPL) nebo Antimalware Protected Process Light (Antimalwarový Chráněný Proces Light), která se pokusí načíst jako poskytovatel AMSI, může se v protokolu událostí integrity kódu zobrazit následující informace:

 
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.

Pokud chcete zobrazit protokol událostí integrity kódu, postupujte takto:

Otevřete Prohlížeč událostí.
V navigačním podokně rozbalte Protokoly aplikací a služeb>Microsoft>Windows>Integrita kódu, a poté vyberte Provozní.

Nebo pokud máte povolené auditování integrity systému, vyhledejte toto:

Název protokolu: Zabezpečení
Zdroj: Zabezpečení systému Microsoft Windows
ID události: 5038

Hodnota hash souboru není platná.

Rozhraní API AMSI je navržené tak, aby fungovalo s nechráněnými procesy. ISV nejsou schopni podepsat své registrované knihovny DLL v AMSI, aby tyto mohly být načteny do procesů zabezpečených pomocí ELAM/PPL. V takových případech se v protokolu událostí zabezpečení systému Windows mohou zobrazit následující informace:


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

Pokud chcete zobrazit protokol událostí zabezpečení systému Windows, postupujte takto:

Otevřete Prohlížeč událostí.
V navigačním podokně rozbalte Protokoly systému Windowsa pak vyberte Zabezpečení.

Řešení problému:

Události můžete filtrovat pomocí následujícího postupu:

Pokud chcete vyfiltrovat událost, například ID události 3033 nebo 5038, otevřete Prohlížeč událostí.
V navigačním podokně rozbalte Protokoly aplikací a služeb>Microsoft>Windows>Integrita kódu, a poté vyberte Provozní.
Klikněte pravým tlačítkem na Provoznía pak vyberte Filtrovat aktuální protokol....
Do pole <Všechna ID událostí> zadejte -3033 (nebo -5038) a pak vyberte OK.

Nebo můžete v Prohlížeči událostí rozbalit protokoly systému Windows, klepněte pravým tlačítkem myši na položku Zabezpečení, vyberte Filtrovat aktuální protokol...a pak zadejte -3033 nebo -5038.

Spropitné

Pokud používáte předávání událostí systému Windows (WEF), můžete filtrovat podrobnosti, jaké ID nebo popisy událostí se přeposílají. Další informace najdete v blogu technické komunity: Pokročilé filtrování XML v prohlížeči událostí systému Windows

Vyfiltrujte události 3033 a 5038 pro siEM

Pokud vaše organizace používá server SIEM, nezapomeňte vyfiltrovat ID události 3033 nebo ID události 5038 specifické pro AMSI, abyste neingestovat informace, které nejsou užitečné pro analytiky SOC (Security Operations Center). Další informace naleznete v tématu Použití předávání událostí systému Windows k pomoci s detekcí neoprávněných vniknutí.

Sdílet prostřednictvím