Referenční informace k rozhraní API pro správu výstrah pro místní konzoly pro správu

Tento článek obsahuje seznam rozhraní REST API pro správu výstrah podporovaných pro místní konzoly pro správu v programu Microsoft Defender for IoT.

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

Pomocí tohoto rozhraní API můžete načíst všechna nebo filtrovaná upozornění z místní konzoly pro správu.

identifikátoru URI : nebo

DOSTAT

žádost

parametry dotazu:

Jméno	Popis	Příklad	Povinné nebo volitelné
stavu	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ý
toTime	Získejte upozornění vytvořená pouze před daným časem 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ý
zoneId	Zóna, na 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

Možná nemáte ID webu a zóny. Pokud se jedná o tento případ, nejprve se dotázat na všechna zařízení, aby načetla ID webu a zóny. Další informace najdete v referenčních informacích k rozhraní Integration API pro místní konzoly pro správu (Public Preview).

Typ: JSON

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

Jméno	Typ	Nullable / Not nullable	Seznam hodnot
id	Číselný	Nelze použít hodnotu null.	-
sensorId	Číselný	Nelze použít hodnotu null.	-
zoneId	Číselný	Nelze použít hodnotu null.	-
čas	Číselný	Nelze použít hodnotu null.	Milisekundy od epochy, v časovém pásmu UTC
nadpisu	Řetězec	Nelze použít hodnotu null.	-
zprávy	Ř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, Malware, Anomalynebo Operational
sourceDevice	Číselný	Nullable	ID zařízení
destinationDevice	Číselný	Nullable	ID zařízení
nápravné kroky	Řetězec	Nullable	Nápravné kroky zobrazené v upozornění
další informační	Další informační objekt	Nullable	-
zpracovávané	Logická hodnota, stav výstrahy	Nelze použít hodnotu null.	true nebo false

Další informační pole:

Jméno	Typ	Nullable / Not nullable	Seznam hodnot
popis	Řetězec	Nelze použít hodnotu null.	-
informace	Pole JSON	Nelze použít hodnotu null.	Řetězec

přidáno proV2:

Jméno	Typ	Nullable / Not nullable	Seznam hodnot
sourceDeviceAddress	Řetězec	Nullable	IP adresa nebo adresa MAC
destinationDeviceAddress	Řetězec	Nullable	IP adresa nebo adresa MAC
nápravné kroky	Pole JSON	Nelze použít hodnotu null.	Řetězce, kroky nápravy popsané v upozornění
sensorName	Řetězec	Nelze použít hodnotu null.	Název senzoru definovaného uživatelem
zoneName	Řetězec	Nelze použít hodnotu null.	Název zóny přidružené k senzoru
název_webu	Řetězec	Nelze použít hodnotu null.	Název lokality asociované se senzorem

Další informace najdete v referenční informace k verzi rozhraní API snímače.

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 pro IoT.

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

identifikátoru URI: /external/v1/alerts/<UUID>

DÁT

žádost

Typ: JSON

parametry dotazu:

Jméno	Popis	Příklad	Povinné nebo volitelné
UUID	Definuje univerzální jedinečný identifikátor (UUID) pro výstrahu, kterou chcete zpracovat nebo zpracovat a naučit se.	/api/v1/alerts/7903F632-H7EJ-4N69-F40F-4B1E689G00Q0	Požadovaný

parametry textu

Jméno	Popis	Příklad	Povinné nebo volitelné
akce	Řetězec	handle nebo handleAndLearn	Požadovaný

Příklad požadavku

{
    "action": "handle"
}

Typ: JSON

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

pole odpovědi :

Jméno	Typ	Povinné nebo volitelné	Popis
obsah / chyb	Řetězec	Požadovaný	Pokud je požadavek úspěšný, zobrazí se vlastnost obsahu. V opačném případě se zobrazí chybová vlastnost.

Možné hodnoty obsahu:

Stavový kód	Zpráva	Popis
200	Žádost o aktualizaci výstrah byla úspěšně dokončena.	Žádost o aktualizaci byla úspěšně dokončena. Žádné komentáře.
200	Výstraha byla již zpracována (popisovač).	Výstraha se už zpracovávala, když se zobrazila žádost o zpracování výstrahy. Výstraha zůstává zpracována.
200	Upozornění bylo již zpracováno a naučeno (handleAndLearn).	Výstraha se už zpracovala a dozvěděla se, když byla přijata žádost o zpracováníAndLearn. Výstraha zůstane ve stavu zpracována AndLearn.
200	Výstraha byla již zpracována (zpracována). Obslužná rutina a výuka (handleAndLearn) byla u výstrahy provedena.	Výstraha už byla zpracována, když byla přijata žádost o zpracováníAndLearn. Výstraha se stane handleAndLearn.
200	Upozornění bylo již zpracováno a naučeno (handleAndLearn). Ignorované zpracování požadavku	Výstraha již byla zpracováníAndLearn, když byla přijata žádost o zpracování výstrahy. Výstraha zůstane handleAndLearn.
500	Neplatná akce	Akce, která byla odeslána, není platná akce, která se má s výstrahou 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	Žádost se nepovedlo spustit, protože pro toto UUID nebyla nalezena žádná výstraha.	Zadaný identifikátor UUID upozornění nebyl v systému nalezen.

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 (vytvoření vyloučení výstrah)

Spravuje časové období údržby, pod kterými 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 Defenderu pro IoT, které by se měly vyloučit.

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

Časová období údržby, která definují rozhraní API maintenanceWindow, 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 je podporováno 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 použijte pouze pro jednorázové dočasné operace údržby.

identifikátoru URI: /external/v1/maintenanceWindow

POST

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

žádost

základní parametry:

Jméno	Popis	Příklad	Povinné nebo volitelné
id lístku	Ř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	Požadovaný
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í se časové období údržby překoná a systém se chová normálně znovu.	180	Požadovaný
motory	Pole JSON řetězců Definuje, který modul má potlačit výstrahy během časového období údržby. Možné hodnoty: - ANOMALY - MALWARE - OPERATIONAL - POLICY_VIOLATION - PROTOCOL_VIOLATION	ANOMALY,OPERATIONAL	Volitelný
sensorIds	Pole JSON řetězců Definuje, které senzory potlačí výstrahy během časového období údržby. Tato ID snímačů můžete získat z zařízení (správa zařízení snímačů OT) rozhraní API.	1,35,63	Volitelný
podsítě	Pole JSON řetězců Definuje podsítě, ze které se mají potlačit výstrahy 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 byla úspěšně dokončena.
400 (chybný požadavek)	Bez ID lístku	V požadavku rozhraní API nebyla nalezena hodnota ticketId.
400 (chybný požadavek)	Neplatná hodnota TTL	Požadavek rozhraní API obsahoval nekladnou nebo nečíselná hodnotu TTL.
400 (chybný požadavek)	Požadavek nelze analyzovat.	Problém s analýzou textu, například nesprávných parametrů nebo neplatných hodnot
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 (konfliktní)	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

VYMAZAT

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

žádost

parametry dotazu:

Jméno	Popis	Příklad	Povinné nebo volitelné
id lístku	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	Požadovaný

kódy chyb :

Kód	Zpráva	Popis
200 (OK)	-	Akce byla úspěšně dokončena.
400 (chybný požadavek)	Bez ID lístku	V požadavku chybí parametr ticketId.
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: 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

DOSTAT

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

žádost

parametry dotazu:

Jméno	Popis	Příklad	Povinné nebo volitelné
fromDate	Filtruje protokoly z předdefinovaného data a novějšího. Formát je YYYY-MM-DD.	2022-08-10	Volitelný
	Filtruje protokoly až do předdefinovaného data. Formát je YYYY-MM-DD.	2022-08-10	Volitelný
id lístku	Filtruje protokoly související s konkrétním ID lístku.	9a5fe99c-d914-4bda-9332-307384fe40bf	Volitelný
tokenName	Filtruje protokoly související s konkrétním názvem tokenu.	čtvrtletní-sanity-window	Volitelný

kódy chyb :

Kód	Zpráva	Popis
200	OK	Akce byla úspěšně dokončena.
204:	Žádný obsah	Neexistují žádná data, která by se zobrazila.
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.

struktury odpovědi :

Jméno	Typ	Nullable / Not 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 došlo k aktivitě, například: 2022-04-23T18:25:43.511Z
id lístku	Řetězec	Nelze použít hodnotu null.	ID časového období údržby. Příklad: 9a5fe99c-d914-4bda-9332-307384fe40bf
tokenName	Řetězec	Nelze použít hodnotu null.	Název tokenu časového období údržby. Příklad: quarterly-sanity-window
motory	Pole řetězců	Nullable	Motory, na kterých se vztahuje časové období údržby, jak je uvedeno při vytváření časového období údržby: Protocol Violation, Policy Violation, Malware, Anomalynebo Operational
sensorIds	Pole řetězce	Nullable	Senzory, na kterých se vztahuje časové období údržby, jak je dodáno během vytváření časového období údržby.
podsítě	Pole řetězce	Nullable	Podsítě, na kterých se vztahuje časové období údržby, jak je uvedeno při vytváření časového období údržby.
ttl	Číselný	Nullable	Časové období údržby (TTL), jak je uvedeno při vytváření nebo aktualizaci časového období údržby.
operationType	Řetězec	Nelze použít hodnotu null.	Jedna z následujících hodnot: OPEN, UPDATEa 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'

DÁT

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í.

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 na 120 minutu a obnovte tak počet trvání.

žádost

parametry dotazu:

Jméno	Popis	Příklad	Povinné nebo volitelné
id lístku	Řetězec. Definuje ID lístku údržby v systémech uživatele.	2987345p98234	Požadovaný
ttl	Kladné celé číslo. Definuje dobu trvání okna v minutách.	210	Požadovaný

kódy chyb :

Kód	Zpráva	Popis
200 (OK)	-	Akce byla úspěšně dokončena.
400 (chybný požadavek)	Bez ID lístku	V požadavku chybí hodnota ticketId.
400 (chybný požadavek)	Neplatná hodnota TTL	Hodnota TTL definovaná není číselné nebo není kladné celé číslo.
400 (chybný požadavek)	Žádost se nepovedlo analyzovat.	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 slouží k vyžádání souboru PCAP souvisejícího s výstrahou.

identifikátoru URI: /external/v2/alerts/

DOSTAT

žádost

parametry dotazu:

Jméno	Popis	Příklad	Povinné nebo volitelné
id	ID upozornění z místní konzoly pro správu	/external/v2/alerts/pcap/<id>	Požadovaný

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ých polích.
500 (vnitřní chyba serveru)	Výstraha nebyla nalezena.	Zadané ID upozornění se nenašlo v místní konzole pro správu.
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

Jméno	Typ	Nullable / Not 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 výstrahy konzoly senzoru
downloadUrl	Řetězec	Nelze použít hodnotu null.	Adresa URL použitá ke stažení souboru PCAP
tokenu	Ř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ích informacích krozhraní API Defenderu pro IoT.