Referenční informace k rozhraní API pro správu upozornění pro místní konzoly pro správu

Článek
06/01/2023

Tento článek uvádí rozhraní REST API pro správu upozornění podporovaná pro Microsoft Defender pro místní konzoly pro správu IoT.

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

Pomocí tohoto rozhraní API můžete načíst všechny nebo filtrované výstrahy z místní konzoly pro správu.

Identifikátor URI: /external/v1/alerts nebo /external/v2/alerts

GET

Parametry dotazu:

Název	Popis	Příklad	Povinné/volitelné
Státu	Získejte pouze zpracovávaná nebo neošetřená upozornění. Podporované hodnoty: - `handled` - `unhandled` Všechny ostatní hodnoty se ignorují.	`/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é
ID webu	Web, na kterém byla výstraha zjištěna.	`/api/v1/alerts?siteId=1`	Volitelné
ID zóny	Zóna, ve které byla výstraha zjištěna.	`/api/v1/alerts?zoneId=1`	Volitelné
sensorId	Senzor, na kterém byla výstraha zjištěna.	`/api/v1/alerts?sensorId=1`	Volitelné

Poznámka

Id webu a zóny pravděpodobně nemáte. V takovém případě nejprve zadejte dotaz na všechna zařízení, aby načetla ID lokality a zóny. Další informace najdete v tématu Referenční informace k rozhraní API pro integraci pro místní konzoly pro správu (Public Preview).

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.	-
sensorId	Číselný	Nelze použít hodnotu null.	-
ID zóny	Čí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`, `Major`nebo `Critical`
Motoru	Řetězec	Nelze použít hodnotu null.	`Protocol Violation`, , `Policy Violation`, `AnomalyMalware`nebo`Operational`
zdrojová zařízení	Číselný	Vynulovatelné	ID zařízení
cílová zařízení	Číselný	Vynulovatelné	ID zařízení
nápravné kroky	Řetězec	Vynulovatelné	Postup nápravy zobrazený v upozornění
další informace	Objekt Další informace	Vynulovatelné	-
Zpracovány	Logická hodnota, stav výstrahy	Nelze použít hodnotu null.	`true` nebo `false`

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í
název_senzoru	Řetězec	Nelze použít hodnotu null.	Název senzoru definovaný uživatelem
Název_zóny	Řetězec	Nelze použít hodnotu null.	Název zóny přidružené k senzoru
Sitename	Řetězec	Nelze použít hodnotu null.	Název lokality přidružené k senzoru

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

Příklad odpovědi

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

Rozhraní API:

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

Příklad:

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 (správa upozornění na základě UUID)

Pomocí tohoto rozhraní API můžete provést zadanou akci u konkrétní výstrahy zjištěné Defenderem for IoT.

Toto rozhraní API můžete například použít k vytvoření pravidla předávání, které předává data do QRadaru. Další informace najdete v tématu Integrace Qadaru s Microsoft Defender pro IoT.

Identifikátor URI: /external/v1/alerts/<UUID>

PUT

Typ: JSON

Parametry dotazu:

Název	Popis	Příklad	Povinné/volitelné
UUID	Definuje universálně jedinečný identifikátor (UUID) výstrahy, kterou chcete zpracovat nebo zpracovat a zjistit.	`/api/v1/alerts/7903F632-H7EJ-4N69-F40F-4B1E689G00Q0`	Vyžadováno

Parametry textu

Název	Popis	Příklad	Povinné/volitelné
Akce	Řetězec	Buď nebo `handlehandleAndLearn`	Vyžadováno

Příklad požadavku

{
    "action": "handle"
}

Typ: JSON

Pole objektů JSON, které představují zařízení.

Pole odpovědi:

Název	Typ	Povinné/volitelné	Popis
obsah nebo chyba	Řetězec	Vyžadováno	Pokud je požadavek úspěšný, zobrazí se vlastnost content. V opačném případě se zobrazí vlastnost error.

Možné hodnoty obsahu:

Stavový kód	Zpráva	Popis
200	Žádost o aktualizaci upozornění byla úspěšně dokončena.	Žádost o aktualizaci byla úspěšně dokončena. Žádné komentáře.
200	Výstraha už byla zpracována (popisovač).	Upozornění bylo již zpracováno při přijetí žádosti o zpracování výstrahy. Výstraha zůstane zpracována.
200	Výstraha už byla zpracována a naučila se (handleAndLearn).	Upozornění už bylo zpracováno a zjistilo se, když byla přijata žádost o zpracováníAndLearn . Výstraha zůstává ve stavu handledAndLearn .
200	Upozornění už bylo zpracováno (zpracováno). U upozornění se provedlo zpracování a učení (handleAndLearn).	Upozornění už bylo zpracováno, když byl přijat požadavek na zpracováníAndLearn . Upozornění se změní na handleAndLearn.
200	Výstraha už byla zpracována a naučila se (handleAndLearn). Ignorovaný požadavek na zpracování	Upozornění už bylo handleAndLearn , když byl přijat požadavek na zpracování výstrahy. Upozornění zůstane handleAndLearn.
500	Neplatná akce	Odeslaná akce není platná akce, která by se měla u výstrahy provést.
500	Došlo k neočekávané chybě.	Došlo k neočekávané chybě. Pokud chcete tento problém vyřešit, obraťte se na technickou podporu.
500	Požadavek se nepovedlo spustit, protože pro toto UUID se nenašlo žádné upozornění.	Zadané UUID výstrahy nebylo v systému nalezeno.

Příklad odpovědi: Úspěšná

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

Příklad odpovědi: Neúspěšné

{
    "error": "Invalid action"
}

Typ: PUT

Rozhraní API:

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

Příklad:

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

maintenanceWindow (vytváření vyloučení výstrah)

Spravuje časové intervaly údržby, ve kterých se nebudou odesílat upozornění. Pomocí tohoto rozhraní API můžete definovat a aktualizovat časy zastavení a spuštění, zařízení nebo podsítě, které by se měly vyloučit při aktivaci upozornění, nebo definovat a aktualizovat moduly Defender for IoT, které by měly být vyloučené.

Například během časového období údržby můžete chtít zastavit doručování všech výstrah s výjimkou upozornění na malware na důležitých zařízeních.

Časová období údržby definovaná rozhraním maintenanceWindow API se zobrazí v okně Vyloučení výstrah místní konzoly pro správu jako pravidlo vyloučení jen pro čtení s názvem s následující syntaxí: Maintenance-{token name}-{ticket ID}.

Důležité

Toto rozhraní API se podporuje pouze pro účely údržby a po omezenou dobu a není určeno k použití místo pravidel vyloučení upozornění. Toto rozhraní API slouží pouze k jednorázovým operacím dočasné údržby.

Identifikátor URI: /external/v1/maintenanceWindow

POST

Vytvoří nové časové období údržby.

Parametry textu:

Název	Popis	Příklad	Povinné/volitelné
ticketId	Řetězec. Definuje ID lístku údržby v systémech uživatele. Ujistěte se, že ID lístku není propojené s existujícím otevřeným oknem.	`2987345p98234`	Vyžadováno
Ttl	Kladné celé číslo. Definuje hodnotu TTL (Time to Live), což je doba trvání časového období údržby v minutách. Po dokončení definovaného časového období je časové období údržby u konce a systém se chová znovu normálně.	`180`	Vyžadováno
Motory	Pole řetězců JSON. Definuje, který modul má potlačit upozornění během časového období údržby. Možné hodnoty: - `ANOMALY` - `MALWARE` - `OPERATIONAL` - `POLICY_VIOLATION` - `PROTOCOL_VIOLATION`	`ANOMALY,OPERATIONAL`	Volitelné
sensorIds	Pole řetězců JSON. Definuje, ze kterých senzorů se mají potlačit upozornění během časového období údržby. Tato ID senzorů můžete získat z rozhraní API zařízení (Správa zařízení senzorů OT).	`1,35,63`	Volitelné
Podsítí	Pole řetězců JSON. Definuje podsítě, ze které se mají potlačit upozornění během časového období údržby. Definujte každou podsíť v zápisu CIDR.	`192.168.0.0/16,138.136.80.0/14,112.138.10.0/8`	Volitelné

Stavový kód	Zpráva	Popis
201 (vytvořeno)	-	Akce se úspěšně dokončila.
400 (Chybný požadavek)	Žádné ID lístku	V požadavku rozhraní API chyběla `ticketId` hodnota.
400 (Chybný požadavek)	Neplatná hodnota TTL	Požadavek rozhraní API obsahoval nekladnou nebo nečíselnou hodnotu TTL.
400 (Chybný požadavek)	Žádost se nepovedlo parsovat.	Problém s analýzou textu, například nesprávné parametry nebo neplatné hodnoty
400 (Chybný požadavek)	Časové období údržby se stejnými parametry již existuje.	Zobrazí se, pokud již existuje existující časové období údržby se stejnými podrobnostmi.
404 (Nenalezena)	Neznámé ID senzoru	Jeden ze senzorů uvedených v požadavku neexistuje.
409 (konflikt)	ID lístku už má otevřené okno.	ID lístku je propojené s jiným otevřeným časovým obdobím údržby.
500 (vnitřní chyba serveru)	-	Jakákoli jiná neočekávaná chyba.

Typ: POST

Rozhraní 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říklad:

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

Zavře existující časové období údržby.

Parametry dotazu:

Název	Popis	Příklad	Povinné/volitelné
ticketId	Definuje ID lístku údržby v systémech uživatele. Ujistěte se, že ID lístku je propojené s existujícím otevřeným oknem.	`2987345p98234`	Vyžadováno

Kódy chyb:

Kód	Zpráva	Popis
200 (OK)	-	Akce se úspěšně dokončila.
400 (Chybný požadavek)	Žádné ID lístku	V požadavku chybí parametr ticketId .
404 (Nenalezena):	Časové období údržby nebylo nalezeno.	ID lístku není propojené s otevřeným časovým obdobím údržby.
500 (vnitřní chyba serveru)	-	Jakákoli jiná neočekávaná chyba.

Typ: DELETE

Rozhraní API:

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

Příklad:

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

GET

Načtěte protokol všech akcí otevření (POST), zavření (DELETE) a aktualizace (PUT), které byly provedeny pomocí tohoto rozhraní API pro zpracování časových období údržby. T

Parametry dotazu:

Název	Popis	Příklad	Povinné/volitelné
fromDate	Filtruje protokoly z předdefinovaného data a novějšího. Formát je `YYYY-MM-DD`.	`2022-08-10`	Volitelné
datum	Filtruje protokoly až do předdefinovaného data. Formát je `YYYY-MM-DD`.	`2022-08-10`	Volitelné
ticketId	Filtruje protokoly související s konkrétním ID lístku.	`9a5fe99c-d914-4bda-9332-307384fe40bf`	Volitelné
název_tokenu	Filtruje protokoly související s konkrétním názvem tokenu.	quarterly-sanity-window	Volitelné

Kódy chyb:

Kód	Zpráva	Popis
200	OK	Akce se úspěšně dokončila.
204:	Žádný obsah	Neexistují žádná data, která by bylo potřeba zobrazit.
400	Chybný požadavek	Formát data je nesprávný.
500	Vnitřní chyba serveru	Jakákoli jiná neočekávaná chyba.

Typ: JSON

Pole objektů JSON, které představují operace časového období údržby.

Struktura odpovědi:

Název	Typ	S možnou hodnotou null / není nullable	Seznam hodnot
id	Dlouhé celé číslo	Nelze použít hodnotu null.	Interní ID aktuálního protokolu
Datetime	Řetězec	Nelze použít hodnotu null.	Čas, kdy k aktivitě došlo, například: `2022-04-23T18:25:43.511Z`
ticketId	Řetězec	Nelze použít hodnotu null.	ID časového období údržby. Příklad: `9a5fe99c-d914-4bda-9332-307384fe40bf`
název_tokenu	Řetězec	Nelze použít hodnotu null.	Název tokenu časového období údržby. Příklad: `quarterly-sanity-window`
Motory	Pole řetězců	Vynulovatelné	Moduly, na které se vztahuje časové období údržby, dodané při vytváření časového období údržby: `Protocol Violation`, `Policy Violation`, `Malware`, `Anomaly`nebo `Operational`
sensorIds	Pole řetězců	Vynulovatelné	Senzory, na které se vztahuje časové období údržby, dodané během vytváření časového období údržby.
Podsítí	Pole řetězců	Vynulovatelné	Podsítě, na které se vztahuje časové období údržby, poskytnuté při vytváření časového období údržby.
Ttl	Číselný	Vynulovatelné	Hodnota TTL (Time to Live) časového období údržby zadaná během vytváření nebo aktualizace časového období údržby.
Operationtype	Řetězec	Nelze použít hodnotu null.	Jedna z následujících hodnot: `OPEN`, `UPDATE`a `CLOSE`

Typ: GET

Rozhraní API:

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

Příklad:

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žňuje aktualizovat dobu trvání časového období údržby po spuštění procesu údržby změnou parametru ttl . Nová definice doby trvání přepíše předchozí definici.

Tato metoda je užitečná, pokud chcete nastavit delší dobu trvání, než je aktuálně nakonfigurovaná doba trvání. Pokud jste například původně definovali 180 minut, uplynulo 90 minut a chcete přidat dalších 30 minut, aktualizujte ttl hodnotu na 120 minutu a resetujte tak počet dob trvání.

Parametry dotazu:

Název	Popis	Příklad	Povinné/volitelné
ticketId	Řetězec. Definuje ID lístku údržby v systémech uživatele.	`2987345p98234`	Vyžadováno
Ttl	Kladné celé číslo. Definuje dobu trvání okna v minutách.	`210`	Vyžadováno

Kódy chyb:

Kód	Zpráva	Popis
200 (OK)	-	Akce se úspěšně dokončila.
400 (Chybný požadavek)	Žádné ID lístku	V požadavku chybí `ticketId` hodnota.
400 (Chybný požadavek)	Neplatná hodnota TTL	Hodnota TTL definovaná není číselná nebo není kladné celé číslo.
400 (Chybný požadavek)	Žádost se nepovedlo parsovat.	V požadavku chybí hodnota parametru `ttl` .
404 (Nenalezena)	Časové období údržby se nenašlo.	ID lístku není propojené s otevřeným časovým obdobím údržby.
500 (vnitřní chyba serveru)	-	Jakákoli jiná neočekávaná chyba.

Typ: PUT

Rozhraní API:

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

Příklad:

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 (žádost o upozornění PCAP)

Toto rozhraní API použijte k vyžádání souboru PCAP souvisejícího s upozorněním.

Identifikátor URI: /external/v2/alerts/

GET

Parametry dotazu:

Název	Popis	Příklad	Povinné/volitelné
id	ID upozornění z místní konzoly pro správu	`/external/v2/alerts/pcap/<id>`	Vyžadováno

Typ: JSON

Řetězec zprávy s podrobnostmi o stavu operace:

Stavový kód	Zpráva	Popis
200 (OK)	-	Objekt JSON s daty o požadovaném souboru PCAP. Další informace najdete v tématu Datová pole.
500 (vnitřní chyba serveru)	Upozornění se nenašlo.	Zadané ID upozornění nebylo v místní konzole pro správu nalezeno.
500 (vnitřní chyba serveru)	Chyba při získávání tokenu pro ID xsense `<number>`	Při získávání tokenu senzoru pro zadané ID senzoru došlo k chybě.
500 (vnitřní chyba serveru)	-	Jakákoli jiná neočekávaná chyba.

Datová pole

Název	Typ	S možnou hodnotou null / není nullable	Seznam hodnot
id	Číselný	Nelze použít hodnotu null.	ID upozornění místní konzoly pro správu
xsenseId	Číselný	Nelze použít hodnotu null.	ID senzoru
xsenseAlertId	Číselný	Nelze použít hodnotu null.	ID upozornění konzoly senzoru
downloadUrl	Řetězec	Nelze použít hodnotu null.	Adresa URL použitá ke stažení souboru PCAP
token	Řetězec	Nelze použít hodnotu null.	Token senzoru, který se má použít při stahování souboru PCAP

Příklad odpovědi: Úspěch

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

Příklad odpovědi: Chyba

{
  "error": "alert not found"
}

Typ: GET

Rozhraní API

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

* Příklad:

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

Další kroky

Další informace najdete v referenčním přehledu rozhraní Defender for IoT API.

Sdílet prostřednictvím

Referenční informace k rozhraní API pro správu upozornění pro místní konzoly pro správu

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

GET

Příklad odpovědi

UUID (správa upozornění na základě UUID)

PUT

Příklad odpovědi: Úspěšná

Příklad odpovědi: Neúspěšné

maintenanceWindow (vytváření vyloučení výstrah)

POST

DELETE

GET

PUT

pcap (žádost o upozornění PCAP)

GET

Datová pole

Příklad odpovědi: Úspěch

Příklad odpovědi: Chyba

Další kroky

Váš názor

Další materiály