Riasztáskezelési API-referencia ot monitorozási érzékelőkhöz

Cikk
06/01/2023

Ez a cikk az IoT OT-monitorozási érzékelők Microsoft Defender által támogatott riasztáskezelési REST API-kat sorolja fel.

riasztások (riasztási információk lekérése)

Ezzel az API-val lekérheti az IoT-hez készült Defender érzékelő által észlelt összes riasztás listáját.

URI: /api/v1/alerts

GET

Lekérdezési paraméterek

Név	Leírás	Példa	Kötelező/ Nem kötelező
Állami	Csak a kezelt vagy nem kezelt riasztások lekérése. Támogatott értékek: - `handled` - `unhandled`	`/api/v1/alerts?state=handled`	Választható
fromTime	Az adott időponttól kezdődően, a korszaktól számított ezredmásodpercben és UTC időzónában létrehozott riasztások lekérése.	`/api/v1/alerts?fromTime=<epoch>`	Választható
toTime	A riasztások létrehozása csak egy adott időpontban, ezredmásodpercben a korszaktól és az UTC időzónától kezdve.	`/api/v1/alerts?toTime=<epoch>`	Választható
típus	Csak egy adott típusú riasztások lekérése. Támogatott értékek: - `unexpected new devices` - `disconnections` Az összes többi érték figyelmen kívül lesz hagyva.	`/api/v1/alerts?type=disconnections`	Választható

Típus: JSON

A riasztások listája a következő mezőkkel:

Név	Típus	Nullable / Not nullable	Értékek listája
ID (Azonosító)	Numerikus	Nem null értékű	-
Idő	Numerikus	Nem null értékű	Ezredmásodperc a korszaktól, UTC időzónában
cím	Sztring	Nem null értékű	-
üzenet	Sztring	Nem null értékű	-
Súlyossága	Sztring	Nem null értékű	`Warning`, `Minor`, `Major`vagy `Critical`
Motor	Sztring	Nem null értékű	`Protocol Violation`, `Policy Violation`, `Malware`, `Anomaly`vagy `Operational`
sourceDevice	Numerikus	Nullázható	Eszközazonosító
destinationDevice	Numerikus	Nullázható	Eszközazonosító
additionalInformation	További információs objektum	Nullázható	-

További információmezők

Név	Típus	Nullable / Not nullable	Értékek listája
leírás	Sztring	Nem null értékű	-
Információ	JSON-tömb	Nem null értékű	Sztring

Hozzáadva a V2-hez:

Név	Típus	Nullable / Not nullable	Értékek listája
sourceDeviceAddress	Sztring	Nullázható	IP- vagy MAC-cím
destinationDeviceAddress	Sztring	Nullázható	IP- vagy MAC-cím
remediationSteps	JSON-tömb	Nem null értékű	A riasztásban leírt sztringek, szervizelési lépések

További információ: Sensor API-verzióhivatkozás.

Példa válaszra

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

Típus: GET

API:

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

Példa:

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

események (Idősoresemények lekérése)

Ezzel az API-val kérheti le az esemény ütemtervének jelentett események listáját.

Megjegyzés

Ha az azonos API-t ugyanazon az órán belül futtatja, pontosan ugyanazokkal a paraméterértékekkel, egy gyorsítótárazott értéket ad vissza. Ha egy óra alatt kétszer futtatja ezt az API-t, javasoljuk, hogy módosítsa a lekérdezési paramétereket, hogy frissített választ kapjon.

URI: /api/v1/events

GET

Lekérdezési paraméterek

Név	Leírás	Példa	Kötelező/ Nem kötelező
minutesTimeFrame	Szűrje az eredményeket egy adott időkeret szerint, amely alatt eseményeket jelentettek. Az aktuális időponttól visszafelé definiálva. Maximum = `4320` (3 nap). A nagyobb értékeket a rendszer 4320-asként kezeli, hiba nélkül	`/api/v1/events?minutesTimeFrame=20`	Választható
típus	Csak egy adott típus eredményeinek szűrése. A támogatott típustól eltérő értékek figyelmen kívül lesznek hagyva. További információ: Esemény `type` és `title` referencia.	`/api/v1/events?type=DEVICE_CONNECTION_CREATED` `/api/v1/events?type=REMOTE_ACCESS&minutesTimeFrame`	Választható

