Dokumentacja interfejsu API zarządzania alertami dla czujników monitorowania OT

W tym artykule wymieniono interfejsy API REST zarządzania alertami obsługiwane dla Microsoft Defender dla czujników monitorowania IoT OT.

alerty (pobieranie informacji o alertach)

Użyj tego interfejsu API, aby zażądać listy wszystkich alertów wykrytych przez czujnik usługi Defender for IoT.

Identyfikator URI: /api/v1/alerts

GET

Żądanie

Parametry zapytania

Nazwa	Opis	Przykład	Wymagane /Opcjonalne
Państwa	Uzyskaj tylko obsługiwane lub nieobsługiwane alerty. Obsługiwane wartości: - handled - unhandled	/api/v1/alerts?state=handled	Opcjonalne
fromTime	Pobierz alerty utworzone od danego czasu w milisekundach z epoki i w strefie czasowej UTC.	/api/v1/alerts?fromTime=<epoch>	Opcjonalne
toTime	Pobierz alerty utworzone tylko wcześniej w danym momencie w milisekundach z epoki i w strefie czasowej UTC.	/api/v1/alerts?toTime=<epoch>	Opcjonalne
typ	Pobieranie alertów tylko o określonym typie. Obsługiwane wartości: - unexpected new devices - disconnections Wszystkie inne wartości są ignorowane.	/api/v1/alerts?type=disconnections	Opcjonalne

Odpowiedź

Typ: JSON

Lista alertów z następującymi polami:

Nazwa	Typ	Nullable /Not nullable	Lista wartości
ID (Identyfikator)	Numeryczny	Nie można pustoć	-
Czas	Numeryczny	Nie można pustoć	Milisekundy z 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, Majorlub Critical
Silnika	Ciąg	Nie można pustoć	Protocol Violation, Policy Violation, , Malware, Anomalylub Operational
sourceDevice	Numeryczny	Dopuszczający wartość null	Identyfikator urządzenia
destinationDevice	Numeryczny	Dopuszczający wartość null	Identyfikator urządzenia
additionalInformation	Obiekt informacji dodatkowych	Dopuszczający wartość null	-

Dodatkowe pola informacji

Nazwa	Typ	Nullable /Not nullable	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

Aby uzyskać więcej informacji, zobacz Dokumentacja wersji interfejsu API czujnika.

Przykład odpowiedzi

[
    {
        "engine": "Policy Violation",
        "severity": "Major",
        "title": "Internet Access Detected",
        "additionalinformation": {
            "information": [
                "170.60.50.201 over port BACnet (47808)"
            ],
            "description": "External Addresses"
        },
        "sourceDevice": null,
        "destinationDevice": null,
        "time": 1509881077000,
        "message": "Device 192.168.0.13 tried to access an external IP address which is an address in the Internet and is not allowed by policy. It is recommended to notify the security officer of the incident.",
        "id": 1
    },
    {
        "engine": "Protocol Violation",
        "severity": "Major",
        "title": "Illegal MODBUS Operation (Exception Raised by Master)",
        "sourceDevice": 3,
        "destinationDevice": 4,
        "time": 1505651605000,
        "message": "A MODBUS master 192.168.110.131 attempted to initiate an illegal operation.\nThe operation is considered to be illegal since it incorporated function code \#129 which should not be used by a master.\nIt is recommended to notify the security officer of the incident.",
        "id": 2,
        "additionalInformation": null,
    }
]

cURL, polecenie

Typ: GET

Interfejs API:

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/api/v1/alerts?state=<STATE>&fromTime=<FROM_TIME>&toTime=<TO_TIME>&type=<TYPE>'

Przykład:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/api/v1/alerts?state=unhandled&fromTime=1594550986000&toTime=1594550986001&type=disconnections'

zdarzenia (pobieranie zdarzeń osi czasu)

Użyj tego interfejsu API, aby zażądać listy zdarzeń zgłoszonych na osi czasu zdarzenia.

Uwaga

Uruchomienie identycznego interfejsu API w ciągu tej samej godziny, z dokładnie tymi samymi wartościami parametrów, zwraca wartość z pamięci podręcznej. Jeśli używasz tego interfejsu API dwa razy w ciągu godziny, zalecamy zmodyfikowanie parametrów zapytania w celu uzyskania zaktualizowanej odpowiedzi.

Identyfikator URI: /api/v1/events

GET

Żądanie

Parametry zapytania

Nazwa	Opis	Przykład	Wymagane/opcjonalne
minutesTimeFrame	Filtruj wyniki według danego przedziału czasu, w którym zgłoszono zdarzenia. Zdefiniowane wstecz od bieżącego czasu. Maksimum = 4320 (3 dni). Każda większa wartość jest traktowana jako 4320 bez błędu	/api/v1/events?minutesTimeFrame=20	Opcjonalne
typ	Filtruj wyniki tylko dla określonego typu. Każda wartość inna niż obsługiwane typy jest ignorowana. Aby uzyskać więcej informacji, zobacz Event and reference (Zdarzenie type i title dokumentacja).	/api/v1/events?type=DEVICE_CONNECTION_CREATED /api/v1/events?type=REMOTE_ACCESS&minutesTimeFrame	Opcjonalne

Odpowiedź

Typ: JSON

Tablica obiektów JSON reprezentujących najnowsze 100 zdarzeń posortowanych według znacznika czasu zdarzenia z najnowszym zdarzeniem.

Pola zdarzeń obejmują:

Nazwa	Typ	Dopuszczanie wartości null/brak wartości null	Lista wartości
Sygnatury czasowej	Numeryczny	Nie można pustoć	Milisekundy czasu epoki w strefie czasowej UTC
Typu	Ciąg	Nie można pustoć	Jeden z obsługiwanych typów
title	Ciąg	Nie można pustoć	Jeden z obsługiwanych tytułów
Ważności	Ciąg	Nie można pustoć	INFO, NOTICElub ALERT
Właściciel	Ciąg	Dopuszczający wartość null	Ciąg. Jeśli zdarzenie zostało utworzone ręcznie, to pole będzie zawierać nazwę użytkownika, która utworzyła zdarzenie.
Zawartości	Ciąg	Nie można pustoć	Ciąg opisujący zdarzenie.

Przykład odpowiedzi

[
    {
        "severity": "INFO",
        "title": "Back to Normal",
        "timestamp": 1504097077000,
        "content": "Device 10.2.1.15 was found responsive, after being suspected as disconnected",
        "owner": null,
        "type": "BACK_TO_NORMAL"
    },
    {
        "severity": "ALERT",
        "title": "Alert Detected",
        "timestamp": 1504096909000,
        "content": "Device 10.2.1.15 is suspected to be disconnected (unresponsive).",
        "owner": null,
        "type": "ALERT_REPORTED"
    },
    {
        "severity": "ALERT",
        "title": "Alert Detected",
        "timestamp": 1504094446000,
        "content": "A DNP3 Master 10.2.1.14 attempted to initiate a request which is not allowed by policy.\nThe policy indicates the allowed function codes, address ranges, point indexes and time intervals.\nIt is recommended to notify the security officer of the incident.",
        "owner": null,
        "type": "ALERT_REPORTED"
    },
    {
        "severity": "NOTICE",
        "title": "PLC Program Update",
        "timestamp": 1504094344000,
        "content": "Program update detected, sent from 10.2.1.25 to 10.2.1.14",
        "owner": null,
        "type": "PROGRAM_DEVICE"
    }
]

polecenie cURL

Typ: GET

Interfejs API:

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/api/v1/events?minutesTimeFrame=<TIME_FRAEM>&type=<TYPE>'

Przykład:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/api/v1/events?minutesTimeFrame=20&type=DEVICE_CONNECTION_CREATED'`

Zdarzenie type i title odwołanie

W tej sekcji wymieniono wartości obsługiwane jako typ zdarzenia i wartości tytułu dla interfejsu API zdarzeń .

