Public du développeur et exemple de code

Article
01/06/2025

L’interface d’analyse anti-programme malveillant est conçue pour être utilisée par deux groupes de développeurs.

Développeurs d’applications qui souhaitent effectuer des demandes aux produits anti-programme malveillant à partir de leurs applications.
Créateurs tiers de produits anti-programme malveillant qui veulent que leurs produits offrent les meilleures fonctionnalités aux applications.

Développeurs d’applications

AMSI est conçu en particulier pour lutter contre les « programmes malveillants sans fichier ». Les types d’applications qui peuvent tirer le meilleur parti de la technologie AMSI incluent des moteurs de script, des applications nécessitant des mémoires tampons de mémoire à analyser avant de les utiliser et des applications qui traitent des fichiers qui peuvent contenir du code exécutable non PE (tels que des macros Microsoft Word et Excel ou des documents PDF). Toutefois, l’utilité de la technologie AMSI n’est pas limitée à ces exemples.

Il existe deux façons d’interagir avec AMSI dans votre application.

À l’aide des API AMSI Win32. Consultez les fonctions AMSI (Antimalware Scan Interface).
À l’aide des interfaces COM AMSI. Voir l’interface IAmsiStream.

Pour obtenir un exemple de code montrant comment utiliser AMSI dans votre application COM, consultez l’exemple d’application d’interface IAmsiStream.

Créateurs tiers de produits anti-programme malveillant

En tant que créateur de produits anti-programme malveillant, vous pouvez choisir de créer et d’inscrire votre propre serveur COM in-process (a DLL) pour fonctionner en tant que fournisseur AMSI. Ce fournisseur AMSI doit implémenter l’interface IAntimalwareProvider, et il doit exécuter in-process.

Notez que, après Windows 10, version 1709 (la mise à jour de Fall 2017 Creators), votre DLL du fournisseur AMSI peut ne pas fonctionner si elle dépend d’autres DLL dans son chemin d’accès à charger en même temps. Pour empêcher le détournement de DLL, nous vous recommandons de charger explicitement ses dépendances (avec un chemin complet) à l’aide d’appels LoadLibrary sécurisés ou équivalents. Nous vous recommandons de le faire au lieu de vous appuyer sur le comportement de recherche LoadLibrary .

La section ci-dessous montre comment inscrire votre fournisseur AMSI. Pour obtenir un exemple de code complet montrant comment créer votre propre DLL de fournisseur AMSI, consultez l’exemple d’application d’interface IAntimalwareProvider.

Inscrire votre DLL de fournisseur auprès d’AMSI

Pour commencer, vous devez vous assurer que ces clés de Registre Windows existent.

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

Un fournisseur AMSI est un serveur COM in-process. Par conséquent, il doit s’inscrire auprès de COM. Les classes COM sont inscrites dans HKLM\SOFTWARE\Classes\CLSID.

Le code ci-dessous montre comment inscrire un fournisseur AMSI dont le GUID (pour cet exemple) nous partons du principe 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;
}

Si votre DLL implémente la fonction DllRegisterServer, comme dans l’exemple ci-dessus, vous pouvez l’inscrire à l’aide de l’exécutable regsvr32.exefourni par Windows. À partir d’une invite de commandes avec élévation de privilèges, émettez une commande de ce formulaire.

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

Dans cet exemple, la commande crée les entrées suivantes.

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

(Par défaut) REG_SZ exemple d’implémentation du fournisseur AMSI

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

(Par défaut) REG_EXPAND_SZ %ProgramFiles%\TestProvider\SampleAmsiProvider.dll

ThreadingModel REG_SZ les deux

Outre l’inscription COM régulière, vous devez également inscrire le fournisseur auprès d’AMSI. Pour ce faire, ajoutez une entrée à la clé suivante.

HKLM\SOFTWARE\Microsoft\AMSI\Providers

Par exemple,

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

Problèmes connus

Le processus ne répondait pas aux exigences de niveau de signature

Si vous disposez d’un service anti-programme malveillant non Microsoft qui est Windows Protected Process Light (PPL) ou Antimalware Protected Process Light (PPL anti-programme malveillant) qui tente de charger dans un fournisseur AMSI, vous pouvez voir les informations suivantes dans le journal des événements Intégrité du code :

 
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.

Pour afficher le journal des événements Intégrité du code, procédez comme suit :

Ouvrez l’ Observateur d’événements.
Dans le volet de navigation, développez Applications et services journalise>l’intégrité>>, puis sélectionnez Opérationnel.

Si vous avez activé l’audit d’intégrité de l’audit du système, recherchez ceci :

Nom du journal : Sécurité
Source : Microsoft Sécurité Windows
ID d’événement : 5038

Un hachage de fichier n’est pas valide

Les API AMSI sont conçues pour fonctionner avec des processus non protégés. Les éditeurs de logiciels indépendants (ISV) ne peuvent pas signer leurs DLL inscrites auprès de l'AMSI pour pouvoir les charger dans des processus sécurisés par ELAM/PPL. Dans ce cas, vous pouvez voir les informations suivantes dans le journal des événements de sécurité 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

Pour afficher le journal des événements de sécurité Windows, procédez comme suit :

Ouvrez l’ Observateur d’événements.
Dans le volet de navigation, développez Journaux Windows, puis sélectionnez Sécurité.

Solution de contournement :

Vous pouvez filtrer les événements en procédant comme suit :

Pour filtrer un événement, tel que l’ID d’événement 3033 ou 5038, ouvrez l’Observateur d’événements.
Dans le volet de navigation, développez Applications et services journalise>l’intégrité>>, puis sélectionnez Opérationnel.
Cliquez avec le bouton droit sur En fonctionnement, puis sélectionnez Filtrer le journal actuel....
Dans la zone <Tous les ID d’événement>, tapez -3033 (ou -5038), puis sélectionnez OK.

Ou, dans l’Observateur d’événements, vous pouvez développer les journaux Windows, cliquer avec le bouton droit sur Sécurité, sélectionner Filtrer le journal actuel..., puis spécifier -3033 ou -5038.

Conseil

Si vous utilisez le transfert d’événements Windows (WEF), vous pouvez filtrer les détails des ID d’événement ou des descriptions transférés. Pour plus d’informations, consultez blog de la communauté technique : filtrage XML avancé dans l’observateur d’événements Windows

Filtrer les événements 3033 et 5038 pour votre SIEM

Si votre organisation utilise un serveur SIEM, veillez à filtrer l’ID d’événement 3033 et/ou l’ID d’événement 5038 spécifique à AMSI afin de ne pas ingérer les informations qui ne sont pas utiles pour vos analystes SOC (Security Operations Center). Pour plus d’informations, consultez Utiliser le transfert d’événements Windows pour faciliter la détection des intrusions.

Partager via