Udostępnij za pośrednictwem


Dokumentacja interfejsu API zarządzania alertami dla lokalnych konsol zarządzania

W tym artykule wymieniono interfejsy API REST zarządzania alertami obsługiwane dla Microsoft Defender dla lokalnych konsol zarządzania IoT.

alerty (pobieranie informacji o alertach)

Ten interfejs API służy do pobierania wszystkich lub filtrowanych alertów z lokalnej konsoli zarządzania.

Identyfikator URI: /external/v1/alerts lub /external/v2/alerts

GET

Parametry zapytania:

Nazwa Opis Przykład Wymagane/opcjonalne
Państwa Pobierz tylko obsługiwane lub nieobsługiwane alerty. Obsługiwane wartości:
- handled
- unhandled
Wszystkie inne wartości są ignorowane.
/api/v1/alerts?state=handled Opcjonalne
fromTime Pobierz alerty utworzone od danego czasu w milisekundach z czasu epoki i w strefie czasowej UTC. /api/v1/alerts?fromTime=<epoch> Opcjonalne
toTime Pobierz alerty utworzone tylko wcześniej w danym momencie w milisekundach w czasie epoki i w strefie czasowej UTC. /api/v1/alerts?toTime=<epoch> Opcjonalne
siteId Witryna, w której wykryto alert. /api/v1/alerts?siteId=1 Opcjonalne
zoneId Strefa, w której wykryto alert. /api/v1/alerts?zoneId=1 Opcjonalne
sensorId Czujnik, na którym wykryto alert. /api/v1/alerts?sensorId=1 Opcjonalne

Uwaga

Być może nie masz identyfikatora witryny i strefy. W takim przypadku należy najpierw wysłać zapytanie do wszystkich urządzeń w celu pobrania identyfikatora witryny i strefy. Aby uzyskać więcej informacji, zobacz Dokumentacja interfejsu API integracji dla lokalnych konsol zarządzania (publiczna wersja zapoznawcza).

UUID (Zarządzanie alertami na podstawie identyfikatora UUID)

Ten interfejs API umożliwia podjęcie określonej akcji dotyczącej określonego alertu wykrytego przez usługę Defender for IoT.

Za pomocą tego interfejsu API można na przykład utworzyć regułę przekazywania przekazującą dane do usługi QRadar. Aby uzyskać więcej informacji, zobacz Integrowanie narzędzia Qradar z Microsoft Defender dla IoT.

Identyfikator URI: /external/v1/alerts/<UUID>

PUT

Typ: JSON

Parametry zapytania:

Nazwa Opis Przykład Wymagane /Opcjonalne
UUID Definiuje uniwersalny unikatowy identyfikator (UUID) dla alertu, który chcesz obsługiwać lub obsługiwać i uczyć się. /api/v1/alerts/7903F632-H7EJ-4N69-F40F-4B1E689G00Q0 Wymagane

Parametry treści

Nazwa Opis Przykład Wymagane /Opcjonalne
Działania Ciąg Albo handle lub handleAndLearn Wymagane

Przykład żądania

{
    "action": "handle"
}

maintenanceWindow (Tworzenie wykluczeń alertów)

Zarządza oknami obsługi, w których alerty nie będą wysyłane. Ten interfejs API służy do definiowania i aktualizowania czasów zatrzymania i uruchamiania, urządzeń lub podsieci, które należy wykluczyć podczas wyzwalania alertów, lub zdefiniować i zaktualizować aparaty usługi Defender for IoT, które powinny zostać wykluczone.

Na przykład w oknie obsługi można zatrzymać dostarczanie alertów wszystkich alertów, z wyjątkiem alertów dotyczących złośliwego oprogramowania na krytycznych urządzeniach.

Okna obsługi zdefiniowane za pomocą interfejsu maintenanceWindow API są wyświetlane w oknie Wykluczenia alertów lokalnej konsoli zarządzania jako reguła wykluczania tylko do odczytu o nazwie z następującą składnią: Maintenance-{token name}-{ticket ID}.

Ważne

Ten interfejs API jest obsługiwany tylko do celów konserwacji i przez ograniczony czas i nie ma być używany zamiast reguł wykluczania alertów. Ten interfejs API służy tylko do jednorazowych operacji konserwacji tymczasowej.

Identyfikator URI: /external/v1/maintenanceWindow

POST

Tworzy nowe okno obsługi.

Parametry treści:

