Referência da API de gestão de alertas para sensores de monitorização de OT

Este artigo lista as APIs REST de gestão de alertas suportadas para Microsoft Defender para sensores de monitorização de OT IoT.

alertas (Obter informações de alerta)

Utilize esta API para pedir uma lista de todos os alertas que o sensor do Defender para IoT detetou.

URI: /api/v1/alerts

GET

Pedir

Parâmetros de consulta

Nome	Descrição	Exemplo	Obrigatório/Opcional
estado	Obtenha apenas alertas processados ou não processados. Valores suportados: - handled - unhandled	/api/v1/alerts?state=handled	Opcional
fromTime	Obtenha alertas criados a partir de um determinado momento, em milissegundos a partir da hora da época e no fuso horário UTC.	/api/v1/alerts?fromTime=<epoch>	Opcional
toTime	Obtenha alertas criados apenas antes num determinado momento, em milissegundos a partir da hora da época e no fuso horário UTC.	/api/v1/alerts?toTime=<epoch>	Opcional
tipo	Obtenha alertas apenas de um tipo específico. Valores suportados: - unexpected new devices - disconnections Todos os outros valores são ignorados.	/api/v1/alerts?type=disconnections	Opcional

Response

Tipo: JSON

Uma lista de alertas com os seguintes campos:

Nome	Tipo	Anulável / Não nulo	Lista de valores
ID	Operador numérico	Não nulo	-
hora	Operador numérico	Não nulo	Milissegundos da Hora da Época, no fuso horário UTC
título	String	Não nulo	-
mensagem	String	Não nulo	-
gravidade	String	Não nulo	Warning, Minor, Majorou Critical
motor	String	Não nulo	Protocol Violation, Policy Violation, Malware, Anomalyou Operational
sourceDevice	Operador numérico	Pode ser nulo	ID do Dispositivo
destinationDevice	Operador numérico	Pode ser nulo	ID do Dispositivo
additionalInformation	Objeto de informações adicionais	Pode ser nulo	-

Campos de informações adicionais

Nome	Tipo	Anulável / Não nulo	Lista de valores
descrição	String	Não nulo	-
informações	Matriz JSON	Não nulo	String

Adicionado para V2:

Nome	Tipo	Anulável / Não nulo	Lista de valores
sourceDeviceAddress	String	Pode ser nulo	Endereço IP ou MAC
destinationDeviceAddress	String	Pode ser nulo	Endereço IP ou MAC
remediationSteps	Matriz JSON	Não nulo	Cadeias, passos de remediação descritos em alerta

Para obter mais informações, veja Referência da versão da API do Sensor.

Exemplo de resposta

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

Exemplo:

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

eventos (Obter eventos de linha cronológica)

Utilize esta API para pedir uma lista de eventos comunicados à linha cronológica do evento.

Nota

Executar a API idêntica na mesma hora, com os mesmos valores de parâmetro, devolve um valor em cache. Se estiver a executar esta API duas vezes numa hora, recomendamos que modifique os parâmetros de consulta para obter uma resposta atualizada.

URI: /api/v1/events

GET

Pedir

Parâmetros de consulta

Nome	Descrição	Exemplo	Obrigatório/Opcional
minutesTimeFrame	Filtre os resultados por um determinado período de tempo durante o qual os eventos foram reportados. Definido para trás a partir da hora atual. Máximo = 4320 (3 dias). Qualquer valor maior é tratado como 4320, sem erros	/api/v1/events?minutesTimeFrame=20	Opcional
tipo	Filtrar resultados apenas para um tipo específico. Qualquer valor diferente dos tipos suportados é ignorado. Para obter mais informações, veja Evento type e title referência.	/api/v1/events?type=DEVICE_CONNECTION_CREATED /api/v1/events?type=REMOTE_ACCESS&minutesTimeFrame	Opcional

Response

Tipo: JSON

Matriz de objetos JSON que representam os 100 eventos mais recentes, ordenados pelo carimbo de data/hora do evento, com o evento mais recente primeiro.

Os campos do evento incluem:

Nome	Tipo	Nulo / Não nulo	Lista de valores
carimbo de data/hora	Operador numérico	Não nulo	Milissegundos da hora da época, no fuso horário UTC
tipo	String	Não nulo	Um dos tipos suportados
título	String	Não nulo	Um dos títulos suportados
gravidade	String	Não nulo	INFO, NOTICEou ALERT
proprietário	String	Pode ser nulo	Cadeia. Se o evento tiver sido criado manualmente, este campo incluirá o nome de utilizador que criou o evento.
conteúdo	String	Não nulo	Cadeia que descreve o evento.

Exemplo de resposta

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

Exemplo:

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

Evento type e title referência

Esta secção lista os valores suportados como tipo de evento e valores de título para a API de eventos .

Tipo de evento	Título do evento
DEVICE_CREATE	Dispositivo Detetado
DEVICE_UPDATE	Dispositivo Atualizado
ALERT_REPORTED	Alerta Detetado
ALERT_UPDATED	Alerta Atualizado
DIGITALIZAR	Analisar Dispositivo Detetado
PROGRAM_DEVICE	Programação PLC
MMS_PROGRAM_DEVICE	Atualização do Programa PLC
SCL_UPLOADED	SCL Carregado
EXCLUSION_RULE_CREATED	Regra de Exclusão Criada
EXCLUSION_RULE_REMOVED	Regra de Exclusão Removida
EXCLUSION_RULE_UPDATED	Regra de Exclusão Atualizada
DEVICE_CONNECTION_CREATED	Ligação do Dispositivo Detetada
USER_LOGIN	Tentativa de Início de Sessão do Utilizador
FILE_TRANSFER	Transferência de Ficheiros Detetada
CUSTOM_EVENT	Evento Definido pelo Utilizador
REMOTE_ACCESS	Ligação de Acesso Remoto Estabelecida
BACK_TO_NORMAL	Voltar ao Normal
MMS_MEMORY_BLOCK_OPERATION	Operação de Bloco de Memória MMS
MMS_PROGRAM_OPERATION	Operação do Programa MMS
HTTP_BASIC_AUTHENTICATION	Autenticação Básica http
SIEMENS_S_7_MEMORY_BLOCK_OPERATION	Operação de Bloqueio de Memória Da Siemens S7
SIEMENS_S_7_AUTHENTICATION	Autenticação Siemens S7
REPORT_CREATED	Relatório Criado
SNMP_TRAP	SNMP Trap detetado
DATABASE_ACTION	Manipulação da Estrutura da Base de Dados
PLC_MODULE_CHANGE	Alteração do Módulo PLC
FIRMWARE_UPDATE	Atualização de Firmware
PLC_START	Iniciar PLC
SRTP_PLC_RESET	Reposição PLC
SRTP_PLC_COPY_FIRMWARE	Atualização de Firmware
SRTP_LOGIN_PROGRAMMING	Conjunto de Modos de Programação PLC
SRTP_PLC_CHANGE_PASSWORD	Alteração da Palavra-passe plc
OPC_DATA_ACCESS_GROUP_MANAGEMENT_OPERATION	Operação de Gestão de Grupos de Acesso a Dados OPC
OPC_DATA_ACCESS_ITEM_MANAGEMENT_OPERATION	Operação de Gestão de Itens de Acesso a Dados OPC
OPC_DATA_ACCESS_IO_SUBSCRIPTION_MANAGEMENT_OPERATION	Operação de Gestão de Subscrições de E/S de Acesso a Dados OPC
OPC_AE_EVENT_SUBSCRIPTION	Subscrição de Eventos OPC AE
OPC_AE_EVENT_CONDITION_MANAGEMENT_OPERATION	Operação de Gestão de Condições de Eventos OPC AE
OPC_AE_EVENT	Evento OPC AE
SRTP_CHANGE_PRIVILEGE	Plc Alterar nível de acesso
SRTP_CHANGE_LEVEL_FAILED	Falha ao alterar o nível de acesso de PLC
SUITELINK_INIT_CONNECTION	Sessão wonderware inicializada
USER_OPERATION	Operação do Utilizador
DIP_UPLOADED	Pacote de Informações de Dados Carregado
FTP_AUTHENTICATION_FAILURE	Falha de Autenticação de FTP
PROFINET_DPC_VALUE_SET	Operação Profinet SET
S7PLUS_PLC_MODE_CHANGE	Alteração do Modo PLC
S7_PLC_MODE_CHANGE	Alteração do Modo PLC
DELETE_DEVICE	Dispositivo Eliminado
S7PLUS_PROGRAMMING	Programação PLC
FIRMWARE_CHANGED	Firmware PLC Alterado
DELTAV_PROGRAMMING	Script de Instalação DeltaV
USER_DEFINED_RULE_CREATED	Regra Definida pelo Utilizador Criada
USER_DEFINED_RULE_EDITED	Regra Definida pelo Utilizador Editada
USER_DEFINED_RULE_DELETED	Regra Definida pelo Utilizador Eliminada
USER_DEFINED_RULE_OPERATION	Operação de Regra Definida pelo Utilizador
REMOTE_PROCESS_EXECUTION	Execução de Processos Remotos
DEVICE_UNIFICATION	Dispositivo Atualizado
NOTIFICAÇÃO	A notificação foi resolvida manualmente
ENIP_CONTROLLER_PROGRAM_DELETE	Eliminação do Programa do Controlador
ENIP_CONTROLLER_PROGRAM_RESET	Reposição do Programa do Controlador
ENIP_CONTROLLER_GENERIC_RESET	Reposição do Controlador
ENIP_CONTROLLER_GENERIC_STOP	Paragem do Controlador
ENIP_CONTROLLER_GENERIC_START	Início do Controlador
TELNET_AUTHENTICATION_FAILURE	Falha de Autenticação telnet
CONFIGURATION_OF_CLEARTEXT_PASSWORD	Configuração da Palavra-passe de Texto Não Encriptado
CLEARTEXT_AUTHENTICATION	Autenticação Cleartext
PROGRAM_UPLOAD_DEVICE	Carregamento do Programa PLC
CONFIGURATION_CHANGE	Escrita de Configuração PLC
CONFIGURATION_READ	Leitura da Configuração plc
SYSLOG_MSG	Mensagem do Syslog
INTERNET_ACCESS	Acesso à Internet
CAMP_MEMORY_WRITE_OPERATION	Operação de Escrita de Memória do Protocolo de Mensagem ASCII Comum
MUTED_ALERT	Evento Detetado e Desativado
DHCP_UPDATE	Atualização de Endereços
DIP_FAILURE	Falha na Instalação do Pacote de Inteligência de Dados
DELETE_DEVICE_SCHEDULE	Dispositivos Inativos Agendados para eliminação
PLC_OPERATING_MODE_CHANGED	Alteração do Modo de Operação PLC Detetada
HARDWARE_UPDATE_BY_IDENTIFIER	Atualização de Endereços

Passos seguintes

Para obter mais informações, veja Descrição geral da referência da API do Defender para IoT.