通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

使用上传 API 将威胁情报导入 Microsoft Sentinel（预览版）

  • 项目
  • 适用于:
    Microsoft Sentinel in the Azure portal

导入威胁情报，以便通过上传 API 在 Microsoft Sentinel 中使用。 无论是使用威胁情报平台还是自定义应用程序，都使用本文档作为有关将 TIP 与上传 API 连接中的说明的补充参考。 安装数据连接器不需要连接到 API。 可以导入的威胁情报包括泄露指示器和其他 STIX 域对象。

重要

此 API 目前以预览版提供。 Azure 预览版补充条款包含适用于 beta 版、预览版或其他尚未正式发布的 Azure 功能的其他法律条款。

结构化威胁信息表达式（STIX）是表达网络威胁和可观察信息的语言。 上传 API 包含对以下域对象的增强支持：

  • indicator
  • 攻击模式
  • 威胁参与者
  • identity
  • 关系

有关详细信息，请参阅 STIX 简介。

注意

以前的上传指示器 API 现在为旧版。 如果需要在转换到此新上传 API 时引用该 API，请参阅 旧版上传指示器 API。

调用 API

对上传 API 的调用有五个组件：

  1. 请求 URI
  2. HTTP 请求消息标头
  3. HTTP 请求消息正文
  4. （可选）处理 HTTP 响应消息标头
  5. （可选）处理 HTTP 响应消息正文

使用 Microsoft Entra ID 注册客户端应用程序

为了向 sentinel Microsoft 进行身份验证，上传 API 的请求需要有效的Microsoft Entra 访问令牌。 有关应用程序注册的详细信息，请参阅使用Microsoft 标识平台注册应用程序，或者通过上传 API 设置在 Connect 威胁智能中查看基本步骤。

此 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：

  • 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.net
  • https://management.azure.com/
  • https://management.azure.com

组合请求消息

请求 URI

API 版本控制：api-version=2024-02-01-preview
终结点：https://api.ti.sentinel.azure.com/workspaces/{workspaceId}/threat-intelligence-stix-objects:upload?api-version={apiVersion}
方法：POST

请求标头

Authorization：包含 OAuth2 持有者令牌
Content-Type: application/json

请求正文

正文的 JSON 对象包含以下字段：

字段名 数据类型 描述
sourcesystem（必需） string 标识源系统名称。 值 Microsoft Sentinel 受限。
stixobjects（必需） array STIX 2.0 或 2.1 格式的 STIX 对象的 数组

使用 STIX 格式规范创建 STIX 对象的数组。 此处扩展了一些 STIX 属性规范，方便使用指向相关 STIX 文档部分的链接。 另请注意，某些属性虽然对 STIX 有效，但在 Microsoft Sentinel 中没有相应的对象架构属性。

公共属性

使用上传 API 导入的所有对象共享这些通用属性。

属性名称 类型​​ 说明
id（必需） string 用于标识 STIX 对象的 ID。 有关如何创建 的规范，请参阅 2.9id 部分。 格式与 indicator--<UUID> 类似
spec_version（可选） string STIX 对象版本。 STIX 规范中需要此值，但由于此 API 仅支持 STIX 2.0 和 2.1，如果未设置此字段，则 API 默认为 2.1
type（必需） string 此属性 的值必须是 受支持的 STIX 对象。
created（必需） timestamp 有关此通用属性的规范，请参阅 3.2 部分。
created_by_ref（可选） 字符串 created_by_ref 属性指定创建此对象的实体的 ID 属性。

如果省略此属性，则此信息的源未定义。 对于希望保持匿名的对象创建者，请将此值保留为未定义。
modified（必需） timestamp 有关此通用属性的规范，请参阅 3.2 部分。
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 部分。

有关详细信息，请参阅 STIX 通用属性。

指示器

属性名称 类型​​ 说明
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（可选） 字符串列表 此指示器对应的终止链阶段。

此属性的值应该来自终止链阶段。

有关详细信息，请参阅 STIX 指示器。

攻击模式

有关详细信息，请参阅 STIX 攻击模式。

标识

有关详细信息，请参阅 STIX 标识。

威胁参与者

有关详细信息，请参阅 STIX 威胁参与者。

关系

有关详细信息，请参阅 STIX 关系。

处理响应消息

响应标头包含一个 HTTP 状态代码。 有关如何解释 API 调用结果的详细信息，请参考此表。

状态代码 说明
200 成功。 成功验证并发布一个或多个 STIX 对象时，API 将返回 200。
400 格式错误。 请求中的某些内容格式不正确。
401 未授权。
404 找不到文件。 通常，当找不到工作区 ID 时，会发生此错误。
429 超过一分钟内的最大请求数。
500 服务器错误。 通常是 API 或 Microsoft Sentinel 服务中的错误。

响应正文是 JSON 格式的错误消息阵列：

字段名 数据类型 说明
错误 错误对象阵列 验证错误列表

Error 对象

字段名 数据类型 说明
recordIndex int 请求中 STIX 对象的索引
errorMessages 字符串数组 错误消息

针对 API 限制的限制

所有限制均根据用户应用：

  • 每个请求 100 个对象。
  • 每分钟 100 个请求。

如果请求数超过限制，响应标头中的一个 429 http 状态代码将随以下响应正文一起返回：

{
    "statusCode": 429,
    "message": "Rate limit is exceeded. Try again in <number of seconds> seconds."
}

在收到限制错误之前，每分钟大约 10,000 个对象是最大吞吐量。

示例指示器请求正文

以下示例演示如何在 STIX 规范中表示两个指示器。 Test Indicator 2 突出显示使用映射的对象标记设置为白色的交通灯协议（TLP），并阐明其说明和标签采用英语。

{
    "sourcesystem": "test", 
    "stixobjects":[
        {
            "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"
                }
            ]
        }
    ]
}

包含验证错误的示例响应正文

如果成功验证了所有 STIX 对象，则会使用空响应正文返回 HTTP 200 状态。

如果一个或多个对象的验证失败，则返回响应正文，其中包含更多信息。 例如，如果发送包含四个指示器的阵列，并且前三个指示器正常，但第四个没有 id（必填字段），则会生成 HTTP 状态代码 200 响应，其正文如下：

{
    "errors": [
        {
            "recordIndex":3, 
            "errorMessages": [
                "Error for Property=id: Required property is missing. Actual value: NULL."
            ]
        }
    ]
}

对象作为数组发送，因此从 recordIndex 以下位置 0开始。

其他示例

示例指示器

在此示例中，该指示器标有绿色 TLP。 还包括更多扩展属性toxicityrank和属性。 尽管这些属性不在指示器Microsoft Sentinel 架构中，但引入具有这些属性的对象不会触发错误。 这些属性只是不会在工作区中引用或编制索引。

{
    "sourcesystem": "TestStixObjects",
    "stixobjects": [
    {
          "type": "indicator",
          "spec_version": "2.1",
          "id": "indicator--12345678-71a2-445c-ab86-927291df48f8",
          "created": "2010-02-26T18:29:07.778Z",
          "modified": "2011-02-26T18:29:07.778Z",
          "created_by_ref": "identity--f431f809-377b-45e0-aa1c-6a4751cae5ff",
          "revoked": true,
          "labels": [
            "heartbleed",
            "has-logo"
          ],
          "confidence": 55,
          "lang": "en",
          "external_references": [
            {
              "source_name": "veris",
              "description": "Threat report",
              "external_id": "0001AA7F-C601-424A-B2B8-BE6C9F5164E7",
              "url": "https://abc.com//example.json",
              "hashes": {
                "SHA-256": "6db12788c37247f2316052e142f42f4b259d6561751e5f401a1ae2a6df9c674b"
              }
            }
          ],
          "object_marking_refs": [
            "marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da"
          ],
          "granular_markings": [
            {
              "marking_ref": "marking-definition--089a6ecb-cc15-43cc-9494-767639779123",
              "selectors": [
                "description",
                "labels"
              ],
              "lang": "en"
            }
          ],
          "extensions": {
            "extension-definition--d83fce45-ef58-4c6c-a3f4-1fbc32e98c6e": {
              "extension_type": "property-extension",
              "rank": 5,
              "toxicity": 8
            }
          },
          "name": "Indicator 2.1 Test",
          "description": "TS ID: 35766958; iType: bot_ip; State: active; Org: 52.3667; Source: Emerging Threats - Compromised",
          "indicator_types": [
            "threatstream-severity-low",
            "threatstream-confidence-80"
          ],
          "pattern": "[ipv4-addr:value = '94.102.52.185']",
          "pattern_type": "stix",
          "pattern_version": "2.1",
          "valid_from": "2015-02-26T18:29:07.778Z",
          "valid_until": "2016-02-26T18:29:07.778Z",
          "kill_chain_phases": [
            {
              "kill_chain_name": "lockheed-martin-cyber-kill-chain",
              "phase_name": "reconnaissance"
            }
          ]
        }
    ]
}

