反馈 编辑

使用 Microsoft Graph 安全性 API

  • 项目

重要

Microsoft Graph版本下的 /beta API 可能会发生更改。 不支持在生产应用程序中使用这些 API。 若要确定 API 是否在 v1.0 中可用，请使用 版本 选择器。

Microsoft Graph 安全性 API 提供了统一的界面的架构，用于与 Microsoft 和生态系统合作伙伴的安全性解决方案集成。 这使客户能够简化安全性操作和更好地抵御日益增多的网络威胁。 Microsoft Graph 安全性 API 将查询与所有已上架的安全性提供商进行联接并生成相关响应。 使用 Microsoft Graph 安全性 API 构建具有以下优势的应用程序：

  • 合并和关联多个来源的安全警报
  • 解锁上下文数据，以提供信息帮助调查
  • 自动处理安全任务、业务流程、工作流和报告
  • 发送 Microsoft 产品威胁指示器供自定义检测
  • 采取操作来应对新的威胁
  • 直观显示安全数据，实现主动风险管理

Microsoft Graph 安全性 API 包括以下关键实体。

操作（预览版）

利用 Microsoft Graph 安全性 securityAction 实体立即采取行动来抵御威胁。 当安全分析师发现新的指示器（如恶意文件、URL、域或 IP 地址）时，可立即在你的 Microsoft 安全解决方案中启用保护。 针对特定提供商采取操作，查看所采取的全部操作，还可在需要时取消操作。 尝试使用 Microsoft Defender for Endpoint (以前是 Microsoft Defender ATP) 的安全操作，以使用警报中发现的属性或在调查期间识别的属性阻止 Windows 终结点上的恶意活动。

注意： 安全操作当前仅支持应用程序权限。

警报

警报是指 Microsoft 或其合作伙伴安全解决方案在客户的租户中识别并标记要进行操作或发送通知的潜在安全问题。 借助 Microsoft Graph 安全性警报实体，你可对所有集成解决方案中的安全问题进行统一和简化。 此外，这还能使应用程序关联警报和上下文，从而提升威胁防护和响应。 利用警报更新功能，你可以更新警报实体，从而同步与 Microsoft Graph 安全性 API 集成的不同安全产品和服务中的特定警报状态。

Microsoft Graph 安全性 API 提供来自以下提供商的警报。 下表显示了对 GET 警报、PATCH 警报和订阅（通过 webhooks）的支持。

安全提供商

GET 警报

PATCH 警报

订阅订阅
Azure 安全中心

✓

✓

✓
Azure Active Directory Identity Protection

✓

提交问题 *

✓
Microsoft Defender for Cloud Apps (以前是 Microsoft Cloud App Security)

✓

提交问题 *

✓
Microsoft Defender for Endpoint (以前是 Microsoft Defender ATP) **

✓

✓

提交问题

Microsoft Defender for Identity (以前是 Azure 高级威胁防护) ***

✓

提交问题 *

✓
Microsoft 365

✓

提交问题

提交问题

Azure 信息保护（预览版）

✓

提交问题 *

✓
Azure Sentinel（预览版）

✓

在 Azure Sentinel 中不受支持

✓

注意： 新的提供商将会不断加入 Microsoft Graph 安全生态系统。 要请求新的提供商或从现有提供商处获取更长时间的支持，请在 Microsoft Graph 安全性 GitHub 存储库中提交问题。

* 文件问题：警报状态在 Microsoft Graph 安全性 API 集成应用程序中得到更新，但不反映在供应商的管理经验中。

**与 Microsoft Graph 安全性 API 相比，Microsoft Defender for Endpoint 所需的用户角色更多。 只有同时具备 Microsoft Defender for Endpoint 和 Microsoft Graph 安全性 API 角色的用户才可访问 Microsoft Defender for Endpoint 数据。 由于仅限应用程序的身份验证不受此约束限制，我们建议使用仅限应用程序的身份验证令牌。

*** Microsoft Defender for Identity 警报通过 Microsoft Defender for Cloud Apps 集成提供。 这意味着只有在加入了 Unified SecOps 并将 Microsoft Defender for Identity 连接到 Microsoft Defender for Cloud Apps 时，才会收到 Microsoft Defender for Identity 警报。 了解有关如何集成 Microsoft Defender for Identity 和 Microsoft Defender for Cloud Apps 的详细信息。

攻击模拟和培训（预览版）

攻击模拟和培训是 Microsoft Defender for Office 365 的一部分。 此服务可让租户中的用户体验真实的恶意钓鱼攻击，并从中学习。 最终用户的社交工程模拟和培训体验有助于降低用户被这些攻击技术入侵的风险。 攻击模拟和培训 API 使租户管理员能够查看启动的模拟练习和培训，并获取有关网络钓鱼模拟中用户在线行为的派生见解的报告。

电子数据展示（预览版）

