Referência da API de gerenciamento de alertas para consoles de gerenciamento locais

Artigo
06/13/2022

Este artigo lista as APIs REST de gerenciamento de alertas com suporte para os consoles de gerenciamento locais do Microsoft Defender for IoT.

alertas (Recuperar informações de alerta)

Use essa API para recuperar todos os alertas ou alertas filtrados de um console de gerenciamento local.

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

OBTER

Parâmetros de consulta:

Designação	Descrição	Exemplo	Obrigatório / Opcional
estado	Obtenha apenas alertas manipulados ou não tratados. Valores suportados: - `handled` - `unhandled` Todos os outros valores são ignorados.	`/api/v1/alerts?state=handled`	Opcional
fromTime	Receba alertas criados a partir de um determinado momento, em milissegundos a partir da hora Epoch e no fuso horário UTC.	`/api/v1/alerts?fromTime=<epoch>`	Opcional
toTime	Receba alertas criados apenas antes de um determinado momento, em milissegundos a partir da hora de Epoch e no fuso horário UTC.	`/api/v1/alerts?toTime=<epoch>`	Opcional
siteId	O local em que o alerta foi descoberto.	`/api/v1/alerts?siteId=1`	Opcional
zoneId	A zona em que o alerta foi descoberto.	`/api/v1/alerts?zoneId=1`	Opcional
sensorId	O sensor no qual o alerta foi descoberto.	`/api/v1/alerts?sensorId=1`	Opcional

Observação

Talvez você não tenha o ID do site e da zona. Se esse for o caso, primeiro consulte todos os dispositivos para recuperar o ID do site e da zona. Para obter mais informações, consulte referência da API de integração para consoles de gerenciamento locais (visualização pública).

Tipo: JSON

Uma lista de alertas com os seguintes campos:

Designação	Tipo	Nulo / Não anulável	Lista de valores
ID	Numérico	Não anulável	-
sensorId	Numérico	Não anulável	-
zoneId	Numérico	Não anulável	-
tempo	Numérico	Não anulável	Milissegundos a partir de da hora de Epoch, no fuso horário UTC
título	String	Não anulável	-
mensagem	String	Não anulável	-
gravidade	String	Não anulável	`Warning`, `Minor`, `Major`ou `Critical`
motor	String	Não anulável	`Protocol Violation`, `Policy Violation`, `Malware`, `Anomaly`ou `Operational`
sourceDevice	Numérico	Nulo	ID do dispositivo
destinationDevice	Numérico	Nulo	ID do dispositivo
remediaçãoPassos	String	Nulo	Etapas de correção mostradas no alerta
informações adicionais	Objeto de informação adicional	Nulo	-
tratados	Booleano, estado de alerta	Não anulável	`true` ou `false`

Campos de informação adicional:

Designação	Tipo	Nulo / Não anulável	Lista de valores
descrição	String	Não anulável	-
informações	Matriz JSON	Não anulável	String

Adicionado para V2:

Designação	Tipo	Nulo / Não anulável	Lista de valores
sourceDeviceAddress	String	Nulo	Endereço IP ou MAC
destinationDeviceAddress	String	Nulo	Endereço IP ou MAC
remediaçãoPassos	Matriz JSON	Não anulável	Strings, etapas de correção descritas no alerta
sensorName	String	Não anulável	Nome do sensor definido pelo utilizador
zoneName	String	Não anulável	Nome da zona associada ao sensor
siteName	String	Não anulável	Nome do local associado ao sensor

Para obter mais informações, consulte Sensor API version reference.

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 (Gerenciar alertas com base no UUID)

Use esta API para executar uma ação específica em um alerta específico detetado pelo Defender for IoT.

Por exemplo, você pode usar essa API para criar uma regra de encaminhamento que encaminha dados para o QRadar. Para obter mais informações, consulte integrar o Qradar com o Microsoft Defender para IoT.

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

COLOCAR

Tipo: JSON

Parâmetros de consulta:

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

Parâmetros corporais

Designação	Descrição	Exemplo	Obrigatório / Opcional
ação	String	Ou `handle` ou `handleAndLearn`	Necessário

Exemplo de solicitação

{
    "action": "handle"
}

Tipo: JSON

Matriz de objetos JSON que representam dispositivos.

Campos de resposta:

Designação	Tipo	Obrigatório / Opcional	Descrição
conteúdo / erro	String	Necessário	Se a solicitação for bem-sucedida, a propriedade content será exibida. Caso contrário, a propriedade error será exibida.

Valores de conteúdo possíveis:

Código de status	Mensagem	Descrição
200	Solicitação de atualização de alerta concluída com êxito.	A solicitação de atualização foi concluída com êxito. Sem comentários.
200	O alerta já foi tratado (identificador).	O alerta já era tratado quando uma solicitação de identificador para o alerta foi recebida. O alerta permanece tratado.
200	O alerta já foi tratado e aprendido (handleAndLearn).	O alerta já foi tratado e aprendido quando uma solicitação para handleAndLearn foi recebida. O alerta permanece no status manipuladoAndLearn.
200	O alerta já foi tratado (tratado). Manipular e aprender (handleAndLearn) foi realizado no alerta.	O alerta já foi tratado quando uma solicitação para handleAndLearn foi recebida. O alerta torna-se handleAndLearn.
200	O alerta já foi tratado e aprendido (handleAndLearn). Solicitação de identificador ignorada.	O alerta já estava manipulador quando uma solicitação para lidar com o alerta foi recebida. O alerta permanece handleAndLearn.
500	Ação inválida.	A ação que foi enviada não é uma ação válida a ser executada 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 a solicitação porque nenhum alerta foi encontrado para este UUID.	O UUID de alerta especificado não foi encontrado no sistema.

Exemplo de resposta: bem-sucedido

{
    "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)

Gerencia as janelas de manutenção, sob as quais os alertas não serão enviados. Use essa API para definir e atualizar horários de parada e início, dispositivos ou sub-redes que devem ser excluídos ao disparar alertas ou definir e atualizar mecanismos do Defender para IoT que devem ser excluídos.

Por exemplo, durante uma janela de manutenção, talvez você queira interromper a entrega de alertas de todos os alertas, exceto alertas de malware em dispositivos críticos.

As janelas de manutenção definidas com a API maintenanceWindow aparecem na janela Exclusões de Alerta do console de gerenciamento local como uma regra de exclusão somente leitura, nomeada 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 usada em vez de regras de exclusão de alerta. Use esta API apenas para operações de manutenção únicas e temporárias.

URI: /external/v1/maintenanceWindow

PUBLICAR

Cria uma nova janela de manutenção.

Parâmetros do corpo:

Designação	Descrição	Exemplo	Obrigatório / Opcional
ticketId	String. Define o ID do tíquete de manutenção nos sistemas do usuário. Certifique-se de que o ID do bilhete não está vinculado a uma janela aberta existente.	`2987345p98234`	Necessário
ttl	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 volta a comportar-se normalmente.	`180`	Necessário
motores	Matriz JSON de cadeias de caracteres. Define de qual mecanismo 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 de caracteres. Define de quais sensores suprimir alertas durante a janela de manutenção. Você pode obter esses IDs de sensor dos dispositivos (Gerenciar dispositivos de sensor OT) API.	`1,35,63`	Opcional
sub-redes	Matriz JSON de cadeias de caracteres. Define as sub-redes a serem suprimidas durante a janela de manutenção. Defina cada sub-rede em uma notação CIDR.	`192.168.0.0/16,138.136.80.0/14,112.138.10.0/8`	Opcional

Código de status	Mensagem	Descrição
201 (Criado)	-	A ação foi concluída com sucesso.
400 (Mau pedido)	Sem TicketId	A solicitação de API estava faltando um valor de `ticketId`.
400 (Mau pedido)	TTL ilegal	A solicitação de API incluiu um valor TTL não positivo ou não numérico.
400 (Mau pedido)	Não foi possível analisar a solicitação.	Problema ao analisar o corpo, como parâmetros incorretos ou valores inválidos.
400 (Mau pedido)	Já existe uma janela de manutenção com os mesmos parâmetros.	Aparece quando já existe uma janela de manutenção existente com os mesmos detalhes.
404 (Não encontrado)	ID do sensor desconhecido	Um dos sensores listados na solicitação não existe.
409 (Conflito)	O ID do bilhete já tem uma janela aberta.	O ID do ticket está vinculado 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

SUPRIMIR

Fecha uma janela de manutenção existente.

Parâmetros de consulta:

Designação	Descrição	Exemplo	Obrigatório / Opcional
ticketId	Define o ID do tíquete de manutenção nos sistemas do usuário. Certifique-se de que o ID do bilhete está vinculado 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 sucesso.
400 (Mau pedido)	Sem TicketId	O parâmetro ticketId está ausente da solicitação.
404 (Não encontrado):	Janela de manutenção não encontrada.	O ID do ticket não está vinculado 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

OBTER

Recupere um log de todos os abrir (POST), feche (DELETE) e atualizar (PUT) que foram executadas usando essa API para lidar com janelas de manutenção. T

Parâmetros de consulta:

Designação	Descrição	Exemplo	Obrigatório / Opcional
a partir de Data	Filtra os logs da data predefinida e posteriores. O formato é `YYYY-MM-DD`.	`2022-08-10`	Opcional
até à data	Filtra os logs até a data predefinida. O formato é `YYYY-MM-DD`.	`2022-08-10`	Opcional
ticketId	Filtra os logs relacionados a um ID de tíquete específico.	`9a5fe99c-d914-4bda-9332-307384fe40bf`	Opcional
tokenName	Filtra os logs relacionados a um nome de token específico.	janela trimestral de sanidade mental	Opcional

Códigos de erro:

Código	Mensagem	Descrição
200	OK	A ação foi concluída com sucesso.
204:	Sem conteúdo	Não há dados para mostrar.
400	Mau pedido	O formato de data está incorreto.
500	Erro interno do servidor	Qualquer outro erro inesperado.

Tipo: JSON

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

Estrutura de resposta:

Designação	Tipo	Nulo / Não anulável	Lista de valores
id	Inteiro longo	Não anulável	Uma ID interna para o log atual
dateTime	String	Não anulável	A hora em que a atividade ocorreu, por exemplo: `2022-04-23T18:25:43.511Z`
ticketId	String	Não anulável	O ID da janela de manutenção. Por exemplo: `9a5fe99c-d914-4bda-9332-307384fe40bf`
tokenName	String	Não anulável	O nome do token da janela de manutenção. Por exemplo: `quarterly-sanity-window`
motores	Matriz de cadeias de caracteres	Nulo	Os motores aos quais se aplica a janela de manutenção, conforme fornecidos durante a criação da janela de manutenção: `Protocol Violation`, `Policy Violation`, `Malware`, `Anomaly`ou `Operational`
sensorIds	Matriz de cadeia de caracteres	Nulo	Os sensores nos quais a janela de manutenção se aplica, conforme fornecidos durante a criação da janela de manutenção.
sub-redes	Matriz de cadeia de caracteres	Nulo	As sub-redes nas quais a janela de manutenção se aplica, conforme fornecido durante a criação da janela de manutenção.
ttl	Numérico	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 anulável	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'

COLOCAR

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

Esse método é útil quando você deseja definir uma duração maior do que a duração configurada no momento. Por exemplo, se você definiu originalmente 180 minutos, 90 minutos se passaram e deseja adicionar mais 30 minutos, atualize o ttl para 120 minuto para redefinir a contagem de duração.

Parâmetros de consulta:

Designação	Descrição	Exemplo	Obrigatório / Opcional
ticketId	String. Define o ID do tíquete de manutenção nos sistemas do usuário.	`2987345p98234`	Necessário
ttl	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 sucesso.
400 (Mau pedido)	Sem TicketId	A solicitação está faltando um valor de `ticketId`.
400 (Mau pedido)	TTL ilegal	O TTL definido não é numérico ou não é um número inteiro positivo.
400 (Mau pedido)	Não foi possível analisar a solicitação	A solicitação está faltando um valor de parâmetro `ttl`.
404 (Não encontrado)	Janela de manutenção não encontrada	O ID do ticket não está vinculado 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 (Solicitar alerta PCAP)

Use essa API para solicitar um arquivo PCAP relacionado a um alerta.

URI: /external/v2/alerts/

OBTER

Parâmetros de consulta:

Designação	Descrição	Exemplo	Obrigatório / Opcional
id	ID de alerta do console de gerenciamento local	`/external/v2/alerts/pcap/<id>`	Necessário

Tipo: JSON

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

Código de status	Mensagem	Descrição
200 (OK)	-	Objeto JSON com dados sobre o arquivo PCAP solicitado. Para obter mais informações, consulte Campos de dados.
500 (Erro interno do servidor)	Alerta não encontrado	A ID de alerta fornecida não foi encontrada no console de gerenciamento local.
500 (Erro interno do servidor)	Erro ao obter token para `<number>` de id xsense	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

Designação	Tipo	Nulo / Não anulável	Lista de valores
id	Numérico	Não anulável	O ID de alerta do console de gerenciamento local
xsenseId	Numérico	Não anulável	O ID do sensor
xsenseAlertId	Numérico	Não anulável	O ID de alerta do console do sensor
downloadUrl	String	Não anulável	O URL usado para baixar o arquivo PCAP
token	String	Não anulável	O token do sensor, para ser usado ao baixar o arquivo PCAP

Exemplo de resposta: Sucesso

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

Próximos passos

Para obter mais informações, consulte a visão geral de referência da API do Defender for IoT.

Partilhar via

Referência da API de gerenciamento de alertas para consoles de gerenciamento locais

alertas (Recuperar informações de alerta)

OBTER

Exemplo de resposta

UUID (Gerenciar alertas com base no UUID)

COLOCAR

Exemplo de resposta: bem-sucedido

Exemplo de resposta: Sem êxito

maintenanceWindow (Criar exclusões de alerta)

PUBLICAR

SUPRIMIR

OBTER

COLOCAR

pcap (Solicitar alerta PCAP)

OBTER

Campos de dados

Exemplo de resposta: Sucesso

Exemplo de resposta: Erro

Próximos passos

Recursos adicionais