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

I den här artikeln visas rest-API:er för aviseringshantering som stöds för lokala hanteringskonsoler för Microsoft Defender för IoT.

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

FÅ

Begäran

Frågeparametrar:

Namn	Beskrivning	Exempel	Obligatoriskt/valfritt
tillstånd	Få endast hanterade eller ohanterade aviseringar. Värden som stöds: - handled - unhandled Alla andra värden ignoreras.	/api/v1/alerts?state=handled	Valfri
fromTime	Få aviseringar skapade från och med en viss tidpunkt, i millisekunder från Epoch-tid och i UTC-tidszon.	/api/v1/alerts?fromTime=<epoch>	Valfri
toTime	Få aviseringar som skapats endast tidigare vid en viss tidpunkt, i millisekunder från Epoch-tid och i UTC-tidszon.	/api/v1/alerts?toTime=<epoch>	Valfri
siteId	Den webbplats där aviseringen upptäcktes.	/api/v1/alerts?siteId=1	Valfri
zoneId	Zonen där aviseringen upptäcktes.	/api/v1/alerts?zoneId=1	Valfri
sensorId	Sensorn som aviseringen upptäcktes på.	/api/v1/alerts?sensorId=1	Valfri

Not

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 plats- och zon-ID:t. Mer information finns i Integration API-referens för lokala hanteringskonsoler (offentlig förhandsversion).

Svar

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	-
zoneId	Numerisk	Inte nullbar	-
tid	Numerisk	Inte nullbar	Millisekunder från epoktid, i UTC-tidszon
rubrik	Sträng	Inte nullbar	-
meddelande	Sträng	Inte nullbar	-
allvarlighetsgrad	Sträng	Inte nullbar	Warning, Minor, Majoreller Critical
motor	Sträng	Inte nullbar	Protocol Violation, Policy Violation, Malware, Anomalyeller Operational
källaEnhet	Numerisk	Nullbar	Enhets-ID
destinationEnhet	Numerisk	Nullbar	Enhets-ID
reparationSteg	Sträng	Nullbar	Reparationssteg som visas i aviseringen
ytterligareInformation	Ytterligare informationsobjekt	Nullbar	-
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
källanDeviceAddress	Sträng	Nullbar	IP- eller MAC-adress
destinationDeviceAddress	Sträng	Nullbar	IP- eller MAC-adress
reparationSteg	JSON-matris	Inte nullbar	Strängar, reparationssteg som beskrivs i aviseringen
sensorName	Sträng	Inte nullbar	Namnet på sensorn som definierats av användaren
zoneName	Sträng	Inte nullbar	Namnet på zonen som är associerad med sensorn
siteName	Sträng	Inte nullbar	Namnet på platsen som är associerad med sensorn

Mer information finns i sensor-API-versionsreferens.

Svarsexempel

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

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 vidarebefordransregel som vidarebefordrar data till QRadar. Mer information finns i Integrera Qradar med Microsoft Defender för IoT.

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

STÄLLA

Begäran

typ: JSON

Frågeparametrar:

Namn	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	Krävs

Brödtextparametrar

Namn	Beskrivning	Exempel	Obligatoriskt/valfritt
åtgärd	Sträng	Antingen handle eller handleAndLearn	Krävs

Exempel på begäran

{
    "action": "handle"
}

Svar

typ: JSON

Matris med JSON-objekt som representerar enheter.

Fält för svar:

Namn	Typ	Obligatoriskt/valfritt	Beskrivning
innehåll/fel	Sträng	Krävs	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 (hantera).	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 (hanteraAndLearn).	Aviseringen hanterades redan och lärde sig när en begäran om att hanteraAndLearn togs emot. Aviseringen finns kvar i statusen hanteradeAndLearn.
200	Aviseringen hanterades redan (hanterades). Hantera och lär dig (handleAndLearn) utfördes på aviseringen.	Aviseringen hanterades redan när en begäran om att handleAndLearn togs emot. Aviseringen blir handleAndLearn.
200	Aviseringen har redan hanterats och lärts (hanteraAndLearn). Ignorerad handtagsbegäran.	Aviseringen var redan hanteraAndLearn när en begäran om att hantera aviseringen togs emot. Aviseringen förblir hanteraAndLearn.
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.	Ett oväntat fel uppstod. 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.	Det gick inte att hitta det angivna UUID-aviseringen i systemet.

Svarsexempel: Lyckades

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

Svarsexempel: Misslyckades

{
    "error": "Invalid action"
}

cURL-kommando

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 ett underhållsperiod kanske du till exempel vill stoppa aviseringsleveransen för alla aviseringar, förutom aviseringar om skadlig kod på kritiska enheter.

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