Microsoft Purview 电子数据展示（高级版） 提供端到端工作流，用于保留、收集、分析、审阅和导出响应组织内部和外部调查的内容。

信息保护

标签 - 信息保护标签提供有关如何正确地将敏感度标签应用到信息的详细信息。 信息保护标签 API 描述对某一用户或租户应用的敏感度标签配置。

威胁评估 - Microsoft Graph 威胁评估 API 可帮助组织评估租户中任何用户收到的威胁。 这样，客户就可将其收到的垃圾电子邮件、网络钓鱼 URL 或恶意软件附件报告给 Microsoft。 Microsoft 在生成结果之前检查相关示例和组织策略，以便租户管理员可以了解威胁扫描结果并调整其组织策略。 还可以用来报告合法的电子邮件，以防止遭到阻止。

注意： 建议改用 威胁提交 API。

安全功能分数

Microsoft 安全功能分数是一款安全分析解决方案，可让你了解安全项目组合以及如何改进这些组合。 只需一个分数，你就可以更好地了解已采取了哪些措施来降低 Microsoft 解决方案中的风险。 此外，你还可以将你的分数与其他组织比较，以了解你的分数趋势。 Microsoft Graph 安全性 secureScore 和 secureScoreControlProfile 实体可以帮助你实现组织的安全性与生产力需求之间的平衡，同时支持相应的安全功能混合。 你也可以计划采取安全功能之后的分数。

威胁情报指示器（预览版）

威胁指示器也称为泄露指示器 (IoC)，它们表示已知威胁的相关数据，例如恶意文件、URL、域和 IP 地址。 客户可通过内部威胁智能收集功能生成指示器，也可从威胁智能社区、经过许可的源或其他来源获取指示器。 这些指示器随后可在各种安全工具中用来防御相关威胁。

借助 Microsoft Graph 安全性 tiIndicator 实体，客户可向 Microsoft 安全解决方案提供威胁指示器，以便阻止（并发出警报）或允许恶意活动操作，这会遏制被判定为与某组织无关的指示器的操作。 发送指示器时，会指定要使用这些指示器的 Microsoft 解决方案以及要对指示器执行的操作。

你可将 tiIndicator 实体集成到应用程序中，或者使用下述集成威胁智能平台 (TIP) 之一：

现在可从以下产品获取通过 Microsoft Graph 安全性 API 发送的威胁指示器：

  • Azure Sentinel – 可以将威胁指示器与日志数据关联在一起，获取恶意活动警报。
  • Microsoft Defender for Endpoint – 使你能够针对与恶意活动关联的威胁指示器发出警报和/或进行阻止。 还可以允许指示器，以忽略此指示器，免于对其进行自动调查。 有关支持的指示器类型以及每个租户的指示器数限制的详细信息，请参阅管理指示器。

即将在其他 Microsoft 安全服务中提供支持。

威胁提交

Microsoft Graph 威胁评估 API 可帮助组织评估租户中任何用户收到的威胁。 这样，客户就可将其收到的垃圾电子邮件、网络钓鱼 URL 或恶意软件附件报告给 Microsoft。 Microsoft 根据实际情况检查组织策略提交，并将其发送给人工评分员进行分析。 策略检查结果和重新扫描结果可帮助租户管理员了解威胁扫描判定并调整其组织策略。 管理员还可以使用结果来报告合法的电子邮件，以防止遭到阻止。

注意： 建议使用此 API，而不是弃用信息保护威胁评估 API。 威胁提交 API 提供统一的安全威胁提交功能，并添加统一的结果支持、用户提交查询支持、租户允许块列表支持、管理员评审支持和仅应用模式支持。

常见用例

以下是使用 Microsoft Graph 安全性 API 的一些热门的请求。

用例 REST 资源 在 Graph 浏览器中试调用
操作（预览版）
获取安全操作 获取安全操作 https://graph.microsoft.com/beta/security/securityActions/{id}
列出安全操作 列出安全操作 https://graph.microsoft.com/beta/security/securityActions
创建安全操作 创建安全操作 https://graph.microsoft.com/beta/security/securityActions
取消安全操作 取消安全操作 https://graph.microsoft.com/beta/security/securityActions/{id}/cancelSecurityAction
警告
列出警报 List alerts https://graph.microsoft.com/beta/security/alerts
更新警报 更新警报
更新多个警报		 https://graph.microsoft.com/beta/security/alerts/{alert-id}
https://graph.microsoft.com/beta/security/alerts/updateAlerts
攻击模拟和培训（预览版）
列出模拟 列出模拟 https://graph.microsoft.com/beta/security/attackSimulation/simulations
获取模拟概述报告 获取模拟概述报告 https://graph.microsoft.com/beta/security/attackSimulation/simulations/{id}/report/overview
列出模拟用户报告 列出模拟用户报告 https://graph.microsoft.com/beta/security/attackSimulation/simulations/{id}/report/simulationUsers
电子数据展示
列出电子数据展示案例 List eDiscoveryCases https://graph.microsoft.com/beta/security/cases/eDiscoveryCases
列出电子数据展示案例操作 List caseOperations https://graph.microsoft.com/beta/security/cases/eDiscoverycases/{id}/operations
安全功能分数
列出安全功能分数 列出 secureScores https://graph.microsoft.com/beta/security/secureScores
安全功能分数控制配置文件
列出安全功能分数控制配置文件 列出 secureScoreControlProfiles https://graph.microsoft.com/beta/security/secureScoreControlProfiles
更新安全功能分数控制配置文件 更新 secureScoreControlProfiles https://graph.microsoft.com/beta/security/secureScoreControlProfiles/{id}
威胁情报指示（预览版）
获取 TI 指示器 获取 tiIndicator https://graph.microsoft.com/beta/security/tiIndicators/{id}
列出 TI 指示器 列出 tiIndicator https://graph.microsoft.com/beta/security/tiIndicators
创建 TI 指示器 创建 tiIndicator https://graph.microsoft.com/beta/security/tiIndicators
提交 TI 指示器 提交 tiIndicator https://graph.microsoft.com/beta/security/tiIndicators/submitTiIndicators
更新 TI 指示器 更新 tiIndicator
更新多个 tiIndicator		 https://graph.microsoft.com/beta/security/tiIndicators/{id}
https://graph.microsoft.com/beta/security/tiIndicators/updateTiIndicators
删除 TI 指示器 删除 tiIndicator
删除多个 tiIndicator
按 externalId 删除 tiIndicator		 DELETE
https://graph.microsoft.com/beta/security/tiIndicators/{id}
POST
https://graph.microsoft.com/beta/security/tiIndicators/deleteTiIndicators
POST
https://graph.microsoft.com/beta/security/tiIndicators/deleteTiIndicatorsByExternalId
威胁提交
获取电子邮件威胁提交 获取 emailThreat https://graph.microsoft.com/beta/security/threatSubmission/emailThreats/{id}
列出电子邮件威胁提交 列出 emailThreats https://graph.microsoft.com/beta/threatSubmission/emailThreats
创建电子邮件威胁提交 创建 emailThreat https://graph.microsoft.com/beta/security/threatSubmission/emailThreats
查看电子邮件威胁提交 查看 emailThreat https://graph.microsoft.com/beta/security/threatSubmission/emailThreats/{id}/review
获取文件威胁提交 获取 fileThreat https://graph.microsoft.com/beta/security/threatSubmission/fileThreats/{id}
列出文件威胁提交 列出 fileThreats https://graph.microsoft.com/beta/threatSubmission/urlThreats
创建文件威胁提交 创建 fileThreat https://graph.microsoft.com/beta/security/threatSubmission/fileThreats
获取 URL 威胁提交 获取 urlThreat https://graph.microsoft.com/beta/security/threatSubmission/urlThreats/{id}
列出 URL 威胁提交 列出 urlThreats https://graph.microsoft.com/beta/security/threatSubmission/urlThreats
创建 URL 威胁提交 创建 urlThreat https://graph.microsoft.com/beta/security/threatSubmission/urlThreats
获取电子邮件威胁提交策略 获取 emailThreatSubmissionPolicy https://graph.microsoft.com/beta/security/threatSubmission/emailThreatSubmissionPolicies/{id}
列出电子邮件威胁提交策略 列出 emailThreatSubmissionPolicies https://graph.microsoft.com/beta/security/threatSubmission/emailThreatSubmissionPolicies
创建电子邮件威胁提交策略 创建 emailThreatSubmissionPolicy https://graph.microsoft.com/beta/security/threatSubmission/emailThreatSubmissionPolicies
更新电子邮件威胁提交策略 更新 emailThreatSubmissionPolicy https://graph.microsoft.com/beta/security/threatSubmission/emailThreatSubmissionPolicies/{id}
删除电子邮件威胁提交策略 删除 emailThreatSubmissionPolicy https://graph.microsoft.com/beta/security/threatSubmission/emailThreatSubmissionPolicies/{id}

你可使用 Microsoft Graph Webhook 来订阅和接收 Microsoft Graph 安全性 API 实体更新的相关通知。

最近更新

了解这些 API 集的最新功能和更新。

后续步骤

Microsoft Graph 安全性 API 可以为你提供使用 Microsoft 和合作伙伴的不同安全解决方案的新方式。请按照以下步骤操作开始使用：

需要更多灵感？请参阅我们的一些合作伙伴如何使用 Microsoft Graph。

另请参阅

Microsoft Graph 安全性 API 示例的代码和贡献情况：

了解可与 Microsoft Graph 安全性 API 连接的其他选项：

与社区互动：