Nazwa Opis Przykład Wymagane /Opcjonalne
ticketId Ciąg. Definiuje identyfikator biletu obsługi w systemach użytkownika. Upewnij się, że identyfikator biletu nie jest połączony z istniejącym otwartym oknem. 2987345p98234 Wymagane
Ttl Dodatnia liczba całkowita. Definiuje czas wygaśnięcia (czas wygaśnięcia), czyli czas trwania okna obsługi w minutach. Po zakończeniu zdefiniowanego okresu okno obsługi jest w toku, a system działa normalnie ponownie. 180 Wymagane
Silniki Tablica ciągów w formacie JSON. Definiuje aparat pomijający alerty w oknie obsługi. Możliwe wartości:

- ANOMALY
- MALWARE
- OPERATIONAL
- POLICY_VIOLATION
- PROTOCOL_VIOLATION
ANOMALY,OPERATIONAL Opcjonalne
sensorIds Tablica ciągów w formacie JSON. Określa, które czujniki mają pomijać alerty podczas okna obsługi. Te identyfikatory czujników można uzyskać z interfejsu API urządzeń (zarządzanie urządzeniami czujników OT ). 1,35,63 Opcjonalne
Podsieci Tablica ciągów w formacie JSON. Definiuje podsieci do pomijania alertów w oknie obsługi. Zdefiniuj każdą podsieć w notacji CIDR. 192.168.0.0/16,138.136.80.0/14,112.138.10.0/8 Opcjonalne

DELETE

Zamyka istniejące okno obsługi.

Parametry zapytania:

Nazwa Opis Przykład Wymagane/opcjonalne
ticketId Definiuje identyfikator biletu konserwacji w systemach użytkownika. Upewnij się, że identyfikator biletu jest połączony z istniejącym otwartym oknem. 2987345p98234 Wymagane

GET

Pobierz dziennik wszystkich otwartych (POST), zamknij (DELETE) i zaktualizuj (PUT) akcje, które zostały wykonane przy użyciu tego interfejsu API do obsługi okien obsługi. T

Parametry zapytania:

Nazwa Opis Przykład Wymagane/opcjonalne
fromDate Filtruje dzienniki ze wstępnie zdefiniowanej daty i później. Format to YYYY-MM-DD. 2022-08-10 Opcjonalne
toDate Filtruje dzienniki do wstępnie zdefiniowanej daty. Format to YYYY-MM-DD. 2022-08-10 Opcjonalne
ticketId Filtruje dzienniki związane z określonym identyfikatorem biletu. 9a5fe99c-d914-4bda-9332-307384fe40bf Opcjonalne
tokenName Filtruje dzienniki powiązane z określoną nazwą tokenu. kwartalne okno sanity Opcjonalne

Kody błędów:

Kod Komunikat Opis
200 OK Akcja została pomyślnie ukończona.
204: Brak zawartości Brak danych do pokazania.
400 Nieprawidłowe żądanie Format daty jest niepoprawny.
500 Wewnętrzny błąd serwera Wszelkie inne nieoczekiwane błędy.

PUT

Umożliwia zaktualizowanie czasu trwania okna obsługi po rozpoczęciu procesu konserwacji przez zmianę parametru ttl . Nowa definicja czasu trwania zastępuje poprzednią definicję.

Ta metoda jest przydatna, gdy chcesz ustawić dłuższy czas trwania niż aktualnie skonfigurowany czas trwania. Na przykład jeśli pierwotnie zdefiniowano 180 minut, minęło 90 minut i chcesz dodać kolejne 30 minut, zaktualizuj ttl wartość do 120 minuty, aby zresetować liczbę czasu trwania.

Parametry zapytania:

Nazwa Opis Przykład Wymagane /Opcjonalne
ticketId Ciąg. Definiuje identyfikator biletu obsługi w systemach użytkownika. 2987345p98234 Wymagane
Ttl Dodatnia liczba całkowita. Definiuje czas trwania okna w minutach. 210 Wymagane

pcap (Żądanie alertu PCAP)

Użyj tego interfejsu API, aby zażądać pliku PCAP powiązanego z alertem.

Identyfikator URI: /external/v2/alerts/

GET

Parametry zapytania:

Nazwa Opis Przykład Wymagane /Opcjonalne
id Identyfikator alertu z lokalnej konsoli zarządzania /external/v2/alerts/pcap/<id> Wymagane

Następne kroki

Aby uzyskać więcej informacji, zobacz Omówienie interfejsu API usługi Defender for IoT.