使用 Microsoft Graph 安全 API

  • 项目

重要

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

Microsoft Graph 安全 API 提供统一的接口和架构，用于与 Microsoft 和生态系统合作伙伴的安全解决方案集成。 它使客户能够简化安全操作，并更好地防范日益严重的网络威胁。 Microsoft Graph 安全 API 将查询联合到所有载入的安全提供程序并聚合响应。 使用 Microsoft Graph 安全 API 生成以下应用程序：

  • 合并并关联来自多个源的安全警报。
  • 从属于 Microsoft 365 Defender 或与 Microsoft 365 Defender 集成的服务拉取和调查所有事件和警报。
  • 解锁上下文数据，以提供信息帮助调查。
  • 自动执行安全任务、业务流程、工作流和报告。
  • 将威胁指示器发送到 Microsoft 产品进行自定义检测。
  • 调用 操作以响应新威胁。
  • 提供对安全数据的可见性，以实现主动风险管理。

Microsoft Graph 安全 API 提供关键功能，如以下部分所述。

操作（预览版）

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

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

高级搜寻

高级搜寻是一种基于查询的威胁搜寻工具，可用于浏览多达 30 天的原始数据。 你可以主动检查网络中的事件来找到威胁指示器和实体。 通过灵活访问数据，可以不受约束地搜寻已知威胁和潜在威胁。

使用 runHuntingQuery 对 Microsoft 365 Defender 中存储的数据运行Kusto 查询语言 (KQL) 查询。 利用返回的结果集来丰富现有调查或发现网络中未检测到的威胁。

配额和资源分配

  1. 只能对过去 30 天的数据运行查询。

  2. 结果最多包含 100,000 行。

  3. 每个租户的执行次数受到限制：

    • API 调用：每分钟最多 45 个请求，每小时最多 1500 个请求。
    • 执行时间：每小时运行 10 分钟，每天运行 3 小时。

  4. 单个请求的最大执行时间为 200 秒。

  5. HTTP 429 的响应代码表示已达到 API 调用次数或执行时间的配额。 请参阅响应正文以确认已达到限制。

  6. 单个请求的最大查询结果大小不能超过 124 MB。 超过大小限制会导致 HTTP 400 错误请求，并显示消息“查询执行已超出允许的结果大小。 通过限制结果数来优化查询，然后重试。”

自定义检测

可以创建特定于安全操作的高级搜寻 自定义检测规则 ，以便主动监视威胁并采取措施。 例如，可以创建自定义检测规则来查找已知指示器或错误配置的设备。 这些自动触发警报和你指定的任何响应操作。

配额

  1. 获取多个规则：每个应用程序每分钟 10 个规则，每个应用程序每小时 300 个规则，每个租户每小时 600 个规则
  2. 获取单个规则：每个应用程序每分钟 100 个规则，每个应用程序每小时 1,500 个规则，每个租户每小时 1,800 个规则
  3. 创建规则：每个应用程序每分钟 10 个规则，每个应用程序每小时 1,500 个规则，每个租户每小时 1,800 个规则
  4. 更新规则：每个应用程序每分钟 100 个规则，每个应用程序每小时 1,500 个规则，每个租户每小时 1,800 个规则
  5. 删除规则：每个应用程序每分钟 100 个规则，每个应用程序每小时 1,500 个规则，每个租户每小时 1,800 个规则

警报

警报是有关客户租户中可疑活动的详细警告，Microsoft 或合作伙伴安全提供商已识别并标记为要采取行动。 攻击通常对不同类型的实体（如设备、用户和邮箱）采用各种技术。 结果是来自租户中多个实体的多个安全提供程序发出的警报。 将单个警报拼凑在一起以深入了解攻击可能具有挑战性且非常耗时。

安全 API 的 beta 版本提供两种类型的警报，这些警报聚合来自安全提供程序的其他警报，使分析攻击和确定响应变得更容易：

  • 警报和事件 - Microsoft Graph 安全 API 中的最新一代警报。 它们由命名空间中microsoft.graph.security定义的警报资源及其集合事件资源表示。
  • 旧警报 - Microsoft Graph 安全 API 中的第一代警报。 它们由 命名空间中microsoft.graph定义的警报资源表示。

警报和事件