Typ zdarzenia	Tytuł zdarzenia
DEVICE_CREATE	Wykryto urządzenie
DEVICE_UPDATE	Zaktualizowano urządzenie
ALERT_REPORTED	Wykryto alert
ALERT_UPDATED	Zaktualizowano alert
SKANOWANIA	Wykryto urządzenie skanowania
PROGRAM_DEVICE	Programowanie PLC
MMS_PROGRAM_DEVICE	Aktualizacja programu PLC
SCL_UPLOADED	Przekazano listę SCL
EXCLUSION_RULE_CREATED	Utworzono regułę wykluczania
EXCLUSION_RULE_REMOVED	Usunięto regułę wykluczania
EXCLUSION_RULE_UPDATED	Zaktualizowano regułę wykluczania
DEVICE_CONNECTION_CREATED	Wykryto połączenie urządzenia
USER_LOGIN	Próba logowania użytkownika
FILE_TRANSFER	Wykryto transfer plików
CUSTOM_EVENT	Zdarzenie zdefiniowane przez użytkownika
REMOTE_ACCESS	Nawiązane połączenie dostępu zdalnego
BACK_TO_NORMAL	Powrót do normalnego
MMS_MEMORY_BLOCK_OPERATION	Operacja bloku pamięci programu MMS
MMS_PROGRAM_OPERATION	Operacja programu MMS
HTTP_BASIC_AUTHENTICATION	Uwierzytelnianie podstawowe HTTP
SIEMENS_S_7_MEMORY_BLOCK_OPERATION	Operacja bloku pamięci Siemens S7
SIEMENS_S_7_AUTHENTICATION	Uwierzytelnianie Firmy Siemens S7
REPORT_CREATED	Utworzony raport
SNMP_TRAP	Wykryto pułapkę SNMP
DATABASE_ACTION	Manipulowanie strukturą bazy danych
PLC_MODULE_CHANGE	Zmiana modułu PLC
FIRMWARE_UPDATE	Aktualizacja oprogramowania układowego
PLC_START	Rozpoczęcie sterownika PLC
SRTP_PLC_RESET	Resetowanie sterownika PLC
SRTP_PLC_COPY_FIRMWARE	Aktualizacja oprogramowania układowego
SRTP_LOGIN_PROGRAMMING	Zestaw trybu programowania PLC
SRTP_PLC_CHANGE_PASSWORD	Zmiana hasła PLC
OPC_DATA_ACCESS_GROUP_MANAGEMENT_OPERATION	Operacja zarządzania grupami dostępu do danych OPC
OPC_DATA_ACCESS_ITEM_MANAGEMENT_OPERATION	Operacja zarządzania elementami dostępu do danych OPC
OPC_DATA_ACCESS_IO_SUBSCRIPTION_MANAGEMENT_OPERATION	Operacja zarządzania subskrypcjami we/wy dostępu do danych OPC
OPC_AE_EVENT_SUBSCRIPTION	Subskrypcja zdarzeń OPC AE
OPC_AE_EVENT_CONDITION_MANAGEMENT_OPERATION	Operacja zarządzania warunkiem zdarzenia OPC AE
OPC_AE_EVENT	Zdarzenie OPC AE
SRTP_CHANGE_PRIVILEGE	Poziom dostępu zmiany sterownika PLC
SRTP_CHANGE_LEVEL_FAILED	Zmiana poziomu dostępu sterownika PLC nie powiodła się
SUITELINK_INIT_CONNECTION	Zainicjowano sesję wonderware
USER_OPERATION	Operacja użytkownika
DIP_UPLOADED	Przekazany pakiet analizy danych
FTP_AUTHENTICATION_FAILURE	Niepowodzenie uwierzytelniania FTP
PROFINET_DPC_VALUE_SET	Operacja Profinet SET
S7PLUS_PLC_MODE_CHANGE	Zmiana trybu PLC
S7_PLC_MODE_CHANGE	Zmiana trybu PLC
DELETE_DEVICE	Usunięcie urządzenia
S7PLUS_PROGRAMMING	Programowanie PLC
FIRMWARE_CHANGED	Zmieniono oprogramowanie układowe STEROWNIKA PLC
DELTAV_PROGRAMMING	Skrypt instalacji usługi DeltaV
USER_DEFINED_RULE_CREATED	Utworzono regułę zdefiniowaną przez użytkownika
USER_DEFINED_RULE_EDITED	Edytowana reguła zdefiniowana przez użytkownika
USER_DEFINED_RULE_DELETED	Usunięto regułę zdefiniowaną przez użytkownika
USER_DEFINED_RULE_OPERATION	Operacja reguły zdefiniowanej przez użytkownika
REMOTE_PROCESS_EXECUTION	Zdalne wykonywanie procesów
DEVICE_UNIFICATION	Zaktualizowano urządzenie
POWIADOMIENIE	Powiadomienie zostało rozwiązane ręcznie
ENIP_CONTROLLER_PROGRAM_DELETE	Usuwanie programu kontrolera
ENIP_CONTROLLER_PROGRAM_RESET	Resetowanie programu kontrolera
ENIP_CONTROLLER_GENERIC_RESET	Resetowanie kontrolera
ENIP_CONTROLLER_GENERIC_STOP	Zatrzymaj kontroler
ENIP_CONTROLLER_GENERIC_START	Uruchamianie kontrolera
TELNET_AUTHENTICATION_FAILURE	Błąd uwierzytelniania Telnet
CONFIGURATION_OF_CLEARTEXT_PASSWORD	Konfiguracja hasła w postaci zwykłego tekstu
CLEARTEXT_AUTHENTICATION	Uwierzytelnianie w postaci zwykłego tekstu
PROGRAM_UPLOAD_DEVICE	Przekazywanie programu PLC
CONFIGURATION_CHANGE	Zapis konfiguracji sterownika PLC
CONFIGURATION_READ	Odczyt konfiguracji sterownika PLC
SYSLOG_MSG	Komunikat dziennika systemowego
INTERNET_ACCESS	Dostęp do Internetu
CAMP_MEMORY_WRITE_OPERATION	Typowa operacja zapisu pamięci protokołu komunikatów ASCII
MUTED_ALERT	Wykryto zdarzenie i wyciszono
DHCP_UPDATE	Aktualizacja adresu
DIP_FAILURE	Niepowodzenie instalacji pakietu analizy danych
DELETE_DEVICE_SCHEDULE	Nieaktywne urządzenia zaplanowane do usunięcia
PLC_OPERATING_MODE_CHANGED	Wykryto zmianę trybu operacyjnego PLC
HARDWARE_UPDATE_BY_IDENTIFIER	Aktualizacja adresu

Następne kroki

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