Informations de référence sur l’API de gestion des alertes pour les consoles de gestion locales

Cet article répertorie les API REST de gestion des alertes prises en charge pour les consoles de gestion locales Microsoft Defender pour IoT.

alertes (récupérer les informations d’alerte)

Utilisez cette API pour récupérer toutes les alertes ou filtrer à partir d’une console de gestion locale.

URI : /external/v1/alerts ou /external/v2/alerts

AVOIR

demande de

paramètres de requête:

Nom	Description	Exemple	Obligatoire /Facultatif
d’état	Obtenez uniquement des alertes gérées ou non gérées. Valeurs prises en charge : - handled - unhandled Toutes les autres valeurs sont ignorées.	/api/v1/alerts?state=handled	Optionnel
fromTime	Obtenez des alertes créées à partir d’un moment donné, en millisecondes à partir de l’heure de l’époque et dans le fuseau horaire UTC.	/api/v1/alerts?fromTime=<epoch>	Optionnel
toTime	Obtenez des alertes créées uniquement avant à un moment donné, en millisecondes à partir de l’heure de l’époque et dans le fuseau horaire UTC.	/api/v1/alerts?toTime=<epoch>	Optionnel
siteId	Site sur lequel l’alerte a été découverte.	/api/v1/alerts?siteId=1	Optionnel
zoneId	Zone sur laquelle l’alerte a été découverte.	/api/v1/alerts?zoneId=1	Optionnel
sensorId	Capteur sur lequel l’alerte a été découverte.	/api/v1/alerts?sensorId=1	Optionnel

Note

Vous n’avez peut-être pas l’ID de site et de zone. Si c’est le cas, interrogez d’abord tous les appareils pour récupérer le site et l’ID de zone. Pour plus d’informations, consultez informations de référence sur l’API d’intégration pour les consoles de gestion locales (préversion publique).

Réponse

type: JSON

Liste des alertes avec les champs suivants :

Nom	Type	Nullable / Non nullable	Liste des valeurs
id de	Numérique	Non nullable	-
sensorId	Numérique	Non nullable	-
zoneId	Numérique	Non nullable	-
heure	Numérique	Non nullable	Millisecondes de heure d’époque, en fuseau horaire UTC
titre	Corde	Non nullable	-
message	Corde	Non nullable	-
gravité	Corde	Non nullable	Warning, Minor, Majorou Critical
moteur	Corde	Non nullable	Protocol Violation, Policy Violation, Malware, Anomalyou Operational
sourceDevice	Numérique	Nullable	ID d’appareil
destinationDevice	Numérique	Nullable	ID d’appareil
correctionSteps	Corde	Nullable	Étapes de correction affichées dans l’alerte
d’informations supplémentaires	Objet d’informations supplémentaires	Nullable	-
géré	Boolean, état de l’alerte	Non nullable	true ou false

champs d’informations supplémentaires:

Nom	Type	Nullable / Non nullable	Liste des valeurs
description	Corde	Non nullable	-
informations	Tableau JSON	Non nullable	Corde

ajouté pour laV2 :

Nom	Type	Nullable / Non nullable	Liste des valeurs
sourceDeviceAddress	Corde	Nullable	Adresse IP ou MAC
destinationDeviceAddress	Corde	Nullable	Adresse IP ou MAC
correctionSteps	Tableau JSON	Non nullable	Chaînes, étapes de correction décrites dans l’alerte
sensorName	Corde	Non nullable	Nom du capteur défini par l’utilisateur
zoneName	Corde	Non nullable	Nom de la zone associée au capteur
siteName	Corde	Non nullable	Nom du site associé au capteur

Pour plus d’informations, consultez informations de référence sur la version de l’API Sensor.

Exemple de réponse

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

commande cURL

type: GET

API:

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

exemple :

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 (Gérer les alertes en fonction de l’UUID)

Utilisez cette API pour effectuer une action spécifiée sur une alerte spécifique détectée par Defender pour IoT.

Par exemple, vous pouvez utiliser cette API pour créer une règle de transfert qui transfère les données à QRadar. Pour plus d’informations, consultez Intégrer Qradar à Microsoft Defender pour IoT.

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

METTRE

demande de

type: JSON

paramètres de requête:

Nom	Description	Exemple	Obligatoire /Facultatif
UUID	Définit l’identificateur universel unique (UUID) de l’alerte que vous souhaitez gérer ou gérer et apprendre.	/api/v1/alerts/7903F632-H7EJ-4N69-F40F-4B1E689G00Q0	Obligatoire

paramètres corps

Nom	Description	Exemple	Obligatoire /Facultatif
action	Corde	handle ou handleAndLearn	Obligatoire

exemple de requête

{
    "action": "handle"
}

Réponse

type: JSON

Tableau d’objets JSON qui représentent des appareils.

champs réponse :

Nom	Type	Obligatoire /Facultatif	Description
contenu / d’erreur	Corde	Obligatoire	Si la demande réussit, la propriété de contenu s’affiche. Sinon, la propriété d’erreur s’affiche.

Valeurs de contenu possibles:

Code d’état	Message	Description
200	La demande de mise à jour d’alerte s’est terminée avec succès.	La demande de mise à jour s’est terminée correctement. Aucun commentaire.
200	L’alerte a déjà été gérée (handle).	L’alerte a déjà été gérée lorsqu’une demande de handle pour l’alerte a été reçue. L’alerte reste gérée.
200	L’alerte a déjà été gérée et apprise (handleAndLearn).	L’alerte a déjà été gérée et apprise lorsqu’une demande de handleAndLearn a été reçue. L’alerte reste dans l’état handledAndLearn.
200	L’alerte a déjà été gérée (gérée). Handle and learn (handleAndLearn) a été effectué sur l’alerte.	L’alerte a déjà été gérée lorsqu’une demande de handleAndLearn a été reçue. L’alerte devient handleAndLearn.
200	L’alerte a déjà été gérée et apprise (handleAndLearn). Demande de handle ignorée.	L’alerte était déjà handleAndLearn lorsqu’une demande de gestion de l’alerte a été reçue. L’alerte reste handleAndLearn.
500	Action non valide.	L’action envoyée n’est pas une action valide à effectuer sur l’alerte.
500	Une erreur inattendue s’est produite.	Une erreur inattendue s’est produite. Pour résoudre le problème, contactez le support technique.
500	Impossible d’exécuter la requête, car aucune alerte n’a été trouvée pour cet UUID.	L’UUID d’alerte spécifié n’a pas été trouvé dans le système.

Exemple de réponse : Réussite

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

Exemple de réponse : Échec

{
    "error": "Invalid action"
}

commande cURL

type: PUT

API:

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

exemple :

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

maintenanceWindow (Créer des exclusions d’alerte)

Gère les fenêtres de maintenance, sous lesquelles les alertes ne seront pas envoyées. Utilisez cette API pour définir et mettre à jour les heures d’arrêt et de démarrage, les appareils ou les sous-réseaux qui doivent être exclus lors du déclenchement d’alertes, ou pour définir et mettre à jour les moteurs Defender pour IoT qui doivent être exclus.

Par exemple, lors d’une fenêtre de maintenance, vous pouvez arrêter la remise d’alertes de toutes les alertes, à l’exception des alertes de programmes malveillants sur les appareils critiques.

Les fenêtres de maintenance qui définissent avec l’API maintenanceWindow apparaissent dans la fenêtre Exclusions d’alerte de la console de gestion locale en tant que règle d’exclusion en lecture seule, nommée avec la syntaxe suivante : Maintenance-{token name}-{ticket ID}.

Important

Cette API est prise en charge uniquement à des fins de maintenance et pendant une période limitée, et n’est pas destinée à être utilisée au lieu de règles d’exclusion d’alerte. Utilisez cette API uniquement pour les opérations de maintenance temporaire unique.

URI: /external/v1/maintenanceWindow

PUBLIER

Crée une fenêtre de maintenance.

demande de

paramètres corps:

Nom	Description	Exemple	Obligatoire /Facultatif
ticketId	Corde. Définit l’ID du ticket de maintenance dans les systèmes de l’utilisateur. Vérifiez que l’ID de ticket n’est pas lié à une fenêtre ouverte existante.	2987345p98234	Obligatoire
ttl	Entier positif. Définit la durée de vie (durée de vie), qui est la durée de la fenêtre de maintenance, en minutes. Une fois la période définie terminée, la fenêtre de maintenance est terminée et le système se comporte normalement.	180	Obligatoire
moteurs	Tableau JSON de chaînes. Définit le moteur à partir duquel supprimer les alertes pendant la fenêtre de maintenance. Valeurs possibles : - ANOMALY - MALWARE - OPERATIONAL - POLICY_VIOLATION - PROTOCOL_VIOLATION	ANOMALY,OPERATIONAL	Optionnel
sensorIds	Tableau JSON de chaînes. Définit les capteurs à partir desquels supprimer les alertes pendant la fenêtre de maintenance. Vous pouvez obtenir ces ID de capteur à partir des appliances (Gérer les appliances de capteur OT) API.	1,35,63	Optionnel
sous-réseaux	Tableau JSON de chaînes. Définit les sous-réseaux pour supprimer les alertes pendant la fenêtre de maintenance. Définissez chaque sous-réseau dans une notation CIDR.	192.168.0.0/16,138.136.80.0/14,112.138.10.0/8	Optionnel

Réponse

Code d’état	Message	Description
201 (créé)	-	L’action a été effectuée avec succès.
400 (demande incorrecte)	No TicketId	La demande d’API n’a pas été définie sur une valeur ticketId.
400 (demande incorrecte)	Durée de vie illégale	La demande d’API incluait une valeur TTL non positive ou non numérique.
400 (demande incorrecte)	Impossible d’analyser la requête.	Émettez l’analyse du corps, par exemple des paramètres incorrects ou des valeurs non valides.
400 (demande incorrecte)	La fenêtre de maintenance avec les mêmes paramètres existe déjà.	S’affiche lorsqu’une fenêtre de maintenance existante existe déjà avec les mêmes détails.
404 (introuvable)	ID de capteur inconnu	L’un des capteurs répertoriés dans la requête n’existe pas.
409 (conflit)	L’ID de ticket comporte déjà une fenêtre ouverte.	L’ID de ticket est lié à une autre fenêtre de maintenance ouverte.
500 (erreur de serveur interne)	-	Toute autre erreur inattendue.

commande cURL

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

exemple :

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

SUPPRIMER

Ferme une fenêtre de maintenance existante.

demande de

paramètres de requête:

Nom	Description	Exemple	Obligatoire /Facultatif
ticketId	Définit l’ID du ticket de maintenance dans les systèmes de l’utilisateur. Vérifiez que l’ID de ticket est lié à une fenêtre ouverte existante.	2987345p98234	Obligatoire

Réponse

codes d’erreur :

Code	Message	Description
200 (OK)	-	L’action a été effectuée avec succès.
400 (demande incorrecte)	No TicketId	Le paramètre ticketId est manquant dans la requête.
404 (introuvable):	Fenêtre de maintenance introuvable.	L’ID de ticket n’est pas lié à une fenêtre de maintenance ouverte.
500 (erreur de serveur interne)	-	Toute autre erreur inattendue.

commande cURL

type: DELETE

API:

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

exemple :

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

AVOIR

Récupérez un journal de tous les ouvrir (POST), fermer (DELETE) et mettre à jour (PUT) actions effectuées à l’aide de cette API pour gérer les fenêtres de maintenance. T

demande de

paramètres de requête:

Nom	Description	Exemple	Obligatoire /Facultatif
fromDate	Filtre les journaux à partir de la date prédéfinie et des versions ultérieures. Le format est YYYY-MM-DD.	2022-08-10	Optionnel
toDate	Filtre les journaux jusqu’à la date prédéfinie. Le format est YYYY-MM-DD.	2022-08-10	Optionnel
ticketId	Filtre les journaux liés à un ID de ticket spécifique.	9a5fe99c-d914-4bda-9332-307384fe40bf	Optionnel
tokenName	Filtre les journaux liés à un nom de jeton spécifique.	trimestre-sanity-window	Optionnel

codes d’erreur :

Code	Message	Description
200	D’ACCORD	L’action a été effectuée avec succès.
204:	Aucun contenu	Il n’y a pas de données à afficher.
400	Demande incorrecte	Le format de date est incorrect.
500	Erreur interne du serveur	Toute autre erreur inattendue.

Réponse

type: JSON

Tableau d’objets JSON qui représentent des opérations de fenêtre de maintenance.

structure de réponse:

Nom	Type	Nullable / Non nullable	Liste des valeurs
id de	Entier long	Non nullable	ID interne du journal actuel
dateTime	Corde	Non nullable	Heure à laquelle l’activité s’est produite, par exemple : 2022-04-23T18:25:43.511Z
ticketId	Corde	Non nullable	ID de la fenêtre de maintenance. Par exemple : 9a5fe99c-d914-4bda-9332-307384fe40bf
tokenName	Corde	Non nullable	Nom du jeton de fenêtre de maintenance. Par exemple : quarterly-sanity-window
moteurs	Tableau de chaînes	Nullable	Moteurs sur lesquels la fenêtre de maintenance s’applique, comme indiqué lors de la création de la fenêtre de maintenance : Protocol Violation, Policy Violation, Malware, Anomalyou Operational
sensorIds	Tableau de chaînes	Nullable	Capteurs sur lesquels la fenêtre de maintenance s’applique, tel qu’il est fourni lors de la création de la fenêtre de maintenance.
sous-réseaux	Tableau de chaînes	Nullable	Sous-réseaux sur lesquels la fenêtre de maintenance s’applique, comme indiqué lors de la création de la fenêtre de maintenance.
ttl	Numérique	Nullable	Durée de vie (TTL) de la fenêtre de maintenance, telle qu’elle est fournie lors de la création ou de la mise à jour de la fenêtre de maintenance.
operationType	Corde	Non nullable	Une des valeurs suivantes : OPEN, UPDATEet CLOSE

commande cURL

type: GET

API:

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

exemple :

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'

METTRE

Vous permet de mettre à jour la durée de la fenêtre de maintenance après avoir démarré le processus de maintenance en modifiant le paramètre ttl. La nouvelle définition de durée remplace la précédente.

Cette méthode est utile lorsque vous souhaitez définir une durée plus longue que la durée actuellement configurée. Par exemple, si vous avez initialement défini 180 minutes, 90 minutes sont passées et que vous souhaitez ajouter 30 minutes supplémentaires, mettez à jour le ttl sur 120 minute pour réinitialiser le nombre de durées.

demande de

paramètres de requête:

Nom	Description	Exemple	Obligatoire /Facultatif
ticketId	Corde. Définit l’ID du ticket de maintenance dans les systèmes de l’utilisateur.	2987345p98234	Obligatoire
ttl	Entier positif. Définit la durée de la fenêtre en minutes.	210	Obligatoire

Réponse

codes d’erreur :

Code	Message	Description
200 (OK)	-	L’action a été effectuée avec succès.
400 (demande incorrecte)	No TicketId	La requête ne contient pas de valeur ticketId.
400 (demande incorrecte)	Durée de vie illégale	La durée de vie définie n’est pas numérique ou n’est pas un entier positif.
400 (demande incorrecte)	Impossible d’analyser la requête	La requête n’a pas de valeur de paramètre ttl.
404 (introuvable)	Fenêtre de maintenance introuvable	L’ID de ticket n’est pas lié à une fenêtre de maintenance ouverte.
500 (erreur de serveur interne)	-	Toute autre erreur inattendue.

commande cURL

type: PUT

API:

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

exemple :

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 (Demander une alerte PCAP)

Utilisez cette API pour demander un fichier PCAP lié à une alerte.

URI: /external/v2/alerts/

AVOIR

demande de

paramètres de requête:

Nom	Description	Exemple	Obligatoire /Facultatif
id de	ID d’alerte à partir de la console de gestion locale	/external/v2/alerts/pcap/<id>	Obligatoire

Réponse

type: JSON

Chaîne de message avec les détails de l’état de l’opération :

Code d’état	Message	Description
200 (OK)	-	Objet JSON avec des données sur le fichier PCAP demandé. Pour plus d’informations, consultez champs de données.
500 (erreur de serveur interne)	Alerte introuvable	L’ID d’alerte fourni n’a pas été trouvé sur la console de gestion locale.
500 (erreur de serveur interne)	Erreur lors de l’obtention du jeton pour l’ID xsense <number>	Une erreur s’est produite lors de l’obtention du jeton du capteur pour l’ID de capteur spécifié
500 (erreur de serveur interne)	-	Toute autre erreur inattendue.

Champs de données

Nom	Type	Nullable / Non nullable	Liste des valeurs
id de	Numérique	Non nullable	ID d’alerte de la console de gestion locale
xsenseId	Numérique	Non nullable	ID du capteur
xsenseAlertId	Numérique	Non nullable	ID d’alerte de la console de capteur
downloadUrl	Corde	Non nullable	URL utilisée pour télécharger le fichier PCAP
jeton	Corde	Non nullable	Jeton du capteur à utiliser lors du téléchargement du fichier PCAP

Exemple de réponse : Réussite

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

Exemple de réponse : Erreur

{
  "error": "alert not found"
}

commande cURL

type: GET

API

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

exemple *:

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

Étapes suivantes

Pour plus d’informations, consultez la vue d’ensemble de la référence de l’API Defender pour IoT.