Viktig

Det här API:et stöds endast i underhållssyfte 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.

Begäran

brödtextparametrar:

Namn	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	Krävs
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	Krävs
motorer	JSON-matris med strängar. Definierar vilken motor som aviseringar ska ignoreras från under underhållsfönstret. Möjliga värden: - ANOMALY - MALWARE - OPERATIONAL - POLICY_VIOLATION - PROTOCOL_VIOLATION	ANOMALY,OPERATIONAL	Valfri
sensorIds	JSON-matris med strängar. Definierar vilka sensorer som ska ignorera aviseringar från under underhållsperioden. Du kan hämta dessa sensor-ID:n från -apparaterna (Hantera OT-sensorenheter)-API:et.	1,35,63	Valfri
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	Valfri

Svar

Statuskod	Meddelande	Beskrivning
201 (skapad)	-	Åtgärden har slutförts.
400 (felaktig begäran)	Inget TicketId	API-begäran saknade ett ticketId värde.
400 (felaktig begäran)	Ogiltig TTL	API-begäran innehöll 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 ett befintligt underhållsfönster 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.

cURL-kommando

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

TA BORT

Stänger en befintlig underhållsperiod.

Begäran

Frågeparametrar:

Namn	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	Krävs

Svar

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ållsfönstret.	Biljett-ID:t är inte länkat till en öppen underhållsperiod.
500 (internt serverfel)	-	Andra oväntade fel.

cURL-kommando

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

FÅ

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

Begäran

Frågeparametrar:

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

Felkoder:

Kod	Meddelande	Beskrivning
200	OKEJ	Å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.

Svar

typ: JSON

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

Svarsstruktur:

Namn	Typ	Nullable /Not nullable	Lista över värden
ID	Långt heltal	Inte nullbar	Ett internt ID för den aktuella loggen
dateTime	Sträng	Inte nullbar	Den tid då aktiviteten inträffade, till exempel: 2022-04-23T18:25:43.511Z
ticketId	Sträng	Inte nullbar	Underhållsfönstrets ID. Till exempel: 9a5fe99c-d914-4bda-9332-307384fe40bf
tokenName	Sträng	Inte nullbar	Namn på underhållsfönstertoken. Till exempel: quarterly-sanity-window
motorer	Matris med strängar	Nullbar	De motorer som underhållsperioden gäller för, enligt skapande av underhållsperiod: Protocol Violation, Policy Violation, Malware, Anomalyeller Operational
sensorIds	Strängmatris	Nullbar	De sensorer som underhållsperioden gäller för, som tillhandahålls när underhållsfönstret skapas.
undernät	Strängmatris	Nullbar	De undernät som underhållsperioden gäller för, enligt vad som angavs när underhållsfönstret skapades.
ttl	Numerisk	Nullbar	Underhållsfönstrets TTL (Time to Live), enligt vad som angavs när underhållsperioden skapades eller uppdaterades.
operationType	Sträng	Inte nullbar	Ett av följande värden: OPEN, UPDATEoch CLOSE

cURL-kommando

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'

STÄLLA

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 du ttl till 120 minut för att återställa varaktighetsantalet.

Begäran

Frågeparametrar:

Namn	Beskrivning	Exempel	Obligatoriskt/valfritt
ticketId	Sträng. Definierar underhållsbiljettens ID i användarens system.	2987345p98234	Krävs
ttl	Positivt heltal. Definierar varaktigheten för fönstret i minuter.	210	Krävs

Svar

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ållsfönstret	Biljett-ID:t är inte länkat till en öppen underhållsperiod.
500 (internt serverfel)	-	Andra oväntade fel.

cURL-kommando

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

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/

FÅ

Begäran

Frågeparametrar:

Namn	Beskrivning	Exempel	Obligatoriskt/valfritt
ID	Aviserings-ID från den lokala hanteringskonsolen	/external/v2/alerts/pcap/<id>	Krävs

Svar

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 skulle hämtas för det angivna sensor-ID:t
500 (internt serverfel)	-	Andra oväntade fel.

Datafält

Namn	Typ	Nullable /Not nullable	Lista över värden
ID	Numerisk	Inte nullbar	Aviserings-ID:t för den lokala hanteringskonsolen
xsenseId	Numerisk	Inte nullbar	Sensor-ID:t
xsenseAlertId	Numerisk	Inte nullbar	Sensorkonsolens aviserings-ID
downloadUrl	Sträng	Inte nullbar	Url:en som används för att ladda ned PCAP-filen
token	Sträng	Inte nullbar	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"
}

cURL-kommando

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 Defender för IoT API.