透過上傳 API (預覽) 將威脅情報匯入 Microsoft Sentinel

適用於: Microsoft Sentinel in the Azure portal

透過上傳 API 匯入威脅情報以用於 Microsoft Sentinel。無論你使用威脅情報平台還是自訂應用程式，請將此文件作為「將你的 TIP 與上傳 API 連結」說明的補充參考。安裝資料連接器並非連接 API 的必要條件。你能匯入的威脅情報包含入侵指標及其他 STIX 網域物件。

重要事項

此 API 目前處於預覽階段。 Azure 預覽補充條款包含適用於 Azure 測試版、預覽版或其他尚未正式發布的功能的額外法律條款。

結構化威脅資訊表達 STIX () 是一種用來表達網路威脅及可觀察資訊的語言。上傳 API 包含對以下網域物件的強化支援：

指示器
攻擊模式
威脅行為者
身分識別
關聯

欲了解更多資訊，請參閱《STIX導論》。

注意事項

先前的上傳指示器 API 現在是舊有的。如果你在轉換到這個新的上傳 API 時需要參考該 API，請參考舊有的上傳指示器 API。

呼叫 API

呼叫上傳 API 包含五個組件：

請求 URI
HTTP 請求訊息標頭
HTTP 請求訊息主體
可選擇性地處理 HTTP 回應訊息標頭
可選擇性地處理 HTTP 回應訊息主體

用 Microsoft Entra ID 註冊你的客戶端應用程式

為了向 Microsoft Sentinel 進行認證，上傳 API 的請求需要有效的 Microsoft Entra 存取權杖。欲了解更多應用程式註冊資訊，請參閱「以 Microsoft 身分識別平台註冊應用程式」或參考「Connect 威脅情報與上傳 API 設定」中的基本步驟。

此 API 要求呼叫的 Microsoft Entra 應用程式必須在工作空間層級被授予 Microsoft Sentinel 貢獻者角色。

建立請求

本節涵蓋前述五個組成部分中的前三個。你首先需要從 Microsoft Entra ID 取得存取權杖，用它來組合你的請求訊息標頭。

取得存取權杖

取得帶有 OAuth 2.0 認證的 Microsoft Entra 存取權杖。 V1.0 和 V2.0 是 API 接受的有效代幣。

