Atualizar a API de incidentes

  • Artigo

Aplica-se a:

Observação

Experimente nossas novas APIs usando a API de segurança do MS Graph. Saiba mais em: Usar 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 usando a API de segurança do MS Graph, consulte Atualizar incidente.

Importante

Algumas informações estão relacionadas a produtos pré-lançados que podem ser substancialmente modificados antes de seu lançamento comercial. A Microsoft não faz garantias, expressas ou implícitas, quanto às informações fornecidas aqui.

Descrição da API

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

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

  1. Você pode fazer até 50 chamadas por minuto ou 1.500 chamadas por hora antes de atingir o limite de limitação.
  2. Você só poderá definir a determination propriedade se classification estiver definida como TruePositive.

Se sua solicitação for limitada, ela retornará um código de 429 resposta. O corpo da resposta indica a hora em que você pode começar a fazer novas chamadas.

Permissões

Uma das seguintes permissões é necessária para chamar esta API. Para saber mais, incluindo como escolher permissões, consulte Acessar as APIs de Microsoft Defender XDR.

Tipo de permissão Permissão Nome da exibição de permissão
Application Incident.ReadWrite.All Ler e gravar todos os incidentes
Delegado (conta corporativa ou de estudante) Incident.ReadWrite Incidentes de leitura e gravação

Observação

Ao obter um token usando credenciais de usuário, o usuário precisa ter permissão para atualizar o incidente no portal.

Solicitação HTTP

PATCH /api/incidents/{id}

Cabeçalhos de solicitação

Nome Tipo Descrição
Autorização Cadeia de caracteres {token} de portador. Obrigatório.
Content-Type Cadeia de Caracteres application/json. Obrigatório.

Corpo da solicitação

No corpo da solicitação, forneça os valores para os campos que devem ser atualizados. As propriedades existentes que não estão incluídas no corpo da solicitação mantêm seus valores, a menos que precisem ser recalculadas devido a alterações nos valores relacionados. Para obter o melhor desempenho, você deve omitir valores existentes que não foram alterados.

Propriedade Tipo Descrição
status Enum Especifica o status atual do incidente. Os valores possíveis são: Active, Resolved, InProgress, e Redirected.
assignedTo string Proprietário do incidente.
classificação Enum Especificação do incidente. Os valores possíveis são: TruePositive (Verdadeiro positivo), InformationalExpectedActivity (atividade informativa, esperada) e FalsePositive (False Positive).
Determinação Enum Especifica a determinação do incidente.

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

  • Verdadeiro positivo: MultiStagedAttack (ataque multilocatário), MaliciousUserActivity (atividade de usuário mal-intencionado), CompromisedAccount (conta comprometida) – considere alterar o nome da enumeração na api pública de acordo, Malware (Malware), Phishing (Phishing), UnwantedSoftware (software indesejado) e Other (Outros).
  • Atividade informativa e esperada:SecurityTesting (Teste de segurança), LineOfBusinessApplication (aplicativo de linha de negócios), ConfirmedActivity (atividade confirmada) – considere alterar o nome da enumeração na api pública de acordo e Other (Outros).
  • Falso positivo:Clean (Não mal-intencionado) – considere alterar o nome da enumeração na api pública de acordo, NoEnoughDataToValidate (Não há dados suficientes para validar) e Other (Outros).
    		•
    tags lista de cadeias de caracteres Lista de marcas de incidente.
    comment string Comentário a ser adicionado ao incidente.

    Observação

    Por volta de 29 de agosto de 2022, os valores de determinação de alerta com suporte anterior ('Apt' e 'SecurityPersonnel') serão preteridos e não estarão mais disponíveis por meio da API.

    Resposta

    Se for bem-sucedido, esse método retornará 200 OK. O corpo da resposta contém a entidade de incidente com propriedades atualizadas. Se um incidente com a ID especificada não tiver sido encontrado, o método retornará 404 Not Found.

    Exemplo

    Exemplo de solicitação

    Aqui está um exemplo da solicitação.

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

    Exemplo de dados de solicitação

    {
    "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"
          }
      ]
}

    Dica

    Você deseja aprender mais? Engage com a comunidade de Segurança da Microsoft em nossa Comunidade Tecnológica: Microsoft Defender XDR Tech Community.