你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
Microsoft Sentinel上传指标 API 允许威胁情报平台或自定义应用程序将 STIX 格式的入侵指标导入Microsoft Sentinel工作区。 本文档用作对旧 API 的引用。
重要
此 API 以预览版提供，但不再推荐使用。 使用预览版中的新 STIX 对象 API 上传威胁情报。 有关详细信息，请参阅 STIX 对象 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) 由 accessTokenAcceptedVersion 应用程序正在调用的 API 的应用清单 中的 属性确定。 如果 accessTokenAcceptedVersion 设置为 1，则应用程序将收到 v1.0 令牌。
使用 Microsoft 身份验证库 MSAL 获取 v1.0 或 v2.0 访问令牌。 或者，使用以下格式将请求发送到 REST API：
- 发布
https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token - 用于使用 Microsoft Entra 应用的标头：
- grant_type：“client_credentials”
- client_id： {Microsoft Entra App 的客户端 ID}
- client_secret： {Microsoft Entra App 的机密}
- 范围：
"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
汇编请求消息
旧版 API 有两个版本。 请求正文中需要不同的数组名称，具体取决于终结点。 这还由两个版本的逻辑应用连接器操作表示。
- 连接器操作名称： 威胁情报 - 上传泄露指示器 (已弃用)
- 端点：
https://sentinelus.azure-api.net/{workspaceId}/threatintelligence:upload-indicators - 指示器名称数组：
value
- 端点：
- 连接器操作名称： 威胁情报 - 上传入侵指示器 (V2) (预览版)
- 端点：
https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload - 指示器名称数组：
indicators{ "sourcesystem":"TIsource-example", "indicators":[] }
- 端点：
请求 URI
API 版本控制： api-version=2022-07-01
端点： https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload?api-version=2022-07-01
方法： POST
请求标头
Authorization：包含 OAuth2 持有者令牌
Content-Type: application/json
请求正文
正文的 JSON 对象包含以下字段：
| 字段名 | 数据类型 | 说明 |
|---|---|---|
| SourceSystem (必需) | string | 标识源系统名称。 该值 Microsoft Sentinel 受到限制。 |
| 所需的指标 () | 数组 | 采用 STIX 2.0 或 2.1 格式的指示器数组 |
使用 STIX 2.1 指示器格式规范创建指标数组，为了方便起见，此处已精简了这些指标，其中包含指向重要部分的链接。 另请注意，某些属性虽然对 STIX 2.1 有效，但在Microsoft Sentinel中没有相应的指示器属性。
| 属性名 | 类型 | 说明 |
|---|---|---|
id 需要 () |
string | 用于标识指示器的 ID。 有关如何创建 id的规范，请参阅 2.9 部分。 格式类似于 indicator--<UUID> |
spec_version（可选） |
string | STIX 指示器版本。 此值在 STIX 规范中是必需的，但由于此 API 仅支持 STIX 2.0 和 2.1，因此如果未设置此字段，API 将默认为 2.1 |
type 需要 () |
string | 此属性的值 必须为indicator。 |
created 需要 () |
时间 戳 | 有关此公共属性的规范，请参阅 第 3.2 节。 |
modified 需要 () |
时间 戳 | 有关此公共属性的规范，请参阅 第 3.2 节。 |
name（可选） |
string | 用于标识指示器的名称。 制作者 应 提供此属性来帮助产品和分析师了解此指标的实际用途。 |
description（可选） |
string | 提供有关指标的更多详细信息和上下文（可能包括其用途和关键特征）的说明。 制作者 应 提供此属性来帮助产品和分析师了解此指标的实际用途。 |
indicator_types（可选） |
字符串列表 | 此指标的一组分类。 此属性的值 应 来自 indicator-type-ov |
pattern 需要 () |
string | 此指示器的检测模式 可以 表示为 STIX 模式 或其他适当的语言，例如 SNORT、YARA 等。 |
pattern_type 需要 () |
string | 此指示器中使用的模式语言。 此属性的值 应 来自 模式类型。 此属性的值 必须与 模式属性中包含的模式数据类型匹配。 |
pattern_version（可选） |
string | 用于模式属性中数据的模式语言版本，该版本 必须与 模式属性中包含的模式数据类型匹配。 对于没有正式规范的模式， 应 使用该模式已知的内部版本或代码版本。 对于 STIX 模式语言，对象的规范版本确定默认值。 对于其他语言，默认值 应 为创建此对象时模式语言的最新版本。 |
valid_from 需要 () |
时间 戳 | 此指示器被视为它与或表示相关的行为的有效指示器的时间。 |
valid_until（可选） |
时间 戳 | 此指标不再被视为它与 或 表示相关的行为的有效指示器的时间。 如果省略 valid_until 属性，则指标的最近有效时间没有约束。 此时间戳 必须 大于valid_from时间戳。 |
kill_chain_phases（可选） |
字符串列表 | 终止链阶段 (与此指标对应的) 。 此属性的值 应 来自 终止链阶段。 |
created_by_ref（可选） |
string | created_by_ref 属性指定创建此对象的实体的 ID 属性。 如果省略此属性，则未定义此信息的源。 对于希望保持匿名的对象创建者，请保持此值未定义。 |
revoked（可选） |
boolean | 撤销的对象不再被对象创建者视为有效。 撤消对象是永久性的;不得创建具有此id对象的未来版本。此属性的默认值为 false。 |
labels（可选） |
字符串列表 | 属性 labels 指定用于描述此对象的一组术语。 术语由用户定义或信任组定义。 这些标签在 Microsoft Sentinel 中显示为“标记”。 |
confidence（可选） |
integer | 属性 confidence 标识创建者对其数据正确性的置信度。 置信度值 必须是 0-100 范围内的数字。附录 A 包含到其他置信度刻度的规范映射表，在在其中一个刻度中呈现置信度值时 必须使用 这些标度。 如果置信度属性不存在，则未指定内容的置信度。 |
lang（可选） |
string | 属性 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."
}
每分钟大约 10,000 个指示器是收到限制错误之前的最大吞吐量。
示例请求正文
{
"sourcesystem": "test",
"indicators":[
{
"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。
后续步骤
此 API 是旧 API。 请迁移以使用 STIX 对象 API 上传威胁情报。 有关详细信息，请参阅 STIX 对象 API。