開發人員物件和範例程序代碼

發行項
11/15/2024

Antimalware 掃描介面是專為兩組開發人員所設計。

想要從其應用程式內向反惡意代碼產品提出要求的應用程式開發人員。
想要其產品為應用程式提供最佳功能的反惡意代碼產品第三方建立者。

應用程式開發人員

AMSI 是特別設計來對抗「無檔案惡意代碼」。可以優化運用AMSI技術的應用程式類型包括腳本引擎、使用前需要掃描記憶體緩衝區的應用程式，以及處理可包含非PE可執行程式碼的應用程式（例如Microsoft Word 和 Excel 巨集或 PDF 檔案）。不過，AMSI 技術的實用性不限於這些範例。

有兩種方式可讓您在應用程式中與AMSI進行介面。

使用AMSI Win32 API。請參閱反惡意代碼掃描介面（AMSI）函式。
使用AMSI COM介面。請參閱 IAmsiStream 介面。

如需示範如何在 COM 應用程式中取用 AMSI 的範例程式代碼，請參閱 IAmsiStream 介面範例應用程式。

反惡意代碼產品的第三方建立者

身為反惡意代碼產品的建立者，您可以選擇撰寫並註冊自己的同進程 COM 伺服器（DLL），以作為AMSI提供者運作。該 AMSI 提供者必須實 作 IAntimalwareProvider 介面，而且必須在進程中執行。

請注意，在 Windows 10 版本 1709 （Fall 2017 Creators' Update）之後，如果您的 AMSI 提供者 DLL 相依於要同時載入路徑中的其他 DLL，您的 AMSI 提供者 DLL 可能無法運作。若要防止 DLL 劫持，建議您使用安全的 LoadLibrary 呼叫或對等專案，明確載入提供者 DLL 載入其相依性（含完整路徑）。建議您不要依賴 LoadLibrary 搜尋行為。

下一節說明如何註冊AMSI提供者。如需示範如何撰寫您自己的AMSI提供者 DLL 的完整範例程式代碼，請參閱 IAntimalwareProvider 介面範例應用程式。

向AMSI註冊您的提供者 DLL

首先，您必須確定這些 Windows 登錄機碼存在。

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

AMSI 提供者是進程內 COM 伺服器。因此，它需要向 COM 註冊自己。 COM 類別已在中 HKLM\SOFTWARE\Classes\CLSID註冊。

下列程式代碼示範如何註冊 AMSI 提供者，我們將假設其 GUID （在此範例中）是 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;
}

如果您的 DLL 實作 DllRegisterServer 函式，如上述範例所示，您可以使用 Windows 提供的可執行文件 regsvr32.exe來註冊它。從提升許可權的命令提示字元發出此表單的命令。

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

在此範例中，命令會建立下列專案。

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

（預設值）REG_SZ範例AMSI提供者實作

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

（預設值）REG_EXPAND_SZ %ProgramFiles%\TestProvider\SampleAmsiProvider.dll

ThreadingModel REG_SZ兩者

除了一般 COM 註冊之外，您也需要向 AMSI 註冊提供者。您可以藉由將專案新增至下列索引鍵來執行此動作。

HKLM\SOFTWARE\Microsoft\AMSI\Providers

例如，

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

已知問題

如果您有非Microsoft反惡意代碼服務，其為 Windows Protected Process Light （PPL）或 Antimalware Protected Process Light （Anti-malware PPL）嘗試載入 AMSI 提供者，您可能會在程式代碼完整性事件記錄檔中看到下列資訊：

 
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.

若要檢視程式代碼完整性事件記錄檔，請遵循下列步驟：

開啟 [事件檢視器]。
在瀏覽窗格中，展開 [應用程式和服務記錄>]>Microsoft [Windows>程序代碼完整性]，然後選取 [操作]。

或者，如果您已啟用系統稽核完整性稽核，請尋找下列專案：

記錄名稱：安全性
來源：Microsoft Windows 安全性
事件識別碼： 5038

共用方式為

開發人員物件和範例程序代碼

應用程式開發人員

反惡意代碼產品的第三方建立者

向AMSI註冊您的提供者 DLL

已知問題

意見反應

其他資源