Dokumentacja interfejsu API zarządzania alertami dla lokalnych konsol zarządzania
Artykuł 04/11/2023
Współautorzy: 3
Opinia
W tym artykule
W tym artykule wymieniono interfejsy API REST zarządzania alertami obsługiwane dla Microsoft Defender dla lokalnych konsol zarządzania IoT.
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
Typ : JSON
Lista alertów z następującymi polami:
Nazwa
Typ
Dopuszczanie wartości null/brak wartości null
Lista wartości
Identyfikator
Numeryczny
Nie można pustoć
-
sensorId
Numeryczny
Nie można pustoć
-
zoneId
Numeryczny
Nie można pustoć
-
Czas
Numeryczny
Nie można pustoć
Milisekundy czasu epoki w strefie czasowej UTC
title
Ciąg
Nie można pustoć
-
message
Ciąg
Nie można pustoć
-
Ważności
Ciąg
Nie można pustoć
Warning
, , Minor
Major
lubCritical
Silnika
Ciąg
Nie można pustoć
Protocol Violation
, , Policy Violation
, Malware
, Anomaly
lub Operational
sourceDevice
Numeryczny
Dopuszczający wartość null
Identyfikator urządzenia
destinationDevice
Numeryczny
Dopuszczający wartość null
Identyfikator urządzenia
remediationSteps
Ciąg
Dopuszczający wartość null
Kroki korygowania wyświetlane w alercie
additionalInformation
Obiekt dodatkowych informacji
Dopuszczający wartość null
-
Obsługiwane
Wartość logiczna, stan alertu
Nie można pustoć
true
lub false
Dodatkowe pola informacji :
Nazwa
Typ
Dopuszczanie wartości null/brak wartości null
Lista wartości
opis
Ciąg
Nie można pustoć
-
Informacji
Tablica JSON
Nie można pustoć
Ciąg
Dodano dla wersji 2 :
Nazwa
Typ
Nullable /Not nullable
Lista wartości
sourceDeviceAddress
Ciąg
Dopuszczający wartość null
Adres IP lub ADRES MAC
destinationDeviceAddress
Ciąg
Dopuszczający wartość null
Adres IP lub ADRES MAC
remediationSteps
Tablica JSON
Nie można pustoć
Ciągi, kroki korygowania opisane w alercie
sensorName
Ciąg
Nie można pustoć
Nazwa czujnika zdefiniowanego przez użytkownika
Nazwa_strefy
Ciąg
Nie można pustoć
Nazwa strefy skojarzonej z czujnikiem
Sitename
Ciąg
Nie można pustoć
Nazwa lokacji skojarzonej z czujnikiem
Aby uzyskać więcej informacji, zobacz Dokumentacja wersji interfejsu API czujnika .
Przykład odpowiedzi
[
{
"engine": "Operational",
"handled": false,
"title": "Traffic Detected on sensor Interface",
"additionalInformation": null,
"sourceDevice": 0,
"zoneId": 1,
"siteId": 1,
"time": 1594808245000,
"sensorId": 1,
"message": "The sensor resumed detecting network traffic on ens224.",
"destinationDevice": 0,
"id": 1,
"severity": "Warning"
},
{
"engine": "Anomaly",
"handled": false,
"title": "Address Scan Detected",
"additionalInformation": null,
"sourceDevice": 4,
"zoneId": 1,
"siteId": 1,
"time": 1594808260000,
"sensorId": 1,
"message": "Address scan detected.\nScanning address: 10.10.10.22\nScanned subnet: 10.11.0.0/16\nScanned addresses: 10.11.1.1, 10.11.20.1, 10.11.20.10, 10.11.20.100, 10.11.20.2, 10.11.20.3, 10.11.20.4, 10.11.20.5, 10.11.20.6, 10.11.20.7...\nIt is recommended to notify the security officer of the incident.",
"destinationDevice": 0,
"id": 2,
"severity": "Critical"
},
{
"engine": "Operational",
"handled": false,
"title": "Suspicion of Unresponsive MODBUS Device",
"additionalInformation": null,
"sourceDevice": 194,
"zoneId": 1,
"siteId": 1,
"time": 1594808285000,
"sensorId": 1,
"message": "Outstation device 10.13.10.1 (Protocol Address 53) seems to be unresponsive to MODBUS requests.",
"destinationDevice": 0,
"id": 3,
"severity": "Minor"
}
]
Typ : GET
Interfejs API :
curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<>IP_ADDRESS>/external/v1/alerts?state=&zoneId=&fromTime=&toTime=&siteId=&sensor='
Przykład:
curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/external/v1/alerts?state=unhandled&zoneId=1&fromTime=0&toTime=1594551777000&siteId=1&sensor=1'
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"
}
Typ : JSON
Tablica obiektów JSON reprezentujących urządzenia.
Pola odpowiedzi :
Nazwa
Typ
Wymagane /Opcjonalne
Opis
zawartość/błąd
Ciąg
Wymagane
Jeśli żądanie zakończy się pomyślnie, zostanie wyświetlona właściwość zawartości. W przeciwnym razie zostanie wyświetlona właściwość błędu.
Możliwe wartości zawartości :
Kod stanu
Komunikat
Opis
200
Żądanie aktualizacji alertu zakończyło się pomyślnie.
Żądanie aktualizacji zakończyło się pomyślnie. Brak komentarzy.
200
Alert został już obsłużony (obsługa ).
Alert został już obsłużony, gdy odebrano żądanie obsługi alertu. Alert pozostaje obsługiwany .
200
Alert został już obsłużony i poznany (handleAndLearn ).
Alert został już obsłużony i dowiedział się, kiedy odebrano żądanie obsługi elementuAndLearn . Alert pozostaje w stanie obsłużonymAndLearn .
200
Alert został już obsłużony (obsługiwany ). Obsługa i nauka (handleAndLearn ) została wykonana w alercie.
Alert został już obsłużony, gdy odebrano żądanie obsługi elementuAndLearn . Alert staje się handleAndLearn .
200
Alert został już obsłużony i poznany (handleAndLearn ). Zignorowano żądanie obsługi.
Alert był już obsługiwany przez usługęAndLearn , gdy odebrano żądanie obsługi alertu. Alert pozostaje w obsłudzeAndLearn .
500
Nieprawidłowa akcja.
Akcja, która została wysłana, nie jest prawidłową akcją do wykonania w alercie.
500
Wystąpił nieoczekiwany błąd.
Wystąpił nieoczekiwany błąd. Aby rozwiązać ten problem, skontaktuj się z pomocą techniczną.
500
Nie można wykonać żądania, ponieważ nie znaleziono alertu dla tego identyfikatora UUID.
Określony identyfikator UUID alertu nie został znaleziony w systemie.
Przykład odpowiedzi: Powodzenie
{
"content": "Alert update request finished successfully"
}
Przykład odpowiedzi: Niepowodzenie
{
"error": "Invalid action"
}
Typ : PUT
Interfejsy API :
curl -k -X PUT -d '{"action": "<ACTION>"}' -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/external/v1/alerts/<UUID>
Przykład:
curl -k -X PUT -d '{"action": "handle"}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/alerts/1-1594550943000
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
Kod stanu
Komunikat
Opis
201 (utworzono)
-
Akcja została pomyślnie ukończona.
400 (Nieprawidłowe żądanie)
Brak identyfikatora biletu
Brak wartości żądania interfejsu ticketId
API.
400 (Nieprawidłowe żądanie)
Niedozwolony czas wygaśnięcia
Żądanie interfejsu API obejmowało wartość czasu wygaśnięcia nie dodatniego lub nieliczbowego.
400 (Nieprawidłowe żądanie)
Nie można przeanalizować żądania.
Problem z analizowaniem treści, na przykład nieprawidłowymi parametrami lub nieprawidłowymi wartościami.
400 (Nieprawidłowe żądanie)
Okno obsługi z tymi samymi parametrami już istnieje.
Pojawia się, gdy istniejące okno obsługi już istnieje z tymi samymi szczegółami.
404 (nie znaleziono)
Nieznany identyfikator czujnika
Jeden z czujników wymienionych w żądaniu nie istnieje.
409 (konflikt)
Identyfikator biletu ma już otwarte okno.
Identyfikator biletu jest połączony z innym otwartym oknem obsługi.
500 (wewnętrzny błąd serwera)
-
Inny nieoczekiwany błąd.
Typ : POST
Interfejs API :
curl -k -X POST -d '{"ticketId": "<TICKET_ID>",ttl": <TIME_TO_LIVE>,"engines": [<ENGINE1, ENGINE2...ENGINEn>],"sensorIds": [<SENSOR_ID1, SENSOR_ID2...SENSOR_IDn>],"subnets": [<SUBNET1, SUBNET2....SUBNETn>]}' -H "Authorization: <AUTH_TOKEN>" https://<IP address>/external/v1/maintenanceWindow
Przykład:
curl -k -X POST -d '{"ticketId": "a5fe99c-d914-4bda-9332-307384fe40bf","ttl": "20","engines": ["ANOMALY"],"sensorIds": ["5","3"],"subnets": ["10.0.0.0/16"]}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/maintenanceWindow
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
Kody błędów :
Kod
Komunikat
Opis
200 (OK)
-
Akcja została pomyślnie ukończona.
400 (Nieprawidłowe żądanie)
Brak identyfikatora biletu
Brak parametru ticketId w żądaniu.
404 (nie znaleziono) :
Nie można odnaleźć okna obsługi.
Identyfikator biletu nie jest połączony z otwartym oknem obsługi.
500 (Wewnętrzny błąd serwera)
-
Wszelkie inne nieoczekiwane błędy.
Typ : DELETE
Interfejs API :
curl -k -X DELETE -d '{"ticketId": "<TICKET_ID>"}' -H "Authorization: <AUTH_TOKEN>" https://<IP address>/external/v1/maintenanceWindow
Przykład:
curl -k -X DELETE -d '{"ticketId": "a5fe99c-d914-4bda-9332-307384fe40bf"}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/maintenanceWindow
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.
Typ : JSON
Tablica obiektów JSON reprezentujących operacje okna obsługi.
Struktura odpowiedzi :
Nazwa
Typ
Dopuszczanie wartości null/brak wartości null
Lista wartości
id
Długa liczba całkowita
Nie można pustoć
Wewnętrzny identyfikator bieżącego dziennika
Datetime
Ciąg
Nie można pustoć
Czas wystąpienia działania, na przykład: 2022-04-23T18:25:43.511Z
ticketId
Ciąg
Nie można pustoć
Identyfikator okna obsługi. Na przykład: 9a5fe99c-d914-4bda-9332-307384fe40bf
tokenName
Ciąg
Nie można pustoć
Nazwa tokenu okna obsługi. Na przykład: quarterly-sanity-window
Silniki
Tablica ciągów
Dopuszczający wartość null
Aparaty, na których stosuje się okno obsługi, zgodnie z informacjami podanymi podczas tworzenia okna obsługi: Protocol Violation
, Policy Violation
, , Malware
lub Anomaly
Operational
sensorIds
Tablica ciągów
Dopuszczający wartość null
Czujniki, na których stosuje się okno obsługi, zgodnie z informacjami dostarczonymi podczas tworzenia okna obsługi.
Podsieci
Tablica ciągów
Dopuszczający wartość null
Podsieci, w których ma zastosowanie okno obsługi, zgodnie z informacjami podanymi podczas tworzenia okna obsługi.
Ttl
Numeryczny
Dopuszczający wartość null
Czas wygaśnięcia okna obsługi (TTL), zgodnie z informacjami podanymi podczas tworzenia lub aktualizowania okna obsługi.
Operationtype
Ciąg
Nie można pustoć
Jedna z następujących wartości: OPEN
, UPDATE
i CLOSE
Typ : GET
Interfejs API :
curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/external/v1/maintenanceWindow?fromDate=&toDate=&ticketId=&tokenName='
Przykład:
curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/external/v1/maintenanceWindow?fromDate=2020-01-01&toDate=2020-07-14&ticketId=a5fe99c-d914-4bda-9332-307384fe40bf&tokenName=a'
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
Kody błędów :
Kod
Komunikat
Opis
200 (OK)
-
Akcja została pomyślnie ukończona.
400 (Nieprawidłowe żądanie)
Brak identyfikatora biletu
W żądaniu brakuje ticketId
wartości.
400 (Nieprawidłowe żądanie)
Niedozwolony czas wygaśnięcia
Zdefiniowany czas wygaśnięcia nie jest liczbowy lub nie jest dodatnią liczbą całkowitą.
400 (Nieprawidłowe żądanie)
Nie można przeanalizować żądania
W żądaniu brakuje wartości parametru ttl
.
404 (nie znaleziono)
Nie znaleziono okna obsługi
Identyfikator biletu nie jest połączony z otwartym oknem obsługi.
500 (wewnętrzny błąd serwera)
-
Inny nieoczekiwany błąd.
Typ : PUT
Interfejs API :
curl -k -X PUT -d '{"ticketId": "<TICKET_ID>",ttl": "<TIME_TO_LIVE>"}' -H "Authorization: <AUTH_TOKEN>" https://<IP address>/external/v1/maintenanceWindow
Przykład:
curl -k -X PUT -d '{"ticketId": "a5fe99c-d914-4bda-9332-307384fe40bf","ttl": "20"}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/maintenanceWindow
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
Typ : JSON
Ciąg komunikatu ze szczegółami stanu operacji:
Kod stanu
Komunikat
Opis
200 (OK)
-
Obiekt JSON z danymi dotyczącymi żądanego pliku PCAP. Aby uzyskać więcej informacji, zobacz Pola danych .
500 (wewnętrzny błąd serwera)
Nie znaleziono alertu
Podany identyfikator alertu nie został znaleziony w lokalnej konsoli zarządzania.
500 (wewnętrzny błąd serwera)
Błąd podczas pobierania tokenu dla identyfikatora xsense <number>
Wystąpił błąd podczas pobierania tokenu czujnika dla określonego identyfikatora czujnika
500 (wewnętrzny błąd serwera)
-
Inny nieoczekiwany błąd.
Pola danych
Nazwa
Typ
Nullable /Not nullable
Lista wartości
id
Numeryczny
Nie można pustoć
Identyfikator alertu lokalnej konsoli zarządzania
xsenseId
Numeryczny
Nie można pustoć
Identyfikator czujnika
xsenseAlertId
Numeryczny
Nie można pustoć
Identyfikator alertu konsoli czujnika
downloadUrl
Ciąg
Nie można pustoć
Adres URL używany do pobierania pliku PCAP
token
Ciąg
Nie można pustoć
Token czujnika, który ma być używany podczas pobierania pliku PCAP
Przykład odpowiedzi: Powodzenie
{
"downloadUrl": "https://10.1.0.2/api/v2/alerts/pcap/1",
"xsenseId": 1,
"token": "d2791f58-2a88-34fd-ae5c-2651fe30a63c",
"id": 1,
"xsenseAlertId": 1
}
Przykład odpowiedzi: Błąd
{
"error": "alert not found"
}
Typ : GET
Interfejsy API
curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/external/v2/alerts/pcap/<ID>'
*
Przykład :
curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://10.1.0.1/external/v2/alerts/pcap/1'
Następne kroki
Aby uzyskać więcej informacji, zobacz Omówienie interfejsu API usługi Defender for IoT .