Microsoft Sentinel 上傳指標 API 允許威脅情報平台或自訂應用程式以 STIX 格式匯入入侵指標至 Microsoft Sentinel 工作空間。 本文件作為舊有 API 的參考。
重要事項
這個 API 目前處於預覽階段，但已不再推薦。 在預覽版中使用新的 STIX 物件 API 來上傳威脅情報。 欲了解更多資訊，請參閱 STIX 物件 API。 Azure 預覽補充條款包含適用於 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 接受的有效代幣。
你的應用程式收到的 token (v1.0 或 v2.0) 版本，是由 accessTokenAcceptedVersion 你應用程式呼叫的 API 的 App manifest 屬性決定的。 如果 accessTokenAcceptedVersion 設為 1，那麼你的應用程式會收到一個 v1.0 的 token。
使用 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 應用程式的客戶 ID}
- client_secret：{Microsoft Entra App 的祕密}
- 範圍：
"https://management.azure.com/.default"
如果 accessTokenAcceptedVersion 應用程式中的 manifest 設為 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 (需要) | 字串 | 請確認你的來源系統名稱。
Microsoft Sentinel價值是有限的。 |
| 指示器 () | 陣列 | STIX 2.0 或 2.1 格式的指示器陣列 |
請使用STIX 2.1指示器格式規範建立指示器陣列，該規範在此已為方便你濃縮，並附有重要章節連結。 另外請注意，雖然某些屬性適用於 STIX 2.1，但在 Microsoft Sentinel 中卻沒有相應的指示屬性。
| 內容名稱 | 類型 | 描述 |
|---|---|---|
id (需要) |
字串 | 用來識別指示器的識別碼。 關於如何建立 。id 格式大致如下 indicator--<UUID> |
spec_version (選) |
字串 | STIX指示器版本。 此值在 STIX 規範中是必需的，但由於此 API 僅支援 STIX 2.0 與 2.1，當此欄位未設定時，API 預設為 2.1 |
type (需要) |
字串 | 此財產的價值 必須 為 indicator。 |
created (需要) |
時間戳記 | 有關此公共財產的規格，請參見 第3.2 節。 |
modified (需要) |
時間戳記 | 有關此公共財產的規格，請參見 第3.2 節。 |
name (選) |
字串 | 用來識別指示器的名稱。 生產者 應 提供此特性，幫助產品與分析師了解該指標的實際作用。 |
description (選) |
字串 | 描述內容能提供更多關於指標的細節與背景，可能包括其目的及主要特徵。 生產者 應 提供此特性，幫助產品與分析師了解該指標的實際作用。 |
indicator_types (選) |
字串列表 | 此指標的一組分類。 此屬性 的值應 來自 indicator-type-ov |
pattern (需要) |
字串 | 此指示器的偵測模式 可用STIX 模式 或其他適當語言如 SNORT、YARA 等表示。 |
pattern_type (需要) |
字串 | 本指標所使用的模式語言。 此屬性 的價值應 來自 圖案類型。 此屬性的值 必須 與圖案屬性中包含的模式資料類型相符。 |
pattern_version (選) |
字串 | 模式屬性中資料所使用的模式語言版本 ，必須 與模式屬性中包含的模式資料類型相符。 對於沒有正式規範的模式， 應該 使用該模式已知可使用的建置版本或程式碼版本。 對於 STIX 模式語言，物件的規格版本決定預設值。 對於其他語言，預設 值應 為該物件建立時的模式語言最新版本。 |
valid_from (需要) |
時間戳記 | 該指標被視為其相關行為或代表行為有效指標的時間點。 |
valid_until (選) |
時間戳記 | 這個指標何時不再被視為其相關或代表行為的有效指標。 若省略valid_until性質，則對指示器有效的最新時間沒有限制。 這個時間戳 必須 大於valid_from的時間戳。 |
kill_chain_phases (選) |
字串列表 | 殺鏈階段 (s) ，該指示器對應此階段。 這個屬性 的價值應該 來自 擊殺連鎖階段。 |
created_by_ref (選) |
字串 | created_by_ref屬性指定了創建此物件的實體的ID屬性。 若省略此屬性，則資訊來源未定義。 對於希望保持匿名的物件創作者，請保持此數值不明確定義。 |
revoked (選) |
布林值 | 被撤銷的物件不再被物件建立者視為有效。 撤銷物件是永久性的;id再建立包含此物件的版本。此屬性的預設值為假值。 |
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 物件
| 欄位名稱 | 資料類型 | 描述 |
|---|---|---|
| 紀錄索引 | int | 請求中指標的索引 |
| 錯誤訊息 | 字串陣列 | 錯誤訊息 |
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 (a required field) ，那麼會產生一個 HTTP 狀態碼 200 的回應，並附帶以下內容：
{
"errors": [
{
"recordIndex":3,
"errorMessages": [
"Error for Property=id: Required property is missing. Actual value: NULL."
]
}
]
}
指示器以陣列形式傳送，因此 從 recordIndex 開始 0。
下一步
這個 API 是舊有的。 請遷移至 STIX 物件 API 來上傳威脅情報。 欲了解更多資訊，請參閱 STIX 物件 API。