Riasztáskezelési API-referencia helyszíni felügyeleti konzolokhoz

Ez a cikk a helyszíni IoT felügyeleti konzolok 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 összes vagy szűrt riasztást egy helyszíni felügyeleti konzolról.

URI: /external/v1/alerts vagy /external/v2/alerts

GET

Kérés

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 Az összes többi érték figyelmen kívül lesz hagyva.	/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ó
siteId	A webhely, amelyen a riasztást felfedezték.	/api/v1/alerts?siteId=1	Választható
zoneId	Az a zóna, amelyen a riasztást észlelték.	/api/v1/alerts?zoneId=1	Választható
sensorId	Az érzékelő, amelyen a riasztást észlelték.	/api/v1/alerts?sensorId=1	Választható

Megjegyzés

Előfordulhat, hogy nem rendelkezik a hely- és zónaazonosítóval. Ebben az esetben először kérdezze le az összes eszközt a hely és a zónaazonosító lekéréséhez. További információ: Integrációs API-referencia helyszíni felügyeleti konzolokhoz (nyilvános előzetes verzió).

Válasz

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	Numerikus	Nem null értékű	-
sensorId	Numerikus	Nem null értékű	-
zoneId	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, Majorvagy Critical
Motor	Sztring	Nem null értékű	Protocol Violation, Policy Violation, Malware, Anomalyvagy Operational
sourceDevice	Numerikus	Nullázható	Eszközazonosító
destinationDevice	Numerikus	Nullázható	Eszközazonosító
remediationSteps	Sztring	Nullázható	A riasztásban megjelenő szervizelési lépések
additionalInformation	További információs objektum	Nullázható	-
Kezelni	Logikai érték, a riasztás állapota	Nem null értékű	true vagy false

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 lehet null értékű	Sztring

V2-hez hozzáadva:

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 lehet null értékű	A riasztásban ismertetett sztringek, szervizelési lépések
sensorName	Sztring	Nem lehet null értékű	A felhasználó által definiált érzékelő neve
zoneName	Sztring	Nem lehet null értékű	Az érzékelőhöz társított zóna neve
siteName	Sztring	Nem lehet null értékű	Az érzékelőhöz társított hely neve

További információ: Sensor API verzióreferenciája.

Példa válaszra

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

cURL-parancs

Típus: GET

API:

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<>IP_ADDRESS>/external/v1/alerts?state=&zoneId=&fromTime=&toTime=&siteId=&sensor='

Példa:

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 (Riasztások kezelése az UUID alapján)

Ezzel az API-val meghatározott műveletet hajthat végre az IoT-hez készült Defender által észlelt adott riasztáson.

Ezzel az API-val például létrehozhat egy továbbítási szabályt, amely adatokat továbbít a QRadarnak. További információ: A Qradar integrálása Microsoft Defender az IoT-hez.

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

PUT

Kérés

Típus: JSON

Lekérdezési paraméterek:

Név	Leírás	Példa	Kötelező/nem kötelező
UUID	Meghatározza a kezelni vagy kezelni és megtanulni kívánt riasztás univerzálisan egyedi azonosítóját (UUID).	/api/v1/alerts/7903F632-H7EJ-4N69-F40F-4B1E689G00Q0	Kötelező

Törzsparaméterek

Név	Leírás	Példa	Kötelező/nem kötelező
Akció	Sztring	Vagy handlehandleAndLearn	Kötelező

Példa kérésre

{
    "action": "handle"
}

Válasz

Típus: JSON

Az eszközöket képviselő JSON-objektumok tömbje.

Válaszmezők:

Név	Típus	Kötelező/nem kötelező	Description
content /error	Sztring	Kötelező	Ha a kérés sikeres, megjelenik a tartalomtulajdonság. Ellenkező esetben megjelenik a hibatulajdonság.

Lehetséges tartalomértékek:

Állapotkód	Üzenet	Leírás
200	A riasztásfrissítési kérelem sikeresen befejeződött.	A frissítési kérelem sikeresen befejeződött. Nincsenek megjegyzések.
200	A riasztást már kezelték (leíró).	A riasztást már akkor kezelték, amikor a riasztásra vonatkozó leírókérés érkezett. A riasztás továbbra is kezelhető.
200	A riasztást már kezelték és megtanulták (handleAndLearn).	A riasztást már kezelték, és megtudták, hogy mikor érkeztek meg azAndLearn kezelésére vonatkozó kérések. A riasztás a handledAndLearn állapotban marad.
200	A riasztást már kezelték (kezelték). A handle and learn (handleAndLearn) a riasztáson lett végrehajtva.	A riasztást már akkor kezelték, amikor egy kérés érkezett azAndLearn kezelésére . A riasztás a handleAndLearn lesz.
200	A riasztást már kezelték és megtanulták (handleAndLearn). A leírókérés figyelmen kívül hagyva.	A riasztást már akkor kezelték ÉsLearn , amikor a riasztás kezelésére vonatkozó kérés érkezett. A riasztás továbbra is a handleAndLearn lesz.
500	Érvénytelen művelet.	Az elküldött művelet nem érvényes művelet a riasztáson.
500	Váratlan hiba történt.	Váratlan hiba történt. A probléma megoldásához forduljon a műszaki támogatási szolgálathoz.
500	Nem sikerült végrehajtani a kérést, mert nem található riasztás ehhez az UUID-hoz.	A megadott riasztás UUID-azonosítója nem található a rendszerben.

Példa válaszra: Sikeres

{
    "content": "Alert update request finished successfully"
}

Példa válaszra: Sikertelen

{
    "error": "Invalid action"
}

cURL-parancs

Típus: PUT

API-k:

curl -k -X PUT -d '{"action": "<ACTION>"}' -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/external/v1/alerts/<UUID>

Példa:

curl -k -X PUT -d '{"action": "handle"}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/alerts/1-1594550943000

maintenanceWindow (Riasztáskizárások létrehozása)

Kezeli a karbantartási időszakokat, amelyek alatt a rendszer nem küld riasztásokat. Ezzel az API-val meghatározhatja és frissítheti azokat a leállítási és indítási időpontokat, eszközöket vagy alhálózatokat, amelyeket ki kell zárni a riasztások aktiválásakor, vagy definiálhatja és frissítheti az IoT-hez készült Defender-motorokat, amelyeket ki kell zárni.

Egy karbantartási időszak alatt például előfordulhat, hogy le szeretné állítani az összes riasztás riasztásainak kézbesítését, kivéve a kritikus eszközökre vonatkozó kártevő-riasztásokat.

Az API-val maintenanceWindow definiált karbantartási időszakok a helyszíni felügyeleti konzol Riasztáskizárások ablakában csak olvasható kizárási szabályként jelennek meg, amelynek neve a következő szintaxissal van elnevezve: Maintenance-{token name}-{ticket ID}.

Fontos

Ez az API csak karbantartási célokra és korlátozott ideig támogatott, és nem használható riasztáskizárási szabályok helyett. Ezt az API-t csak egyszeri, ideiglenes karbantartási műveletekhez használja.

URI: /external/v1/maintenanceWindow

POST

Létrehoz egy új karbantartási időszakot.

Kérés

Törzsparaméterek:

Név	Leírás	Példa	Kötelező/nem kötelező
ticketId	Sztring. Meghatározza a karbantartási jegy azonosítóját a felhasználó rendszereiben. Győződjön meg arról, hogy a jegyazonosító nincs meglévő megnyitott ablakhoz csatolva.	2987345p98234	Kötelező
Ttl	Pozitív egész szám. Meghatározza a TTL-t (az élettartamot), amely a karbantartási időszak időtartama, percekben megadva. A megadott időszak befejeződése után a karbantartási időszak véget ér, és a rendszer ismét a szokásos módon viselkedik.	180	Kötelező
Motorok	Sztringek JSON-tömbje. Meghatározza, hogy a karbantartási időszak során melyik motorról tiltsa le a riasztásokat. Lehetséges értékek: - ANOMALY - MALWARE - OPERATIONAL - POLICY_VIOLATION - PROTOCOL_VIOLATION	ANOMALY,OPERATIONAL	Választható
sensorIds	Sztringek JSON-tömbje. Meghatározza, hogy mely érzékelők mellőzik a riasztásokat a karbantartási időszak során. Ezeket az érzékelőazonosítókat a berendezések (OT érzékelőberendezések kezelése) API-ból szerezheti be.	1,35,63	Választható
Alhálózatok	Sztringek JSON-tömbje. Meghatározza azokat az alhálózatokat, amelyekkel letilthatók a riasztások a karbantartási időszak során. Definiálja az egyes alhálózatokat egy CIDR-jelölésben.	192.168.0.0/16,138.136.80.0/14,112.138.10.0/8	Választható

Válasz

