Informations de référence sur l’API de gestion des alertes pour les capteurs de surveillance OT

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

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

Utilisez cette API pour demander une liste de toutes les alertes détectées par le capteur Defender pour IoT.

URI : /api/v1/alerts

GET

Requête

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	/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
type	Obtenez des alertes d’un type spécifique uniquement. Valeurs prises en charge : - unexpected new devices - disconnections Toutes les autres valeurs sont ignorées.	/api/v1/alerts?type=disconnections	Facultatif

Réponse

Type : JSON

Liste d’alertes avec les champs suivants :

Nom	Type	Autorise la valeur Null/N’accepte pas la valeur Null	Liste de valeurs
Identifiant	Numérique	N'accepte pas la valeur null	-
time	Numérique	N'accepte pas la valeur null	Millisecondes depuis l’heure Epoch, en fuseau horaire UTC
title	String	N'accepte pas la valeur null	-
message	String	N'accepte pas la valeur null	-
severity	String	N'accepte pas la valeur null	Warning, Minor, Major ou Critical
engine	String	N'accepte pas la valeur null	Protocol Violation, Policy Violation, Malware, Anomaly ouOperational
sourceDevice	Numérique	Nullable	ID de périphérique
destinationDevice	Numérique	Nullable	ID de périphérique
additionalInformation	Objet d’informations supplémentaires	Nullable	-

Champs d’informations supplémentaires

Nom	Type	Autorise la valeur Null/N’accepte pas la valeur Null	Liste de valeurs
description	String	N'accepte pas la valeur null	-
information	Tableau JSON	N'accepte pas la valeur null	String

Ajouté pour la V2 :

Nom	Type	Autorise la valeur Null/N’accepte pas la valeur Null	Liste de valeurs
sourceDeviceAddress	String	Nullable	Adresse IP ou MAC
destinationDeviceAddress	String	Nullable	Adresse IP ou MAC
remediationSteps	Tableau JSON	N'accepte pas la valeur null	Chaînes, étapes de correction décrites dans l’alerte

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

Exemple de réponse

[
    {
        "engine": "Policy Violation",
        "severity": "Major",
        "title": "Internet Access Detected",
        "additionalinformation": {
            "information": [
                "170.60.50.201 over port BACnet (47808)"
            ],
            "description": "External Addresses"
        },
        "sourceDevice": null,
        "destinationDevice": null,
        "time": 1509881077000,
        "message": "Device 192.168.0.13 tried to access an external IP address which is an address in the Internet and is not allowed by policy. It is recommended to notify the security officer of the incident.",
        "id": 1
    },
    {
        "engine": "Protocol Violation",
        "severity": "Major",
        "title": "Illegal MODBUS Operation (Exception Raised by Master)",
        "sourceDevice": 3,
        "destinationDevice": 4,
        "time": 1505651605000,
        "message": "A MODBUS master 192.168.110.131 attempted to initiate an illegal operation.\nThe operation is considered to be illegal since it incorporated function code \#129 which should not be used by a master.\nIt is recommended to notify the security officer of the incident.",
        "id": 2,
        "additionalInformation": null,
    }
]

Commande cURL

Type : GET

API :

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/api/v1/alerts?state=<STATE>&fromTime=<FROM_TIME>&toTime=<TO_TIME>&type=<TYPE>'

Exemple :

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/api/v1/alerts?state=unhandled&fromTime=1594550986000&toTime=1594550986001&type=disconnections'

événements (Récupérer les événements de chronologie)

Utilisez cette API pour demander une liste des événements signalés à la chronologie des événements.

Notes

L’exécution de l’API identique dans la même heure, avec les mêmes valeurs de paramètre, retourne une valeur mise en cache. Si vous exécutez cette API deux fois en moins d’une heure, nous vous recommandons de modifier les paramètres de requête pour obtenir une réponse mise à jour.

URI : /api/v1/events

GET

Requête

Paramètres de requête

Nom	Description	Exemple	Obligatoire/facultatif
minutesTimeFrame	Filtrez les résultats selon un délai donné pendant lequel des événements ont été signalés. Défini en comptant en arrière à partir de l’heure actuelle. Maximum = 4320 (3 jours). Toute valeur supérieure est traitée comme 4320, sans erreur	/api/v1/events?minutesTimeFrame=20	Facultatif
type	Filtrez les résultats d’un type spécifique uniquement. Toute valeur autre que les types pris en charge est ignorée. Pour plus d’informations, consultez la Référence de l’événement type et title.	/api/v1/events?type=DEVICE_CONNECTION_CREATED /api/v1/events?type=REMOTE_ACCESS&minutesTimeFrame	Facultatif

Réponse

Type : JSON

Tableau d’objets JSON qui représentent les 100 derniers événements, triés par timestamp d’événement, avec le dernier événement en premier.

Les champs d’événement sont les suivants :

Nom	Type	Autorise la valeur Null/N’accepte pas la valeur Null	Liste de valeurs
timestamp	Numérique	N'accepte pas la valeur null	Millisecondes depuis l’heure Epoch, en fuseau horaire UTC
type	String	N'accepte pas la valeur null	Un des types pris en charge
title	String	N'accepte pas la valeur null	Un des titres pris en charge
severity	String	N'accepte pas la valeur null	INFO, NOTICEou ALERT
propriétaire	String	Nullable	Chaîne. Si l’événement a été créé manuellement, ce champ inclut le nom de l’utilisateur qui a créé l’événement.
content	String	N'accepte pas la valeur null	Chaîne qui décrit l’événement.

Exemple de réponse

[
    {
        "severity": "INFO",
        "title": "Back to Normal",
        "timestamp": 1504097077000,
        "content": "Device 10.2.1.15 was found responsive, after being suspected as disconnected",
        "owner": null,
        "type": "BACK_TO_NORMAL"
    },
    {
        "severity": "ALERT",
        "title": "Alert Detected",
        "timestamp": 1504096909000,
        "content": "Device 10.2.1.15 is suspected to be disconnected (unresponsive).",
        "owner": null,
        "type": "ALERT_REPORTED"
    },
    {
        "severity": "ALERT",
        "title": "Alert Detected",
        "timestamp": 1504094446000,
        "content": "A DNP3 Master 10.2.1.14 attempted to initiate a request which is not allowed by policy.\nThe policy indicates the allowed function codes, address ranges, point indexes and time intervals.\nIt is recommended to notify the security officer of the incident.",
        "owner": null,
        "type": "ALERT_REPORTED"
    },
    {
        "severity": "NOTICE",
        "title": "PLC Program Update",
        "timestamp": 1504094344000,
        "content": "Program update detected, sent from 10.2.1.25 to 10.2.1.14",
        "owner": null,
        "type": "PROGRAM_DEVICE"
    }
]

Commande cURL

Type : GET

API :

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/api/v1/events?minutesTimeFrame=<TIME_FRAEM>&type=<TYPE>'

Exemple :

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/api/v1/events?minutesTimeFrame=20&type=DEVICE_CONNECTION_CREATED'`

Référence de l’événement type et title

Cette section répertorie les valeurs prises en charge en tant que type d’événement et les valeurs de titre pour l’API Événements .

