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

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

alertas (recuperar informações de alerta)

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

de URI : ou

OBTER

parâmetros de consulta:

Nome	Descrição	Exemplo	Obrigatório/opcional
de estado	Obtenha apenas alertas manipulados ou sem tratamento. Valores com suporte: - 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 da época e no fuso horário UTC.	/api/v1/alerts?fromTime=<epoch>	Opcional
toTime	Obtenha alertas criados somente antes em um determinado momento, em milissegundos da época e no fuso horário UTC.	/api/v1/alerts?toTime=<epoch>	Opcional
siteId	O site no qual o alerta foi descoberto.	/api/v1/alerts?siteId=1	Opcional
zoneId	A zona na qual 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

Nota

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

Type: JSON

Uma lista de alertas com os seguintes campos:

Nome	Tipo	Anulável/ 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 de de tempo de época, no fuso horário UTC
título	Corda	Não anulável	-
de mensagem	Corda	Não anulável	-
de gravidade	Corda	Não anulável	Warning, Minor, Majorou Critical
do mecanismo	Corda	Não anulável	Protocol Violation, Policy Violation, Malware, Anomalyou Operational
sourceDevice	Numérico	Nullable	ID do dispositivo
destinationDevice	Numérico	Nullable	ID do dispositivo
remediationSteps	Corda	Nullable	Etapas de correção mostradas em alerta
additionalInformation	Objeto de informações adicionais	Nullable	-
manipulada	Booliano, estado do alerta	Não anulável	true ou false

campos de informações adicionais:

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

adicionado paraV2:

Nome	Tipo	Anulável/ Não anulável	Lista de valores
sourceDeviceAddress	Corda	Nullable	Endereço IP ou MAC
destinationDeviceAddress	Corda	Nullable	Endereço IP ou MAC
remediationSteps	Matriz JSON	Não anulável	Cadeias de caracteres, etapas de correção descritas em alerta
sensorName	Corda	Não anulável	Nome do sensor definido pelo usuário
zoneName	Corda	Não anulável	Nome da zona associada ao sensor
siteName	Corda	Não anulável	Nome do site associado ao sensor

Para obter mais informações, consulte referência de 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

da 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 na UUID)

Use essa API para executar uma ação especificada em um alerta específico detectado pelo Defender para 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 ao Microsoft Defender para IoT.

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

PÔR

Type: JSON

parâmetros de consulta:

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

parâmetros do corpo

Nome	Descrição	Exemplo	Obrigatório/opcional
de ação	Corda	handle ou handleAndLearn	Necessário

exemplo de solicitação

{
    "action": "handle"
}

Type: JSON

Matriz de objetos JSON que representam dispositivos.

campos de resposta:

Nome	Tipo	Obrigatório/opcional	Descrição
conteúdo/ de erro	Corda	Necessário	Se a solicitação for bem-sucedida, a propriedade de conteúdo será exibida. Caso contrário, a propriedade de erro será exibida.

Possíveis valores de conteúdo:

Código de status	Mensagem	Descrição
200	A solicitação de atualização de alerta foi 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á foi 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 de handledAndLearn.
200	O alerta já foi tratado (tratado). O identificador e o aprendizado (handleAndLearn) foram executados no alerta.	O alerta já foi tratado quando uma solicitação para handleAndLearn foi recebida. O alerta se torna handleAndLearn.
200	O alerta já foi tratado e aprendido (handleAndLearn). Solicitação de identificador ignorada.	O alerta já estava handleAndLearn quando uma solicitação para lidar com o alerta foi recebida. O alerta permanece handleAndLearn.
500	Ação inválida.	A ação enviada não é uma ação válida a ser executada no alerta.
500	Erro inesperado.	Ocorreu um erro inesperado. Para resolver o problema, entre em contato com o Suporte Técnico.
500	Não foi possível executar a solicitação porque nenhum alerta foi encontrado para essa UUID.	A UUID de alerta especificada não foi encontrada 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 janelas de manutenção, sob as quais os alertas não serão enviados. Use essa API para definir e atualizar os horários de parada e de início, dispositivos ou sub-redes que devem ser excluídos ao disparar alertas ou definir e atualizar os 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 para alertas de malware em dispositivos críticos.

As janelas de manutenção que definem 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

Essa API tem suporte apenas para fins de manutenção e por um período de tempo limitado e não deve ser usada em vez de regras de exclusão de alerta. Use essa API somente para operações de manutenção temporária única.

URI: /external/v1/maintenanceWindow

POSTAR

Cria uma nova janela de manutenção.

parâmetros do corpo :

Nome	Descrição	Exemplo	Obrigatório/opcional
ticketId	Corda. Define a ID do tíquete de manutenção nos sistemas do usuário. Verifique se a ID do tíquete não está vinculada a uma janela aberta existente.	2987345p98234	Necessário
ttl	Inteiro positivo. Define o TTL (tempo de vida útil), que é a duração da janela de manutenção, em minutos. Depois que o período de tempo definido for concluído, a janela de manutenção terminará e o sistema se comportará normalmente novamente.	180	Necessário
mecanismos	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 essas 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 das quais suprimir alertas 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 êxito.
400 (Solicitação Incorreta)	Sem TicketId	A solicitação de API não tinha um valor de ticketId.
400 (Solicitação Incorreta)	TTL ilegal	A solicitação de API incluiu um valor TTL não positivo ou não numérico.
400 (Solicitação Incorreta)	Não foi possível analisar a solicitação.	Problema ao analisar o corpo, como parâmetros incorretos ou valores inválidos.
400 (Solicitação Incorreta)	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)	A ID do tíquete já tem uma janela aberta.	A ID do tíquete está vinculada a outra janela de manutenção aberta.
500 (erro interno do servidor)	-	Qualquer outro erro inesperado.

Tipo: POST

da 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

EXCLUIR

Fecha uma janela de manutenção existente.

parâmetros de consulta:

Nome	Descrição	Exemplo	Obrigatório/opcional
ticketId	Define a ID do tíquete de manutenção nos sistemas do usuário. Verifique se a ID do tíquete está vinculada 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 (Solicitação Incorreta)	Sem TicketId	O parâmetro ticketId está ausente da solicitação.
404 (Não Encontrado):	Janela de manutenção não encontrada.	A ID do tíquete não está vinculada a uma janela de manutenção aberta.
500 (erro interno do servidor)	-	Qualquer outro erro inesperado.

Tipo: DELETE

da 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 abertos (POST), fechar (DELETE) e atualizar (PUT) ações que foram executadas usando essa API para lidar com janelas de manutenção. T

parâmetros de consulta:

Nome	Descrição	Exemplo	Obrigatório/opcional
fromDate	Filtra os logs da data predefinida e posterior. O formato é YYYY-MM-DD.	2022-08-10	Opcional
toDate	Filtra os logs até a data predefinida. O formato é YYYY-MM-DD.	2022-08-10	Opcional
ticketId	Filtra os logs relacionados a uma ID de tíquete específica.	9a5fe99c-d914-4bda-9332-307384fe40bf	Opcional
tokenName	Filtra os logs relacionados a um nome de token específico.	quarterly-sanity-window	Opcional

códigos de erro:

Código	Mensagem	Descrição
200	OKEY	A ação foi concluída com êxito.
204:	Sem conteúdo	Não há dados a serem mostrados.
400	Solicitação incorreta	O formato de data está incorreto.
500	Erro interno do servidor	Qualquer outro erro inesperado.

Type: JSON

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

estrutura de resposta:

Nome	Tipo	Anulável/ Não anulável	Lista de valores
de ID	Inteiro longo	Não anulável	Uma ID interna para o log atual
dateTime	Corda	Não anulável	A hora em que a atividade ocorreu, por exemplo: 2022-04-23T18:25:43.511Z
ticketId	Corda	Não anulável	A ID da janela de manutenção. Por exemplo: 9a5fe99c-d914-4bda-9332-307384fe40bf
tokenName	Corda	Não anulável	O nome do token da janela de manutenção. Por exemplo: quarterly-sanity-window
mecanismos	Matriz de cadeias de caracteres	Nullable	Os mecanismos nos quais a janela de manutenção se aplica, conforme fornecido durante a criação da janela de manutenção: Protocol Violation, Policy Violation, Malware, Anomalyou Operational
sensorIds	Matriz de cadeia de caracteres	Nullable	Os sensores nos quais a janela de manutenção se aplica, conforme fornecido durante a criação da janela de manutenção.
sub-redes	Matriz de cadeia de caracteres	Nullable	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	Nullable	TTL (Time to Live) da janela de manutenção, conforme fornecido durante a criação ou atualização da janela de manutenção.
operationType	Corda	Não anulável	Um dos seguintes valores: OPEN, UPDATEe CLOSE

Tipo: GET

da 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'

PÔR

Permite que você atualize 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 atualmente configurada. 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:

Nome	Descrição	Exemplo	Obrigatório/opcional
ticketId	Corda. Define a 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 êxito.
400 (Solicitação Incorreta)	Sem TicketId	A solicitação não tem um valor ticketId.
400 (Solicitação Incorreta)	TTL ilegal	O TTL definido não é numérico ou não é um inteiro positivo.
400 (Solicitação Incorreta)	Não foi possível analisar a solicitação	A solicitação não tem um valor de parâmetro ttl.
404 (não encontrado)	Janela de manutenção não encontrada	A ID do tíquete não está vinculada a uma janela de manutenção aberta.
500 (erro interno do servidor)	-	Qualquer outro erro inesperado.

Tipo: PUT

da 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 solicitação)

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

URI: /external/v2/alerts/

OBTER

parâmetros de consulta:

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

Type: JSON

Cadeia de caracteres de mensagem com os detalhes de 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 o token para a ID do xsense <number>	Erro ao obter o token do sensor para a ID do sensor especificada
500 (erro interno do servidor)	-	Qualquer outro erro inesperado.

Campos de dados

Nome	Tipo	Anulável/ Não anulável	Lista de valores
de ID	Numérico	Não anulável	A ID de alerta do console de gerenciamento local
xsenseId	Numérico	Não anulável	A ID do sensor
xsenseAlertId	Numérico	Não anulável	A ID de alerta do console do sensor
downloadUrl	Corda	Não anulável	A URL usada para baixar o arquivo PCAP
de token	Corda	Não anulável	O token do sensor, a ser usado ao baixar o arquivo 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'

Próximas etapas

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