示例攻击模式

{
    "sourcesystem": "TestStixObjects",
    "stixobjects": [
        {
          "type": "attack-pattern",
          "spec_version": "2.1",
          "id": "attack-pattern--fb6aa549-c94a-4e45-b4fd-7e32602dad85",
          "created": "2015-05-15T09:12:16.432Z",
          "modified": "2015-05-20T09:12:16.432Z",
          "created_by_ref": "identity--f431f809-377b-45e0-aa1c-6a4751cae5ff",
          "revoked": false,
          "labels": [
            "heartbleed",
            "has-logo"
          ],
          "confidence": 55,
          "lang": "en",
          "object_marking_refs": [
            "marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da"
          ],
          "granular_markings": [
            {
              "marking_ref": "marking-definition--089a6ecb-cc15-43cc-9494-767639779123",
              "selectors": [
                "description",
                "labels"
              ],
              "lang": "en"
            }
          ],
          "extensions": {
            "extension-definition--d83fce45-ef58-4c6c-a3f4-1fbc32e98c6e": {
              "extension_type": "property-extension",
              "rank": 5,
              "toxicity": 8
            }
          },
          "external_references": [
            {
              "source_name": "capec",
              "description": "spear phishing",
              "external_id": "CAPEC-163"
            }
          ],
          "name": "Attack Pattern 2.1",
          "description": "menuPass appears to favor spear phishing to deliver payloads to the intended targets. While the attackers behind menuPass have used other RATs in their campaign, it appears that they use PIVY as their primary persistence mechanism.",
          "kill_chain_phases": [
            {
              "kill_chain_name": "mandiant-attack-lifecycle-model",
              "phase_name": "initial-compromise"
            }
          ],
          "aliases": [
            "alias_1",
            "alias_2"
          ]
        }
    ]
}

与威胁参与者和标识的示例关系

{
    "sourcesystem": "TestStixObjects",
    "stixobjects": [
    {
          "type": "identity",
          "spec_version": "2.1",
          "id": "identity--733c5838-34d9-4fbf-949c-62aba761184c",
          "created": "2016-08-23T18:05:49.307Z",
          "modified": "2016-08-23T18:05:49.307Z",
          "name": "Identity 2.1",
          "description": "Disco Team is the name of an organized threat actor crime-syndicate.",
          "identity_class": "organization",
          "contact_information": "disco-team@stealthemail.com",
          "roles": [
            "administrators"
          ],
          "sectors": [
            "education"
          ],
          "created_by_ref": "identity--f431f809-377b-45e0-aa1c-6a4751cae5ff",
          "revoked": true,
          "labels": [
            "heartbleed",
            "has-logo"
          ],
          "confidence": 55,
          "lang": "en",
          "external_references": [
            {
              "source_name": "veris",
              "description": "Threat report",
              "external_id": "0001AA7F-C601-424A-B2B8-BE6C9F5164E7",
              "url": "https://abc.com//example.json",
              "hashes": {
                "SHA-256": "6db12788c37247f2316052e142f42f4b259d6561751e5f401a1ae2a6df9c674b"
              }
            }
          ],
          "object_marking_refs": [
            "marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da"
          ],
          "granular_markings": [
            {
              "marking_ref": "marking-definition--089a6ecb-cc15-43cc-9494-767639779123",
              "selectors": [
                "description",
                "labels"
              ],
              "lang": "en"
            }
          ]
        },
        {
          "type": "threat-actor",
          "spec_version": "2.1",
          "id": "threat-actor--dfaa8d77-07e2-4e28-b2c8-92e9f7b04428",
          "created": "2014-11-19T23:39:03.893Z",
          "modified": "2014-11-19T23:39:03.893Z",
          "created_by_ref": "identity--f431f809-377b-45e0-aa1c-6a4751cae5ff",
          "revoked": true,
          "labels": [
            "heartbleed",
            "has-logo"
          ],
          "confidence": 55,
          "lang": "en",
          "external_references": [
            {
              "source_name": "veris",
              "description": "Threat report",
              "external_id": "0001AA7F-C601-424A-B2B8-BE6C9F5164E7",
              "url": "https://abc.com//example.json",
              "hashes": {
                "SHA-256": "6db12788c37247f2316052e142f42f4b259d6561751e5f401a1ae2a6df9c674b"
              }
            }
          ],
          "object_marking_refs": [
            "marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da"
          ],
          "granular_markings": [
            {
              "marking_ref": "marking-definition--089a6ecb-cc15-43cc-9494-767639779123",
              "selectors": [
                "description",
                "labels"
              ],
              "lang": "en"
            }
          ],
          "name": "Threat Actor 2.1",
          "description": "This organized threat actor group operates to create profit from all types of crime.",
          "threat_actor_types": [
            "crime-syndicate"
          ],
          "aliases": [
            "Equipo del Discoteca"
          ],
          "first_seen": "2014-01-19T23:39:03.893Z",
          "last_seen": "2014-11-19T23:39:03.893Z",
          "roles": [
            "agent"
          ],
          "goals": [
            "Steal Credit Card Information"
          ],
          "sophistication": "expert",
          "resource_level": "organization",
          "primary_motivation": "personal-gain",
          "secondary_motivations": [
            "dominance"
          ],
          "personal_motivations": [
            "revenge"
          ]
        },
        {
          "type": "relationship",
          "spec_version": "2.1",
          "id": "relationship--a2e3efb5-351d-4d46-97a0-6897ee7c77a0",
          "created": "2020-02-29T18:01:28.577Z",
          "modified": "2020-02-29T18:01:28.577Z",
          "relationship_type": "attributed-to",
          "description": "Description Relationship 2.1",
          "source_ref": "threat-actor--dfaa8d77-07e2-4e28-b2c8-92e9f7b04428",
          "target_ref": "identity--733c5838-34d9-4fbf-949c-62aba761184c",
          "start_time": "2020-02-29T18:01:28.577Z",
          "stop_time": "2020-03-01T18:01:28.577Z",
          "created_by_ref": "identity--f431f809-377b-45e0-aa1c-6a4751cae5ff",
          "revoked": true,
          "labels": [
            "heartbleed",
            "has-logo"
          ],
          "confidence": 55,
          "lang": "en",
          "external_references": [
            {
              "source_name": "veris",
              "description": "Threat report",
              "external_id": "0001AA7F-C601-424A-B2B8-BE6C9F5164E7",
              "url": "https://abc.com//example.json",
              "hashes": {
                "SHA-256": "6db12788c37247f2316052e142f42f4b259d6561751e5f401a1ae2a6df9c674b"
              }
            }
          ],
          "object_marking_refs": [
            "marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da"
          ],
          "granular_markings": [
            {
              "marking_ref": "marking-definition--089a6ecb-cc15-43cc-9494-767639779123",
              "selectors": [
                "description",
                "labels"
              ],
              "lang": "en"
            }
          ]
        }
    ]
}

后续步骤

有关如何在 Microsoft Sentinel 中处理威胁情报的详细信息，请参阅以下文章：