Recall DLP Interfejs API dostawcy

Recall (wersja zapoznawcza) umożliwia użytkownikom wyszukiwanie lokalnie zapisanych i analizowanych migawek ekranu przy użyciu języka naturalnego. Recall integruje się z dostawcami ochrony przed utratą danych (DLP), aby zapobiec przechowywaniu poufnej zawartości na podstawie zasad organizacji. W tym artykule opisano publiczny interfejs API, który umożliwia Recall pracę z dowolnym DLP narzędziem.

Architektura systemu

Na poniższym diagramie przedstawiono sposób interakcji systemu Windows Recall z dostawcą DLP :

┌─────────────────────────────────────────────────────────────┐
│ Windows Recall                                              │
│ - Captures screenshots and app content                      │
│ - Queries DLP provider before capturing                     │
└─────────────────────┬───────────────────────────────────────┘
                      │ Query: Should we capture this window?
                      │ Context: Process, Window, File, Labels
                      ▼
┌─────────────────────────────────────────────────────────────┐
│ AIContext.exe Process                                       │
│                                                             │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Your DLP Provider DLL (loaded in-process)               │ │
│ │ - Evaluates organizational policies                     │ │
│ │ - Returns capture restrictions                          │ │
│ │ - Provides sensitivity label information                │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────┬───────────────────────────────────────┘
                      │ Response: Allow/Block/Warn/Audit
                      │ Labels: Sensitivity information
                      ▼
┌─────────────────────────────────────────────────────────────┐
│ Windows Recall                                              │
│ - Enforces returned restrictions                            │
│ - Displays sensitivity labels to user                       │
│ - Logs audit events as required                             │
└─────────────────────────────────────────────────────────────┘

Publiczne API

Struktury podstawowe

OgraniczenieEnforcement, wyliczenie

Definiuje poziom wymuszania dla określonego ograniczenia.

enum RestrictionEnforcement
{
    RestrictionEnforcement_Allow = 0,
    RestrictionEnforcement_AuditAndAllow = 1,
    RestrictionEnforcement_Warn = 2,
    RestrictionEnforcement_Block = 3,
};

Wartości:

• RestrictionEnforcement_Allow (0): operacja jest dozwolona bez ograniczeń.
• RestrictionEnforcement_AuditAndAllow (1): Operacja jest dozwolona, ale powinna być rejestrowana do celów inspekcji.
• RestrictionEnforcement_Warn (2): operacja wyświetla użytkownikowi ostrzeżenie przed kontynuowaniem.
• RestrictionEnforcement_Block (3): Operacja jest całkowicie blokowana.

Struktura ograniczeń

Określa poziom wymuszania dla różnych operacji.

struct Restrictions
{
    RestrictionEnforcement CopyToClipboard;
    RestrictionEnforcement CaptureInRecall;
};

Członków:

• CopyToClipboard: poziom wymuszania kopiowania zawartości do schowka.
• CaptureInRecall: poziom wymuszania przechwytywania zawartości w Recall migawkach.

SensitivityLabelDescription, struktura

Zawiera informacje o etykiecie poufności do wyświetlania użytkownikowi.

struct SensitivityLabelDescription
{
    LPCWSTR Name;
    LPCWSTR Color;
    LPCWSTR TooltipText;
    uint32_t Sensitivity;
};

Członków:

• Nazwa: Nazwa wyświetlana etykiety poufności (na przykład "Poufne").
• Kolor: kod koloru szesnastkowego dla reprezentacji wizualnej (na przykład "#FF0000").
• TooltipText: tekst opisowy wyświetlany po umieszczeniu wskaźnika myszy na etykiecie.
• Czułość: poziom poufności liczbowej (wyższe wartości wskazują większą czułość).

EnterpriseContextQuery, struktura

Zawiera informacje o żądaniu przechwytywania i odpowiedzi od dostawcy DLP .

struct EnterpriseContextQuery
{
    uint32_t ProcessId;
    uint64_t WindowHandle;
    LPCWSTR FileName;
    LPCWSTR SensitivityLabelId;
    LPCWSTR OrganizationId;
    SensitivityLabelDescription SensitivityLabelDescription;
    Restrictions Restrictions;
};

Członków:

• ProcessId: identyfikator procesu aplikacji do przechwycenia.
• WindowHandle: Uchwyt do przechwyconego okna.
• FileName: pełna ścieżka do pliku otwartego w aplikacji (jeśli ma to zastosowanie).
• SensitivityLabelId: identyfikator dowolnej istniejącej etykiety poufności.
• OrganizationId: identyfikator organizacji z bieżącego kontekstu użytkownika.
• SensitivityLabelDescription: informacje o etykiecie poufności do wyświetlenia (wypełnione przez dostawcę).
• Ograniczenia: ograniczenia przechwytywania, które mają być wymuszane (wypełniane przez dostawcę).

Wymagane eksporty bibliotek DLL

Biblioteka DLP DLL dostawcy musi wyeksportować te funkcje z dokładnymi nazwami pokazanymi:

EnterpriseContextProvider_QueryEnterpriseContext