收到的 v1.0 或 v2.0) (token 版本是由應用程式呼叫的 API 應用程式accessTokenAcceptedVersion中的屬性決定。如果 accessTokenAcceptedVersion 設為 1，那麼你的應用程式會收到一個 v1.0 的標記。

Microsoft MSAL) ( 認證函式庫取得 v1.0 或 v2.0 存取權杖。使用存取權杖建立包含持有憑證的授權標頭。

例如，對上傳 API 的請求會使用以下元素來取得存取權杖並建立授權標頭，該標頭會在每個請求中使用：

後期 https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token

使用 Microsoft Entra 應用程式的標頭：

grant_type：「client_credentials」
client_id：{Microsoft Entra 應用程式的客戶 ID}
client_secret或client_certificate：{Microsoft Entra App 的祕密}
範圍： "https://management.azure.com/.default"

如果 accessTokenAcceptedVersion 應用程式中的 manifest 設為 1，你的應用程式會收到 v1.0 的存取權杖，即使它正在呼叫 v2 的權杖端點。

資源/範圍值是該代幣的受眾。此 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，但在 Microsoft Sentinel 裡沒有對應的物件結構屬性。

警告

如果你使用 Microsoft Sentinel Logic App 連接上傳 API，請注意有三種威脅情報行動可用。只使用 威脅情報 - 上傳 STIX 物件 (預覽) 。另外兩個會在這個端點和 JSON 主體欄位時失敗。

範例請求訊息

這裡有一個範例 PowerShell 函式，利用上傳到 Entra 應用程式註冊的自簽憑證，產生存取權杖和授權標頭：

function Test-UploadApi {
<#
.SYNOPSIS
    requires Powershell module MSAL.PS version 4.37 or higher
    https://www.powershellgallery.com/packages/MSAL.PS/
.EXAMPLE
    Test-Api -API UploadApi -WorkspaceName "workspacename" -ResourceGroupName "rgname" -AppId "00001111-aaaa-2222-bbbb-3333cccc4444" -TenantName "contoso.onmicrosoft.com" -FilePath "C:\Users\user\Documents\stixobjects.json"
#>
[CmdletBinding()]
param (
    [Parameter(Mandatory = $true)]
    [string]$TenantName,
    [Parameter(Mandatory = $true)]
    [string]$CertThumbprint,
    [Parameter(Mandatory = $true)]
    [string]$AppId,
    [Parameter(Mandatory = $true)]
    [string]$WorkspaceId,
    [Parameter(Mandatory = $true)]
    [string]$FilePath
)
$Scope = "https://management.azure.com/.default"
# Connection details for getting initial token with self-signed certificate from local store
$connectionDetails = @{
    'TenantId'          = $TenantName
    'ClientId'          = $AppId
    'ClientCertificate' = Get-Item -Path "Cert:\CurrentUser\My\$CertThumbprint"
    scope               = $Scope
}
# Request the token
#  Using Powershell module MSAL.PS https://www.powershellgallery.com/packages/MSAL.PS/
#  Get-MsalToken is automatically using OAuth 2.0 token endpoint https://login.microsoftonline.com/$TenantName/oauth2/v2.0/token
#  and sets auth flow to grant_type = 'client_credentials'
$token = Get-MsalToken @connectionDetails

# Create header
#  Again relying on MSAL.PS which has method CreateAuthorizationHeader() getting us the bearer token
$Header = @{
    'Authorization' = $token.CreateAuthorizationHeader()
}
$Uri = "https://api.ti.sentinel.azure.com/workspaces/$workspaceId/threat-intelligence-stix-objects:upload?api-version=$apiVersion"
$stixobjects = get-content -path $FilePath
if(-not $stixobjects) { Write-Host "No file found at $FilePath"; break }
$results = Invoke-RestMethod -Uri $Uri -Headers $Header -Body $stixobjects -Method POST -ContentType "application/json"

$results | ConvertTo-Json -Depth 4
}

常見特性

你用上傳 API 匯入的所有物件都共享這些共同屬性。

內容名稱	類型	描述
`id` (需要)	字串	一個用來識別 STIX 物件的 ID。關於如何建立。`id` 格式大致如下 `indicator--<UUID>`
`spec_version` (選)	字串	STIX 物件版本。此值在 STIX 規範中是必需的，但由於此 API 僅支援 STIX 2.0 和 2.1，當此欄位未設定時，API 預設為 `2.0`
`type` (需要)	字串	此屬性的值必須是支援的 STIX 物件。
`created` (需要)	時間戳記	有關此公共財產的規格，請參見第3.2 節。
`created_by_ref` (選)	字串	created_by_ref屬性指定了創建此物件的實體的ID屬性。若省略此屬性，則資訊來源未定義。對於希望保持匿名的物件創作者，請保持此數值不明確定義。
`modified` (需要)	時間戳記	有關此公共財產的規格，請參見第3.2 節。
`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 節以了解資料標記的進一步定義。

欲了解更多資訊，請參閱 STIX 常見特性。

指標

內容名稱	類型	描述
`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` (選)	字串列表	該指示器所對應的殺鏈階段。這個屬性的價值應該來自擊殺連鎖階段。

欲了解更多資訊，請參閱 STIX 指標。

攻擊模式

請依照 STIX 規範建立攻擊模式 STIX 物件。用這個例子作為額外參考。

欲了解更多資訊，請參閱 STIX 攻擊模式。

身分識別

請依照 STIX 規範建立身份 STIX 物件。用這個例子作為額外參考。

欲了解更多資訊，請參閱 STIX 身份。

威脅行為者

請依照 STIX 規範建立威脅行為者 STIX 物件。用這個例子作為額外參考。

欲了解更多資訊，請參閱 STIX 威脅行動者。

關聯

請依照 STIX 規範建立關係 STIX 物件。用這個例子作為額外參考。

欲了解更多資訊，請參閱 STIX關係。

處理回應訊息

回應標頭包含 HTTP 狀態碼。請參閱此表格以了解如何解讀 API 呼叫結果的更多資訊。

狀態碼	描述
200	成功。當一個或多個 STIX 物件成功驗證並發佈時，API 會回傳 200。
400	格式不好。請求裡有些東西格式不正確。
401	未經授權。
404	檔案未找到。通常這個錯誤發生在找不到工作區 ID 時。
429	每分鐘最多請求數已被超越。
500	伺服器錯誤。通常是 API 或 Microsoft Sentinel 服務出錯。

回應主體是一個以 JSON 格式排列的錯誤訊息陣列：

欄位名稱	資料類型	描述
錯誤	錯誤物件陣列	驗證錯誤列表

Error 物件

欄位名稱	資料類型	描述
紀錄索引	int	請求中 STIX 物件的索引
錯誤訊息	字串陣列	錯誤訊息

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 (a required field) ，那麼會產生一個 HTTP 狀態碼 200 的回應，並附帶以下內容：

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

物件以陣列形式傳送，因此從 recordIndex0開始。

其他取樣

樣本指示器

在此範例中，指示器以綠色TLP標記，並 marking-definition--089a6ecb-cc15-43cc-9494-767639779123 於公共財產中使用 object_marking_refs 。也包含了和 toxicity 的rank更多擴展屬性。雖然這些屬性不在 Microsoft Sentinel 的指示器結構中，但匯入帶有這些屬性的物件並不會觸發錯誤。這些屬性在工作區中根本沒有被引用或索引。