Partager via


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 les alertes filtrées à partir d’une console de gestion locale.

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

GET

Paramètres de requête :

Nom Description Exemple Obligatoire/facultatif
state Obtenir uniquement les 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 Facultatif
fromTime Obtenez des alertes créées à partir d’un moment donné, en millisecondes à partir de l’heure Epoch et dans le fuseau horaire UTC. /api/v1/alerts?fromTime=<epoch> Facultatif
toTime Obtenez des alertes créées uniquement avant à un moment donné, en millisecondes à partir de l’heure Epoch et dans le fuseau horaire UTC. /api/v1/alerts?toTime=<epoch> Facultatif
siteId Site sur lequel l’alerte a été découverte. /api/v1/alerts?siteId=1 Facultatif
zoneId Zone dans laquelle l’alerte a été découverte. /api/v1/alerts?zoneId=1 Facultatif
sensorId Capteur sur lequel l’alerte a été découverte. /api/v1/alerts?sensorId=1 Facultatif

Notes

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

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 des données à QRadar. Pour plus d’informations, consultez Intégrer Qradar avec Microsoft Defender pour IoT.

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

PUT

Type : JSON

Paramètres de requête :

Nom Description Exemple Obligatoire/facultatif
UUID Définit l’identificateur unique universel (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 du corps

Name Description Exemple Obligatoire/facultatif
action String handle ou handleAndLearn Obligatoire

Exemple de requête

{
    "action": "handle"
}

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 sous-réseaux qui doivent être exclus lors du déclenchement d’alertes ou les moteurs Defender pour IoT qui doivent être exclus.

Par exemple, au cours d’une fenêtre de maintenance, vous souhaiterez peut-être arrêter l’envoi de toutes les alertes, à l’exception des alertes de programmes malveillants sur les appareils critiques.

Les fenêtres de maintenance définies avec l’API maintenanceWindow apparaissent dans la fenêtre Exclusions d’alerte de la console de gestion locale comme 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 pour une durée limitée, et n’est pas destinée à être utilisée à la place des règles d’exclusion d’alerte. Utilisez cette API pour les opérations de maintenance temporaires et ponctuelles uniquement.

URI : /external/v1/maintenanceWindow

POST

Crée une fenêtre de maintenance.

Paramètres du corps :

Nom Description Exemple Obligatoire/facultatif
ticketId Chaîne. Définit l’ID du ticket de maintenance dans les systèmes de l’utilisateur. Assurez-vous 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 (TTL), qui correspond à 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 à nouveau normalement. 180 Obligatoire
engines Tableau JSON de chaînes. Définit le moteur pour lequel supprimer les alertes pendant la fenêtre de maintenance. Valeurs possibles :

- ANOMALY
- MALWARE
- OPERATIONAL
- POLICY_VIOLATION
- PROTOCOL_VIOLATION
ANOMALY,OPERATIONAL Facultatif
sensorIds Tableau JSON de chaînes. Définit les capteurs pour lesquels supprimer les alertes pendant la fenêtre de maintenance. Vous pouvez obtenir ces ID de capteur à partir de l’API appliances (Gérer les appliances de capteur OT). 1,35,63 Facultatif
Sous-réseaux Tableau JSON de chaînes. Définit les sous-réseaux pour lesquels 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 Facultatif

Suppression

Ferme une fenêtre de maintenance existante.

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. Assurez-vous que l’ID de ticket est lié à une fenêtre ouverte existante. 2987345p98234 Obligatoire

GET

Récupérez un journal de toutes les actions open (POST), close (DELETE) et update (PUT) effectuées à l’aide de cette API pour gérer les fenêtres de maintenance. T

Paramètres de requête :

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

Codes d’erreur :

Code Message Description
200 Ok L’action s’est effectuée correctement.
204 : Pas de contenu Aucune donnée à afficher.
400 Demande incorrecte Le format de date est incorrect.
500 Erreur interne du serveur Autre erreur inattendue.

PUT

Permet la mise à jour de la durée de la fenêtre de maintenance après le démarrage du processus de maintenance en modifiant le paramètre ttl. La nouvelle définition de durée remplace l’ancienne.

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 défini à l’origine 180 minutes, que 90 minutes sont passées et que vous souhaitez ajouter 30 minutes supplémentaires, mettez à jour ttl à la 120 minute pour réinitialiser la durée.

Paramètres de requête :

Nom Description Exemple Obligatoire/facultatif
ticketId Chaîne. 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

pcap (Demander un PCAP d’alerte)

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

URI : /external/v2/alerts/

GET

Paramètres de requête :

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

Étapes suivantes

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