Atualizar a API de incidentes

  • Artigo

Aplica-se a:

Nota

Experimente as nossas novas APIs com a API de segurança do MS Graph. Saiba mais em: Utilizar a API de segurança do Microsoft Graph – Microsoft Graph | Microsoft Learn. Para obter informações sobre a nova API de incidentes de atualização com a API de segurança do MS Graph, veja Atualizar incidente.

Importante

Algumas informações estão relacionadas com o produto pré-lançado que pode ser substancialmente modificado antes de ser lançado comercialmente. A Microsoft não oferece garantias, expressas ou implícitas, em relação às informações aqui fornecidas.

Descrição da API

Atualizações propriedades do incidente existente. As propriedades atualizáveis são: status, determination, classification, assignedTo, tagse comments.

Quotas, alocação de recursos e outras restrições

  1. Pode fazer até 50 chamadas por minuto ou 1500 chamadas por hora antes de atingir o limiar de limitação.
  2. Só pode definir a determination propriedade se classification estiver definida como TruePositive.

Se o pedido for limitado, devolve um 429 código de resposta. O corpo da resposta indica a hora em que pode começar a fazer novas chamadas.

Permissões

É necessária uma das seguintes permissões para chamar esta API. Para saber mais, incluindo como escolher permissões, veja Aceder às APIs Microsoft Defender XDR.

Tipo de permissão Permissão Nome a apresentar da permissão
Aplicação Incident.ReadWrite.All Ler e escrever todos os incidentes
Delegado (conta escolar ou profissional) Incident.ReadWrite Incidentes de leitura e escrita

Nota

Ao obter um token com credenciais de utilizador, o utilizador tem de ter permissão para atualizar o incidente no portal.

Pedido HTTP

PATCH /api/incidents/{id}

Cabeçalhos de pedido

Name Tipo Descrição
Autorização Cadeia Portador {token}. Obrigatório.
Tipo de Conteúdo Cadeia application/json. Obrigatório.

Corpo do pedido

No corpo do pedido, forneça os valores para os campos que devem ser atualizados. As propriedades existentes que não estão incluídas no corpo do pedido mantêm os respetivos valores, a menos que tenham de ser recalculadas devido a alterações a valores relacionados. Para um melhor desempenho, deve omitir valores existentes que não foram alterados.

Propriedade Tipo Descrição
estado Enumeração Especifica o estado atual do incidente. Os valores possíveis são: Active, Resolved, InProgresse Redirected.
atribuído A cadeia Proprietário do incidente.
classificação Enumeração Especificação do incidente. Os valores possíveis são: TruePositive (Verdadeiro positivo), InformationalExpectedActivity (Informativo, atividade esperada) e FalsePositive (Falso Positivo).
determinação Enumeração Especifica a determinação do incidente.

Os valores de determinação possíveis para cada classificação são:

  • Verdadeiro positivo: MultiStagedAttack (Ataque multicamada), MaliciousUserActivity (Atividade de utilizador malicioso), CompromisedAccount (Conta comprometida) – considere alterar o nome da enumeração na API pública em conformidade, Malware (Software Maligno), Phishing (Phishing), UnwantedSoftware (Software indesejável) e Other (Outro).
  • Atividade informativa e esperada:SecurityTesting (Teste de segurança), LineOfBusinessApplication (Aplicação de linha de negócio), ConfirmedActivity (Atividade confirmada) – considere alterar o nome da enumeração na API pública em conformidade e Other (Outro).
  • Falso positivo:Clean (Não malicioso) – considere alterar o nome da enumeração na API pública em conformidade ( NoEnoughDataToValidate Não existem dados suficientes para validar) e Other (Outro).
    		•
    etiquetas lista de cadeias Lista de Etiquetas de incidentes.
    comentário cadeia Comentário a adicionar ao incidente.

    Nota

    Por volta de 29 de agosto de 2022, os valores de determinação de alertas anteriormente suportados ("Apt" e "Pessoal de Segurança") serão preteridos e deixarão de estar disponíveis através da API.

    Resposta

    Se for bem-sucedido, este método devolve 200 OK. O corpo da resposta contém a entidade do incidente com propriedades atualizadas. Se não for encontrado um incidente com o ID especificado, o método devolve 404 Not Found.

    Exemplos:

    Exemplo de pedido

    Eis um exemplo do pedido.

     PATCH https://api.security.microsoft.com/api/incidents/{id}

    Exemplo de dados de pedido

    {
    "status": "Resolved",
    "assignedTo": "secop2@contoso.com",
    "classification": "TruePositive",
    "determination": "Malware",
    "tags": ["Yossi's playground", "Don't mess with the Zohan"],
    "comments": [
          {
              "comment": "pen testing",
              "createdBy": "secop2@contoso.com",
              "createdTime": "2021-05-02T09:34:21.5519738Z"
          },
          {
              "comment": "valid incident",
              "createdBy": "secop2@contoso.comt",
              "createdTime": "2021-05-02T09:36:27.6652581Z"
          }
      ]
}

    Sugestão

    Quer saber mais? Interaja com a comunidade do Microsoft Security na nossa Tech Community: Microsoft Defender XDR Tech Community.