Type d'événement	Titre de l’événement
DEVICE_CREATE	Appareil détecté
DEVICE_UPDATE	Appareil mis à jour
ALERT_REPORTED	Alerte détectée
ALERT_UPDATED	Alerte mise à jour
SCAN	Appareil détecté par l’analyse
PROGRAM_DEVICE	Programmation PLC
MMS_PROGRAM_DEVICE	Mise à jour du programme PLC
SCL_UPLOADED	SCL chargé
EXCLUSION_RULE_CREATED	Règle d’exclusion créée
EXCLUSION_RULE_REMOVED	Règle d’exclusion supprimée
EXCLUSION_RULE_UPDATED	Règle d’exclusion mise à jour
DEVICE_CONNECTION_CREATED	Connexion de l’appareil détectée
USER_LOGIN	Tentative de connexion utilisateur
FILE_TRANSFER	Transfert de fichiers détecté
CUSTOM_EVENT	Événement défini par l’utilisateur
REMOTE_ACCESS	Connexion d’accès à distance établie
BACK_TO_NORMAL	Retour à la normale
MMS_MEMORY_BLOCK_OPERATION	Opération de bloc de mémoire MMS
MMS_PROGRAM_OPERATION	Opération de programme MMS
HTTP_BASIC_AUTHENTICATION	Authentification de base HTTP
SIEMENS_S_7_MEMORY_BLOCK_OPERATION	Opération de bloc de mémoire Siemens S7
SIEMENS_S_7_AUTHENTICATION	Authentification Siemens S7
REPORT_CREATED	Rapport créé
SNMP_TRAP	Interruption SNMP détectée
DATABASE_ACTION	Manipulation de structure de base de données
PLC_MODULE_CHANGE	Modification du module PLC
FIRMWARE_UPDATE	Mise à jour du microprogramme
PLC_START	Démarrage du PLC
SRTP_PLC_RESET	Réinitialisation du PLC
SRTP_PLC_COPY_FIRMWARE	Mise à jour du microprogramme
SRTP_LOGIN_PROGRAMMING	Mode de programmation PLC défini
SRTP_PLC_CHANGE_PASSWORD	Modification de mot de passe PLC
OPC_DATA_ACCESS_GROUP_MANAGEMENT_OPERATION	Opération de gestion des groupes d’accès aux données OPC
OPC_DATA_ACCESS_ITEM_MANAGEMENT_OPERATION	Opération de gestion des éléments d’accès aux données OPC
OPC_DATA_ACCESS_IO_SUBSCRIPTION_MANAGEMENT_OPERATION	Opération de gestion des abonnements à l’accès aux données OPC
OPC_AE_EVENT_SUBSCRIPTION	Abonnement aux événements OPC AE
OPC_AE_EVENT_CONDITION_MANAGEMENT_OPERATION	Opération de gestion des conditions d’événement OPC AE
OPC_AE_EVENT	Événement OPC AE
SRTP_CHANGE_PRIVILEGE	Changer le niveau d’accès PLC
SRTP_CHANGE_LEVEL_FAILED	Échec du changement de niveau d’accès PLC
SUITELINK_INIT_CONNECTION	Session Wonderware initialisée
USER_OPERATION	Opération utilisateur
DIP_UPLOADED	Package Data Intelligence chargé
FTP_AUTHENTICATION_FAILURE	Échec de l’authentification FTP
PROFINET_DPC_VALUE_SET	Opération SET Profinet
S7PLUS_PLC_MODE_CHANGE	Modification du mode PLC
S7_PLC_MODE_CHANGE	Modification du mode PLC
DELETE_DEVICE	Appareil supprimé
S7PLUS_PROGRAMMING	Programmation PLC
FIRMWARE_CHANGED	Modification du microprogramme PLC
DELTAV_PROGRAMMING	Script d’installation DeltaV
USER_DEFINED_RULE_CREATED	Règle définie par l’utilisateur créée
USER_DEFINED_RULE_EDITED	Règle définie par l’utilisateur modifiée
USER_DEFINED_RULE_DELETED	Règle définie par l’utilisateur supprimée
USER_DEFINED_RULE_OPERATION	Opération de règle définie par l’utilisateur
REMOTE_PROCESS_EXECUTION	Exécution de processus à distance
DEVICE_UNIFICATION	Appareil mis à jour
NOTIFICATION	La notification a été résolue manuellement
ENIP_CONTROLLER_PROGRAM_DELETE	Suppression du programme de contrôleur
ENIP_CONTROLLER_PROGRAM_RESET	Réinitialisation du programme du contrôleur
ENIP_CONTROLLER_GENERIC_RESET	Réinitialisation du contrôleur
ENIP_CONTROLLER_GENERIC_STOP	Arrêt du contrôleur
ENIP_CONTROLLER_GENERIC_START	Début du contrôleur
TELNET_AUTHENTICATION_FAILURE	Échec de l’authentification Telnet
CONFIGURATION_OF_CLEARTEXT_PASSWORD	Configuration du mot de passe en texte clair
CLEARTEXT_AUTHENTICATION	Authentification en texte clair
PROGRAM_UPLOAD_DEVICE	Chargement du programme PLC
CONFIGURATION_CHANGE	Écriture de configuration PLC
CONFIGURATION_READ	Lecture de configuration PLC
SYSLOG_MSG	Message Syslog
INTERNET_ACCESS	Accès à Internet
CAMP_MEMORY_WRITE_OPERATION	Opération courante d’écriture de mémoire du protocole de message ASCII
MUTED_ALERT	Événement détecté et désactivé.
DHCP_UPDATE	Mise à jour de l’adresse
DIP_FAILURE	Échec de l’installation du package Data Intelligence
DELETE_DEVICE_SCHEDULE	Appareils inactifs planifiés pour suppression
PLC_OPERATING_MODE_CHANGED	Changement du mode d’exploitation PLC détecté
HARDWARE_UPDATE_BY_IDENTIFIER	Mise à jour de l’adresse

Étapes suivantes

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