Usar a API de segurança do Microsoft Graph
Importante
As APIs na versão /beta no Microsoft Graph estão sujeitas a alterações. Não há suporte para o uso dessas APIs em aplicativos de produção. Para determinar se uma API está disponível na v1.0, use o seletor Versão.
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. Ele capacita os clientes a simplificar as operações de segurança e se defender melhor contra o aumento das 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.
Ações (visualização)
Tome medidas imediatas para se defender contra ameaças usando a entidade securityAction . Quando um analista de segurança descobre um indicador novo, como um arquivo mal-intencionado, URL, domínio ou endereço IP, a proteção pode ser habilitada instantaneamente em suas soluções de segurança da Microsoft. Usar uma ação específica do provedor, ver todas as ações executadas e cancelar uma ação, se necessário. Experimente ações de segurança com o Microsoft Defender para Ponto de Extremidade (antigo Microsoft Defender ATP) para bloquear atividades mal-intencionadas nos seus pontos de extremidade com Windows usando propriedades vistas em alertas ou identificadas durante as investigações.
Observação: Ações de segurança no momento apenas oferecem suporte às permissões do aplicativo.
Busca avançada
A busca avançada é uma ferramenta de busca de ameaças baseada em consultas 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. Aproveite o conjunto de resultados retornado para enriquecer uma investigação existente ou descobrir ameaças não detectadas em sua rede.
Cotas e alocação de recursos
Você pode executar uma consulta em dados somente nos últimos 30 dias.
Os resultados incluem um máximo de 100.000 linhas.
O número de execuções é limitado por locatário:
- Chamadas de API: até 45 solicitações por minuto e até 1500 solicitações por hora.
- Tempo de execução: 10 minutos de tempo de execução a cada hora e 3 horas de tempo de execução por dia.
O tempo máximo de execução de uma única solicitação é de 200 segundos.
Um código de resposta de HTTP 429 significa que você atingiu a cota para o número de chamadas de API ou tempo de execução. Consulte o corpo da resposta para confirmar o limite atingido.
O tamanho máximo do resultado da consulta de uma única solicitação não pode exceder 124 MB. Exceder o limite de tamanho resulta em HTTP 400 Solicitação Incorreta com a mensagem "A execução de consulta excedeu o tamanho do resultado permitido. Otimize sua consulta limitando o número de resultados e tente novamente."
Detecções personalizadas
Você pode criar regras avançadas de detecção personalizadas específicas para suas operações de segurança para permitir que você monitore proativamente ameaças e tome medidas. Por exemplo, você pode fazer regras de detecção personalizadas que procuram indicadores conhecidos ou dispositivos configurados incorretamente. Eles disparam automaticamente alertas e todas as ações de resposta especificadas.
Cotas
- Obter várias regras: 10 regras por minuto por aplicativo, 300 regras por hora por aplicativo, 600 regras por hora por locatário
- Obter uma única regra: 100 regras por minuto por aplicativo, 1.500 regras por hora por aplicativo, 1.800 regras por hora por locatário
- Criar regra: 10 regras por minuto por aplicativo, 1.500 regras por hora por aplicativo, 1.800 regras por hora por locatário
- Regra de atualização: 100 regras por minuto por aplicativo, 1.500 regras por hora por aplicativo, 1.800 regras por hora por locatário
- Excluir regra: 100 regras por minuto por aplicativo, 1.500 regras por hora por aplicativo, 1.800 regras por hora por locatário
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 versão beta da 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 de respostas:
- Alertas e incidentes – 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.securitynamespace. - Alertas herdados – 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.graphnamespace.
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 e responder a ameaças coletivamente.
Os alertas dos seguintes provedores de segurança estão disponíveis por meio desses alertas e incidentes avançados:
- Microsoft Entra ID Protection
- Microsoft 365 Defender
- Microsoft Defender for Cloud Apps
- Microsoft Defender para Ponto de Extremidade
- Microsoft Defender para Identidade
- Obter o Microsoft Defender para Office 365
- Prevenção Contra Perda de Dados do Microsoft Purview
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.
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 seguintes provedores de segurança estão disponíveis por meio do recurso de alerta herdado. 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 | ✓ |
✓ |
|
| Central de Segurança do Azure | ✓ |
✓ |
✓ |
Microsoft 365
|
✓ |
||
| Microsoft Defender for Cloud Apps (antigo Microsoft Cloud App Security) | ✓ |
✓ |
|
| Microsoft Defender para Ponto de Extremidade (antigo Microsoft Defender ATP)** | ✓ |
✓ |
|
| Microsoft Defender para Identidade (antigo Azure Advanced Threat Protection)*** | ✓ |
✓ |
|
| 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 ter acesso aos 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 tiver ingressado em SecOps Unificados e conectado 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 (versão prévia)
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.
Consulta de logs de auditoria (versão prévia)
Auditoria do Microsoft Purview fornece uma solução integrada para ajudar as organizações a responder efetivamente a eventos de segurança, investigações forenses, investigações internas e obrigações de conformidade. Milhares de operações de usuário e de administrador realizadas em dezenas de serviços e soluções do Microsoft 365 são capturadas, registradas e retidas no log de auditoria unificado da sua organização. Os registros de auditoria para esses eventos podem ser pesquisados em sua organização por operadores de segurança, administradores de TI, equipes de risco internas e investigadores legais e de conformidade. Esse recurso fornece visibilidade das atividades realizadas em sua organização Microsoft 365.
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
Etiquetas - As Etiquetas de proteção de informações fornecem detalhes sobre como aplicar corretamente uma etiqueta de sensibilidade às informações. A API da etiquetas de proteção de informações descreve a configuração das etiquetas de sensibilidade que se aplicam a um usuário ou locatário.
Avaliação de riscos - 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 denunciem spam ou emails suspeitos, URLs de phishing ou anexos de malware que receberem para a Microsoft. A Microsoft verifica o exemplo em questão e as políticas organizacionais em jogo antes de gerar um resultado para que os administradores de locatários possam entender o veredicto de verificação de ameaças e ajustar sua política organizacional. Eles também podem usá-lo para denunciar emails legítimos para evitar que sejam bloqueados.
Nota: Recomendamos que você use a API de submissão de ameaças.
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 violação de segurança e permitir que seus funcionários compartilhem conhecimentos eficazes e ágeis que sejam atuais e relevantes para eles. 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 única classificação, é possível entender melhor o que você 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 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 será sua pontuação depois de adotar recursos de segurança.
Inteligência contra ameaças (versão prévia)
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 (versão prévia) 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, incluindo IoCs e veredictos de reputação e, por fim, dados de enriquecimento, incluindo DNS passivo, cookies, componentes e rastreadores.
Indicadores de inteligência contra ameaças (visualização)
Observação
A entidade tiIndicator está preterida e será removida até abril de 2026.
Os indicadores de ameaça também conhecidos como indicadores de comprometimento (IoCs), representam dados sobre ameaças conhecidas, como arquivos mal-intencionados, URLs, domínios e endereços IP. Os clientes podem gerar indicadores através da coleta interna de inteligência contra ameaças ou adquirir indicadores de comunidades de inteligência contra ameaças, feeds licenciados e outras fontes. Esses indicadores, em seguida, são usados nas várias ferramentas de segurança para proteger contra ameaças relacionadas.
A entidade tiIndicator permite que os clientes alimentem indicadores de ameaças a soluções de segurança da Microsoft para tomar um bloco ou uma ação de alerta sobre uma atividade mal-intencionada ou permitir que a atividade que foi determinada como irrelevante para a organização e suprime as ações para o indicador. Para enviar um indicador, especifique a solução de segurança da Microsoft destinada a utilizar o indicador e a ação a ser tomada para esse indicador.
Você pode integrar a entidade tiIndicator em seu aplicativo ou use uma das seguintes plataformas integradas de inteligência contra ameaças (DICA):
- Compartilhamento de inteligência contra Ameaças Palo Alto Networks
- Plataforma de inteligência contra ameaças de Código Aberto MISP disponíveis em exemplo IT
Os indicadores de ameaça enviados por meio da API de segurança do Microsoft Graph estão disponíveis hoje nos seguintes produtos:
- Microsoft Defender para Ponto de Extremidade – Permite que você alerte e/ou bloqueie indicadores de ameaça associados à atividade mal-intencionada. Você também pode permitir que um indicador ignore o indicador das investigações automatizadas. Para mais detalhes sobre os tipos de indicadores com suporte e limites de contagens de indicadores por locatário, confira Gerenciar indicadores.
- Microsoft Sentinel – somente clientes existentes podem usar a API tiIndicator para enviar indicadores de inteligência contra ameaças ao Microsoft Sentinel. Para obter as instruções mais atualizadas e detalhadas sobre como enviar indicadores inteligentes de ameaças ao Microsoft Sentinel, consulte Conectar sua plataforma de inteligência contra ameaças ao Microsoft Sentinel.
Envio de ameaça
A API de envio de ameaças do Microsoft Graph ajuda as organizações a enviar uma ameaça recebida por qualquer usuário em um locatário. Isso permite que os clientes denunciem spam ou emails suspeitos, URLs de phishing ou anexos de malware que receberem para a Microsoft. A Microsoft verifica o envio em relação às políticas organizacionais em vigor e o envia para avaliadores humanos para análise. O resultado ajuda os administradores de locatários a entender o veredicto de verificação de ameaças e ajustar sua política organizacional. Os administradores também podem usar os resultados para relatar emails legítimos para evitar que sejam bloqueados.
Nota: Recomendamos que você use a API de envio de ameaças em vez da API de avaliação de ameaças Proteção de Informações preterida. A API de envio de ameaças fornece funcionalidade unificada de envio de ameaças de segurança e adiciona suporte a resultados unificados, suporte a consultas de envio de usuários, suporte a lista de bloqueio de permissão de locatário, suporte a revisão de administrador e suporte ao modo somente aplicativo.
Email e proteção de colaboração (versão prévia)
Microsoft Defender para Office 365 é um serviço de filtragem de email baseado em nuvem que ajuda a proteger sua organização contra ameaças avançadas a ferramentas de email e colaboração, como phishing, compromisso de email comercial e ataques de malware. Você pode usar o Microsoft Graph analyzeemails e corrigir APIs para recuperar metadados de email e executar ações de resposta (exclusão suave, exclusão dura, mover para lixo eletrônico, passar para Caixa de Entrada) em mensagens analisadas.
Nota: Essas APIs são apenas um sucesso para Defender para Office 365 plano 2 ou Microsoft 365 A5/E5/F5/G5 Planos de serviço de segurança. Para obter a lista mais atualizada de planos de serviço, consulte Microsoft Defender para Office 365 descrição do serviço.
Identidades
Problemas de integridade
A API de problemas de integridade do Defender para Identidade permite que você monitore o status de integridade de seus sensores e agentes em sua infraestrutura de identidade híbrida. Você pode usar a API de problemas de integridade para recuperar informações sobre os problemas de integridade atuais de seus sensores, como o tipo de problema, status, configuração e gravidade. Você também pode usar a API para identificar e resolve quaisquer problemas que possam afetar a funcionalidade ou a segurança de seus sensores e agentes.
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.
Você pode usar webhooks do Microsoft Graph para assinar e receber notificações sobre atualizações para entidades de API de segurança do Microsoft Graph.
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:
- Analise alerts, tiIndicator (preview), securityAction (preview), secureScore e secureScoreControlProfiles.
- Experimente a API no Explorador do Graph. Em Consultas de Exemplo, escolha mostrar mais amostras e defina a categoria Segurança como on.
- Experimente assinar e receber notificações sobre alterações de entidade.
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:
- Conectores de segurança do Microsoft Graph para Aplicativos Lógicos, Fluxo e Power Apps
- Exemplos de bloco de anotações Jupyter
Participe da comunidade:
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários