Usar a API de segurança do Microsoft Graph

  • Artigo

A API de segurança do Microsoft Graph fornece uma interface e um esquema unificados para integrar com soluções de segurança da Microsoft e parceiros do ecossistema. Isso permite aos clientes agilizar as operações de segurança e a se proteger melhor contra as crescentes ameaças cibernéticas. A API de segurança do Microsoft Graph federa consultas a todos os provedores de segurança integrados e agrega respostas. Use a API de segurança do Microsoft Graph para criar aplicativos que:

  • Consolidar e correlacionar alertas de segurança de várias fontes.
  • Puxe e investigue todos os incidentes e alertas de serviços que fazem parte ou integrados ao Microsoft 365 Defender.
  • Desbloqueie dados contextuais para informar as investigações.
  • Automatizar tarefas de segurança, processos empresariais, fluxos de trabalho e relatórios.
  • Envie indicadores de ameaça para produtos da Microsoft para detecções personalizadas.
  • Invocar ações para em resposta a novas ameaças.
  • Forneça visibilidade dos dados de segurança para habilitar o gerenciamento proativo de riscos.

A API de segurança do Microsoft Graph fornece os principais recursos, conforme descrito nas seções a seguir.

Busca avançada

A caça avançada é uma ferramenta de busca de ameaças baseada em consulta que permite explorar até 30 dias de dados brutos. Você pode inspecionar proativamente os eventos na sua rede para localizar indicadores e entidades ameaçadoras.. O acesso flexível aos dados permite a busca irrestrita tanto por ameaças conhecidas como potenciais.

Use runHuntingQuery para executar uma consulta de Linguagem de Consulta Kusto (KQL) em dados armazenados no Microsoft 365 Defender. Use o conjunto de resultados retornado para enriquecer uma investigação existente ou para descobrir ameaças não detectadas em sua rede.

Cotas e alocação de recursos

As condições a seguir estão relacionadas a todas as consultas.

  1. As consultas exploram e retornam dados dos últimos 30 dias.
  2. Os resultados podem retornar até 100.000 linhas.
  3. Você pode fazer pelo menos 45 chamadas por minuto por locatário. O número de chamadas varia de acordo com o tamanho do locatário.
  4. Cada locatário é alocado recursos de CPU, com base no tamanho do locatário. As consultas serão bloqueadas se o locatário atingir 100% dos recursos alocados até depois do próximo ciclo de 15 minutos. Para evitar consultas bloqueadas devido ao consumo excessivo, siga as diretrizes em Otimizar suas consultas para evitar atingir cotas de CPU.
  5. Se uma única solicitação for executada por mais de três minutos, ela sairá e retornará um erro.
  6. Um 429 código de resposta HTTP indica que você alcançou os recursos de CPU alocados, por número de solicitações enviadas ou pelo tempo de execução alocado. Leia o corpo da resposta para entender o limite atingido.

Alertas

Alertas são avisos detalhados sobre atividades suspeitas no locatário de um cliente que os provedores de segurança da Microsoft ou parceiros identificaram e sinalizaram para a ação. Ataques normalmente empregam várias técnicas contra diferentes tipos de entidades, como dispositivos, usuários e caixas de correio. O resultado são alertas de vários provedores de segurança para várias entidades no locatário. Juntar os alertas individuais para obter informações sobre um ataque pode ser desafiador e demorado.

A API de segurança oferece dois tipos de alertas que agregam outros alertas de provedores de segurança e facilitam a análise de ataques e a determinação da resposta:

  • Alertas e incidentes - estas são a última geração de alertas na API de segurança do Microsoft Graph. Eles são representados pelo recurso de alerta e sua coleção, recurso de incidente , definido no microsoft.graph.security namespace.
  • Alertas herdados – estas são a primeira geração de alertas na API de segurança do Microsoft Graph. Eles são representados pelo recurso de alerta definido no microsoft.graph namespace.

Alertas e incidentes

Esses recursos de alerta primeiro puxam dados de alerta dos serviços do provedor de segurança, que fazem parte ou são integrados ao Microsoft 365 Defender. Em seguida, eles consomem os dados para retornar pistas ricas e valiosas sobre um ataque concluído ou contínuo, os ativos afetados e evidências associadas. Além disso, eles correlacionam automaticamente outros alertas com as mesmas técnicas de ataque ou o mesmo invasor em um incidente para fornecer um contexto mais amplo de um ataque. Eles recomendam ações de resposta e correção, oferecendo a capacidade de ação consistente em todos os diferentes provedores. O conteúdo rico torna mais fácil para os analistas investigar coletivamente e responder a ameaças.

Os alertas dos seguintes provedores de segurança estão disponíveis por meio desses alertas e incidentes avançados:

Alertas herdados

Observação

A API de alertas herdados está preterida e será removida até abril de 2026. Recomendamos que você migre para a nova API de alertas e incidentes .

Os recursos de alerta herdados federam a chamada de provedores de segurança do Azure e do Microsoft 365 Defender com suporte. Eles agregam dados de alerta comuns entre os diferentes domínios para permitir que os aplicativos unifiquem e agilizem o gerenciamento de problemas de segurança em todas as soluções integradas. Eles permitem que os aplicativos correlacionam alertas e contexto para melhorar a proteção e a resposta contra ameaças.

A versão herdada da API de segurança oferece o recurso de alerta que federa a chamada de provedores de segurança do Azure e do Microsoft 365 Defender com suporte. Esse recurso de alerta agrega dados de alerta comuns entre os diferentes domínios para permitir que os aplicativos unifiquem e agilizem o gerenciamento de problemas de segurança em todas as soluções integradas. Isso permite que os aplicativos correlacionam alertas e contexto para melhorar a proteção e a resposta contra ameaças.

Com o recurso de atualização de alerta, você pode sincronizar o status de alertas específicos em diferentes produtos e serviços de segurança integrados à API de segurança do Microsoft Graph atualizando sua entidade de alerta.

Os alertas dos provedores a seguir estão disponíveis por meio do recurso de alerta . O suporte para alertas GET, alertas PATCH e assinatura (via webhooks) é indicado na tabela a seguir.

Provedor de segurança

Alerta GET

Alerta PATCH

Assinar o alerta
Microsoft Entra ID Protection

✓

Problema de arquivo *

✓
Microsoft 365

✓

Problema de arquivo

Problema de arquivo

Microsoft Defender for Cloud Apps

✓

Problema de arquivo *

✓
Microsoft Defender para Ponto de Extremidade **

✓

✓

Problema de arquivo

Microsoft Defender para Identidade ***

✓

Problema de arquivo *

✓
Microsoft Sentinel (antigo Azure Sentinel)

✓

Não há suporte no Microsoft Sentinel

✓

Nota: Novos provedores estão continuamente integrando-se ao ecossistema de segurança do Microsoft Graph. Para solicitar novos provedores ou para obter suporte estendido de provedores existentes, registre um problema no repositório GitHub de segurança do Microsoft Graph.

* Problema de arquivo: o status de alerta é atualizado entre aplicativos integrados à API de segurança do Microsoft Graph, mas não refletido na experiência de gerenciamento do provedor.

** Microsoft Defender para Ponto de Extremidade requer funções de usuário adicionais às exigidas pela API de segurança do Microsoft Graph. Somente os usuários em funções de API de segurança do Microsoft Defender para Ponto de Extremidade e do Microsoft Graph podem acessar os dados Microsoft Defender para Ponto de Extremidade. A autenticação somente para aplicativos não é limitada por isso. Portanto, recomendamos que você use um token de autenticação somente para aplicativos.

Microsoft Defender para Identidade alertas estão disponíveis por meio da integração Microsoft Defender para Aplicativos de Nuvem. Isso significa que você só receberá alertas Microsoft Defender para Identidade se ingressou em SecOps Unificados e conectou Microsoft Defender para Identidade em Microsoft Defender para Aplicativos de Nuvem. Saiba mais sobre como integrar o Microsoft Defender para Identidade com o Microsoft Defender for Cloud Apps.

Treinamento e simulação de ataque

Simulação de ataque e treinamento é parte do Microsoft Defender para Office 365. Esse serviço permite que os usuários em um locatário experimentem um ataque de phishing benigno realista e aprendam com ele. Simulação de engenharia social e experiências de treinamento para usuários finais ajudam a reduzir o risco de usuários serem violados por meio dessas técnicas de ataque. A API de simulação e treinamento de ataque permite que os administradores de locatário visualizem os exercícios e treinamentos de simulação lançados e obtenham relatórios sobre os insights derivados dos comportamentos online dos usuários nas simulações de phishing.

Descoberta eletrônica

O Microsoft Purview eDiscovery (Premium) fornece um fluxo de trabalho de ponta a ponta para preservar, coletar, analisar, revisar e exportar conteúdo que responde às investigações internas e externas de sua organização.

Incidentes

Um incidente é uma coleção de alertas correlacionados e dados associados que compõem a história de um ataque. O gerenciamento de incidentes faz parte do Microsoft 365 Defender e está disponível no portal do Microsoft 365 Defender (https://security.microsoft.com/).

Os serviços e aplicativos do Microsoft 365 criam alertas quando detectam um evento ou atividade suspeito ou mal-intencionado. Alertas individuais fornecem dicas valiosas sobre um ataque concluído ou contínuo. No entanto, os ataques geralmente empregam várias técnicas contra diferentes tipos de entidades, como dispositivos, usuários e caixas de correio. O resultado são vários alertas para várias entidades em seu locatário.

Como juntar os alertas individuais para obter informações sobre um ataque pode ser desafiador e demorado, o Microsoft 365 Defender agrega automaticamente os alertas e suas informações associadas a um incidente.

Agrupar alertas relacionados a um incidente oferece uma visão abrangente de um ataque. Por exemplo, você poderá ver:

  • Onde o ataque foi iniciado.
  • Quais táticas foram usadas.
  • Até que ponto o ataque afetou o locatário.
  • O escopo do ataque, como quantos dispositivos, usuários e caixas de correio foram afetados.
  • Todos os dados associados ao ataque.

O recurso do incidente e suas APIs permitem classificar por meio de incidentes para criar uma resposta de segurança cibernética informada. Ele expõe uma coleção de incidentes, com seus alertas relacionados, que foram sinalizados em sua rede, dentro do intervalo de tempo especificado em sua política de retenção de ambiente.

Proteção de informações

A API de avaliação de ameaças do Microsoft Graph ajuda as organizações a avaliar a ameaça recebida por qualquer usuário em um locatário. Isso permite que os clientes relatem emails de spam, URLs de phishing ou anexos de malware recebidos na Microsoft. Os resultados da verificação de política e os resultados ao verificar novamente, podem ajudar os administradores de locatários a entender o veredicto da verificação de ameaças e ajustar sua política organizacional.

Gerenciamento de registros

A maioria das organizações precisa gerenciar dados para cumprir proativamente as regulamentações e políticas internas do setor, reduzir o risco em caso de litígio ou uma violação de segurança e permitir que as pessoas compartilhem conhecimentos eficazes e ágeis que sejam atuais e relevantes para elas. Você pode usar as APIs de gerenciamento de registros para aplicar sistematicamente rótulos de retenção a diferentes tipos de conteúdo que exigem configurações de retenção diferentes. Por exemplo, você pode configurar o início do período de retenção de quando o conteúdo foi criado, modificado pela última vez, rotulado ou quando ocorre um evento para um determinado tipo de evento. Além disso, você pode usar descritores de plano de arquivo para melhorar a capacidade de gerenciamento desses rótulos de retenção.

Classificação de Segurança

A Microsoft Secure Score é uma solução de análise da segurança que fornece visibilidade ao seu portfólio de segurança e mostra como melhorá-lo. Com uma pontuação única, você pode entender melhor o que fez para reduzir o risco em soluções da Microsoft. Você pode também comparar sua classificação com outras organizações e ver como tem sido a tendência ao longo do tempo. As entidades secureScore e secureScoreControlProfile de segurança do Microsoft Graph ajudam você a equilibrar as necessidades de segurança e produtividade da sua organização, permitindo a combinação apropriada de recursos de segurança. Você também pode projetar qual seria sua classificação depois de adotar recursos de segurança.

Inteligência contra ameaças

Informações sobre Ameaças do Microsoft Defender fornece inteligência contra ameaças de classe mundial para ajudar a proteger sua organização contra ameaças cibernéticas modernas. Você pode usar a Inteligência contra Ameaças para identificar adversários e suas operações, acelerar a detecção e a correção e aprimorar seus investimentos e fluxos de trabalho de segurança.

As APIs de inteligência contra ameaças permitem operacionalizar a inteligência encontrada na interface do usuário. Isso inclui inteligência final nas formas de artigos e perfis intel, inteligência de máquina, como IoCs e veredictos de reputação, e dados de enriquecimento, como DNS passivo, cookies, componentes e rastreadores.

Casos de uso comuns

A seguir estão algumas das solicitações mais populares para trabalhar com a API de segurança do Microsoft Graph.

Casos de uso Recursos REST Experimentar no Explorador do Graph
Atualizar perfis de controle da classificação de segurança Atualizar secureScoreControlProfile https://graph.microsoft.com/v1.0/security/secureScoreControlProfiles/{id}
Alertas e incidentes
Listar alertas List alerts https://graph.microsoft.com/v1.0/security/alerts_v2
Atualizar alerta Atualizar alertas https://graph.microsoft.com/v1.0/security/alerts/{id}
Listar incidentes Listar incidentes https://graph.microsoft.com/v1.0/security/incidents
Listar incidentes com alertas Listar incidentes https://graph.microsoft.com/v1.0/security/incidents?$expand=alertas
Atualizar incidente Atualizar incidente https://graph.microsoft.com/v1.0/security/incidents/{id}
Descoberta eletrônica
Listar casos de Descoberta Eletrônica Listar eDiscoveryCases https://graph.microsoft.com/v1.0/security/cases/eDiscoveryCases
Listar operações de caso de Descoberta Eletrônica Listar caseOperations https://graph.microsoft.com/v1.0/security/cases/ediscoveryCases/{id}/operations
Alertas herdados
Listar alertas List alerts https://graph.microsoft.com/v1.0/security/alerts
Atualizar alertas Atualizar alertas https://graph.microsoft.com/v1.0/security/alerts/{alert-id}
Classificações de segurança
Listar classificações de segurança Listar secureScores https://graph.microsoft.com/v1.0/security/secureScores
Obter classificação de segurança Obter secureScore https://graph.microsoft.com/v1.0/security/secureScores/{id}
Listar perfis de controle da classificação de segurança Listar secureScoreControlProfiles https://graph.microsoft.com/v1.0/security/secureScoreControlProfiles
Obter perfis de controle da classificação de segurança Obter secureScoreControlProfile https://graph.microsoft.com/v1.0/security/secureScoreControlProfiles/{id}

Você pode usar webhooks do Microsoft Graph para assinar e receber notificações sobre atualizações para entidades de segurança do Microsoft Graph.

Recursos

Código e contribua para estes exemplos de API de segurança do Microsoft Graph:

Participe da comunidade:

Próximas etapas

A API de segurança do Microsoft Graph pode abrir novas maneiras de você se envolver com diferentes soluções de segurança da Microsoft e parceiros. Siga estas etapas para iniciar:

Conteúdo relacionado

Código e contribui para este exemplo de API de segurança do Microsoft Graph:

Explore outras opções para se conectar à API de segurança do Microsoft Graph:

Participe da comunidade: