API de incidentes XDR do Microsoft Defender e o tipo de recurso incidentes

  • Artigo

Aplica-se a:

Observação

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.

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.

Um incidente é uma coleção de alertas relacionados que ajudam a descrever um ataque. Os eventos de diferentes entidades na sua organização são agregados automaticamente pelo Microsoft Defender XDR. Pode utilizar a API de incidentes para aceder programaticamente aos incidentes e alertas relacionados da sua organização.

Quotas e alocação de recursos

Pode pedir até 50 chamadas por minuto ou 1500 chamadas por hora. Cada método também tem as suas próprias quotas. Para obter mais informações sobre quotas específicas do método, veja o respetivo artigo para o método que pretende utilizar.

Um 429 código de resposta HTTP indica que atingiu uma quota, quer pelo número de pedidos enviados, quer pelo tempo de execução atribuído. O corpo da resposta inclui a hora até que a quota atingida seja reposta.

Permissões

A API de incidentes requer diferentes tipos de permissões para cada um dos seus métodos. Para obter mais informações sobre as permissões necessárias, veja o artigo do respetivo método.

Métodos

Método Tipo de retorno Descrição
Listar incidentes Lista de incidentes Obtenha uma lista de incidentes.
Atualizar incidente Incidente Atualizar um incidente específico.
Obter incidente Incidente Obtenha um único incidente.

Corpo do pedido, resposta e exemplos

Veja os respetivos artigos de método para obter mais detalhes sobre como construir um pedido ou analisar uma resposta e para obter exemplos práticos.

Propriedades comuns

Propriedade Tipo Descrição
incidentId long ID exclusivo do incidente.
redirectIncidentId Anulável longo O ID do Incidente ao qual o Incidente atual foi intercalado.
incidentName string O nome do Incidente.
createdTime DateTimeOffset A data e hora (em UTC) em que o Incidente foi criado.
lastUpdateTime DateTimeOffset A data e hora (em UTC) em que o Incidente foi atualizado pela última vez.
assignedTo string Proprietário do Incidente.
severity Enum Gravidade do Incidente. Os valores possíveis são: UnSpecified, , InformationalLow, , Mediume High.
status Enum Especifica o estado atual do incidente. Os valores possíveis são: Active, InProgress, Resolved, e Redirected.
classificação Enum Especificação do incidente. Os valores possíveis são: TruePositive, Informational, expected activitye FalsePositive.
determinação Enum Especifica a determinação do incidente.

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

  • Verdadeiro positivo: Multistage attack (MultiStagedAttack), Malicious user activity (MaliciousUserActivity), Compromised account (CompromisedUser) – considere alterar o nome da enumeração na API pública em conformidade, Malware (Malware), Phishing (Phishing), Unwanted software (UnwantedSoftware) e Other (Outro).
  • Atividade informativa e esperada:Security test (SecurityTesting), Line-of-business application (LineOfBusinessApplication), Confirmed activity (ConfirmedUserActivity) - considere alterar o nome da enumeração na API pública em conformidade, e Other (Outro).
  • Falso positivo:Not malicious (Limpo) – considere alterar o nome da enumeração na API pública em conformidade, Not enough data to validate (InsufficientData) e Other (Outro).
    		•
    tags lista de cadeias Lista de Etiquetas de incidentes (apenas etiquetas personalizadas).
    comentários Lista de comentários de incidentes O objeto Comentário do Incidente contém: cadeia de comentário, createdBy string e createTime date time.
    alertas lista de alertas Lista de alertas relacionados. Veja exemplos em Listar a documentação da API de incidentes .

    Observação

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

    Dica

    Você deseja aprender mais? Participe da comunidade de Segurança da Microsoft em nossa Tech Community: Tech Community do Microsoft Defender XDR.