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 de versão.

A API de Segurança do Microsoft Graph fornece uma interface unificada e um esquema para integrar soluções de segurança da Microsoft e parceiros de 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 consulta todos os provedores de segurança integrados e agrega respostas. Use a API de Segurança do Microsoft Graph para compilar aplicativos que:

• Consolidem e correlacionem alertas de segurança de várias fontes
• Desbloqueiem dados contextuais para informar investigações
• Automatizem tarefas de segurança, processos de negócios, fluxos de trabalho e relatórios
• Enviem indicadores de ameaças para produtos da Microsoft para detecções personalizados
• Usem ações em resposta à novas ameaças
• Dão visibilidade aos dados de segurança para permitir o gerenciamento proativo dos riscos

A API de Segurança do Microsoft Graph inclui as entidades principais a seguir.

Ações (visualização)

Executar uma ação imediata proteger contra ameaças usando a entidade securityActionde Segurança do Microsoft Graph. 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.

Alertas

Os alertas são possíveis problemas de segurança no locatário de um cliente identificado pela Microsoft ou por soluções de segurança de parceiros identificados e sinalizados para ação ou notificação. Com a entidade de alertas de Segurança do Microsoft Graph, é possível unificar e simplificar o gerenciamento dos problemas de segurança de todas as soluções integradas. Isso também permite que os aplicativos correlacionem alertas e contextos para melhorar a resposta e a proteção contra ameaças. Com o recurso de atualização de alertas, é possível sincronizar o status de alertas específicos em diferentes produtos e serviços de segurança que estão integrados à API de Segurança do Microsoft Graph atualizando sua entidade de alertas.

Alertas dos seguintes provedores estão disponíveis por meio da API de segurança do Microsoft Graph. O suporte para alertas GET, alertas PATCH e inscrições (via webhooks) é indicado na tabela a seguir.

Provedor de segurança	Alerta GET	Alerta PATCH	Assinar o alerta
Central de Segurança do Azure	✓	✓	✓
Proteção de identidade do Azure Active Directory	✓	Problema de arquivo *	✓
Microsoft Defender for Cloud Apps (antigo Microsoft Cloud App Security)	✓	Problema de arquivo *	✓
Microsoft Defender para Ponto de Extremidade (antigo Microsoft Defender ATP)**	✓	✓	Problema de arquivo
Microsoft Defender para Identidade (antigo Azure Advanced Threat Protection)***	✓	Problema de arquivo *	✓
Microsoft 365 Padrão Segurança no Aplicativo na Nuvem Alerta personalizado	✓	Problema de arquivo	Problema de arquivo
Proteção de Informações do Azure (visualização)	✓	Problema de arquivo *	✓
Azure Sentinel (visualização)	✓	Não possui suporte do Azure Sentinel	✓

Observação: Novos provedores estão se integrando continuamente ao ecossistema de Segurança do Microsoft Graph. Para requerer suporte aos novos provedores ou suporte estendido para os provedores existentes, registre o problema no repositório GitHub de segurança do Microsoft Graph.

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

** O Microsoft Defender para Ponto de Extremidade exige funções de usuário adicionais para aquelas requeridas pela API de Segurança do Microsoft Graph. Somente os usuários do Microsoft Defender para Ponto de Extremidade e as funções da API de Segurança do Microsoft Graph podem ter acesso aos dados do 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.

*** Os alertas do Microsoft Defender para Identidade estão disponíveis por meio da integração com o Microsoft Defender for Cloud Apps. Isso significa que você receberá alertas do Microsoft Defender para Identidade somente se tiver ingressado no portal Unified SecOps e conectado o Microsoft Defender para Identidade com o Microsoft Defender for Cloud Apps. Saiba mais sobre como integrar o Microsoft Defender para Identidade com o Microsoft Defender for Cloud Apps.

Simulação de ataque e treinamento (visualização)

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.

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.

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 de Segurança do Microsoft Graph ajudam a equilibrar a segurança e a produtividade de que sua organização precisa, além de habilitar o mix adequado de recursos de segurança. Você também pode projetar qual seria sua classificação depois de adotar recursos de segurança.

Indicadores de inteligência contra ameaças (visualização)

Indicadores de ameaças, também conhecidos como indicadores de compromisso (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 de segurança do Microsoft Graph tiIndicators permite que os clientes alimentem os indicadores de ameaças nas soluções de segurança da Microsoft para habilitar ações em bloco e de alerta em atividades mal-intencionados ou permitir ações de supressão para determinados indicadores não relevantes para a organização. Quando você envia indicadores, a solução Microsoft que utilizará a indicação e a ação a ser tomada sobre o indicador são especificadas.

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 por meio da API de Segurança do Microsoft Graph estão disponíveis hoje nos seguintes produtos:

• Azure Sentinel – Permite correlacionar indicadores de ameaças com dados de log para receber alertas de atividades mal-intencionadas.
• Microsoft Defender para Ponto de Extremidade: permite que você alerte e/ou bloqueie os indicadores de ameaças associados a atividades mal-intencionadas. 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.

O suporte a outros serviços de segurança da Microsoft estará disponível em breve.

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 essa API em vez da API de avaliação de ameaças de proteção de informações obsoleta. 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.

Casos de uso comuns

A seguir, há 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
Ações (visualização)
Obter ações de segurança	Obter ações de segurança	https://graph.microsoft.com/beta/security/securityActions/{id}
Listar ações de segurança	Listar ações de segurança	https://graph.microsoft.com/beta/security/securityActions
Criar ações de segurança	Criar ações de segurança	https://graph.microsoft.com/beta/security/securityActions
Cancelar ações de segurança	Cancelar ações de segurança	https://graph.microsoft.com/beta/security/securityActions/{id}/cancelSecurityAction
Alertas
Listar alertas	List alerts	https://graph.microsoft.com/beta/security/alerts
Atualizar alertas	Atualizar alertas Atualizar vários alertas	https://graph.microsoft.com/beta/security/alerts/{alert-id} https://graph.microsoft.com/beta/security/alerts/updateAlerts
Simulação de ataque e treinamento (visualização)
Listar simulações	Listar simulações	https://graph.microsoft.com/beta/security/attackSimulation/simulations
Obter o relatório de visão geral da simulação	Obter o relatório de visão geral da simulação	https://graph.microsoft.com/beta/security/attackSimulation/simulations/{id}/report/overview
Listar os relatório dos usuários de simulação	Listar os relatório dos usuários de simulação	https://graph.microsoft.com/beta/security/attackSimulation/simulations/{id}/report/simulationUsers
Descoberta eletrônica
Listar casos de Descoberta Eletrônica	Listar eDiscoveryCases	https://graph.microsoft.com/beta/security/cases/eDiscoveryCases
Listar operações de caso de Descoberta Eletrônica	Listar caseOperations	https://graph.microsoft.com/beta/security/cases/eDiscoverycases/{id}/operations
Classificações de segurança
Listar classificações de segurança	Listar secureScores	https://graph.microsoft.com/beta/security/secureScores
Perfis de controle da classificação de segurança
Listar perfis de controle da classificação de segurança	Listar secureScoreControlProfiles	https://graph.microsoft.com/beta/security/secureScoreControlProfiles
Atualizar perfis de controle da classificação de segurança	Atualizar secureScoreControlProfiles	https://graph.microsoft.com/beta/security/secureScoreControlProfiles/{id}
Indicações de inteligência contra ameaças (visualização)
Obter o indicador TI	Obter tiIndicator	https://graph.microsoft.com/beta/security/tiIndicators/{id}
Listar Indicadores TI	Listar tiIndicators	https://graph.microsoft.com/beta/security/tiIndicators
Criar um Indicadores TI	Criar tiIndicator	https://graph.microsoft.com/beta/security/tiIndicators
Enviar Indicadores TI	Enviar tiIndicators	https://graph.microsoft.com/beta/security/tiIndicators/submitTiIndicators
Atualizar Indicadores TI	Atualizar tiIndicator Atualizar vários tiIndicators	https://graph.microsoft.com/beta/security/tiIndicators/{id} https://graph.microsoft.com/beta/security/tiIndicators/updateTiIndicators
Excluir Indicadores TI	Excluir tiIndicator Excluir vários tiIndicators Excluir tiIndicator por externalId	EXCLUIR https://graph.microsoft.com/beta/security/tiIndicators/{id} POSTAR https://graph.microsoft.com/beta/security/tiIndicators/deleteTiIndicators POSTAR https://graph.microsoft.com/beta/security/tiIndicators/deleteTiIndicatorsByExternalId
Envio de ameaça
Receba o envio de ameaças por email	Obter emailThreat	https://graph.microsoft.com/beta/security/threatSubmission/emailThreats/{id}
Listar envios de ameaças por email	Listar emailThreats	https://graph.microsoft.com/beta/threatSubmission/emailThreats
Criar envio de ameaças de email	Crar emailThreat	https://graph.microsoft.com/beta/security/threatSubmission/emailThreats
Revisar o envio de ameaças por email	Revisar emailThreat	https://graph.microsoft.com/beta/security/threatSubmission/emailThreats/{id}/review
Obter envio de ameaça de arquivo	Obter fileThreat	https://graph.microsoft.com/beta/security/threatSubmission/fileThreats/{id}
Listar envios de ameaças de arquivo	Listar fileThreats	https://graph.microsoft.com/beta/threatSubmission/urlThreats
Criar envio de ameaças de arquivo	Criar fileThreat	https://graph.microsoft.com/beta/security/threatSubmission/fileThreats
Obter envio de ameaça de URL	Obter urlThreat	https://graph.microsoft.com/beta/security/threatSubmission/urlThreats/{id}
Listar envios de ameaças à URL	Listar urlThreats	https://graph.microsoft.com/beta/security/threatSubmission/urlThreats
Criar envio de ameaça de URL	Criar urlThreat	https://graph.microsoft.com/beta/security/threatSubmission/urlThreats
Obter política de envio de ameaças por email	Obter emailThreatSubmissionPolicy	https://graph.microsoft.com/beta/security/threatSubmission/emailThreatSubmissionPolicies/{id}
Listar políticas de envio de ameaças por email	Listar emailThreatSubmissionPolicies	https://graph.microsoft.com/beta/security/threatSubmission/emailThreatSubmissionPolicies
Criar política de envio de ameaças por email	Criar emailThreatSubmissionPolicy	https://graph.microsoft.com/beta/security/threatSubmission/emailThreatSubmissionPolicies
Atualizar a política de envio de ameaças por email	Atualizar emailThreatSubmissionPolicy	https://graph.microsoft.com/beta/security/threatSubmission/emailThreatSubmissionPolicies/{id}
Excluir política de envio de ameaças por email	Excluir emailThreatSubmissionPolicy	https://graph.microsoft.com/beta/security/threatSubmission/emailThreatSubmissionPolicies/{id}

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

Novidades

Saiba mais sobre os novos recursos e atualizações mais recentes para esses conjuntos de API.

Próximas etapas

A API de Segurança do Microsoft Graph pode abrir novas formas para você interagir com diferentes soluções de segurança da Microsoft e de parceiros. Siga estas etapas para começar:

• 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.

Precisa de mais ideias? Veja como alguns de nossos parceiros usam o Microsoft Graph.

Confira também

Codifique e contribua com esses exemplos da API de Segurança do Microsoft Graph:

• Amostra do ASP.NET (C#)
• Amostra do Python
• Amostra do Node.js (JavaScript)
• Exemplo do PowerShell
• Outros exemplos ou contribuir com um novo exemplo

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

• Conectores de Segurança do Microsoft Graph para Aplicativos de Lógica, Flow e PowerApps
• Exemplos de bloco de anotações Jupyter

Participe da comunidade:

• Junte-se à comunidade técnica
• Discussão no StackOverflow