Referência da API de gerenciamento de alertas para sensores de monitoramento de OT

Este artigo lista as APIs REST de gerenciamento de alertas com suporte para sensores de monitoramento de OT do Microsoft Defender para IoT.

alertas (recuperar informações de alerta)

Use essa API para solicitar uma lista de todos os alertas que o sensor do Defender para IoT detectou.

URI: /api/v1/alerts

GET

Solicitação

Parâmetros de consulta

Nome	Descrição	Exemplo	Obrigatório/Opcional
state	Obtém somente os alertas manipulados ou não manipulados. Valores com suporte: - handled - unhandled	/api/v1/alerts?state=handled	Opcional
fromTime	Obtenha alertas criados a partir de um determinado horário, em milissegundos, desde a Hora época e no fuso horário UTC.	/api/v1/alerts?fromTime=<epoch>	Opcional
toTime	Obtenha alertas criados antes de um determinado horário, em milissegundos, desde a Hora época e no fuso horário UTC.	/api/v1/alerts?toTime=<epoch>	Opcional
tipo	Obter alertas somente de um tipo específico. Valores com suporte: - unexpected new devices - disconnections Todos os outros valores são ignorados.	/api/v1/alerts?type=disconnections	Opcional

Resposta

Tipo: JSON

Uma lista de alertas com os seguintes campos:

Nome	Type	Anulável/Não anulável	Lista de valores
ID	Numérico	Não permite valor nulo	-
time	Numérico	Não permite valor nulo	Milissegundos a partir da hora Época, no fuso horário UTC
title	String	Não permite valor nulo	-
message	String	Não permite valor nulo	-
severity	String	Não permite valor nulo	Warning, Minor, Major ou Critical
engine	String	Não permite valor nulo	Protocol Violation, Policy Violation, Malware, Anomaly ou Operational
sourceDevice	Numérico	Nullable	ID do Dispositivo
destinationDevice	Numérico	Nullable	ID do Dispositivo
additionalInformation	Objeto de informações adicionais	Nullable	-

Campos de informações adicionais

Nome	Type	Anulável/Não anulável	Lista de valores
descrição	String	Não permite valor nulo	-
information	Matriz JSON	Não permite valor nulo	String

Adicionado para V2:

Nome	Type	Anulável/Não anulável	Lista de valores
sourceDeviceAddress	String	Nullable	Endereço IP ou MAC
destinationDeviceAddress	String	Nullable	Endereço IP ou MAC
remediationSteps	Matriz JSON	Não permite valor nulo	Cadeia de caracteres, etapas de correção descritas no alerta

Para saber mais, confira Referência de 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 de 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'

events (Recuperar eventos da linha do tempo)

Use essa API para solicitar uma lista de eventos relatados na linha do tempo do evento.

Observação

Executar a API idêntica na mesma hora, com os mesmos valores de parâmetro, retorna um valor armazenado em cache. Se você estiver executando essa API duas vezes em uma hora, recomendamos modificar os parâmetros de consulta para obter uma resposta atualizada.

URI: /api/v1/events

GET

Solicitação

Parâmetros de consulta

Nome	Descrição	Exemplo	Obrigatório/Opcional
minutesTimeFrame	Filtrar resultados por um determinado período durante o qual os eventos foram relatados. Definido retrospectivamente com relação à hora atual. Máximo = 4320 (3 dias). Qualquer valor maior é tratado como 4320, sem erro	/api/v1/events?minutesTimeFrame=20	Opcional
tipo	Filtre os resultados somente para um tipo específico. Qualquer valor diferente de tipos com suporte é ignorado. Para mais informações, confira Eventotype e titlereferência.	/api/v1/events?type=DEVICE_CONNECTION_CREATED /api/v1/events?type=REMOTE_ACCESS&minutesTimeFrame	Opcional

Resposta

Tipo: JSON

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

Os campos de evento incluem:

Nome	Type	Anulável/Não anulável	Lista de valores
timestamp	Numérico	Não permite valor nulo	Milissegundos a partir da hora Época, no fuso horário UTC
tipo	String	Não permite valor nulo	Um dos tipos com suporte
title	String	Não permite valor nulo	Um dos títulos com suporte
severity	String	Não permite valor nulo	INFO, NOTICE ou ALERT
proprietário	String	Nullable	Cadeia de caracteres. Se o evento foi criado manualmente, esse campo incluirá o nome de usuário que criou o evento.
content	String	Não permite valor nulo	Cadeia de caracteres 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 de 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 referência title

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

Tipo de evento	Título do evento
DEVICE_CREATE	Dispositivo Detectado
DEVICE_UPDATE	Dispositivo atualizado
ALERT_REPORTED	Alerta Detectado
ALERT_UPDATED	Alerta Atualizado
SCAN	Dispositivo de Exame Detectado
PROGRAM_DEVICE	Programação PLC
MMS_PROGRAM_DEVICE	Atualização do Programa do 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	Conexão do Dispositivo Detectada
USER_LOGIN	Tentativa de Logon do Usuário
FILE_TRANSFER	Transferência de Arquivo Detectada
CUSTOM_EVENT	Evento definido pelo usuário
REMOTE_ACCESS	Conexã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 Bloco de Memória Siemens S7
SIEMENS_S_7_AUTHENTICATION	Autenticação Siemens S7
REPORT_CREATED	Relatório Criado
SNMP_TRAP	Interceptação SNMP detectada
DATABASE_ACTION	Manipulação da Estrutura do Banco de Dados
PLC_MODULE_CHANGE	Alteração do Módulo do PLC
FIRMWARE_UPDATE	Atualizações de firmware
PLC_START	Início do PLC
SRTP_PLC_RESET	Redefinição do PLC
SRTP_PLC_COPY_FIRMWARE	Atualizações de firmware
SRTP_LOGIN_PROGRAMMING	Conjunto de Modo de Programação do PLC
SRTP_PLC_CHANGE_PASSWORD	Alteração de Senha do PLC
OPC_DATA_ACCESS_GROUP_MANAGEMENT_OPERATION	Operação de Gerenciamento de Grupo de Acesso a Dados do OPC
OPC_DATA_ACCESS_ITEM_MANAGEMENT_OPERATION	Operação de Gerenciamento de Itens de Acesso a Dados do OPC
OPC_DATA_ACCESS_IO_SUBSCRIPTION_MANAGEMENT_OPERATION	Operação de Gerenciamento de Assinatura de E/S de Acesso a Dados do OPC
OPC_AE_EVENT_SUBSCRIPTION	Assinatura de Evento de AE do OPC
OPC_AE_EVENT_CONDITION_MANAGEMENT_OPERATION	Operação de Gerenciamento de Condições de Eventos de AE do OPC
OPC_AE_EVENT	Evento de AE do OPC
SRTP_CHANGE_PRIVILEGE	Alterar o nível de acesso do PLC
SRTP_CHANGE_LEVEL_FAILED	Falha ao alterar nível de acesso do PLC
SUITELINK_INIT_CONNECTION	Sessão do Wonderware inicializada
USER_OPERATION	Operação do usuário
DIP_UPLOADED	Pacote de Data Intelligence Carregado
FTP_AUTHENTICATION_FAILURE	Falha na Autenticação FTP
PROFINET_DPC_VALUE_SET	Operação SET do Profinet
S7PLUS_PLC_MODE_CHANGE	Alteração do modo PLC
S7_PLC_MODE_CHANGE	Alteração do modo PLC
DELETE_DEVICE	Dispositivo excluído
S7PLUS_PROGRAMMING	Programação PLC
FIRMWARE_CHANGED	Firmware do PLC Alterado
DELTAV_PROGRAMMING	Script de Instalação do DeltaV
USER_DEFINED_RULE_CREATED	Regra Definida pelo Usuário Criada
USER_DEFINED_RULE_EDITED	Regra Definida pelo Usuário Editada
USER_DEFINED_RULE_DELETED	Regra Definida pelo Usuário Excluída
USER_DEFINED_RULE_OPERATION	Operação de Regra Definida pelo Usuário
REMOTE_PROCESS_EXECUTION	Execução do Processo Remoto
DEVICE_UNIFICATION	Dispositivo atualizado
NOTIFICATION	A notificação foi resolvida manualmente
ENIP_CONTROLLER_PROGRAM_DELETE	Exclusão do Programa do Controlador
ENIP_CONTROLLER_PROGRAM_RESET	Redefinição do Programa do Controlador
ENIP_CONTROLLER_GENERIC_RESET	Redefinição do controlador
ENIP_CONTROLLER_GENERIC_STOP	Parada do controlador
ENIP_CONTROLLER_GENERIC_START	Início do Controlador
TELNET_AUTHENTICATION_FAILURE	Falha na Autenticação do Telnet
CONFIGURATION_OF_CLEARTEXT_PASSWORD	Configuração da Senha de Texto Não Criptografado
CLEARTEXT_AUTHENTICATION	Autenticação de Texto Não Criptografado
PROGRAM_UPLOAD_DEVICE	Upload do Programa do PLC
CONFIGURATION_CHANGE	Gravação da configuração de PLC
CONFIGURATION_READ	Leitura de Configuração do PLC
SYSLOG_MSG	Mensagem Syslog
INTERNET_ACCESS	Acesso à Internet
CAMP_MEMORY_WRITE_OPERATION	Operação Comum de Gravação de Memória do Protocolo de Mensagem ASCII
MUTED_ALERT	Evento detectado e com o mudo ativado
DHCP_UPDATE	Atualização de Endereço
DIP_FAILURE	Falha na Instalação do Pacote de Data Intelligence
DELETE_DEVICE_SCHEDULE	Dispositivos Inativos Agendados para Exclusão
PLC_OPERATING_MODE_CHANGED	Alteração do Modo Operacional do PLC Detectada
HARDWARE_UPDATE_BY_IDENTIFIER	Atualização de Endereço

Próximas etapas

Para obter mais informações, confira a Visão geral de referência da API do Defender para IoT.