这些 警报 资源首先从属于 Microsoft 365 Defender 或与 Microsoft 365 Defender 集成的安全提供程序服务拉取警报数据。 然后，他们使用数据返回有关已完成或正在进行的攻击、受影响的资产和相关证据的丰富、有价值的 线索。 此外，它们会自动将具有相同攻击技术或相同攻击者的其他警报关联到 事件 中，以提供更广泛的攻击上下文。 他们建议响应和修正操作，在所有不同的提供程序之间提供一致的可操作性。 丰富的内容使分析师能够更轻松地共同调查和响应威胁。

可通过以下丰富的警报和事件获取来自以下安全提供程序的警报：

旧警报

这些 警报 资源联合调用受支持的 Azure 和 Microsoft 365 Defender 安全提供程序。 它们聚合不同域之间的常见警报数据，使应用程序能够统一和简化所有集成解决方案中安全问题的管理。 它们使应用程序能够关联警报和上下文，以改善威胁防护和响应。

使用警报更新功能，可以通过更新警报实体来跨与 Microsoft Graph 安全 API 集成的不同安全产品和服务同步特定 警报 的状态。

来自以下安全提供程序的警报可通过 此旧警报 资源获得。 下表显示了通过 webhook) 对 GET 警报、PATCH 警报和订阅 (的支持。

安全提供商

GET 警报

PATCH 警报

订阅订阅
Microsoft Entra ID 保护

✓

提交问题 *

✓
Azure 安全中心

✓

✓

✓
Microsoft 365

✓

提交问题

提交问题

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

✓

提交问题 *

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

✓

✓

提交问题

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

✓

提交问题 *

✓
Microsoft Sentinel (以前为 Azure Sentinel)

✓

Microsoft Sentinel 不支持

✓

注意： 新提供商不断加入 Microsoft Graph 安全生态系统。 若要请求新提供程序或从现有提供程序获得扩展支持，请在 Microsoft Graph 安全性 GitHub 存储库中提出问题。

* 文件问题：警报状态在 Microsoft Graph 安全 API 集成应用程序中更新，但未反映在提供程序的管理体验中。

** Microsoft Defender for Endpoint需要 Microsoft Graph 安全 API 所需的用户角色。 只有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 电子数据展示（高级版） 提供端到端工作流，用于保留、收集、分析、审阅和导出响应组织内部和外部调查的内容。

审核日志查询 (预览)

Microsoft Purview 审核提供了一个集成解决方案，可帮助组织有效地响应安全事件、取证调查、内部调查和合规性义务。 数千名 Microsoft 365 服务和解决方案中执行的用户和管理员操作被捕获、记录并保留在组织的统一审核日志中。 这些事件的审核记录通过安全运营、IT 管理员、预览体验计划团队以及合规与法律支持人员进行搜索。 此功能可跨 Microsoft 365 组织查看执行的活动。

事件

事件是构成攻击故事的相关警报和相关数据的集合。 事件管理是 Microsoft 365 Defender 的一部分，可在 Microsoft 365 Defender 门户中 (https://security.microsoft.com/) 。

Microsoft 365 服务和应用将在检测到可疑或恶意事件或活动时创建警报。 单个警报可提供有关已完成或持续攻击的有价值的线索。 但是，攻击通常对不同类型的实体（如设备、用户和邮箱）使用多种技术。 结果是租户中的多个实体将收到多个警报。

由于将各个警报拼凑在一起以深入了解攻击可能具有挑战性且耗时，因此 Microsoft 365 Defender 会自动将警报及其相关信息聚合到 事件中。

将相关警报组合为一个事件可使你对攻击具有全面了解。 例如，你可以看到：

  • 攻击开始的位置。
  • 使用了什么策略。
  • 攻击侵入租户的程度。
  • 攻击范围，例如受影响的设备、用户和邮箱数。
  • 与攻击有关的所有数据。

事件资源及其 API 允许你对事件进行排序，以创建合理的网络安全响应。 它公开在环境保留策略中指定的时间范围内在网络中标记的事件及其相关 警报的集合。

信息保护

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

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

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

记录管理

大多数组织都需要管理数据，以主动遵守行业法规和内部策略，在发生诉讼或安全漏洞时降低风险，并让其员工有效且敏捷地共享当前相关知识。 可以使用 记录管理 API 系统地将 保留标签 应用于需要不同保留设置的不同类型的内容。 例如，可以配置保留期的开始时间，从内容创建、上次修改、标记时间或特定事件类型发生事件的时间开始。 此外，可以使用 文件计划描述符 来提高这些保留标签的可管理性。

安全功能分数

Microsoft 安全功能分数是一款安全分析解决方案，可让你了解安全项目组合以及如何改进这些组合。 只需一个分数，你就可以更好地了解已采取了哪些措施来降低 Microsoft 解决方案中的风险。 此外，你还可以将你的分数与其他组织比较，以了解你的分数趋势。 secureScore 和 secureScoreControlProfile 实体有助于平衡组织的安全和生产力需求，同时启用适当的安全功能组合。 还可以在采用安全功能后预测分数。

威胁情报 (预览版)

Microsoft Defender 威胁智能提供世界一流的威胁情报，以帮助保护组织免受现代网络威胁的侵害。 可以使用威胁情报来识别攻击者及其操作，加速检测和修正，并增强安全投资和工作流。

使用预览版 (威胁情报 API) ，可以操作用户界面中发现的智能。 这包括文章和 Intel 配置文件形式的完成智能、包括 IoC 和信誉判决的机器智能，最后包括扩充数据，包括被动 DNS、Cookie、组件和跟踪器。

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

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

tiIndicator 实体允许客户将威胁指标馈送给 Microsoft 安全解决方案，以便对恶意活动采取阻止或警报操作，或者允许已确定与组织无关的活动并禁止对指示器执行的操作。 若要发送指示器，请指定旨在利用指示器的 Microsoft 安全解决方案以及要针对该指标执行的操作。

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

通过 Microsoft Graph 安全 API 发送的威胁指标目前在以下产品中可用：

威胁提交

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

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

Email和协作保护 (预览)

Microsoft Defender for Office 365是基于云的电子邮件筛选服务，可帮助保护组织免受电子邮件和协作工具的高级威胁，例如网络钓鱼、企业电子邮件泄露和恶意软件攻击。 可以使用 Microsoft Graph 分析邮件 和 修正 API 检索电子邮件元数据并执行响应操作， (软删除、硬删除、移动到垃圾邮件、移动到收件箱) 已分析的邮件。

注意：这些 API 仅适用于Defender for Office 365计划 2 或 Microsoft 365 A5/E5/F5/G5 安全服务计划。 有关服务计划的最新列表，请参阅Microsoft Defender for Office 365服务说明。

身份

运行状况问题

Defender for Identity 运行状况问题 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_v2
更新警报 更新警报 https://graph.microsoft.com/beta/security/alerts/{id}
列出事件 列出事件 https://graph.microsoft.com/beta/security/incidents
使用警报列出事件 列出事件 https://graph.microsoft.com/beta/security/incidents?$expand=alerts
更新事件 更新事件 https://graph.microsoft.com/beta/security/incidents/{id}
攻击模拟和训练
列出模拟 列出模拟 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
旧警报
列出警报 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
安全功能分数
列出安全功能分数 列出 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}
删除电子邮件威胁提交策略 删除 emailThreatSubmissionPolicy https://graph.microsoft.com/beta/security/threatSubmission/emailThreatSubmissionPolicies/{id}
Email分析和修正
查询电子邮件元数据 LIST analyzedemails https://graph.microsoft.com/beta/security/collaboration/analyzedemails?startTime={startTime}&endTime={endTime}
获取单个消息实例的详细信息 GET 已分析emails/Id https://graph.microsoft.com/beta/security/collaboration/analyzedemails/{Id}
修正已分析的电子邮件 analyzedEmai： 修正 https://graph.microsoft.com/beta/security/collaboration/analyzedemails/remediate
身份
列出运行状况问题 列出运行状况问题 https://graph.microsoft.com/beta/security/identities/healthIssues

可以使用 Microsoft Graph Webhook 订阅和接收有关 Microsoft Graph 安全 API 实体更新的通知。

后续步骤

Microsoft Graph 安全 API 可以开辟新方式，让你与 Microsoft 和合作伙伴的不同安全解决方案互动。 请按照以下步骤开始操作：

相关内容

编写代码并参与 此 Microsoft Graph 安全 API 示例：

探索使用 Microsoft Graph 安全 API 进行连接的其他选项：

与社区互动：