API-referens för aviseringshantering för lokala hanteringskonsoler

Artikel
06/01/2023

Den här artikeln innehåller rest-API:er för aviseringshantering som stöds för Microsoft Defender för lokala IoT-hanteringskonsoler.

aviseringar (Hämta aviseringsinformation)

Använd det här API:et för att hämta alla eller filtrerade aviseringar från en lokal hanteringskonsol.

URI: /external/v1/alerts eller /external/v2/alerts

GET

Frågeparametrar:

Name	Beskrivning	Exempel	Obligatoriskt/valfritt
Statligt	Få endast hanterade eller ohanterade aviseringar. Värden som stöds: - `handled` - `unhandled` Alla andra värden ignoreras.	`/api/v1/alerts?state=handled`	Valfritt
fromTime	Hämta aviseringar som skapats med början vid en viss tidpunkt, i millisekunder från Epoch-tid och i UTC-tidszon.	`/api/v1/alerts?fromTime=<epoch>`	Valfritt
toTime	Hämta aviseringar som skapats endast före vid en viss tidpunkt, i millisekunder från Epoch-tid och i UTC-tidszon.	`/api/v1/alerts?toTime=<epoch>`	Valfritt
siteId	Den plats där aviseringen upptäcktes.	`/api/v1/alerts?siteId=1`	Valfritt
Zonid	Zonen där aviseringen upptäcktes.	`/api/v1/alerts?zoneId=1`	Valfritt
sensorId	Sensorn som aviseringen upptäcktes på.	`/api/v1/alerts?sensorId=1`	Valfritt

Anteckning

Du kanske inte har plats- och zon-ID:t. I så fall måste du först fråga alla enheter för att hämta platsen och zon-ID:t. Mer information finns i Referens för integrations-API för lokala hanteringskonsoler (offentlig förhandsversion).

Typ: JSON

En lista över aviseringar med följande fält:

Namn	Typ	Nullable/Not nullable	Lista över värden
Id	Numerisk	Inte nullbar	-
sensorId	Numerisk	Inte nullbar	-
Zonid	Numerisk	Inte nullbar	-
Tid	Numerisk	Inte nullbar	Millisekunder från epoktid, i UTC-tidszon
title	Sträng	Inte nullbar	-
meddelande	Sträng	Inte nullbar	-
Svårighetsgrad	Sträng	Inte nullbar	`Warning`, `Minor`, `Major`eller `Critical`
Motor	Sträng	Inte nullbar	`Protocol Violation`, `Policy Violation`, `Malware`, `Anomaly`eller `Operational`
sourceDevice	Numerisk	Kan ha värdet null	Enhets-ID
destinationEnhet	Numerisk	Kan ha värdet null	Enhets-ID
remediationSteps	Sträng	Kan ha värdet null	Reparationssteg som visas i aviseringen
additionalInformation	Ytterligare informationsobjekt	Kan ha värdet null	-
Hanteras	Booleskt tillstånd för aviseringen	Inte nullbar	`true` eller `false`

Ytterligare informationsfält:

Namn	Typ	Nullable/Not nullable	Lista över värden
beskrivning	Sträng	Inte nullbar	-
Information	JSON-matris	Inte nullbar	Sträng

Har lagts till för V2:

Namn	Typ	Nullable/Not nullable	Lista över värden
sourceDeviceAddress	Sträng	Kan ha värdet null	IP- eller MAC-adress
destinationDeviceAddress	Sträng	Kan ha värdet null	IP- eller MAC-adress
remediationSteps	JSON-matris	Inte nullbar	Strängar, reparationssteg som beskrivs i aviseringen
sensorName	Sträng	Inte nullbar	Namnet på sensorn som definierats av användaren
Zonnamn	Sträng	Inte nullbar	Namnet på zonen som är associerad med sensorn
Platsnamn	Sträng	Inte nullbar	Namnet på platsen som är associerad med sensorn

Mer information finns i Referens för sensor-API-version.

Exempel på svar

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

API:

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

Exempel:

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 (Hantera aviseringar baserat på UUID)

Använd det här API:et för att vidta angivna åtgärder för en specifik avisering som identifierats av Defender för IoT.

Du kan till exempel använda det här API:et för att skapa en vidarebefordringsregel som vidarebefordrar data till QRadar. Mer information finns i Integrera Qradar med Microsoft Defender för IoT.

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

PUT

Typ: JSON

Frågeparametrar:

Name	Beskrivning	Exempel	Obligatoriskt/valfritt
UUID	Definierar den universellt unika identifieraren (UUID) för den avisering som du vill hantera eller hantera och lära dig.	`/api/v1/alerts/7903F632-H7EJ-4N69-F40F-4B1E689G00Q0`	Obligatorisk

Brödtextparametrar

Name	Beskrivning	Exempel	Obligatoriskt/valfritt
Åtgärder	Sträng	Antingen `handle` eller `handleAndLearn`	Obligatorisk

Exempel på begäran

{
    "action": "handle"
}

Typ: JSON

Matris med JSON-objekt som representerar enheter.

Svarsfält:

Namn	Typ	Obligatoriskt/valfritt	Beskrivning
innehåll/fel	Sträng	Obligatorisk	Om begäran lyckas visas innehållsegenskapen. Annars visas felegenskapen.

Möjliga innehållsvärden:

Statuskod	Meddelande	Beskrivning
200	Begäran om aviseringsuppdatering har slutförts.	Uppdateringsbegäran har slutförts. Inga kommentarer.
200	Aviseringen har redan hanterats (handtaget).	Aviseringen hanterades redan när en referensbegäran för aviseringen togs emot. Aviseringen förblir hanterad.
200	Aviseringen har redan hanterats och lärts (handleAndLearn).	Aviseringen hanterades redan och lärde sig när en begäran om att hanteraAndLearn togs emot. Aviseringen förblir i statusen hanteradAndLearn .
200	Aviseringen hanterades redan (hanterades). Hantera och lära (handleAndLearn) utfördes på aviseringen.	Aviseringen hanterades redan när en begäran om att hanteraAndLearn togs emot. Aviseringen blir handleAndLearn.
200	Aviseringen har redan hanterats och lärts (handleAndLearn). Ignorerad handtagsbegäran.	Aviseringen hanterades redanAndLearn när en begäran om att hantera aviseringen togs emot. Aviseringen förblir handleAndLearn.
500	Ogiltig åtgärd.	Åtgärden som skickades är inte en giltig åtgärd att utföra i aviseringen.
500	Ett oväntat fel uppstod.	Det uppstod ett oväntat fel. Kontakta teknisk support för att lösa problemet.
500	Det gick inte att köra begäran eftersom ingen avisering hittades för detta UUID.	Den angivna aviseringen UUID hittades inte i systemet.

Svarsexempel: Lyckades

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

Svarsexempel: Misslyckades

{
    "error": "Invalid action"
}

Typ: PUT

API:er:

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

Exempel:

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

maintenanceWindow (Skapa aviseringsundantag)

Hanterar underhållsperioder, under vilka aviseringar inte skickas. Använd det här API:et för att definiera och uppdatera stopp- och starttider, enheter eller undernät som ska undantas när aviseringar utlöses, eller definiera och uppdatera Defender för IoT-motorer som ska undantas.

Under en underhållsperiod kanske du till exempel vill stoppa aviseringsleveransen av alla aviseringar, förutom aviseringar om skadlig kod på kritiska enheter.

Underhållsperioderna som definierar med API:et maintenanceWindow visas i den lokala hanteringskonsolens aviseringsundantagsfönster som en skrivskyddad undantagsregel med namnet med följande syntax: Maintenance-{token name}-{ticket ID}.

Viktigt

Det här API:et stöds endast för underhåll och under en begränsad tidsperiod och är inte avsett att användas i stället för regler för aviseringsundantag. Använd det här API:et endast för engångsåtgärder för tillfälligt underhåll.

URI: /external/v1/maintenanceWindow

POST

Skapar en ny underhållsperiod.

Brödtextparametrar:

Name	Beskrivning	Exempel	Obligatoriskt/valfritt
ticketId	Sträng. Definierar underhållsbiljettens ID i användarens system. Kontrollera att biljett-ID:t inte är länkat till ett befintligt öppet fönster.	`2987345p98234`	Obligatorisk
Ttl	Positivt heltal. Definierar TTL (time to live), som är varaktigheten för underhållsfönstret, i minuter. När den definierade tidsperioden har slutförts är underhållsfönstret över och systemet fungerar normalt igen.	`180`	Obligatorisk
Motorer	JSON-matris med strängar. Definierar vilken motor som ska ignorera aviseringar från under underhållsfönstret. Möjliga värden: - `ANOMALY` - `MALWARE` - `OPERATIONAL` - `POLICY_VIOLATION` - `PROTOCOL_VIOLATION`	`ANOMALY,OPERATIONAL`	Valfritt
sensorIds	JSON-matris med strängar. Definierar vilka sensorer som ska ignorera aviseringar från under underhållsfönstret. Du kan hämta dessa sensor-ID:n från apparat-API:et (Hantera OT-sensorenheter).	`1,35,63`	Valfritt
Undernät	JSON-matris med strängar. Definierar undernäten för att förhindra aviseringar från under underhållsperioden. Definiera varje undernät i en CIDR-notation.	`192.168.0.0/16,138.136.80.0/14,112.138.10.0/8`	Valfritt

Statuskod	Meddelande	Beskrivning
201 (skapad)	-	Åtgärden slutfördes.
400 (felaktig begäran)	Inget TicketId	API-begäran saknade ett `ticketId` värde.
400 (felaktig begäran)	Ogiltig TTL	API-begäran inkluderade ett icke-positivt eller icke-numeriskt TTL-värde.
400 (felaktig begäran)	Det gick inte att parsa begäran.	Problem med att parsa brödtexten, till exempel felaktiga parametrar eller ogiltiga värden.
400 (felaktig begäran)	Underhållsfönstret med samma parametrar finns redan.	Visas när det redan finns en befintlig underhållsperiod med samma information.
404 (hittades inte)	Okänt sensor-ID	En av sensorerna som anges i begäran finns inte.
409 (konflikt)	Biljett-ID har redan ett öppet fönster.	Biljett-ID:t är länkat till en annan öppen underhållsperiod.
500 (internt serverfel)	-	Andra oväntade fel.

Typ: 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

Exempel:

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

Stänger en befintlig underhållsperiod.

Frågeparametrar:

Name	Beskrivning	Exempel	Obligatoriskt/valfritt
ticketId	Definierar underhållsbiljettens ID i användarens system. Kontrollera att biljett-ID:t är länkat till ett befintligt öppet fönster.	`2987345p98234`	Obligatorisk

Felkoder:

Kod	Meddelande	Beskrivning
200 (OK)	-	Åtgärden har slutförts.
400 (felaktig begäran)	Inget TicketId	Parametern ticketId saknas i begäran.
404 (hittades inte):	Det går inte att hitta underhållsperioden.	Biljett-ID:t är inte länkat till en öppen underhållsperiod.
500 (internt serverfel)	-	Andra oväntade fel.

Typ: DELETE

API:

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

Exempel:

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

GET

Hämta en logg över alla öppna åtgärder (POST), stäng (DELETE) och uppdatera (PUT) som utfördes med hjälp av det här API:et för hantering av underhållsperioder. T

Frågeparametrar:

Name	Beskrivning	Exempel	Obligatoriskt/valfritt
fromDate	Filtrerar loggarna från det fördefinierade datumet och senare. Formatet är `YYYY-MM-DD`.	`2022-08-10`	Valfritt
toDate	Filtrerar loggarna fram till det fördefinierade datumet. Formatet är `YYYY-MM-DD`.	`2022-08-10`	Valfritt
ticketId	Filtrerar loggarna som är relaterade till ett specifikt biljett-ID.	`9a5fe99c-d914-4bda-9332-307384fe40bf`	Valfritt
tokenName	Filtrerar loggarna som är relaterade till ett specifikt tokennamn.	quarterly-sanity-window	Valfritt

Felkoder:

Kod	Meddelande	Beskrivning
200	OK	Åtgärden har slutförts.
204:	Inget innehåll	Det finns inga data att visa.
400	Felaktig begäran	Datumformatet är felaktigt.
500	Internt serverfel	Andra oväntade fel.

Typ: JSON

Matris med JSON-objekt som representerar underhållsperiodåtgärder.

Svarsstruktur:

Namn	Typ	Nullbar/kan inte ha värdet null	Lista över värden
id	Långt heltal	Kan inte ha värdet null	Ett internt ID för den aktuella loggen
Datetime	Sträng	Kan inte ha värdet null	Den tid då aktiviteten inträffade, till exempel: `2022-04-23T18:25:43.511Z`
ticketId	Sträng	Kan inte ha värdet null	Underhållsfönstrets ID. Exempelvis: `9a5fe99c-d914-4bda-9332-307384fe40bf`
tokenName	Sträng	Kan inte ha värdet null	Namn på token för underhållsperiod. Exempelvis: `quarterly-sanity-window`
Motorer	Strängmatris	Kan ha värdet null	De motorer som underhållsperioden gäller för, enligt vad som tillhandahålls under skapande av underhållsperiod: `Protocol Violation`, `Policy Violation`, `Malware`, `Anomaly`eller `Operational`
sensorIds	Strängmatris	Kan ha värdet null	De sensorer som underhållsperioden gäller för, enligt vad som tillhandahålls vid skapande av underhållsperiod.
Undernät	Strängmatris	Kan ha värdet null	De undernät som underhållsperioden gäller för, enligt vad som anges när underhållsperioden skapas.
Ttl	Numerisk	Kan ha värdet null	Underhållsperiodens TTL (Time to Live), enligt vad som angavs när underhållsperioden skapades eller uppdaterades.
operationType	Sträng	Kan inte ha värdet null	Ett av följande värden: `OPEN`, `UPDATE`och `CLOSE`