Típus: JSON

JSON-objektumok tömbje, amelyek a legutóbbi 100 eseményt jelölik, eseményidőbélyeg szerint rendezve, és először a legújabb eseményt tartalmazzák.

Az eseménymezők a következők:

Név	Típus	Nullable / Not nullable	Értékek listája
Időbélyeg	Numerikus	Nem null értékű	Ezredmásodperc a korszaktól, UTC időzónában
Típus	Sztring	Nem null értékű	Az egyik támogatott típus
cím	Sztring	Nem null értékű	Az egyik támogatott cím
Súlyossága	Sztring	Nem null értékű	`INFO`, , `NOTICE`vagy `ALERT`
Tulajdonos	Sztring	Nullázható	Sztring. Ha az esemény manuálisan lett létrehozva, ez a mező tartalmazza az eseményt létrehozó felhasználónevet.
Tartalom	Sztring	Nem null értékű	Az eseményt leíró sztring.

Példa válaszra

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

Típus: GET

API:

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

Példa:

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

Esemény `type` és `title` hivatkozás

Ez a szakasz az események API eseménytípusaként és címértékeiként támogatott értékeket sorolja fel.

Eseménytípus	Esemény címe
DEVICE_CREATE	Eszköz észlelve
DEVICE_UPDATE	Eszköz frissítve
ALERT_REPORTED	Riasztás észlelve
ALERT_UPDATED	Riasztás frissítve
ÁTKUTAT	Észlelt eszköz vizsgálata
PROGRAM_DEVICE	PLC-programozás
MMS_PROGRAM_DEVICE	PLC programfrissítés
SCL_UPLOADED	SCL feltöltve
EXCLUSION_RULE_CREATED	Kizárási szabály létrehozva
EXCLUSION_RULE_REMOVED	Kizárási szabály el lett távolítva
EXCLUSION_RULE_UPDATED	Kizárási szabály frissítve
DEVICE_CONNECTION_CREATED	Eszközkapcsolat észlelhető
USER_LOGIN	Felhasználói bejelentkezési kísérlet
FILE_TRANSFER	Fájlátvitel észlelhető
CUSTOM_EVENT	Felhasználó által megadott esemény
REMOTE_ACCESS	Távelérési kapcsolat létrejött
BACK_TO_NORMAL	Vissza a normál állapotba
MMS_MEMORY_BLOCK_OPERATION	MMS memóriablokkoló művelet
MMS_PROGRAM_OPERATION	MMS-programművelet
HTTP_BASIC_AUTHENTICATION	ALAPSZINTŰ HTTP-hitelesítés
SIEMENS_S_7_MEMORY_BLOCK_OPERATION	Siemens S7 memóriablokkoló művelet
SIEMENS_S_7_AUTHENTICATION	Siemens S7-hitelesítés
REPORT_CREATED	Jelentés létrehozva
SNMP_TRAP	SNMP-trap észlelve
DATABASE_ACTION	Adatbázisstruktúra-kezelés
PLC_MODULE_CHANGE	PLC-modul módosítása
FIRMWARE_UPDATE	Belsővezérlőprogram-frissítés
PLC_START	PLC Start
SRTP_PLC_RESET	PLC alaphelyzetbe állítása
SRTP_PLC_COPY_FIRMWARE	Belsővezérlőprogram-frissítés
SRTP_LOGIN_PROGRAMMING	PLC programozási mód beállítása
SRTP_PLC_CHANGE_PASSWORD	PLC-jelszó módosítása
OPC_DATA_ACCESS_GROUP_MANAGEMENT_OPERATION	OPC-adathozzáférési csoport felügyeleti művelete
OPC_DATA_ACCESS_ITEM_MANAGEMENT_OPERATION	OPC-adatelérési elem kezelési művelete
OPC_DATA_ACCESS_IO_SUBSCRIPTION_MANAGEMENT_OPERATION	OPC-adathozzáférés I/O-előfizetés-kezelési művelet
OPC_AE_EVENT_SUBSCRIPTION	OPC AE-esemény-előfizetés
OPC_AE_EVENT_CONDITION_MANAGEMENT_OPERATION	OPC AE eseményfeltétel-kezelési művelet
OPC_AE_EVENT	OPC AE-esemény
SRTP_CHANGE_PRIVILEGE	PLC – Hozzáférési szint módosítása
SRTP_CHANGE_LEVEL_FAILED	A PLC-módosítás hozzáférési szintje nem sikerült
SUITELINK_INIT_CONNECTION	Wonderware-munkamenet inicializálva
USER_OPERATION	Felhasználói művelet
DIP_UPLOADED	Feltöltött adatintelligencia-csomag
FTP_AUTHENTICATION_FAILURE	FTP-hitelesítési hiba
PROFINET_DPC_VALUE_SET	Profinet SET művelet
S7PLUS_PLC_MODE_CHANGE	PLC mód módosítása
S7_PLC_MODE_CHANGE	PLC mód módosítása
DELETE_DEVICE	Eszköz törlése
S7PLUS_PROGRAMMING	PLC-programozás
FIRMWARE_CHANGED	A PLC belső vezérlőprogramja megváltozott
DELTAV_PROGRAMMING	DeltaV telepítési szkript
USER_DEFINED_RULE_CREATED	Felhasználó által definiált szabály létrehozva
USER_DEFINED_RULE_EDITED	Felhasználó által definiált szabály szerkesztve
USER_DEFINED_RULE_DELETED	Felhasználó által definiált szabály törölve
USER_DEFINED_RULE_OPERATION	Felhasználó által definiált szabályművelet
REMOTE_PROCESS_EXECUTION	Távoli folyamat végrehajtása
DEVICE_UNIFICATION	Eszköz frissítve
ÉRTESÍTÉS	Az értesítés manuális feloldása megtörtént
ENIP_CONTROLLER_PROGRAM_DELETE	Vezérlőprogram törlése
ENIP_CONTROLLER_PROGRAM_RESET	Vezérlőprogram alaphelyzetbe állítása
ENIP_CONTROLLER_GENERIC_RESET	Vezérlő alaphelyzetbe állítása
ENIP_CONTROLLER_GENERIC_STOP	Vezérlő leállítása
ENIP_CONTROLLER_GENERIC_START	Vezérlő indítása
TELNET_AUTHENTICATION_FAILURE	Telnet-hitelesítési hiba
CONFIGURATION_OF_CLEARTEXT_PASSWORD	A cleartext jelszó konfigurálása
CLEARTEXT_AUTHENTICATION	Cleartext Authentication
PROGRAM_UPLOAD_DEVICE	PLC-program feltöltése
CONFIGURATION_CHANGE	PLC-konfiguráció írása
CONFIGURATION_READ	PLC-konfiguráció olvasása
SYSLOG_MSG	Syslog-üzenet
INTERNET_ACCESS	Internet-hozzáférés
CAMP_MEMORY_WRITE_OPERATION	Az ASCII Message Protocol memóriaírási műveletének gyakori művelete
MUTED_ALERT	Esemény észlelve és elnémítva
DHCP_UPDATE	Címfrissítés
DIP_FAILURE	Adatintelligencia-csomag telepítési hibája
DELETE_DEVICE_SCHEDULE	Törlésre ütemezett inaktív eszközök
PLC_OPERATING_MODE_CHANGED	A PLC működési módjának módosítása észlelhető
HARDWARE_UPDATE_BY_IDENTIFIER	Címfrissítés

Következő lépések

További információ: A Defender for IoT API referencia áttekintése.

Megosztás a következőn keresztül:

Riasztáskezelési API-referencia ot monitorozási érzékelőkhöz

riasztások (riasztási információk lekérése)

GET

Lekérdezési paraméterek

További információmezők

Példa válaszra

események (Idősoresemények lekérése)

GET

Lekérdezési paraméterek

Példa válaszra

Esemény `type` és `title` hivatkozás

Következő lépések

Visszajelzés

További források

Megosztás a következőn keresztül:

Riasztáskezelési API-referencia ot monitorozási érzékelőkhöz

riasztások (riasztási információk lekérése)

GET

Lekérdezési paraméterek

események (Idősoresemények lekérése)

GET

Lekérdezési paraméterek

Esemény type és title hivatkozás

Következő lépések

Visszajelzés

További források

Esemény `type` és `title` hivatkozás