Referenční informace k rozhraní API pro správu výstrah pro senzory monitorování OT

Tento článek uvádí rozhraní REST API pro správu upozornění podporovaná pro Microsoft Defender pro senzory monitorování OT IoT.

výstrahy (načtení informací o upozornění)

Pomocí tohoto rozhraní API si můžete vyžádat seznam všech výstrah, které senzor Defenderu for IoT zjistil.

Identifikátor URI: /api/v1/alerts

GET

Žádost

Parametry dotazů

Název	Popis	Příklad	Povinné/volitelné
Státu	Získejte pouze zpracovávaná nebo neošetřená upozornění. Podporované hodnoty: - handled - unhandled	/api/v1/alerts?state=handled	Volitelné
fromTime	Získejte upozornění vytvořená od určitého času, v milisekundách od epochy a v časovém pásmu UTC.	/api/v1/alerts?fromTime=<epoch>	Volitelné
doTime	Získejte upozornění vytvořená pouze dříve v daném čase, v milisekundách od epochy a v časovém pásmu UTC.	/api/v1/alerts?toTime=<epoch>	Volitelné
typ	Získejte pouze výstrahy určitého typu. Podporované hodnoty: - unexpected new devices - disconnections Všechny ostatní hodnoty se ignorují.	/api/v1/alerts?type=disconnections	Volitelné

Response

Typ: JSON

Seznam výstrah s následujícími poli:

Název	Typ	S možnou hodnotou null / není nullable	Seznam hodnot
ID	Číselný	Nelze použít hodnotu null.	-
Čas	Číselný	Nelze použít hodnotu null.	Milisekundy od epochy v časovém pásmu UTC
title	Řetězec	Nelze použít hodnotu null.	-
message	Řetězec	Nelze použít hodnotu null.	-
Závažnosti	Řetězec	Nelze použít hodnotu null.	Warning, Minor, Majornebo Critical
Motoru	Řetězec	Nelze použít hodnotu null.	Protocol Violation, , Policy Violation, AnomalyMalwareneboOperational
zdrojová zařízení	Číselný	Vynulovatelné	ID zařízení
cílová zařízení	Číselný	Vynulovatelné	ID zařízení
další informace	Objekt Další informace	Vynulovatelné	-

Další pole s informacemi

Název	Typ	S možnou hodnotou null / není nullable	Seznam hodnot
description	Řetězec	Nelze použít hodnotu null.	-
Informace	Pole JSON	Nelze použít hodnotu null.	Řetězec

Přidáno pro V2:

Název	Typ	S možnou hodnotou null / není nullable	Seznam hodnot
zdrojDeviceAddress	Řetězec	Vynulovatelné	IP adresa nebo mac adresa
destinationDeviceAddress	Řetězec	Vynulovatelné	IP adresa nebo mac adresa
nápravné kroky	Pole JSON	Nelze použít hodnotu null.	Řetězce, nápravné kroky popsané v upozornění

Další informace najdete v referenčních informacích k rozhraní Sensor API.

Příklad odpovědi

[
    {
        "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,
    }
]

Příkaz cURL

Typ: GET

Rozhraní API:

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

Příklad:

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

events (načtení událostí časové osy)

Pomocí tohoto rozhraní API si můžete vyžádat seznam událostí nahlášených na časovou osu událostí.

Poznámka

Spuštění identického rozhraní API během stejné hodiny se stejnými hodnotami parametrů vrátí hodnotu uloženou v mezipaměti. Pokud toto rozhraní API spouštíte dvakrát za hodinu, doporučujeme upravit parametry dotazu, abyste získali aktualizovanou odpověď.

Identifikátor URI: /api/v1/events

GET

Žádost

Parametry dotazů

Název	Popis	Příklad	Povinné/volitelné
minutesTimeFrame	Filtrujte výsledky podle zadaného časového rámce, během kterého byly události hlášeny. Definováno zpětně od aktuálního času. Maximum = 4320 (3 dny). Jakákoli větší hodnota se považuje za 4320 bez chyby.	/api/v1/events?minutesTimeFrame=20	Volitelné
Typ	Filtrujte výsledky pouze pro konkrétní typ. Všechny hodnoty jiné než podporované typy se ignorují. Další informace najdete v tématu Událost type a title referenční informace.	/api/v1/events?type=DEVICE_CONNECTION_CREATED /api/v1/events?type=REMOTE_ACCESS&minutesTimeFrame	Volitelné

Response

Typ: JSON

Pole objektů JSON, které představují posledních 100 událostí, seřazené podle časového razítka události, s nejnovější událostí jako první.

Mezi pole události patří:

Název	Typ	S možnou hodnotou null / není nullable	Seznam hodnot
Časové razítko	Číselný	Nelze použít hodnotu null.	Milisekundy od epochy v časovém pásmu UTC
typ	Řetězec	Nelze použít hodnotu null.	Jeden z podporovaných typů
title	Řetězec	Nelze použít hodnotu null.	Jeden z podporovaných titulů
Závažnosti	Řetězec	Nelze použít hodnotu null.	INFO, NOTICEnebo ALERT
Vlastník	Řetězec	Vynulovatelné	Řetězec. Pokud byla událost vytvořena ručně, bude toto pole obsahovat uživatelské jméno, které událost vytvořilo.
Obsah	Řetězec	Nelze použít hodnotu null.	Řetězec, který popisuje událost.

Příklad odpovědi

[
    {
        "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"
    }
]

Příkaz cURL

Typ: GET

Rozhraní API:

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

Příklad:

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

Událost type a title odkazy

V této části jsou uvedené podporované hodnoty typu události anázvu pro rozhraní API událostí .