Typ: GET

API:

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

Exempel:

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

Gör att du kan uppdatera varaktigheten för underhållsperioden när du har startat underhållsprocessen genom att ändra parametern ttl . Den nya varaktighetsdefinitionen åsidosätter den föregående.

Den här metoden är användbar när du vill ange en längre varaktighet än den för närvarande konfigurerade varaktigheten. Om du till exempel ursprungligen har definierat 180 minuter, 90 minuter har passerat och du vill lägga till ytterligare 30 minuter uppdaterar ttl du till 120 minut för att återställa varaktighetsantalet.

Frågeparametrar:

Name	Beskrivning	Exempel	Obligatoriskt/valfritt
ticketId	Sträng. Definierar underhållsbiljettens ID i användarens system.	`2987345p98234`	Obligatorisk
Ttl	Positivt heltal. Definierar varaktigheten för fönstret i minuter.	`210`	Obligatorisk

Felkoder:

Kod	Meddelande	Beskrivning
200 (OK)	-	Åtgärden har slutförts.
400 (felaktig begäran)	Inget TicketId	Begäran saknar ett `ticketId` värde.
400 (felaktig begäran)	Ogiltig TTL	TTL-definitionen är inte numerisk eller inte ett positivt heltal.
400 (felaktig begäran)	Det gick inte att parsa begäran	Begäran saknar ett `ttl` parametervärde.
404 (hittades inte)	Det går inte att hitta underhållsperioden	Biljett-ID:t är inte länkat till en öppen underhållsperiod.
500 (internt serverfel)	-	Andra oväntade fel.

Typ: PUT

API:

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

Exempel:

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 (begärandeavisering PCAP)

Använd det här API:et för att begära en PCAP-fil som är relaterad till en avisering.

URI: /external/v2/alerts/

GET

Frågeparametrar:

Name	Beskrivning	Exempel	Obligatoriskt/valfritt
id	Aviserings-ID från den lokala hanteringskonsolen	`/external/v2/alerts/pcap/<id>`	Obligatorisk

Typ: JSON

Meddelandesträng med information om åtgärdsstatus:

Statuskod	Meddelande	Beskrivning
200 (OK)	-	JSON-objekt med data om den begärda PCAP-filen. Mer information finns i Datafält.
500 (internt serverfel)	Aviseringen hittades inte	Det angivna aviserings-ID:t hittades inte i den lokala hanteringskonsolen.
500 (internt serverfel)	Fel vid hämtar token för xsense-ID `<number>`	Ett fel uppstod när sensorns token hämtades för det angivna sensor-ID:t
500 (internt serverfel)	-	Andra oväntade fel.

Datafält

Namn	Typ	Nullbar/kan inte ha värdet null	Lista över värden
id	Numerisk	Kan inte ha värdet null	Aviserings-ID för den lokala hanteringskonsolen
xsenseId	Numerisk	Kan inte ha värdet null	Sensor-ID:t
xsenseAlertId	Numerisk	Kan inte ha värdet null	Sensorkonsolens aviserings-ID
downloadUrl	Sträng	Kan inte ha värdet null	Url:en som används för att ladda ned PCAP-filen
token	Sträng	Kan inte ha värdet null	Sensorns token som ska användas vid nedladdning av PCAP-filen

Svarsexempel: Lyckades

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

Svarsexempel: Fel

{
  "error": "alert not found"
}

Typ: GET

API:er

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

*Exempel:

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

Nästa steg

Mer information finns i referensöversikten för Defender för IoT API.

Dela via

API-referens för aviseringshantering för lokala hanteringskonsoler

aviseringar (Hämta aviseringsinformation)

GET

Exempel på svar

UUID (Hantera aviseringar baserat på UUID)

PUT

Svarsexempel: Lyckades

Svarsexempel: Misslyckades

maintenanceWindow (Skapa aviseringsundantag)

POST

DELETE

GET

PUT

pcap (begärandeavisering PCAP)

GET

Datafält

Svarsexempel: Lyckades

Svarsexempel: Fel

Nästa steg

Ytterligare resurser