Referência da API de gestão de alertas para consolas de gestão no local

Artigo
04/11/2023

Este artigo lista as APIs REST de gestão de alertas suportadas para Microsoft Defender para consolas de gestão no local do IoT.

alertas (Obter informações de alerta)

Utilize esta API para obter todos os alertas ou os alertas filtrados a partir de uma consola de gestão no local.

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

GET

Parâmetros de consulta:

Nome	Descrição	Exemplo	Obrigatório/Opcional
estado	Obtenha apenas alertas processados ou não processados. Valores suportados: - `handled` - `unhandled` Todos os outros valores são ignorados.	`/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
siteId	O site no qual o alerta foi detetado.	`/api/v1/alerts?siteId=1`	Opcional
zoneId	A zona em que o alerta foi detetado.	`/api/v1/alerts?zoneId=1`	Opcional
sensorId	O sensor no qual o alerta foi detetado.	`/api/v1/alerts?sensorId=1`	Opcional

Nota

Poderá não ter o ID do site e da zona. Se for este o caso, consulte primeiro todos os dispositivos para obter o ID do site e da zona. Para obter mais informações, veja Referência da API de Integração para consolas de gestão no local (Pré-visualização pública).

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	-
sensorId	Operador numérico	Não nulo	-
zoneId	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`, `Major`ou `Critical`
motor	String	Não nulo	`Protocol Violation`, `Policy Violation`, `Malware`, `Anomaly`ou `Operational`
sourceDevice	Operador numérico	Pode ser nulo	ID do Dispositivo
destinationDevice	Operador numérico	Pode ser nulo	ID do Dispositivo
remediationSteps	String	Pode ser nulo	Passos de remediação apresentados em alerta
additionalInformation	Objeto de informações adicionais	Pode ser nulo	-
processado	Booleano, estado do alerta	Não nulo	`true` ou `false`

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	Nulo / 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
sensorName	String	Não nulo	Nome do sensor definido pelo utilizador
zoneName	String	Não nulo	Nome da zona associada ao sensor
siteName	String	Não nulo	Nome do site associado ao sensor

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

Exemplo de resposta

[
    {
        "engine": "Operational",
        "handled": false,
        "title": "Traffic Detected on sensor Interface",
        "additionalInformation": null,
        "sourceDevice": 0,
        "zoneId": 1,
        "siteId": 1,
        "time": 1594808245000,
        "sensorId": 1,
        "message": "The sensor resumed detecting network traffic on ens224.",
        "destinationDevice": 0,
        "id": 1,
        "severity": "Warning"
    },
    {
        "engine": "Anomaly",
        "handled": false,
        "title": "Address Scan Detected",
        "additionalInformation": null,
        "sourceDevice": 4,
        "zoneId": 1,
        "siteId": 1,
        "time": 1594808260000,
        "sensorId": 1,
        "message": "Address scan detected.\nScanning address: 10.10.10.22\nScanned subnet: 10.11.0.0/16\nScanned addresses: 10.11.1.1, 10.11.20.1, 10.11.20.10, 10.11.20.100, 10.11.20.2, 10.11.20.3, 10.11.20.4, 10.11.20.5, 10.11.20.6, 10.11.20.7...\nIt is recommended to notify the security officer of the incident.",
        "destinationDevice": 0,
        "id": 2,
        "severity": "Critical"
    },
    {
        "engine": "Operational",
        "handled": false,
        "title": "Suspicion of Unresponsive MODBUS Device",
        "additionalInformation": null,
        "sourceDevice": 194,
        "zoneId": 1,
        "siteId": 1,
        "time": 1594808285000,
        "sensorId": 1,
        "message": "Outstation device 10.13.10.1 (Protocol Address 53) seems to be unresponsive to MODBUS requests.",
        "destinationDevice": 0,
        "id": 3,
        "severity": "Minor"
    }
]

Tipo: GET

API:

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<>IP_ADDRESS>/external/v1/alerts?state=&zoneId=&fromTime=&toTime=&siteId=&sensor='

