Informazioni di riferimento sulle API di gestione degli avvisi per i sensori di monitoraggio OT

Questo articolo elenca le API REST di gestione degli avvisi supportate per Microsoft Defender per i sensori di monitoraggio IoT OT.

alerts (Recuperare le informazioni sugli avvisi)

Usare questa API per richiedere un elenco di tutti gli avvisi rilevati dal sensore Defender per IoT.

URI: /api/v1/alerts

GET

Richiesta

Parametri di query

Nome	Descrizione	Esempio	Obbligatoria / Facoltativa
state	Ottiene solo avvisi gestiti o non gestiti. Valori supportati: - handled - unhandled	/api/v1/alerts?state=handled	Facoltativo
fromTime	Ottenere gli avvisi creati a partire da un determinato momento, in millisecondi dall'ora Epoch e dal fuso orario UTC.	/api/v1/alerts?fromTime=<epoch>	Facoltativo
toTime	Ottiene gli avvisi creati solo prima in un determinato momento, in millisecondi dall'ora Epoch e nel fuso orario UTC.	/api/v1/alerts?toTime=<epoch>	Facoltativo
type	Ottenere avvisi solo di un tipo specifico. Valori supportati: - unexpected new devices - disconnections Tutti gli altri valori vengono ignorati.	/api/v1/alerts?type=disconnections	Facoltativo

Risposta

Tipo: JSON

Elenco di avvisi con i campi seguenti:

Nome	Tipo	Nullable/Not nullable	Elenco di valori
ID	Numeric	Non ammette valori Null.	-
time	Numeric	Non ammette valori Null.	Millisecondi dall'ora Epoch, nel fuso orario UTC
title	string	Non ammette valori Null.	-
message	string	Non ammette valori Null.	-
severity	string	Non ammette valori Null.	Warning, Minor, Major o Critical
Motore	string	Non ammette valori Null.	Protocol Violation, Policy Violation, Malware, Anomaly o Operational
sourceDevice	Numeric	Nullable	ID dispositivo
destinationDevice	Numeric	Nullable	ID dispositivo
additionalInformation	Oggetto informazioni aggiuntive	Nullable	-

Campi di informazioni aggiuntivi

Nome	Tipo	Nullable/Not nullable	Elenco di valori
description	string	Non ammette valori Null.	-
Informazioni	Matrice JSON	Non ammette valori Null.	string

Aggiunta per V2:

Nome	Tipo	Nullable/Not nullable	Elenco di valori
sourceDeviceAddress	string	Nullable	Indirizzo IP o MAC
destinationDeviceAddress	string	Nullable	Indirizzo IP o MAC
correzioneSteps	Matrice JSON	Non ammette valori Null.	Stringhe, passaggi di correzione descritti nell'avviso

Per altre informazioni, vedere Informazioni di riferimento sulla versione dell'API del sensore.

Esempio di risposta

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

Comando cURL

Tipo: GET

API:

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

Esempio:

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

eventi (recuperare gli eventi della sequenza temporale)

Usare questa API per richiedere un elenco di eventi segnalati alla sequenza temporale degli eventi.

Nota

L'esecuzione dell'API identica entro la stessa ora, con gli stessi valori di parametro, restituisce un valore memorizzato nella cache. Se si esegue questa API due volte all'ora, è consigliabile modificare i parametri di query per ottenere una risposta aggiornata.

URI: /api/v1/events

GET

Richiesta

Parametri di query

Nome	Descrizione	Esempio	Obbligatoria / Facoltativa
minutesTimeFrame	Filtrare i risultati in base a un determinato intervallo di tempo durante il quale sono stati segnalati gli eventi. Definito all'indietro rispetto all'ora corrente. Massimo = 4320 (3 giorni). Qualsiasi valore maggiore viene considerato come 4320, senza errori	/api/v1/events?minutesTimeFrame=20	Facoltativo
type	Filtra solo i risultati per un tipo specifico. Qualsiasi valore diverso dai tipi supportati viene ignorato. Per altre informazioni, vedere Eventi type e title informazioni di riferimento.	/api/v1/events?type=DEVICE_CONNECTION_CREATED /api/v1/events?type=REMOTE_ACCESS&minutesTimeFrame	Facoltativo

Risposta

Tipo: JSON

Matrice di oggetti JSON che rappresentano gli ultimi 100 eventi, ordinati in base al timestamp dell'evento, con l'evento più recente.

I campi evento includono:

Nome	Tipo	Nullable/Not nullable	Elenco di valori
timestamp	Numeric	Non ammette valori Null.	Millisecondi dall'ora Epoch, nel fuso orario UTC
type	string	Non ammette valori Null.	Uno dei tipi supportati
title	string	Non ammette valori Null.	Uno dei titoli supportati
severity	string	Non ammette valori Null.	INFO, NOTICEo ALERT
Proprietario	string	Nullable	Stringa. Se l'evento è stato creato manualmente, questo campo includerà il nome utente che ha creato l'evento.
content	string	Non ammette valori Null.	Stringa che descrive l'evento.

Esempio di risposta

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

Comando cURL

Tipo: GET

API:

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

Esempio:

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

Evento type e title riferimento

Questa sezione elenca i valori supportati come tipo di evento e valori del titolo per l'API degli eventi .

Tipo di evento	Titolo evento
DEVICE_CREATE	Dispositivo rilevato
DEVICE_UPDATE	Dispositivo aggiornato
ALERT_REPORTED	Avviso rilevato
ALERT_UPDATED	Avviso aggiornato
SCAN	Rilevato dispositivo di analisi
PROGRAM_DEVICE	Programmazione PLC
MMS_PROGRAM_DEVICE	Aggiornamento del programma PLC
SCL_UPLOADED	SCL caricato
EXCLUSION_RULE_CREATED	Regola di esclusione creata
EXCLUSION_RULE_REMOVED	Regola di esclusione rimossa
EXCLUSION_RULE_UPDATED	Regola di esclusione aggiornata
DEVICE_CONNECTION_CREATED	Connessione del dispositivo rilevata
USER_LOGIN	Tentativo di accesso utente
FILE_TRANSFER	Trasferimento file rilevato
CUSTOM_EVENT	Evento definito dall'utente
REMOTE_ACCESS	Connessione di accesso remoto stabilita
BACK_TO_NORMAL	Torna a Normale
MMS_MEMORY_BLOCK_OPERATION	Operazione di blocco di memoria MMS
MMS_PROGRAM_OPERATION	Operazione del programma MMS
HTTP_BASIC_AUTHENTICATION	Autenticazione di base HTTP
SIEMENS_S_7_MEMORY_BLOCK_OPERATION	Operazioni di blocco di memoria Siemens S7
SIEMENS_S_7_AUTHENTICATION	Autenticazione di Siemens S7
REPORT_CREATED	Report creato
SNMP_TRAP	Rilevato trap SNMP
DATABASE_ACTION	Manipolazione della struttura del database
PLC_MODULE_CHANGE	Modifica del modulo PLC
FIRMWARE_UPDATE	Aggiornamento del firmware
PLC_START	Avvio DI PLC
SRTP_PLC_RESET	Reimpostazione di PLC
SRTP_PLC_COPY_FIRMWARE	Aggiornamento del firmware
SRTP_LOGIN_PROGRAMMING	Set di modalità di programmazione PLC
SRTP_PLC_CHANGE_PASSWORD	Modifica password PLC
OPC_DATA_ACCESS_GROUP_MANAGEMENT_OPERATION	Operazione di gestione dei gruppi di accesso ai dati OPC
OPC_DATA_ACCESS_ITEM_MANAGEMENT_OPERATION	Operazione di gestione degli elementi di accesso ai dati OPC
OPC_DATA_ACCESS_IO_SUBSCRIPTION_MANAGEMENT_OPERATION	Operazione di gestione delle sottoscrizioni I/OPC per l'accesso ai dati OPC
OPC_AE_EVENT_SUBSCRIPTION	Sottoscrizione di eventi OPC AE
OPC_AE_EVENT_CONDITION_MANAGEMENT_OPERATION	Operazione di gestione delle condizioni evento OPC AE
OPC_AE_EVENT	Evento OPC AE
SRTP_CHANGE_PRIVILEGE	Modificare il livello di accesso di PLC
SRTP_CHANGE_LEVEL_FAILED	La modifica del livello di accesso di PLC non è riuscita
SUITELINK_INIT_CONNECTION	Sessione Wonderware inizializzata
USER_OPERATION	Operazione utente
DIP_UPLOADED	Pacchetto di Intelligence dati caricato
FTP_AUTHENTICATION_FAILURE	Errore di autenticazione FTP
PROFINET_DPC_VALUE_SET	Operazione Profinet SET
S7PLUS_PLC_MODE_CHANGE	Modifica della modalità PLC
S7_PLC_MODE_CHANGE	Modifica della modalità PLC
DELETE_DEVICE	Il dispositivo è stato eliminato
S7PLUS_PROGRAMMING	Programmazione PLC
FIRMWARE_CHANGED	Firmware PLC modificato
DELTAV_PROGRAMMING	Script di installazione DeltaV
USER_DEFINED_RULE_CREATED	Regola definita dall'utente creata
USER_DEFINED_RULE_EDITED	Regola definita dall'utente modificata
USER_DEFINED_RULE_DELETED	Regola definita dall'utente eliminata
USER_DEFINED_RULE_OPERATION	Operazione della regola definita dall'utente
REMOTE_PROCESS_EXECUTION	Esecuzione di processi remoti
DEVICE_UNIFICATION	Dispositivo aggiornato
NOTIFICA	La notifica è stata risolta manualmente
ENIP_CONTROLLER_PROGRAM_DELETE	Eliminazione del programma controller
ENIP_CONTROLLER_PROGRAM_RESET	Reimpostazione del programma controller
ENIP_CONTROLLER_GENERIC_RESET	Reimpostazione controller
ENIP_CONTROLLER_GENERIC_STOP	Arresto del controller
ENIP_CONTROLLER_GENERIC_START	Avvio controller
TELNET_AUTHENTICATION_FAILURE	Errore di autenticazione telnet
CONFIGURATION_OF_CLEARTEXT_PASSWORD	Configurazione della password non crittografata
CLEARTEXT_AUTHENTICATION	Autenticazione cleartext
PROGRAM_UPLOAD_DEVICE	Caricamento del programma PLC
CONFIGURATION_CHANGE	Scrittura della configurazione DI PLC
CONFIGURATION_READ	Configurazione PLC Lettura
SYSLOG_MSG	Messaggio Syslog
INTERNET_ACCESS	Accesso a Internet
CAMP_MEMORY_WRITE_OPERATION	Operazione di scrittura della memoria del protocollo ASCII ASCII
MUTED_ALERT	Evento rilevato e disattivato
DHCP_UPDATE	Aggiornamento indirizzi
DIP_FAILURE	Errore di installazione del pacchetto di Data Intelligence
DELETE_DEVICE_SCHEDULE	Dispositivi inattivi pianificati per l'eliminazione
PLC_OPERATING_MODE_CHANGED	Modifica della modalità operativa PLC rilevata
HARDWARE_UPDATE_BY_IDENTIFIER	Aggiornamento indirizzi

Passaggi successivi

Per altre informazioni, vedere la panoramica di riferimento sull'API Defender per IoT.