Recall wywołuje tę funkcję w celu oceny żądań przechwytywania.

HRESULT STDMETHODCALLTYPE EnterpriseContextProvider_QueryEnterpriseContext(
    _In_ ULONG totalQuerySizeBytes,
    _Inout_updates_all_(totalQuerySizeBytes / sizeof(EnterpriseContextQuery)) EnterpriseContextQuery* queryBuffer);

Parametry:

• totalQuerySizeBytes: całkowity rozmiar buforu zapytania w bajtach.
• queryBuffer: wskaźnik do tablicy EnterpriseContextQuery struktur. Dostawca powinien zaktualizować Restrictions pola i SensitivityLabelDescription na podstawie zasad organizacyjnych.

Wartość zwracana:

• Zwraca wartość S_OK powodzenia lub odpowiedni HRESULT kod błędu w przypadku błędu.

Uwagi:

System Windows może wysyłać wiele zapytań jednocześnie w celu zwiększenia wydajności. Implementacja powinna przetwarzać wszystkie zapytania w buforze i aktualizować odpowiednie pola przed zwróceniem.

EnterpriseContextProvider_FlushEnterpriseContext

Recall okresowo wywołuje tę funkcję, aby umożliwić dostawcy zwalnianie buforowanych ciągów lub zasobów.

VOID STDMETHODCALLTYPE EnterpriseContextProvider_FlushEnterpriseContext();

Uwagi:

Recall wywołuje tę funkcję po przeanalizowaniu lub skopiowaniu danych z poprzedniej odpowiedzi zapytania. Użyj tej funkcji, aby cofnąć przydział wszystkich zasobów, wyczyścić pamięci podręczne lub wykonać operacje oczyszczania.

Rejestracja dostawcy

Konfiguracja rejestru (dostawca)

Instalacja DLP dostawcy tworzy wpis rejestru zawierający ścieżkę do biblioteki DLL:

HKEY_LOCAL_MACHINE\SOFTWARE\YourCompany\DLP
    InstallPath    REG_SZ    C:\Program Files\YourCompany\DLP

Zagadnienia dotyczące zabezpieczeń:

Wzmocnienie zabezpieczeń klucza rejestru, aby zapobiec nieautoryzowanej modyfikacji. Ustaw odpowiednie listy ACL, aby ograniczyć dostęp do zapisu tylko administratorom.

Konfiguracja zasad grupy (administrator)

Administratorzy konfigurują dostawcę za pomocą zasad grupy Ustaw dostawcę ochrony przed utratą danych :

• Nazwa zasad: SetDataLossPreventionProvider
• Lokalizacja zasad: Konfiguracja > komputera Szablony > administracyjne Składniki > systemu Windows AI
• Format wartości zasad: key:<REGISTRY_PATH>; value:<VALUE_NAME>; binary:<DLL_NAME>

Ważny: Pole value odwołuje się do nazwy wartości rejestru w kluczu rejestru określonym przez key.

Przykładowa konfiguracja:

W przypadku utworzenia wpisu rejestru przy użyciu polecenia:

reg add HKLM\Software\YourCompany\DLP -v InstallPath -t REG_SZ -d "C:\Program Files\YourCompany\DLP"

A biblioteka DLL ma nazwę YourCompanyDLP.dll, wartość zasad grupy to:

key:HKLM\software\YourCompany\DLP; value:InstallPath; binary:YourCompanyDLP.dll

Opcjonalne sprawdzanie wersji:

Możesz określić minimalną wymaganą wersję dostawcy DLP :

key:HKLM\software\YourCompany\DLP; value:InstallPath; binary:YourCompanyDLP.dll; minversion:1.2.0.0

Jeśli określisz minversionelement , ładuje plik binarny tylko wtedy, Recall gdy jego wersja jest równa lub większa niż określona wersja.

Przepływ przetwarzania zapytań

Typowa sekwencja interakcji

1. Windows Recall przygotowuje się do przechwytywania zawartości z okna aplikacji.

2. Recall Tworzy zapytania , które obejmują:

   • Identyfikator procesu i uchwyt okna aplikacji docelowej
   • Ścieżka pliku (jeśli aplikacja ma otwarty dokument)
   • Wszelkie istniejące informacje o etykiecie poufności
   • Identyfikator organizacji z bieżącego kontekstu użytkownika

3. Twój DLP Dostawca ocenia każde zapytanie względem zasad organizacji:

   • Sprawdzanie, czy aplikacja powinna zostać przechwycona
   • Weryfikowanie ograniczeń na poziomie pliku
   • Ocena etykiet poufności
   • Stosowanie zasad specyficznych dla użytkowników/grup

4. Dostawca zwraca zaktualizowane struktury zapytań za pomocą:

   • Restrictions.CaptureInRecall: Czy zezwalać, ostrzegać, przeprowadzać inspekcję lub blokować przechwytywanie
   • SensitivityLabelDescription: Nazwa etykiety, kolor i etykietka narzędzia do wyświetlania
   • Wszelkie inne istotne informacje o ograniczeniach

