共用方式為

使用上傳 API 將威脅情報匯入至 Microsoft Sentinel （預覽）

  • 發行項
  • 適用於:
    Microsoft Sentinel in the Azure portal

匯入威脅情報，以搭配上傳 API Microsoft Sentinel 中使用。 無論您是使用威脅情報平臺或自定義應用程式，請使用這份檔作為將 TIP 與上傳 API 連接中指示的補充參考。 不需要安裝數據連接器才能連線到 API。 您可以匯入的威脅情報包括入侵指標和其他 STIX 網域物件。

重要

此 API 目前為預覽狀態。 Azure 預覽補充條款 包含適用於 Azure 功能 (搶鮮版 (Beta)、預覽版，或尚未發行的版本) 的其他法律條款。

結構化威脅資訊表達式 （STIX） 是表達網路威脅和可觀察信息的語言。 上傳 API 包含下列網域物件的增強支援：

  • 指示器
  • 攻擊模式
  • 威脅執行者
  • identity
  • 關聯

如需詳細資訊，請參閱 STIX 簡介。

注意

先前的上傳指標 API 現在是舊版。 如果您需要在轉換至這個新的上傳 API 時參考該 API，請參閱 舊版上傳指標 API。

呼叫 API

對上傳 API 的呼叫有五個元件：

  1. 要求 URI
  2. HTTP 要求訊息標頭
  3. HTTP 要求訊息本文
  4. 選擇性地處理 HTTP 回應消息標頭
  5. 選擇性地處理 HTTP 回應消息本文

使用 Microsoft Entra 識別元註冊用戶端應用程式

為了向 Sentinel 驗證Microsoft，上傳 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：

  • POST https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token
  • 使用 Microsoft Entra 應用程式的標頭：
  • grant_type：“client_credentials”
  • client_id： {Microsoft Entra App} 的用戶端標識符
  • 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.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 （必要） 字串 識別您的來源系統名稱。 此值 Microsoft Sentinel 會受到限制。
stixobjects （必要） 陣列 STIX 2.0 或 2.1 格式的 STIX 物件 陣列

使用 STIX 格式規格建立 STIX 物件的陣列。 這裡擴充了一些 STIX 屬性規格，方便您使用相關 STIX 檔章節的連結。 另請注意，某些屬性在 STIX 有效時，在 Sentinel Microsoft沒有對應的物件架構屬性。

通用屬性

您使用上傳 API 匯入的所有物件都會分享這些通用屬性。

屬性名稱 類型​ 描述
id （必要） 字串 用來識別 STIX 物件的識別碼。 如需如何建立id的規格，請參閱 2.9 節。 格式看起來像這樣 indicator--<UUID>
spec_version (選用) 字串 STIX 物件版本。 STIX 規格中需要這個值，但因為此 API 只支援 STIX 2.0 和 2.1，因此未設定此字段時，API 預設為 2.1
type （必要） 字串 這個屬性 的值必須是 支援的 STIX 物件。
created （必要） timestamp 如需此通用屬性的規格，請參閱第 3.2 節。
created_by_ref (選用) 字串 created_by_ref 屬性會指定建立此物件之實體的ID屬性。

如果省略此屬性，則此資訊的來源為未定義。 對於想要保持匿名的物件建立者，請將此值保持未定義。
modified （必要） timestamp 如需此通用屬性的規格，請參閱第 3.2 節。
revoked (選用) boolean 物件建立者不再將撤銷的物件視為有效。 撤銷物件是永久的;未來版本的物件不得以此id建立。

此屬性的預設值為 false。
labels (選用) 字串清單 屬性 labels 會指定一組用來描述此物件的詞彙。 這些詞彙是使用者定義的或信任群組定義。 這些標籤會顯示為 Sentinel 中Microsoft標籤 。
confidence (選用) 整數 屬性 confidence 會識別建立者對其數據正確性的信心。 信賴值 必須是 介於 0-100 範圍內的數位。

附錄 A 包含一份規範對應表，與在其中一個尺規中呈現信賴值時，必須使用的其他信賴度尺規。

如果信賴屬性不存在，則不會指定內容的信賴度。
lang (選用) 字串 屬性 lang 會識別這個物件中文字內容的語言。 當存在時，它 必須是 符合 RFC5646的語言程序代碼。 如果屬性不存在，則內容的語言為 en （英文）。

如果物件類型包含可轉譯的文字屬性，則此屬性應該存在（例如名稱、描述）。

此物件中個別欄位的語言可能會以細微標記覆寫 lang 屬性（請參閱 7.2.3 節）。
object_marking_refs （選擇性，包括TLP） 字串清單 屬性 object_marking_refs 會指定套用至這個物件的標記定義對象的識別元屬性清單。 例如，使用交通燈通訊協定 （TLP） 標記定義標識符來指定指標來源的敏感度。 如需要用於 TLP 內容之標記定義標識碼的詳細資訊，請參閱 7.2.1.4 節

在某些情況下，雖然不常見，但標記定義本身可能會標示為共用或處理指引。 在此情況下，這個屬性 不得 包含相同標記定義物件的任何參考（也就是說，它不能包含任何循環參考）。

如需進一步定義數據標記，請參閱 7.2.2 節。
external_references (選用) 物件清單 屬性 external_references 會指定參考非 STIX 資訊的外部參考清單。 這個屬性可用來提供一或多個 URL、描述或識別碼給其他系統中的記錄。
granular_markings (選用) 細微標記清單 屬性 granular_markings 有助於以不同的方式定義指標的元件。 例如，指標語言為英文， en 但描述為德文， de。

在某些情況下，雖然不常見，但標記定義本身可能會標示為共用或處理指引。 在此情況下，這個屬性 不得 包含相同標記定義物件的任何參考（也就是說，它不能包含任何循環參考）。

如需進一步定義數據標記，請參閱 7.2.3 節。

如需詳細資訊，請參閱 STIX 通用屬性。

指標

屬性名稱 類型​ 描述
name (選用) 字串 用來識別指標的名稱。

生產者應該提供此屬性，以幫助產品和分析師瞭解此指標的實際用途。
description (選用) 字串 描述，提供指標的詳細數據和內容，可能包括其用途及其主要特性。

生產者應該提供此屬性，以幫助產品和分析師瞭解此指標的實際用途。
indicator_types (選用) 字串清單 此指標的一組分類。

此屬性 的值應該 來自 indicator-type-ov
pattern （必要） 字串 此指標 的偵測模式可能會 以 STIX 模式 或另一種適當的語言表示，例如 SNORT、YARA 等。
pattern_type （必要） 字串 此指標中使用的模式語言。

此屬性 的值應該 來自 模式類型。

這個屬性 的值必須 符合 pattern 屬性中包含的模式數據類型。
pattern_version (選用) 字串 模式屬性中用於數據之模式語言的版本，必須符合 pattern 屬性中包含的模式數據類型。

對於沒有正式規格的模式，應該使用模式已知使用的組建或程式代碼版本。

針對 STIX 模式語言，對象的規格版本會決定預設值。

若為其他語言，預設值 應該是 此物件建立時模式語言的最新版本。
valid_from （必要） timestamp 此指標視為與 或表示之行為的有效指標的時間。
valid_until (選用) timestamp 此指標不應再視為與 或 表示之行為的有效指標。

如果省略valid_until屬性，則指標有效的最新時間沒有條件約束。

此時間戳 必須 大於valid_from時間戳。
kill_chain_phases (選用) 字串清單 這個指針對應的終止鏈結階段。

此屬性 的值應該 來自 Kill Chain Phase。

如需詳細資訊，請參閱 STIX 指標。

攻擊模式

如需詳細資訊，請參閱 STIX 攻擊模式。

身分識別

如需詳細資訊，請參閱 STIX 身分識別。

威脅執行者

如需詳細資訊，請參閱 STIX 威脅執行者。

關聯

如需詳細資訊，請參閱 STIX 關聯性。

處理回應訊息

回應標頭包含 HTTP 狀態代碼。 如需如何解譯 API 呼叫結果的詳細資訊，請參閱此數據表。

狀態碼 描述
200 成功。 當一或多個 STIX 物件成功驗證併發佈時，API 會傳回 200。
400 格式不正確。 要求中的專案格式不正確。
401 未經授權。
404 找不到檔案。 通常當找不到工作區標識符時，就會發生此錯誤。
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 標示。 也包含和 rank 的更多擴充屬性toxicity。 雖然這些屬性不在指標的 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 中使用威脅情報，請參閱下列文章：