Exemplo:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/external/v1/alerts?state=unhandled&zoneId=1&fromTime=0&toTime=1594551777000&siteId=1&sensor=1'

UUID (Gerir alertas com base no UUID)

Utilize esta API para tomar medidas especificadas num alerta específico detetado pelo Defender para IoT.

Por exemplo, pode utilizar esta API para criar uma regra de reencaminhamento que reencaminha dados para o QRadar. Para obter mais informações, veja Integrar o Qradar com Microsoft Defender para IoT.

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

PUT

Tipo: JSON

Parâmetros de consulta:

Nome	Descrição	Exemplo	Obrigatório/Opcional
UUID	Define o identificador universalmente exclusivo (UUID) para o alerta que pretende processar ou processar e aprender.	`/api/v1/alerts/7903F632-H7EJ-4N69-F40F-4B1E689G00Q0`	Necessário

Parâmetros do corpo

Nome	Descrição	Exemplo	Obrigatório/Opcional
ação	String	Ou `handlehandleAndLearn`	Necessário

Exemplo de pedido

{
    "action": "handle"
}

Tipo: JSON

Matriz de objetos JSON que representam dispositivos.

Campos de resposta:

Nome	Tipo	Obrigatório/Opcional	Descrição
conteúdo/erro	String	Necessário	Se o pedido for bem-sucedido, a propriedade de conteúdo será apresentada. Caso contrário, a propriedade de erro é apresentada.

Valores de conteúdo possíveis:

Código de estado	Mensagem	Descrição
200	O pedido de atualização de alertas foi concluído com êxito.	O pedido de atualização foi concluído com êxito. Sem comentários.
200	O alerta já foi processado (identificador).	O alerta já foi processado quando foi recebido um pedido de identificador para o alerta. O alerta continua a ser processado.
200	O alerta já foi processado e aprendido (handleAndLearn).	O alerta já foi processado e ficou a saber quando foi recebido um pedido para processarAndLearn . O alerta permanece no estado handledAndLearn .
200	O alerta já foi processado (processado). O identificador e a aprendizagem (handleAndLearn) foram executados no alerta.	O alerta já foi processado quando foi recebido um pedido para processarAndLearn . O alerta torna-se handleAndLearn.
200	O alerta já foi processado e aprendido (handleAndLearn). Pedido de identificador ignorado.	O alerta já era handleAndLearn quando foi recebido um pedido para processar o alerta. O alerta permanece identificadorAndLearn.
500	Ação inválida.	A ação que foi enviada não é uma ação válida a executar no alerta.
500	Ocorreu um erro inesperado.	Ocorreu um erro inesperado. Para resolver o problema, contacte o Suporte Técnico.
500	Não foi possível executar o pedido porque não foi encontrado nenhum alerta para este UUID.	O UUID do alerta especificado não foi encontrado no sistema.

Exemplo de resposta: Com êxito

{
    "content": "Alert update request finished successfully"
}

Exemplo de resposta: Sem êxito

{
    "error": "Invalid action"
}

Tipo: PUT

APIs:

curl -k -X PUT -d '{"action": "<ACTION>"}' -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/external/v1/alerts/<UUID>

Exemplo:

curl -k -X PUT -d '{"action": "handle"}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/alerts/1-1594550943000

maintenanceWindow (Criar exclusões de alerta)

Gere janelas de manutenção, nas quais os alertas não serão enviados. Utilize esta API para definir e atualizar horas de paragem e início, dispositivos ou sub-redes que devem ser excluídos ao acionar alertas ou definir e atualizar motores do Defender para IoT que devem ser excluídos.

Por exemplo, durante uma janela de manutenção, poderá querer parar a entrega de alertas de todos os alertas, exceto alertas de software maligno em dispositivos críticos.

As janelas de manutenção que definem com a maintenanceWindow API aparecem na janela Exclusões de Alertas da consola de gestão no local como uma regra de exclusão só de leitura, com o nome com a seguinte sintaxe: Maintenance-{token name}-{ticket ID}.

Importante

Esta API é suportada apenas para fins de manutenção e por um período de tempo limitado e não se destina a ser utilizada em vez de regras de exclusão de alertas. Utilize esta API apenas para operações de manutenção temporária única.