5. System Windows Recall wymusza zwracane ograniczenia:

   • Zezwalaj: przechwytuje normalnie
   • AuditAndAllow: przechwytuje i rejestruje akcję
   • Ostrzegaj: monituje użytkownika przed przechwyceniem
   • Blokuj: uniemożliwia całkowite przechwytywanie

Przykładowy scenariusz zapytania 1: Dokument programu Word z etykietą "Poufne"

Wkład:

• Proces: winword.exe
• Plik: SecretProject.docx
• Etykieta: Confidential

Przetwarzanie:

Sprawdź zasady klasyfikacji dokumentów względem reguł organizacyjnych.

Wyjście:

• CaptureInRecall: RestrictionEnforcement_Block
• SensitivityLabelDescription.Name: "Poufne — nie przechwytywane"

Przykładowy scenariusz zapytania 2: Przeglądarka internetowa w witrynie publicznej

Wkład:

• Proces: msedge.exe
• Okno: news.example.com

Przetwarzanie:

Sprawdź domenę pod kątem listy zatwierdzonych.

Wyjście:

• CaptureInRecall: RestrictionEnforcement_Allow

Przykładowy scenariusz zapytania 3: Aplikacja finansowa

Wkład:

• Proces: FinanceApp.exe
• Użytkownik: finance_user

Przetwarzanie:

Sprawdź ważność grupy użytkowników i aplikacji.

Wyjście:

• CaptureInRecall: RestrictionEnforcement_AuditAndAllow
• SensitivityLabelDescription.Name: "Dane finansowe — przeprowadź inspekcję"

Wytyczne dotyczące implementacji

Zagadnienia dotyczące wydajności

• Przetwarzanie wsadowe: system Windows może wysyłać wiele zapytań jednocześnie w celu zwiększenia wydajności. Zoptymalizuj kod w celu obsługi przetwarzania wsadowego.
• Buforowanie: decyzje dotyczące zasad pamięci podręcznej, jeśli są odpowiednie, aby poprawić czas odpowiedzi. Użyj funkcji do zarządzania cyklem FlushEnterpriseContext życia pamięci podręcznej.
• Operacje asynchroniczne: Unikaj blokowania operacji w funkcji zapytania. Wróć szybko, aby zapobiec wpływowi na środowisko użytkownika.

Obsługa błędów

• Zwróć odpowiednie HRESULT kody dla różnych warunków błędu.
• FlushEnterpriseContext Użyj funkcji , aby wyczyścić zasoby.
• Obsługa przypadków, w których informacje o zasadach są tymczasowo niedostępne bezpiecznie (domyślnie bezpieczne zachowanie).

Wymagania dotyczące zabezpieczeń

• In-Process wykonanie: biblioteka DLL jest uruchamiana w procesie AIContext.exe z podwyższonym poziomem uprawnień.
• Bezpieczne praktyki kodowania: postępuj zgodnie z bezpiecznymi rozwiązaniami dotyczącymi kodowania na potrzeby zarządzania pamięcią. Dokładnie zweryfikuj wszystkie parametry wejściowe.
• Podpisywanie cyfrowe: Biblioteka DLL musi być podpisana przez aplikację Authenticode do wdrożenia. Niepodpisane pliki binarne nie są ładowane.
• Ochrona rejestru: Wzmacnianie klucza rejestru określonego w zasadach grupy w celu zapobiegania nieautoryzowanym modyfikacjom.

Proces ładowania

Recall używa LoadLibraryEx metody do załadowania biblioteki DLL ze ścieżki określonej w rejestrze, a następnie wywołuje metodę GetProcAddress pobierania adresów wymaganych wyeksportowanych funkcji. Po wywołaniu metody QueryEnterpriseContextprogram Recall sprawdza i kopiuje dane z odpowiedzi, a następnie wywołuje wywołania FlushEnterpriseContext , aby umożliwić dostawcy bezpłatne przydzielone zasoby.

Wprowadzenie

Wykonaj następujące kroki, aby utworzyć i wdrożyć dostawcę DLP :

1. Opracuj bibliotekę DLL , implementując wymagane eksporty:

   • EnterpriseContextProvider_QueryEnterpriseContext
   • EnterpriseContextProvider_FlushEnterpriseContext

2. Przetestuj implementację za pomocą przykładowych zapytań, aby zapewnić prawidłowe zachowanie w różnych scenariuszach.

3. Podpisz plik binarny przy użyciu certyfikatu Authenticode.

4. Utwórz proces instalacji , który:

   • Instaluje bibliotekę DLL w bezpiecznej lokalizacji
   • Konfiguruje wpis rejestru z odpowiednimi listami ACL
   • Udostępnia narzędzia konfiguracji dla administratorów

5. Podaj instrukcje dotyczące zasad grupy dla administratorów w celu skonfigurowania SetDataLossPreventionProvider zasad.

6. Wdrażanie i konfigurowanie w środowisku przedsiębiorstwa.

Powiązane łącza

• Zarządzanie Recall dla klientów z systemem Windows
• Ustawianie zasad dostawcy ochrony przed utratą danych
• Ochrona przed utratą danych w Microsoft Purview