Typ události	Název události
DEVICE_CREATE	Zařízení se zjistilo
DEVICE_UPDATE	Zařízení se aktualizovalo
ALERT_REPORTED	Rozpoznaná výstraha
ALERT_UPDATED	Výstraha se aktualizovala
SKENOVÁNÍ	Kontrola zjištěného zařízení
PROGRAM_DEVICE	Programování PLC
MMS_PROGRAM_DEVICE	Aktualizace programu PLC
SCL_UPLOADED	Nahraný seznam SCL
EXCLUSION_RULE_CREATED	Pravidlo vyloučení se vytvořilo.
EXCLUSION_RULE_REMOVED	Pravidlo vyloučení se odebralo.
EXCLUSION_RULE_UPDATED	Pravidlo vyloučení se aktualizovalo.
DEVICE_CONNECTION_CREATED	Zjistilo se připojení zařízení
USER_LOGIN	Pokus o přihlášení uživatele
FILE_TRANSFER	Byl zjištěn přenos souborů
CUSTOM_EVENT	Uživatelem definovaná událost
REMOTE_ACCESS	Navázáno připojení ke vzdálenému přístupu
BACK_TO_NORMAL	Zpět do normálního stavu
MMS_MEMORY_BLOCK_OPERATION	Operace bloku paměti MMS
MMS_PROGRAM_OPERATION	Operace programu MMS
HTTP_BASIC_AUTHENTICATION	Základní ověřování HTTP
SIEMENS_S_7_MEMORY_BLOCK_OPERATION	Siemens S7 Memory Block Operation
SIEMENS_S_7_AUTHENTICATION	Siemens S7 Authentication
REPORT_CREATED	Sestava byla vytvořena
SNMP_TRAP	Detekovaný depeše protokolu SNMP
DATABASE_ACTION	Manipulace se strukturou databáze
PLC_MODULE_CHANGE	Změna modulu PLC
FIRMWARE_UPDATE	Aktualizace firmwaru
PLC_START	Spuštění PLC
SRTP_PLC_RESET	Resetování PLC
SRTP_PLC_COPY_FIRMWARE	Aktualizace firmwaru
SRTP_LOGIN_PROGRAMMING	Nastavení programovacího režimu PLC
SRTP_PLC_CHANGE_PASSWORD	Změna hesla PLC
OPC_DATA_ACCESS_GROUP_MANAGEMENT_OPERATION	Operace správy skupiny přístupu k datům OPC
OPC_DATA_ACCESS_ITEM_MANAGEMENT_OPERATION	Operace správy položek přístupu k datům OPC
OPC_DATA_ACCESS_IO_SUBSCRIPTION_MANAGEMENT_OPERATION	Operace správy předplatného vstupně-výstupních operací přístupu k datům OPC
OPC_AE_EVENT_SUBSCRIPTION	Odběr událostí OPC AE
OPC_AE_EVENT_CONDITION_MANAGEMENT_OPERATION	Operace správy podmínek událostí OPC AE
OPC_AE_EVENT	Událost OPC AE
SRTP_CHANGE_PRIVILEGE	PLC – Změna úrovně přístupu
SRTP_CHANGE_LEVEL_FAILED	Změna úrovně přístupu PLC selhala
SUITELINK_INIT_CONNECTION	Inicializována relace Wonderware
USER_OPERATION	Operace uživatele
DIP_UPLOADED	Nahrán balíček datových inteligentních informací
FTP_AUTHENTICATION_FAILURE	Selhání ověřování FTP
PROFINET_DPC_VALUE_SET	Operace Profinet SET
S7PLUS_PLC_MODE_CHANGE	Změna režimu PLC
S7_PLC_MODE_CHANGE	Změna režimu PLC
DELETE_DEVICE	Odstranění zařízení
S7PLUS_PROGRAMMING	Programování PLC
FIRMWARE_CHANGED	Změna firmwaru PLC
DELTAV_PROGRAMMING	Rozdílový instalační skript
USER_DEFINED_RULE_CREATED	Vytvořeno uživatelem definované pravidlo
USER_DEFINED_RULE_EDITED	Upraveno uživatelem definované pravidlo
USER_DEFINED_RULE_DELETED	Pravidlo definované uživatelem se odstranilo.
USER_DEFINED_RULE_OPERATION	Operace pravidla definovaného uživatelem
REMOTE_PROCESS_EXECUTION	Vzdálené spouštění procesů
DEVICE_UNIFICATION	Zařízení se aktualizovalo
OZNÁMENÍ	Oznámení se vyřešilo ručně.
ENIP_CONTROLLER_PROGRAM_DELETE	Odstranění programu kontroleru
ENIP_CONTROLLER_PROGRAM_RESET	Resetování programu kontroleru
ENIP_CONTROLLER_GENERIC_RESET	Resetování kontroleru
ENIP_CONTROLLER_GENERIC_STOP	Zarážka ovladače
ENIP_CONTROLLER_GENERIC_START	Spuštění kontroleru
TELNET_AUTHENTICATION_FAILURE	Selhání ověřování telnetem
CONFIGURATION_OF_CLEARTEXT_PASSWORD	Konfigurace hesla cleartext
CLEARTEXT_AUTHENTICATION	Ověřování pomocí cleartextu
PROGRAM_UPLOAD_DEVICE	Nahrání programu PLC
CONFIGURATION_CHANGE	Zápis konfigurace PLC
CONFIGURATION_READ	Čtení konfigurace PLC
SYSLOG_MSG	Zpráva syslogu
INTERNET_ACCESS	Přístup k internetu
CAMP_MEMORY_WRITE_OPERATION	Běžná operace zápisu do paměti protokolu ASCII
MUTED_ALERT	Zjištění a ztlumené události
DHCP_UPDATE	Aktualizace adresy
DIP_FAILURE	Selhání instalace balíčku datové inteligence
DELETE_DEVICE_SCHEDULE	Neaktivní zařízení naplánovaná k odstranění
PLC_OPERATING_MODE_CHANGED	Zjištění změny provozního režimu PLC
HARDWARE_UPDATE_BY_IDENTIFIER	Aktualizace adresy

Další kroky

Další informace najdete v přehledu referenčních informací k rozhraní API Služby Defender for IoT.