Utilizar 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 esquema unificados para integrar com soluções de segurança da Microsoft e parceiros de ecossistema. Permite que os clientes simplifiquem as operações de segurança e se defendam melhor contra o aumento das ameaças cibernéticas. A API de segurança do Microsoft Graph federa consultas a todos os fornecedores de segurança integrados e agrega respostas. Utilize a API de segurança do Microsoft Graph para criar aplicações que:
- Consolidar e correlacionar alertas de segurança de várias origens.
- Extraia e investigue todos os incidentes e alertas de serviços que fazem parte ou integrados no Microsoft 365 Defender.
- Desbloqueie dados contextuais para informar as investigações.
- Automatizar tarefas de segurança, processos de negócio, fluxos de trabalho e relatórios.
- Enviar indicadores de ameaças para produtos Microsoft para deteções personalizadas.
- Invocar ações para em resposta a novas ameaças.
- Forneça visibilidade sobre os dados de segurança para ativar a gestão proativa de riscos.
A API de segurança do Microsoft Graph fornece as principais funcionalidades, conforme descrito nas secções seguintes.
Ações (visualização)
Tome medidas imediatas para se defender contra ameaças com 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.
Utilize runHuntingQuery para executar uma consulta Linguagem de Consulta Kusto (KQL) em dados armazenados no Microsoft 365 Defender. Tire partido do conjunto de resultados devolvido para enriquecer uma investigação existente ou descobrir ameaças não detetadas na sua rede.
Quotas e alocação de recursos
Só pode executar uma consulta em dados dos últimos 30 dias.
Os resultados incluem um máximo de 100 000 linhas.
O número de execuções é limitado por inquilino:
- Chamadas à API: até 45 pedidos por minuto e até 1500 pedidos 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 um único pedido é de 200 segundos.
Um código de resposta de HTTP 429 significa que atingiu a quota para o número de chamadas à API ou o tempo de execução. Veja o corpo da resposta para confirmar o limite que atingiu.
O tamanho máximo do resultado da consulta de um único pedido não pode exceder os 124 MB. Exceder o limite de tamanho resulta num Pedido Incorreto HTTP 400 com a mensagem "A execução da consulta excedeu o tamanho permitido do resultado. Otimize a consulta ao limitar o número de resultados e tente novamente."
Detecções personalizadas
Pode criar regras de deteção personalizadas de investigação avançadas específicas das suas operações de segurança para permitir que monitorize proativamente ameaças e tome medidas. Por exemplo, pode criar regras de deteção personalizadas que procuram indicadores conhecidos ou dispositivos configurados incorretamente. Estes acionam automaticamente alertas e quaisquer ações de resposta que especificar.
Cotas
- Obter várias regras: 10 regras por minuto por aplicação, 300 regras por hora por aplicação, 600 regras por hora por inquilino
- Obter uma única regra: 100 regras por minuto por aplicação, 1500 regras por hora por aplicação, 1800 regras por hora por inquilino
- Criar regra: 10 regras por minuto por aplicação, 1500 regras por hora por aplicação, 1800 regras por hora por inquilino
- Regra de atualização: 100 regras por minuto por aplicação, 1500 regras por hora por aplicação, 1800 regras por hora por inquilino
- Eliminar regra: 100 regras por minuto por aplicação, 1500 regras por hora por aplicação, 1800 regras por hora por inquilino
Alertas
Os alertas são avisos detalhados sobre atividades suspeitas no inquilino de um cliente que a Microsoft ou os fornecedores de segurança parceiros identificaram e sinalizaram para ação. Normalmente, os ataques utilizam várias técnicas em relação a diferentes tipos de entidades, como dispositivos, utilizadores e caixas de correio. O resultado são alertas de vários fornecedores de segurança para várias entidades no inquilino. Juntar os alertas individuais para obter informações sobre um ataque pode ser desafiante e moroso.
A versão beta da API de segurança oferece dois tipos de alertas que agregam outros alertas de fornecedores de segurança e facilitam a análise de ataques e a determinação das respostas:
-
Alertas e incidentes – a última geração de alertas na API de segurança do Microsoft Graph. São representados pelo recurso de alerta e pela respetiva coleção, recurso de incidente , definido no
microsoft.graph.securityespaço de nomes. -
Alertas legados – a primeira geração de alertas na API de segurança do Microsoft Graph. São representados pelo recurso de alerta definido no
microsoft.graphespaço de nomes.
Alertas e incidentes
Estes recursos de alerta extraem primeiro dados de alerta dos serviços do fornecedor de segurança, que fazem parte ou estão integrados no Microsoft 365 Defender. Em seguida, consomem os dados para devolver pistas valiosas e ricas sobre um ataque concluído ou contínuo, os recursos afetados e as provas associadas. Além disso, correlacionam automaticamente outros alertas com as mesmas técnicas de ataque ou o mesmo atacante num incidente para fornecer um contexto mais amplo de um ataque. Recomendam ações de resposta e remediação, oferecendo uma ação consistente em todos os diferentes fornecedores. O conteúdo formatado torna mais fácil para os analistas investigar e responder a ameaças coletivamente.
Os alertas dos seguintes fornecedores de segurança estão disponíveis através destes 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 legados
Observação
A API de alertas legados foi preterida e será removida até abril de 2026. Recomendamos que migre para a nova API de alertas e incidentes .
Os recursos de alerta legados federam chamadas de fornecedores de segurança suportados do Azure e do Microsoft 365 Defender. Agregam dados de alerta comuns entre os diferentes domínios para permitir que as aplicações unifiquem e simplifiquem a gestão de problemas de segurança em todas as soluções integradas. Permitem que as aplicações correlacionem alertas e contexto para melhorar a proteção e resposta a ameaças.
Com a capacidade de atualização de alertas, pode sincronizar a status de alertas específicos em diferentes produtos e serviços de segurança integrados com a API de segurança do Microsoft Graph ao atualizar a entidade de alerta.
Os alertas dos seguintes fornecedores de segurança estão disponíveis através do recurso de alerta legado. O suporte para alertas GET, alertas patch e subscrição (através de webhooks) é indicado na tabela seguinte.
| 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 (anteriormente Sentinel do Azure) | ✓ |
Não suportado no Microsoft Sentinel |
✓ |
Nota: Os novos fornecedores estão continuamente a integrar no ecossistema de segurança do Microsoft Graph. Para pedir novos fornecedores ou suporte alargado a fornecedores existentes, registe um problema no repositório gitHub de segurança do Microsoft Graph.
* Problema de ficheiro: os status de alertas são atualizados em aplicações integradas da API de segurança do Microsoft Graph, mas não são refletidas na experiência de gestão do fornecedor.
** Microsoft Defender para Ponto de Extremidade requer funções de utilizador adicionais para as necessárias pela API de segurança do Microsoft Graph. Apenas os utilizadores nas funções Microsoft Defender para Ponto de Extremidade e da API de segurança do Microsoft Graph podem ter acesso aos dados Microsoft Defender para Ponto de Extremidade. Uma vez que a autenticação apenas de aplicação não está limitada, recomendamos que utilize um token de autenticação apenas de aplicação.
Microsoft Defender para Identidade alertas estão disponíveis através da integração do Microsoft Defender para Aplicativos de Nuvem. Isto significa que só recebe alertas de Microsoft Defender para Identidade se tiver aderido ao Unified SecOps e ligado Microsoft Defender para Identidade ao 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.
Consulta de registo de auditoria (pré-visualização)
Auditoria do Microsoft Purview fornece uma solução integrada para ajudar as organizações a responder eficazmente 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.
Identidades
Problemas de estado de funcionamento
A API Microsoft Defender para Identidade problemas de estado de funcionamento permite-lhe monitorizar a status de estado de funcionamento dos sensores e agentes na infraestrutura de identidade híbrida. Pode utilizar a API de problemas de estado de funcionamento para obter informações sobre os problemas de estado de funcionamento atuais dos sensores, como o tipo de problema, status, configuração e gravidade. Também pode utilizar a API para identificar e resolve quaisquer problemas que possam afetar a funcionalidade ou segurança dos sensores e agentes.
Nota: A API Microsoft Defender para Identidade problemas de estado de funcionamento só está disponível no plano do Defender para Identidade ou Microsoft 365 E5/Planos de serviço de Segurança A5/G5/F5.
Sensores
A API de gestão de sensores do Defender para Identidade permite-lhe criar relatórios detalhados dos sensores na área de trabalho, incluindo informações sobre o nome do servidor, versão do sensor, tipo, estado e status de estado de funcionamento. Também lhe permite gerir as definições do sensor, como adicionar descrições, ativar ou desativar atualizações atrasadas e especificar o controlador de domínio ao qual o sensor se liga para consultar o Entra ID.
Incidentes
Um incidente é uma coleção de alertas correlacionados e dados associados que compõem a história de um ataque. A gestão 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.
Uma vez que juntar os alertas individuais para obter informações sobre um ataque pode ser desafiante e moroso, o Microsoft 365 Defender agrega automaticamente os alertas e as respetivas 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. Expõe uma coleção de incidentes, com os respetivos alertas relacionados, que foram sinalizados na sua rede, dentro do intervalo de tempo que especificou na política de retenção do 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 inquilinos possam compreender o veredicto de análise de ameaças e ajustar a 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 de gerir dados para cumprir proativamente os regulamentos do setor e as políticas internas, reduzir o risco em caso de litígio ou uma falha de segurança e permitir que os seus funcionários partilhem de forma eficaz e ágil conhecimentos que lhes são atuais e relevantes. Pode utilizar as APIs de gestão de registos para aplicar sistematicamente etiquetas de retenção a diferentes tipos de conteúdo que requerem definições de retenção diferentes. Por exemplo, pode configurar o início do período de retenção a partir do momento em que o conteúdo foi criado, modificado pela última vez, etiquetado ou quando ocorre um evento para um determinado tipo de evento. Além disso, pode utilizar descritores de planos de ficheiros para melhorar a capacidade de gestão destas etiquetas 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-no a equilibrar as necessidades de segurança e produtividade da sua organização, ao mesmo tempo que permitem a combinação adequada de funcionalidades de segurança. Também pode projetar qual será a sua classificação depois de adotar as funcionalidades de segurança.
Informações sobre ameaças (pré-visualização)
Informações sobre Ameaças do Microsoft Defender fornece informações sobre ameaças de classe mundial para ajudar a proteger a sua organização contra ameaças cibernéticas modernas. Pode utilizar as Informações sobre Ameaças para identificar adversários e as respetivas operações, acelerar a deteção e a remediação e melhorar os seus investimentos e fluxos de trabalho de segurança.
As APIs de informações sobre ameaças (pré-visualização) permitem-lhe operacionalizar as informações encontradas na interface de utilizador. Isto inclui informações concluídas nas formas de artigos e perfis de informações, machine intelligence, incluindo IoCs e veredictos de reputação e, por fim, dados de melhoramento, incluindo DNS passivo, cookies, componentes e rastreadores.
Indicadores de inteligência contra ameaças (visualização)
Observação
A entidade tiIndicator foi preterida e será removida até abril de 2026.
Os indicadores de ameaças também referidos como indicadores de compromisso (IoCs), representam dados sobre ameaças conhecidas, tais como ficheiros maliciosos, 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 efetuar uma ação de bloqueio ou alerta sobre uma atividade maliciosa ou permitir que a atividade que foi determinada seja irrelevante para a organização e suprimir 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 tomar 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ças enviados através da API de segurança do Microsoft Graph estão disponíveis atualmente nos seguintes produtos:
- Microsoft Defender para Ponto de Extremidade – permite-lhe alertar e/ou bloquear indicadores de ameaças associados a atividades maliciosas. 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 – apenas os clientes existentes podem utilizar a API tiIndicator para enviar indicadores de informações sobre ameaças para Microsoft Sentinel. Para obter as instruções detalhadas mais atualizadas sobre como enviar indicadores inteligentes de ameaças para Microsoft Sentinel, consulte Ligar a plataforma de informações sobre ameaças a 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 utilize a API de submissão de ameaças em vez da API de avaliação de ameaças preterida Proteção de Informações. 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.
proteção de colaboração e Email
Microsoft Defender para Office 365 é um serviço de filtragem de e-mail baseado na cloud que ajuda a proteger a sua organização contra ameaças avançadas a ferramentas de e-mail e colaboração, como phishing, comprometimento de e-mail empresarial e ataques de software maligno. Pode utilizar os e-mails analisados do Microsoft Graph e remediar APIs para obter metadados de e-mail e efetuar ações de resposta (eliminação recuperável, eliminação dura, mover para lixo, mover para a Caixa de Entrada) em mensagens analisadas.
Nota: Estas APIs só estão disponíveis 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 dos planos de serviço, veja Microsoft Defender para Office 365 descrição do serviço.
Sensores
A API de gestão de sensores do Defender para Identidade permite-lhe criar relatórios detalhados dos sensores na área de trabalho, incluindo informações sobre o nome do servidor, versão do sensor, tipo, estado e status de estado de funcionamento. Também lhe permite gerir as definições do sensor, como adicionar descrições, ativar ou desativar atualizações atrasadas e especificar o controlador de domínio ao qual o sensor se liga para consultar o Entra ID.
Casos de uso comuns
Seguem-se alguns dos pedidos mais populares para trabalhar com a API de segurança do Microsoft Graph.
Pode utilizar webhooks do Microsoft Graph para subscrever e receber notificações sobre atualizações a entidades da API de segurança do Microsoft Graph.
Próximas etapas
A API de segurança do Microsoft Graph pode abrir novas formas de interagir 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
Codize e contribua para este exemplo da API de segurança do Microsoft Graph:
Explore outras opções para se ligar à API de segurança do Microsoft Graph:
- Conectores de segurança do Microsoft Graph para Logic Apps, Flow e Power Apps
- Exemplos de bloco de anotações Jupyter
Participe da comunidade: