參考上傳指標 API （預覽） 將威脅情報匯入至 sentinel Microsoft
Microsoft Sentinel 上傳指標 API 可讓威脅情報平臺或自定義應用程式將 STIX 格式的入侵指標匯入Microsoft Sentinel 工作區。 無論您搭配使用 API 搭配 Microsoft Sentinel 上傳指標 API 數據連接器 ，還是作為自定義解決方案的一部分，本檔都可作為參考。
重要
此 API 目前為預覽狀態。 Azure 預覽補充條款 包含適用於 Azure 功能 (搶鮮版 (Beta)、預覽版，或尚未發行的版本) 的其他法律條款。
上傳指標 API 呼叫有五個元件：
- 要求 URI
- HTTP 要求訊息標頭
- HTTP 要求訊息本文
- 選擇性地處理 HTTP 回應消息標頭
- 選擇性地處理 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.nethttps://management.azure.com/https://management.azure.com
組合要求訊息
上傳指標 API 有兩個版本。 根據端點而定，要求主體中需要不同的數位名稱。 這也會以兩個版本的邏輯應用程式連接器動作來表示。
連接器動作名稱： 威脅情報 - 上傳入侵指標（已淘汰）
- 端點：
https://sentinelus.azure-api.net/{workspaceId}/threatintelligence:upload-indicators - 指標名稱的陣列：
value{ "sourcesystem":"TIsource-example", "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 有效時，在 sentinel Microsoft沒有對應的指標屬性。
| 屬性名稱 | 類型 | 描述 |
|---|---|---|
id （必要） |
字串 | 用來識別指標的標識碼。 如需如何建立id的規格，請參閱 2.9 節。 格式看起來像這樣 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 （必要） |
字串 | 此指標 的偵測模式可能會 以 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。 |
created_by_ref (選用) |
字串 | created_by_ref 屬性會指定建立此物件之實體的ID屬性。 如果省略此屬性，則此資訊的來源為未定義。 對於想要保持匿名的物件建立者，請將此值保持未定義。 |
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 節。 |
處理回應訊息
回應標頭包含 HTTP 狀態代碼。 如需如何解譯 API 呼叫結果的詳細資訊，請參閱此數據表。
| 狀態碼 | 描述 |
|---|---|
| 200 | 成功。 當成功驗證併發佈一或多個指標時，API 會傳回 200。 |
| 400 | 格式不正確。 要求中的專案格式不正確。 |
| 401 | 未經授權。 |
| 404 | 找不到檔案。 通常當找不到工作區標識符時，就會發生此錯誤。 |
| 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。
下一步
若要深入瞭解如何在 Microsoft Sentinel 中使用威脅情報，請參閱下列文章：
- 了解威脅情報
- 使用威脅指標
- 使用比對分析來偵測威脅
- 利用來自 Microsoft 的智慧摘要，並 啟用 MDTI 數據連接器