URI: /external/v1/maintenanceWindow

POST

Cria uma nova janela de manutenção.

Parâmetros do corpo:

Nome	Descrição	Exemplo	Obrigatório/Opcional
ticketId	Cadeia. Define o ID do pedido de manutenção nos sistemas do utilizador. Certifique-se de que o ID da permissão não está ligado a uma janela aberta existente.	`2987345p98234`	Necessário
ttl	Número inteiro positivo. Define o TTL (time to live), que é a duração da janela de manutenção, em minutos. Após a conclusão do período de tempo definido, a janela de manutenção termina e o sistema comporta-se normalmente novamente.	`180`	Necessário
motores	Matriz JSON de cadeias. Define o motor a partir do qual suprimir alertas durante a janela de manutenção. Valores possíveis: - `ANOMALY` - `MALWARE` - `OPERATIONAL` - `POLICY_VIOLATION` - `PROTOCOL_VIOLATION`	`ANOMALY,OPERATIONAL`	Opcional
sensorIds	Matriz JSON de cadeias. Define os sensores a partir dos quais suprimir alertas durante a janela de manutenção. Pode obter estes IDs de sensor a partir da API de aplicações (Gerir aplicações de sensores OT ).	`1,35,63`	Opcional
sub-redes	Matriz JSON de cadeias. Define as sub-redes a partir das quais suprimir alertas durante a janela de manutenção. Defina cada sub-rede numa notação CIDR.	`192.168.0.0/16,138.136.80.0/14,112.138.10.0/8`	Opcional

Código de estado	Mensagem	Descrição
201 (Criado)	-	A ação foi concluída com êxito.
400 (Pedido Incorreto)	Sem TicketId	O pedido da API não tinha um `ticketId` valor.
400 (Pedido Incorreto)	TTL Ilegal	O pedido da API incluía um valor TTL não positivo ou não numérico.
400 (Pedido Incorreto)	Não foi possível analisar o pedido.	Problema ao analisar o corpo, como parâmetros incorretos ou valores inválidos.
400 (Pedido Incorreto)	A janela de manutenção com os mesmos parâmetros já existe.	Aparece quando já existe uma janela de manutenção existente com os mesmos detalhes.
404 (Não Encontrado)	ID de sensor desconhecido	Um dos sensores listados no pedido não existe.
409 (Conflito)	O ID do Pedido de Suporte já tem uma janela aberta.	O ID da permissão está ligado a outra janela de manutenção aberta.
500 (Erro interno do servidor)	-	Qualquer outro erro inesperado.

Tipo: POST

API:

curl -k -X POST -d '{"ticketId": "<TICKET_ID>",ttl": <TIME_TO_LIVE>,"engines": [<ENGINE1, ENGINE2...ENGINEn>],"sensorIds": [<SENSOR_ID1, SENSOR_ID2...SENSOR_IDn>],"subnets": [<SUBNET1, SUBNET2....SUBNETn>]}' -H "Authorization: <AUTH_TOKEN>" https://<IP address>/external/v1/maintenanceWindow

Exemplo:

curl -k -X POST -d '{"ticketId": "a5fe99c-d914-4bda-9332-307384fe40bf","ttl": "20","engines": ["ANOMALY"],"sensorIds": ["5","3"],"subnets": ["10.0.0.0/16"]}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/maintenanceWindow

DELETE

Fecha uma janela de manutenção existente.

Parâmetros de consulta:

Nome	Descrição	Exemplo	Obrigatório/Opcional
ticketId	Define o ID do pedido de manutenção nos sistemas do utilizador. Certifique-se de que o ID do pedido está ligado a uma janela aberta existente.	`2987345p98234`	Necessário

Códigos de erro:

Código	Mensagem	Descrição
200 (OK)	-	A ação foi concluída com êxito.
400 (Pedido Incorreto)	Sem TicketId	O parâmetro ticketId está em falta no pedido.
404 (Não Encontrado):	Janela de manutenção não encontrada.	O ID do pedido de suporte não está ligado a uma janela de manutenção aberta.
500 (Erro interno do Servidor)	-	Qualquer outro erro inesperado.

Tipo: DELETE

API:

curl -k -X DELETE -d '{"ticketId": "<TICKET_ID>"}' -H "Authorization: <AUTH_TOKEN>" https://<IP address>/external/v1/maintenanceWindow

Exemplo:

curl -k -X DELETE -d '{"ticketId": "a5fe99c-d914-4bda-9332-307384fe40bf"}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/maintenanceWindow

GET

Obtenha um registo de todas as ações abertas (POST), close (DELETE) e update (PUT) que foram realizadas com esta API para processar janelas de manutenção. T

Parâmetros de consulta:

Nome	Descrição	Exemplo	Obrigatório/Opcional
fromDate	Filtra os registos a partir da data predefinida e posterior. O formato é `YYYY-MM-DD`.	`2022-08-10`	Opcional
toDate	Filtra os registos até à data predefinida. O formato é `YYYY-MM-DD`.	`2022-08-10`	Opcional
ticketId	Filtra os registos relacionados com um ID de pedido específico.	`9a5fe99c-d914-4bda-9332-307384fe40bf`	Opcional
tokenName	Filtra os registos relacionados com um nome de token específico.	quarterly-sanidade-window	Opcional

Códigos de erro:

Código	Mensagem	Descrição
200	OK	A ação foi concluída com êxito.
204:	Sem Conteúdo	Não existem dados para mostrar.
400	Pedido Incorreto	O formato de data está incorreto.
500	Erro de Servidor Interno	Qualquer outro erro inesperado.

Tipo: JSON

Matriz de objetos JSON que representam operações da janela de manutenção.

Estrutura de resposta:

Nome	Tipo	Nulo / Não nulo	Lista de valores
id	Número inteiro longo	Não nulo	Um ID interno para o registo atual
dateTime	String	Não nulo	A hora em que a atividade ocorreu, por exemplo: `2022-04-23T18:25:43.511Z`
ticketId	String	Não nulo	O ID da janela de manutenção. Por exemplo: `9a5fe99c-d914-4bda-9332-307384fe40bf`
tokenName	String	Não nulo	O nome do token da janela de manutenção. Por exemplo: `quarterly-sanity-window`
motores	Matriz de cadeias	Pode ser nulo	Os motores nos quais se aplica a janela de manutenção, conforme fornecido durante a criação da janela de manutenção: `Protocol Violation`, `Policy Violation`, `Malware`, `Anomaly`ou `Operational`
sensorIds	Matriz da cadeia	Pode ser nulo	Os sensores nos quais se aplica a janela de manutenção, conforme fornecido durante a criação da janela de manutenção.
sub-redes	Matriz da cadeia	Pode ser nulo	As sub-redes nas quais se aplica a janela de manutenção, conforme fornecido durante a criação da janela de manutenção.
ttl	Operador numérico	Pode ser nulo	O Time to Live (TTL) da janela de manutenção, conforme fornecido durante a criação ou atualização da janela de manutenção.
operationType	String	Não nulo	Um dos seguintes valores: `OPEN`, `UPDATE`e `CLOSE`

Tipo: GET

API:

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/external/v1/maintenanceWindow?fromDate=&toDate=&ticketId=&tokenName='

Exemplo:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/external/v1/maintenanceWindow?fromDate=2020-01-01&toDate=2020-07-14&ticketId=a5fe99c-d914-4bda-9332-307384fe40bf&tokenName=a'

PUT

Permite-lhe atualizar a duração da janela de manutenção depois de iniciar o processo de manutenção ao alterar o ttl parâmetro. A nova definição de duração substitui a anterior.

Este método é útil quando pretende definir uma duração mais longa do que a duração atualmente configurada. Por exemplo, se tiver definido originalmente 180 minutos, passaram 90 minutos e pretender adicionar mais 30 minutos, atualize o ttl minuto para 120 repor a contagem de duração.

Parâmetros de consulta:

Nome	Descrição	Exemplo	Obrigatório/Opcional
ticketId	Cadeia. Define o ID do pedido de manutenção nos sistemas do utilizador.	`2987345p98234`	Necessário
ttl	Número inteiro positivo. Define a duração da janela em minutos.	`210`	Necessário

Códigos de erro:

Código	Mensagem	Descrição
200 (OK)	-	A ação foi concluída com êxito.
400 (Pedido Incorreto)	Sem TicketId	Falta um `ticketId` valor ao pedido.
400 (Pedido Incorreto)	TTL Ilegal	O TTL definido não é numérico ou não é um número inteiro positivo.
400 (Pedido Incorreto)	Não foi possível analisar o pedido	O pedido tem um `ttl` valor de parâmetro em falta.
404 (Não Encontrado)	Janela de manutenção não encontrada	O ID do pedido de suporte não está ligado a uma janela de manutenção aberta.
500 (Erro interno do Servidor)	-	Qualquer outro erro inesperado.

Tipo: PUT

API:

curl -k -X PUT -d '{"ticketId": "<TICKET_ID>",ttl": "<TIME_TO_LIVE>"}' -H "Authorization: <AUTH_TOKEN>" https://<IP address>/external/v1/maintenanceWindow

Exemplo:

curl -k -X PUT -d '{"ticketId": "a5fe99c-d914-4bda-9332-307384fe40bf","ttl": "20"}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/maintenanceWindow

pcap (PCAP de alerta de pedido)

Utilize esta API para pedir um ficheiro PCAP relacionado com um alerta.

URI: /external/v2/alerts/

GET

Parâmetros de consulta:

Nome	Descrição	Exemplo	Obrigatório/Opcional
id	ID de alerta da consola de gestão no local	`/external/v2/alerts/pcap/<id>`	Necessário

Tipo: JSON

Cadeia de mensagem com os detalhes do estado da operação:

Código de estado	Mensagem	Descrição
200 (OK)	-	Objeto JSON com dados sobre o ficheiro PCAP pedido. Para obter mais informações, veja Campos de dados.
500 (Erro interno do Servidor)	Alerta não encontrado	O ID de alerta fornecido não foi encontrado na consola de gestão no local.
500 (Erro interno do Servidor)	Erro ao obter o token para o ID do xsense `<number>`	Ocorreu um erro ao obter o token do sensor para o ID do sensor especificado
500 (Erro interno do Servidor)	-	Qualquer outro erro inesperado.

Campos de dados

Nome	Tipo	Nulo / Não nulo	Lista de valores
id	Operador numérico	Não nulo	O ID de alerta da consola de gestão no local
xsenseId	Operador numérico	Não nulo	O ID do sensor
xsenseAlertId	Operador numérico	Não nulo	O ID de alerta da consola do sensor
downloadUrl	String	Não nulo	O URL utilizado para transferir o ficheiro PCAP
token	String	Não nulo	O token do sensor, a ser utilizado ao transferir o ficheiro PCAP

Exemplo de resposta: Êxito

{
  "downloadUrl": "https://10.1.0.2/api/v2/alerts/pcap/1",
  "xsenseId": 1,
  "token": "d2791f58-2a88-34fd-ae5c-2651fe30a63c",
  "id": 1,
  "xsenseAlertId": 1
}

Exemplo de resposta: Erro

{
  "error": "alert not found"
}

Tipo: GET

APIs

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/external/v2/alerts/pcap/<ID>'

* Exemplo:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://10.1.0.1/external/v2/alerts/pcap/1'

Passos seguintes

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

Partilhar via

Referência da API de gestão de alertas para consolas de gestão no local

alertas (Obter informações de alerta)

GET

Exemplo de resposta

UUID (Gerir alertas com base no UUID)

PUT

Exemplo de resposta: Com êxito

Exemplo de resposta: Sem êxito

maintenanceWindow (Criar exclusões de alerta)

POST

DELETE

GET

PUT

pcap (PCAP de alerta de pedido)

GET

Campos de dados

Exemplo de resposta: Êxito

Exemplo de resposta: Erro

Passos seguintes

Comentários

Recursos adicionais