Målgrupp för utvecklare och exempelkod

Artikel
12/20/2024

Gränssnittet för programgenomsökning mot skadlig kod är utformat för användning av två grupper av utvecklare.

Programutvecklare som vill göra begäranden till produkter mot skadlig kod från sina appar.
Tredjepartsskapare av produkter mot skadlig kod som vill att deras produkter ska erbjuda de bästa funktionerna till program.

Programutvecklare

AMSI är särskilt utformat för att bekämpa "fillös skadlig kod". Programtyper som optimalt kan utnyttja AMSI-teknik är skriptmotorer, program som behöver minnesbuffertar som ska genomsökas innan de används och program som bearbetar filer som kan innehålla körbar kod som inte kan köras av PE (till exempel Microsoft Word- och Excel-makron eller PDF-dokument). Amsi-teknikens användbarhet är dock inte begränsad till dessa exempel.

Det finns två sätt att interagera med AMSI i ditt program.

Genom att använda API:er för AMSI Win32. Se Antimalware Scan Interface (AMSI)-funktioner.
Med hjälp av AMSI COM-gränssnitten. Se IAmsiStream-gränssnitt.

Exempelkod som visar hur du använder AMSI i ditt COM-program finns i exempelprogrammet IAmsiStream-gränssnittet.

Tredjepartsskapare av produkter mot skadlig kod

Som skapare av produkter mot skadlig kod kan du välja att skapa och registrera din egen processbaserade COM-server (en DLL) för att fungera som AMSI-provider. Amsi-providern måste implementera IAntimalwareProvider-gränssnittetoch måste köras i processen.

Observera att efter Windows 10 version 1709 (fall 2017 Creators' Update) kanske din AMSI-provider-DLL inte fungerar om den är beroende av att andra DLL:er i dess sökväg läses in samtidigt. För att förhindra DLL-kapning rekommenderar vi att providerns DLL läser in dess beroenden explicit (med en fullständig sökväg) med hjälp av säkra LoadLibrary--anrop eller motsvarande. Vi rekommenderar detta istället för att förlita sig på LoadLibrary:s sökbeteende.

Avsnittet nedan visar hur du registrerar din AMSI-provider. Fullständig exempelkod som visar hur du skapar en egen AMSI-provider-DLL finns i exempelprogrammet IAntimalwareProvider-gränssnittet.

Registrera din provider-DLL med AMSI

Till att börja med måste du se till att dessa Windows-registernycklar finns.

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

En AMSI-tjänst är en intern COM-server. Därför måste den registrera sig hos COM. COM-klasser registreras i HKLM\SOFTWARE\Classes\CLSID.

Koden nedan visar hur du registrerar en AMSI-provider, vars GUID (i det här exemplet) vi antar är 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;
}

Om DLL-filen implementerar funktionen DllRegisterServer, som exemplet ovan gör, kan du registrera den med hjälp av den Windows-levererade körbara filen regsvr32.exe. Från en upphöjd kommandotolk, ange ett kommando i denna form.

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

I det här exemplet skapar kommandot följande poster.

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

(standard) REG_SZ exempelimplementering av AMSI-provider

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

(standard) REG_EXPAND_SZ %ProgramFiles%\TestProvider\SampleAmsiProvider.dll

ThreadingModel REG_SZ Båda

Förutom vanlig COM-registrering måste du också registrera providern med AMSI. Det gör du genom att lägga till ett element i följande nyckel.

HKLM\SOFTWARE\Microsoft\AMSI\Providers

Till exempel

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

Kända problem

Processen uppfyllde inte kraven på signeringsnivå

Om du har en icke-Microsoft-tjänst för program mot skadlig kod som Windows Protected Process Light (PPL) eller Antimalware Protected Process Light (Anti-malware PPL) som försöker ladda in i en AMSI-provider kan du se följande information i händelseloggen för Kodintegritet:

 
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.

Följ dessa steg för att visa händelseloggen för kodintegritet:

Öppna Händelsevisaren.
I navigeringsfönstret expanderar du Program- och tjänstloggar>Microsoft>Windows>Code Integrityoch väljer sedan Operational.

Om du har aktiverat granskning av systemgranskningsintegritet kan du söka efter följande:

Loggnamn: Säkerhet
Källa: Microsoft Windows Security
Händelse-ID: 5038

Filhashen är inte giltig

AMSI API:er är utformade för att fungera med icke-skyddade processer. ISV:er kan inte signera sina AMSI-registrerade DLL:er så att de kan läsas in i ELAM/PPL-skyddade processer. I sådana fall kan du se följande information i händelseloggen för Windows-säkerhet:


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

Följ dessa steg för att visa händelseloggen för Windows-säkerhet:

Öppna Händelsevisaren.
I navigeringsfönstret expanderar du Windows-loggaroch väljer sedan Säkerhet.

Lösning:

Du kan filtrera bort händelser genom att följa dessa steg:

Om du vill filtrera bort en händelse, till exempel Händelse-ID 3033 eller 5038, öppnar du Loggboken.
I navigeringsfönstret expanderar du Program- och tjänstloggar>Microsoft>Windows>Code Integrityoch väljer sedan Operational.
Högerklicka på Operationaloch välj sedan Filtrera aktuell logg....
I rutan <Alla händelse-ID:er> skriver du -3033 (eller -5038) och väljer sedan OK.

Eller expandera Windows-loggar i Händelsevisaren, högerklicka på Säkerhet, välj Filtrera aktuell logg...och sedan ange -3033 eller -5038.

Tips

Om du använder Windows Event Forwarding (WEF) kan du filtrera information om vilka händelse-ID:er eller beskrivningar som vidarebefordras. Mer information finns i Tech Community Blogg: Avancerad XML-filtrering i Windows Händelsevyn

Filtrera bort händelser 3033 och 5038 för SIEM

Om din organisation använder en SIEM-server ska du filtrera bort händelse-ID 3033 och/eller händelse-ID 5038 som är specifikt för AMSI så att du inte matar in information som inte är användbar för dina SOC-analytiker (Security Operations Center). Mer information finns i Använda Vidarebefordran av Windows-händelser för att hjälpa till med intrångsidentifiering.

Dela via