Állapotkód	Üzenet	Leírás
201 (létrehozva)	-	A művelet sikeresen befejeződött.
400 (hibás kérelem)	Nincs jegyazonosító	Az API-kérelemből hiányzik egy ticketId érték.
400 (hibás kérelem)	Illegális TTL	Az API-kérés nem pozitív vagy nem numerikus TTL-értéket tartalmazott.
400 (hibás kérelem)	Nem sikerült elemezni a kérést.	Probléma a törzs elemzésével, például helytelen paraméterekkel vagy érvénytelen értékekkel.
400 (hibás kérelem)	A karbantartási időszak már létezik ugyanazokkal a paraméterekkel.	Akkor jelenik meg, ha már létezik egy meglévő karbantartási időszak ugyanazokkal a részletekkel.
404 (nem található)	Ismeretlen érzékelőazonosító	A kérelemben felsorolt érzékelők egyike nem létezik.
409 (ütközés)	A jegyazonosítónak már van megnyitott ablaka.	A jegyazonosító egy másik nyitott karbantartási időszakhoz van társítva.
500 (belső kiszolgálóhiba)	-	Bármilyen más váratlan hiba.

cURL-parancs

Típus: POST

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

Példa:

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

Bezár egy meglévő karbantartási időszakot.

Kérés

Lekérdezési paraméterek:

Név	Leírás	Példa	Kötelező/ Nem kötelező
ticketId	Meghatározza a karbantartási jegy azonosítóját a felhasználó rendszereiben. Győződjön meg arról, hogy a jegyazonosító egy meglévő nyitott ablakhoz van csatolva.	2987345p98234	Kötelező

Válasz

Hibakódok:

Code	Üzenet	Leírás
200 (OK)	-	A művelet sikeresen befejeződött.
400 (Hibás kérelem)	Nincs jegyazonosító	A ticketId paraméter hiányzik a kérelemből.
404 (nem található):	A karbantartási időszak nem található.	A jegyazonosító nincs összekapcsolva nyitott karbantartási időszakkal.
500 (belső kiszolgálóhiba)	-	Bármilyen más váratlan hiba.

cURL-parancs

Típus: DELETE

API:

curl -k -X DELETE -d '{"ticketId": "<TICKET_ID>"}' -H "Authorization: <AUTH_TOKEN>" https://<IP address>/external/v1/maintenanceWindow

Példa:

curl -k -X DELETE -d '{"ticketId": "a5fe99c-d914-4bda-9332-307384fe40bf"}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/maintenanceWindow

GET

Lekérheti az összes olyan nyitott (POST), bezárási (DELETE) és frissítési (PUT) művelet naplóját, amelyet ezzel az API-val hajtottak végre a karbantartási időszakok kezeléséhez. T

Kérés

Lekérdezési paraméterek:

Név	Leírás	Példa	Kötelező/ Nem kötelező
fromDate	Szűri a naplókat az előre megadott dátumból és újabbakból. A formátum YYYY-MM-DD.	2022-08-10	Választható
toDate	Szűri a naplókat az előre megadott dátumig. A formátum YYYY-MM-DD.	2022-08-10	Választható
ticketId	Szűri az adott jegyazonosítóhoz kapcsolódó naplókat.	9a5fe99c-d914-4bda-9332-307384fe40bf	Választható
tokenName	Szűri az adott jogkivonat nevéhez kapcsolódó naplókat.	negyedéves sanity-window	Választható

Hibakódok:

Code	Üzenet	Leírás
200	OK	A művelet sikeresen befejeződött.
204:	Nincs tartalom	Nincs megjelenítendő adat.
400	Hibás kérés	A dátumformátum helytelen.
500	Belső kiszolgálóhiba	Bármilyen más váratlan hiba.

Válasz

Típus: JSON

A karbantartási időszak műveleteit jelképező JSON-objektumok tömbje.

Válaszstruktúra:

Név	Típus	Nullable / Not nullable	Értékek listája
id	Hosszú egész szám	Nem null értékű	Az aktuális napló belső azonosítója
Datetime	Sztring	Nem null értékű	A tevékenység bekövetkezési ideje, például: 2022-04-23T18:25:43.511Z
ticketId	Sztring	Nem null értékű	A karbantartási időszak azonosítója. Például: 9a5fe99c-d914-4bda-9332-307384fe40bf
tokenName	Sztring	Nem null értékű	A karbantartási időszak jogkivonatának neve. Például: quarterly-sanity-window
Motorok	Sztringek tömbje	Nullázható	Azok a motorok, amelyekre a karbantartási időszak vonatkozik, a karbantartási időszak létrehozásakor megadottak szerint: Protocol Violation, Policy Violation, Malware, , Anomalyvagy Operational
sensorIds	A sztring tömbje	Nullázható	Azok az érzékelők, amelyekre a karbantartási időszak vonatkozik, a karbantartási időszak létrehozásakor megadott módon.
Alhálózatok	A sztring tömbje	Nullázható	Azok az alhálózatok, amelyekre a karbantartási időszak vonatkozik, a karbantartási időszak létrehozásakor megadottak szerint.
Ttl	Numerikus	Nullázható	A karbantartási időszak élettartamát (TTL) a karbantartási időszak létrehozása vagy frissítése során megadottak szerint.
operationType	Sztring	Nem lehet null értékű	Az alábbi értékek egyike: OPEN, UPDATE, és CLOSE

cURL-parancs

Típus: GET

API:

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/external/v1/maintenanceWindow?fromDate=&toDate=&ticketId=&tokenName='

Példa:

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

Lehetővé teszi a karbantartási időszak időtartamának frissítését a karbantartási folyamat elindítása után a ttl paraméter módosításával. Az új időtartam-definíció felülbírálja az előzőt.

Ez a módszer akkor hasznos, ha az aktuálisan konfigurált időtartamnál hosszabb időtartamot szeretne beállítani. Ha például eredetileg 180 percet adott meg, 90 perc telt el, és további 30 percet szeretne hozzáadni, frissítse a ttl120 percet az időtartamok számának alaphelyzetbe állításához.

Kérés

Lekérdezési paraméterek:

Név	Leírás	Példa	Kötelező/nem kötelező
ticketId	Sztring. Meghatározza a karbantartási jegy azonosítóját a felhasználó rendszereiben.	2987345p98234	Kötelező
Ttl	Pozitív egész szám. Az ablak időtartamát határozza meg percekben.	210	Kötelező

Válasz

Hibakódok:

Code	Üzenet	Leírás
200 (OK)	-	A művelet sikeresen befejeződött.
400 (hibás kérelem)	Nincs jegyazonosító	A kérelemből hiányzik egy ticketId érték.
400 (hibás kérelem)	Illegális TTL	A definiált TTL nem numerikus vagy nem pozitív egész szám.
400 (hibás kérelem)	Nem sikerült elemezni a kérést	A kérelemből hiányzik egy ttl paraméterérték.
404 (nem található)	A karbantartási időszak nem található	A jegyazonosító nincs nyitott karbantartási időszakhoz kapcsolva.
500 (belső kiszolgálóhiba)	-	Bármilyen más váratlan hiba.

cURL-parancs

Típus: PUT

API:

curl -k -X PUT -d '{"ticketId": "<TICKET_ID>",ttl": "<TIME_TO_LIVE>"}' -H "Authorization: <AUTH_TOKEN>" https://<IP address>/external/v1/maintenanceWindow

Példa:

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 (Riasztás kérése PCAP)

Ezzel az API-val egy riasztáshoz kapcsolódó PCAP-fájlt kérhet le.

URI: /external/v2/alerts/

GET

Kérés

Lekérdezési paraméterek:

Név	Leírás	Példa	Kötelező/nem kötelező
id	Riasztásazonosító a helyszíni felügyeleti konzolról	/external/v2/alerts/pcap/<id>	Kötelező

Válasz

Típus: JSON

Üzenetsztring a művelet állapotának részleteivel:

Állapotkód	Üzenet	Leírás
200 (OK)	-	JSON-objektum a kért PCAP-fájl adataival. További információ: Adatmezők.
500 (belső kiszolgálóhiba)	A riasztás nem található	A megadott riasztásazonosító nem található a helyszíni felügyeleti konzolon.
500 (belső kiszolgálóhiba)	Hiba történt az xsense-azonosító tokenjének lekérése közben <number>	Hiba történt, amikor lekérte az érzékelő tokenjét a megadott érzékelőazonosítóhoz
500 (belső kiszolgálóhiba)	-	Bármilyen más váratlan hiba.

Adatmezők

Név	Típus	Nullable /Not nullable	Értékek listája
id	Numerikus	Nem lehet null értékű	A helyszíni felügyeleti konzol riasztásazonosítója
xsenseId	Numerikus	Nem lehet null értékű	Az érzékelő azonosítója
xsenseAlertId	Numerikus	Nem lehet null értékű	Az érzékelő konzol riasztási azonosítója
downloadUrl	Sztring	Nem lehet null értékű	A PCAP-fájl letöltéséhez használt URL-cím
jogkivonat	Sztring	Nem lehet null értékű	Az érzékelő jogkivonata, amelyet a PCAP-fájl letöltésekor kell használni

Példa válaszra: Siker

{
  "downloadUrl": "https://10.1.0.2/api/v2/alerts/pcap/1",
  "xsenseId": 1,
  "token": "d2791f58-2a88-34fd-ae5c-2651fe30a63c",
  "id": 1,
  "xsenseAlertId": 1
}

Példa válaszra: Hiba

{
  "error": "alert not found"
}

cURL-parancs

Típus: GET

API-k

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/external/v2/alerts/pcap/<ID>'

*Példa:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://10.1.0.1/external/v2/alerts/pcap/1'

Következő lépések

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