你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
引用上传指示器 API（预览版），以将威胁情报导入到 Microsoft Sentinel
Microsoft Sentinel 上传指示器 API 允许威胁情报平台或自定义应用程序将 STIX 格式的入侵指示器导入到 Microsoft Sentinel 工作区。 无论是将 API 与 Microsoft Sentinel 上传指示器 API 数据连接器一起使用，还是作为自定义解决方案的一部分，本文档都可用作参考。
重要
此 API 目前以预览版提供。 Azure 预览版补充条款包含适用于 beta 版、预览版或其他尚未正式发布的 Azure 功能的其他法律条款。
上传指示器 API 调用包含五个组件：
- 请求 URI
- HTTP 请求消息标头
- HTTP 请求消息正文
- （可选）处理 HTTP 响应消息标头
- （可选）处理 HTTP 响应消息正文
使用 Microsoft Entra ID 注册客户端应用程序
若要向 Microsoft Sentinel 进行身份验证，对上传指示器 API 的请求需要有效的 Microsoft Entra 访问令牌。 有关应用程序注册的详细信息，请参阅使用 Microsoft 标识平台注册应用程序，或参阅上传指示器 API 数据连接器设置中的基本步骤。
权限
此 API 要求在工作区级别向 Microsoft Entra 应用程序授予 Microsoft Sentinel 参与者角色。
创建请求
此部分介绍前面讨论的五个组件中的前三个。 首先需要从 Microsoft Entra ID 获取访问令牌，该令牌用于组合请求消息标头。
获取访问令牌
通过 OAuth 2.0 身份验证获取 Microsoft Entra 访问令牌。 V1.0 和 V2.0 是 API 接受的有效令牌。
应用程序收到的令牌版本（v1.0 或 v2.0）由应用程序调用的 API 的应用清单中的 accessTokenAcceptedVersion 属性决定。 如果 accessTokenAcceptedVersion 设置为 1，则应用程序将收到 v1.0 令牌。
使用 Microsoft 身份验证库 MSAL 获取 v1.0 或 v2.0 访问令牌。 或者，使用以下格式将请求发送到 REST API：
- POST
https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token - 用于使用 Microsoft Entra 应用的标头：
- grant_type: "client_credentials"
- client_id：{Microsoft Entra 应用的客户端 ID}
- client_secret：{Microsoft Entra 应用的机密}
- 范围：
"https://management.azure.com/.default"
如果应用清单中的 accessTokenAcceptedVersion 设置为 1，则即使应用程序调用 v2 令牌终结点，它也会收到 v1.0 访问令牌。
资源/范围值是令牌的受众。 此 API 仅接受以下受众：
https://management.core.windows.net/https://management.core.windows.nethttps://management.azure.com/https://management.azure.com
组合请求消息
请求 URI
API 版本控制：api-version=2022-07-01
终结点：https://sentinelus.azure-api.net/{workspaceId}/threatintelligence:upload-indicators?api-version=2022-07-01
方法：POST
请求标头
Authorization：包含 OAuth2 持有者令牌
Content-Type: application/json
请求正文
正文的 JSON 对象包含以下字段：
| 字段名 | 数据类型 | 说明 |
|---|---|---|
| SourceSystem（必填） | 字符串 | 标识源系统名称。 值 Microsoft Sentinel 受限。 |
| 值（必填） | array | STIX 2.0 或 2.1 格式的指示器阵列 |
使用 STIX 2.1 指示器格式规范创建指示器数组，为方便起见，此处进行了精简，其中包含重要部分的链接。 另请注意，某些属性虽然对 STIX 2.1 有效，但它们在 Microsoft Sentinel 中没有相应的指示器属性。
| 属性名称 | Type | 说明 |
|---|---|---|
id（必需） |
字符串 | 用于标识指示器的 ID。 有关如何创建 的规范，请参阅 2.9id 部分。 格式与 indicator--<UUID> 类似 |
spec_version（可选） |
字符串 | STIX 指示器版本。 STIX 规范中必须要有此值，但由于此 API 仅支持 STIX 2.0 和 2.1，因此如果未设置此字段，则 API 将默认为 2.1 |
type（必需） |
字符串 | 此属性的值必须为 indicator。 |
created（必需） |
timestamp | 有关此通用属性的规范，请参阅 3.2 部分。 |
modified（必需） |
timestamp | 有关此通用属性的规范，请参阅 3.2 部分。 |
name（可选） |
字符串 | 用于标识指示器的名称。 生产者应该提供此属性，帮助产品和分析人员了解此指示器的实际用途。 |
description（可选） |
字符串 | 一份说明，提供有关指示器的更多详细信息和上下文，可能包括用途和重要特征。 生产者应该提供此属性，帮助产品和分析人员了解此指示器的实际用途。 |
indicator_types（可选） |
字符串列表 | 此指示器的一组分类。 此属性的值应该来自 indicator-type-ov |
pattern（必需） |
string | 此指示器的检测模式可能会表示为 STIX 模式，也可能表示为其他适当的语言，如 SNORT、YARA 等。 |
pattern_type（必需） |
字符串 | 此指示器中使用的模式语言。 此属性的值应该来自模式类型。 此属性的值必须与模式属性中包含的模式数据类型匹配。 |
pattern_version（可选） |
字符串 | 用于模式属性中数据的模式语言版本，该版本必须与模式属性中包含的模式数据的类型匹配。 对于没有正式规范的模式，应该使用该模式已知的内部版本或代码版本。 对于 STIX 模式语言，对象的规范版本确定默认值。 对于其他语言，默认值应该是创建此对象时模式语言的最新版本。 |
valid_from（必需） |
timestamp | 一个时间，从该时间开始，此指示器被视为是与之相关或其表现出来的行为的有效指示器。 |
valid_until（可选） |
timestamp | 一个时间，在该时间，此指示器不应再被视为是与之相关或其表现出来的行为的有效指示器。 如果省略 valid_until 属性，则指示器的最新有效时间没有约束。 此时间戳必须大于 valid_from 时间戳。 |
kill_chain_phases（可选） |
字符串列表 | 此指示器对应的终止链阶段。 此属性的值应该来自终止链阶段。 |
created_by_ref（可选） |
字符串 | created_by_ref 属性指定创建此对象的实体的 ID 属性。 如果省略此属性，则此信息的源未定义。 对于希望保持匿名的对象创建者，请将此值保留为未定义。 |
revoked（可选） |
boolean | 对象创建者不再认为撤销的对象有效。 撤销对象是永久性的；不得创建具有此 id 的对象的未来版本。此属性的默认值为 false。 |
labels（可选） |
字符串列表 | labels 属性指定用于描述此对象的一组术语。 术语由用户定义或受信任组定义。 这些标签将在 Microsoft Sentinel 中显示为标记。 |
confidence（可选） |
整型 | confidence 属性标识创建者对其数据的正确性的置信度。 置信度值必须是 0-100 范围内的数字。附录 A 包含指向其他置信度级别的规范映射表，在其中一个级别中呈现置信度值时必须使用这些置信度级别。 如果置信度属性不存在，则未指定内容的置信度。 |
lang（可选） |
字符串 | lang 属性标识此对象中文本内容的语言。 如果存在，它必须是符合 RFC5646 的语言代码。 如果该属性不存在，则内容的语言是 en（英语）。如果对象类型包含可翻译的文本属性（例如名称、说明），则此属性应该存在。 此对象中各个字段的语言可能会以精细标记替代 lang 属性（请参阅 7.2.3 部分）。 |
object_marking_refs（可选，包括 TLP） |
字符串列表 | object_marking_refs 属性指定应用于此对象的标记定义对象的 ID 属性列表。 例如，使用交通灯协议 (TLP) 标记定义 ID 来指定指示器源的敏感度。 有关用于 TLP 内容的标记定义 ID 的详细信息，请参阅 7.2.1.4 部分在某些情况下，虽然不常见，但是标记定义本身可能会使用共享或处理指南进行标记。 在这种情况下，此属性不得包含对同一标记定义对象的任何引用（也就是说，该标记定义对象不能包含任何循环引用）。 有关数据标记的进一步定义，请参阅 7.2.2 部分。 |
external_references（可选） |
对象列表 | external_references 属性指定引用非 STIX 信息的外部引用的列表。 此属性用于向其他系统中的记录提供一个或多个 URL、说明或 ID。 |
granular_markings（可选） |
精细标记列表 | granular_markings 属性有助于以不同的方式定义指示器的各个部分。 例如，指示器语言为英语，en，但说明为德语，de。在某些情况下，虽然不常见，但是标记定义本身可能会使用共享或处理指南进行标记。 在这种情况下，此属性不得包含对同一标记定义对象的任何引用（也就是说，该标记定义对象不能包含任何循环引用）。 有关数据标记的进一步定义，请参阅 7.2.3 部分。 |
处理响应消息
响应标头包含一个 HTTP 状态代码。 有关如何解释 API 调用结果的详细信息，请参考此表。
| 状态代码 | 说明 |
|---|---|
| 200 | 成功。 成功验证并发布一个或多个指示器时，API 将返回 200。 |
| 400 | 格式错误。 请求中的某些内容格式不正确。 |
| 401 | 未授权。 |
| 404 | 找不到文件。 通常，当找不到工作区 ID 时，会发生此错误。 |
| 429 | 已超过一分钟内的请求数。 |
| 500 | 服务器错误。 通常是 API 或 Microsoft Sentinel 服务中的错误。 |
响应正文是 JSON 格式的错误消息阵列：
| 字段名 | 数据类型 | 说明 |
|---|---|---|
| 错误 | 错误对象阵列 | 验证错误列表 |
Error 对象
| 字段名 | 数据类型 | 说明 |
|---|---|---|
| recordIndex | int | 请求中指示器的索引 |
| errorMessages | 字符串数组 | 错误消息 |
针对 API 限制的限制
所有限制均根据用户应用：
- 每个请求 100 个指示器。
- 每分钟 100 个请求。
如果请求数超过限制，响应标头中的一个 429 http 状态代码将随以下响应正文一起返回：
{
"statusCode": 429,
"message": "Rate limit is exceeded. Try again in <number of seconds> seconds."
}
每分钟大约 10000 个指示器是收到限制错误之前的最大吞吐量。
示例请求正文
{
"sourcesystem": "test",
"value":[
{
"type": "indicator",
"spec_version": "2.1",
"id": "indicator--10000003-71a2-445c-ab86-927291df48f8",
"name": "Test Indicator 1",
"created": "2010-02-26T18:29:07.778Z",
"modified": "2011-02-26T18:29:07.778Z",
"pattern": "[ipv4-addr:value = '172.29.6.7']",
"pattern_type": "stix",
"valid_from": "2015-02-26T18:29:07.778Z"
},
{
"type": "indicator",
"spec_version": "2.1",
"id": "indicator--67e62408-e3de-4783-9480-f595d4fdae52",
"created": "2023-01-01T18:29:07.778Z",
"modified": "2025-02-26T18:29:07.778Z",
"created_by_ref": "identity--19f33886-d196-468e-a14d-f37ff0658ba7",
"revoked": false,
"labels": [
"label 1",
"label 2"
],
"confidence": 55,
"lang": "en",
"external_references": [
{
"source_name": "External Test Source",
"description": "Test Report",
"external_id": "e8085f3f-f2b8-4156-a86d-0918c98c498f",
"url": "https://fabrikam.com//testreport.json",
"hashes": {
"SHA-256": "6db12788c37247f2316052e142f42f4b259d6561751e5f401a1ae2a6df9c674b"
}
}
],
"object_marking_refs": [
"marking-definition--613f2e26-407d-48c7-9eca-b8e91df99dc9"
],
"granular_markings": [
{
"marking_ref": "marking-definition--beb3ec79-03aa-4594-ad24-09982d399b80",
"selectors": [ "description", "labels" ],
"lang": "en"
}
],
"name": "Test Indicator 2",
"description": "This is a test indicator to demo valid fields",
"indicator_types": [
"threatstream-severity-low", "threatstream-confidence-80"
],
"pattern": "[ipv4-addr:value = '192.168.1.1']",
"pattern_type": "stix",
"pattern_version": "2.1",
"valid_from": "2023-01-01T18:29:07.778Z",
"valid_until": "2025-02-26T18:29:07.778Z",
"kill_chain_phases": [
{
"kill_chain_name": "lockheed-martin-cyber-kill-chain",
"phase_name": "reconnaissance"
}
]
}
]
}
包含验证错误的示例响应正文
如果成功验证所有指示器，则会返回 HTTP 200 状态，响应正文为空。
如果一个或多个指示器验证失败，则返回包含详细信息的响应正文。 例如，如果发送包含四个指示器的阵列，并且前三个指示器正常，但第四个没有 id（必填字段），则会生成 HTTP 状态代码 200 响应，其正文如下：
{
"errors": [
{
"recordIndex":3,
"errorMessages": [
"Error for Property=id: Required property is missing. Actual value: NULL."
]
}
]
}
指示器以阵列的形式发送，因此 recordIndex 从 0 开始。
后续步骤
有关如何在 Microsoft Sentinel 中处理威胁情报的详细信息，请参阅以下文章：
- 了解威胁情报
- 使用威胁指示器
- 使用匹配分析检测威胁
- 利用 Microsoft 提供的情报源并启用 MDTI 数据连接器