Upload Indicators API (プレビュー) を参照して、脅威インテリジェンスを Microsoft Sentinel にインポートする
Microsoft Sentinel Upload Indicators API を使用すると、脅威インテリジェンス プラットフォームまたはカスタム アプリケーションで、STIX 形式の侵害インジケーターを Microsoft Sentinel ワークスペースにインポートできます。 Microsoft Sentinel Upload Indicators API データ コネクタで API を使用する場合でも、カスタム ソリューションの一部として使用する場合でも、このドキュメントはリファレンスとして使用できます。
重要
現在、この API はプレビュー段階です。 Azure プレビューの追加使用条件には、ベータ版、プレビュー版、またはまだ一般提供されていない Azure 機能に適用される追加の法律条項が含まれています。
Upload Indicators API 呼び出しには、次の 5 つのコンポーネントがあります。
- 要求 URI
- HTTP 要求メッセージ ヘッダー
- HTTP 要求メッセージ本文
- 必要に応じて HTTP 応答メッセージ ヘッダーを処理する
- 必要に応じて HTTP 応答メッセージ本文を処理する
Microsoft Entra ID にクライアント アプリケーションを登録する
Microsoft Sentinel に対して認証を行うには、Upload Indicators API への要求には、有効な Microsoft Entra アクセス トークンが必要です。 アプリケーション登録の詳細については、「アプリケーションをMicrosoft ID プラットフォームに登録する」を参照するか、Upload Indicators API データ コネクタのセットアップの一部としての基本的な手順を参照してください。
アクセス許可
この API を使用するには、呼び出し元の Microsoft Entra アプリケーションに、ワークスペース レベルで Microsoft Sentinel 共同作成者ロールが付与されている必要があります。
要求を作成する
このセクションでは、前に挙げた 5 つのコンポーネントの最初の 3 つについて説明します。 最初に、要求メッセージ ヘッダーのアセンブルに使用する Microsoft Entra ID からのアクセス トークンを取得する必要があります。
アクセス トークンの取得
OAuth 2.0 認証を使用して Microsoft Entra アクセス トークンを取得します。 V1.0 と V2.0 は、API によって受け入れられる有効なトークンです。
アプリケーションが受け取るトークン (v1.0 または v2.0) のバージョンは、アプリケーションが呼び出している API のアプリ マニフェスト の accessTokenAcceptedVersion プロパティ によって決まります。 accessTokenAcceptedVersion が 1 に設定されている場合、アプリケーションは v1.0 トークンを受け取ります。
Microsoft Authentication Library 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.nethttps://management.azure.com/https://management.azure.com
要求メッセージをアセンブルする
要求 URI
API のバージョン管理: api-version=2022-07-01
エンドポイント: https://sentinelus.azure-api.net/{workspaceId}/threatintelligence:upload-indicators?api-version=2022-07-01
メソッド: POST
要求ヘッダー
Authorization: OAuth2 ベアラー トークンを含む
Content-Type: application/json
要求本文
本文の JSON オブジェクトには、次のフィールドが含まれています。
| フィールド名 | データ型 | 説明 |
|---|---|---|
| SourceSystem (必須) | string | ソース システム名を識別します。 値 Microsoft Sentinel は制限されています。 |
| Value (必須) | array | STIX 2.0 または 2.1 形式のインジケーターの配列 |
STIX 2.1 インジケーター形式仕様を使用して、インジケーターの配列を作成します。これは、ここでは、参考までに重要なセクションへのリンクを含めて要約されています。 また、一部のプロパティが、STIX 2.1 では有効でも、Microsoft Sentinel に対応するインジケーター プロパティがないことにも注意してください。
| プロパティ名 | 種類 | 説明 |
|---|---|---|
id (必須) |
string | インジケーターを識別するために使用される ID。 id の作成方法の仕様については、セクション 2.9 を参照してください。 indicator--<UUID> のような形式になります |
spec_version (省略可) |
string | STIX インジケーターのバージョン。 この値は STIX 仕様で必要ですが、この API は STIX 2.0 と 2.1 のみをサポートしているため、このフィールドが設定されていない場合、API は既定で 2.1 に設定されます。 |
type (必須) |
string | このプロパティの値は indicator でなければなりません。 |
created (必須) |
タイムスタンプ | この共通プロパティの仕様については、セクション 3.2 を参照してください。 |
modified (必須) |
タイムスタンプ | この共通プロパティの仕様については、セクション 3.2 を参照してください。 |
name (任意) |
string | インジケーターを識別するために使用される名前。 作成者は、このインジケーターが実際に何を行うかを製品やアナリストが理解できるように、このプロパティを提供する必要があります。 |
description (省略可) |
string | インジケーターに関する詳細とコンテキストを提供する説明。その目的とその主要な特性が含まれている可能性があります。 作成者は、このインジケーターが実際に何を行うかを製品やアナリストが理解できるように、このプロパティを提供する必要があります。 |
indicator_types (省略可) |
文字列のリスト | このインジケーターの一連の分類。 このプロパティの値は、indicator-type-ov に由来するはずです |
pattern (必須) |
string | このインジケーターの検出パターンは、STIX パターンまたは SNORT、YARA などの別の適切な言語として表現されることがあります。 |
pattern_type (必須) |
string | このインジケーターで使用されるパターン言語。 このプロパティの値は、パターン型に由来するはずです。 このプロパティの値は、pattern プロパティに含まれるパターン データの種類と一致していなければなりません。 |
pattern_version (省略可) |
string | pattern プロパティのデータに使用されるパターン言語のバージョン。pattern プロパティに含まれるパターン データの種類と一致していなければなりません。 正式な仕様がないパターンの場合は、パターンが動作することがわかっているビルドまたはコード バージョンを使用する必要があります。 STIX パターン言語の場合、オブジェクトの仕様バージョンによって既定値が決まります。 他の言語の場合、既定値は、このオブジェクトの作成時の最新バージョンのパターン言語である必要があります。 |
valid_from (必須) |
タイムスタンプ | このインジケーターが、関連する、または表す動作の有効なインジケーターと見なされる時間。 |
valid_until (省略可) |
タイムスタンプ | このインジケーターが、関連する、または表す動作の有効なインジケーターと見なされなくなる時間。 valid_until プロパティを省略した場合、インジケーターが有効である最新時刻に制約はありません。 このタイムスタンプは、valid_fromタイムスタンプより大きくなければなりません。 |
kill_chain_phases (省略可) |
文字列の一覧 | このインジケーターが対応するキル チェーン フェーズ。 このプロパティの値は、Kill Chain Phase に由来するはずです。 |
created_by_ref (省略可) |
string | created_by_ref プロパティは、このオブジェクトを作成したエンティティの ID プロパティを指定します。 この属性を省略すると、この情報のソースは未定義になります。 匿名を維持するオブジェクト作成者の場合は、この値を未定義のままにします。 |
revoked (省略可) |
boolean | 取り消されたオブジェクトは、オブジェクト作成者によって有効と見なされなくなります。 オブジェクトの取り消しは永続的な処理です。この id を伴うオブジェクトの将来のバージョンを作成することはできません。このプロパティの既定値は false です。 |
labels (省略可) |
文字列のリスト | labels プロパティは、このオブジェクトを記述するために使用される一連の用語を指定します。 用語は、ユーザー定義または信頼グループ定義です。 これらのラベルは、Microsoft Sentinel でタグとして表示されます。 |
confidence (省略可) |
整数 (integer) | confidence プロパティは、作成者がデータの正確性についてもっている信頼度を識別します。 confidence の値は、0 から 100 の範囲の数値でなければなりません。付録 A には、いずれかのスケールで confidence の値を提示するときに使用しなければならない他の confidence スケールへの規範的なマッピングのテーブルが含まれています。 confidence プロパティが存在しない場合、コンテンツの信頼度は指定されません。 |
lang (省略可) |
string | lang プロパティは、このオブジェクト内のテキスト コンテンツの言語を識別します。 存在する場合は、RFC5646 に準拠した言語コードでなければなりません。 プロパティが存在しない場合、コンテンツの言語は en (英語) になります。このプロパティは、オブジェクトの種類に翻訳可能なテキスト プロパティ (名前、説明など) が含まれている場合に存在する必要があります。 このオブジェクトの個々のフィールドの言語は、細かいマーキングで lang プロパティをオーバーライドする可能性があります (セクション 7.2.3 を参照)。 |
object_marking_refs (省略可能、TLP を含む) |
文字列のリスト | object_marking_refs プロパティは、このオブジェクトに適用されるマーキング定義オブジェクトの ID プロパティの一覧を指定します。 たとえば、Traffic Light Protocol (TLP) マーキング定義 ID を使用して、インジケーター ソースの機密度を指定します。 TLP コンテンツに使用するマーキング定義 ID の詳細については、セクション 7.2.1.4 を参照してください。一般的ではありませんが、場合によっては、マーキング定義そのものが、共有または処理のガイダンスでマークされる場合があります。 この場合、このプロパティには、同じマーキング定義オブジェクトへの参照を含めることはできません (つまり、循環参照を含めることはできません)。 データ マーキングの詳細な定義については、セクション 7.2.2 を参照してください。 |
external_references (省略可) |
オブジェクトの一覧 | external_references プロパティは、STIX 以外の情報を参照する外部参照のリストを指定します。 このプロパティは、1 つ以上の URL、説明、または ID を他のシステム内のレコードに提供するために使用されます。 |
granular_markings (省略可) |
詳細なマーキングの一覧 | granular_markings プロパティは、インジケーターの一部を異なる方法で定義するのに役立ちます。 たとえば、インジケーター言語は英語 (en) ですが、説明はドイツ語 (de) です。一般的ではありませんが、場合によっては、マーキング定義そのものが、共有または処理のガイダンスでマークされる場合があります。 この場合、このプロパティには、同じマーキング定義オブジェクトへの参照を含めることはできません (つまり、循環参照を含めることはできません)。 データ マーキングの詳細な定義については、セクション 7.2.3 を参照してください。 |
応答メッセージの処理
応答ヘッダーには、HTTP 状態コードが含まれています。 API 呼び出しの結果を解釈する方法の詳細については、この表を参照してください。
| 状態コード | 説明 |
|---|---|
| 200 | 成功しました。 1 つ以上のインジケーターが正常に検証され発行されると、API は 200 を返します。 |
| 400 | 形式が正しくありません 要求内に正しくない書式設定があります。 |
| 401 | 権限がありません。 |
| 404 | ファイルが見つかりません。 通常、このエラーは、ワークスペース ID が見つからない場合に発生します。 |
| 429 | 1 分間の要求の数が超過しました。 |
| 500 | サーバー エラー。 通常、API サービスまたは Microsoft Sentinel サービスのエラーです。 |
応答の本文は、JSON 形式のエラー メッセージの配列です。
| フィールド名 | データ型 | 説明 |
|---|---|---|
| エラー | エラー オブジェクトの配列 | 検証エラーの一覧 |
Error オブジェクト
| フィールド名 | データ型 | 説明 |
|---|---|---|
| recordIndex | int | 要求内のインジケーターのインデックス |
| errorMessages | 文字列の配列 | エラー メッセージ |
API のスロットリング制限
すべての制限が、ユーザーごとに適用されます。
- 要求ごとに 100 個のインジケーター。
- 1 分あたり 100 の要求。
制限より多くの要求がある場合は、応答ヘッダーの 429 http 状態コードが、次の応答本文で返されます。
{
"statusCode": 429,
"message": "Rate limit is exceeded. Try again in <number of seconds> seconds."
}
調整エラーを受信する前の最大スループットは、1 分あたり約 10,000 個のインジケーターです。
要求本文の例
{
"sourcesystem": "test",
"value":[
{
"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 状態が空の応答本文で返されます。
1 つ以上のインジケーターについて検証が失敗した場合、応答本文は詳細情報と共に返されます。 たとえば、4 つのインジケーターを含む配列を送信し、最初の 3 つが適切だが、4 番目のインジケーターに id (必須フィールド) がない場合、HTTP 状態コード 200 応答が次の本文と共に生成されます。
{
"errors": [
{
"recordIndex":3,
"errorMessages": [
"Error for Property=id: Required property is missing. Actual value: NULL."
]
}
]
}
インジケーターは配列として送信されるため、recordIndex は 0 から始まります。
次のステップ
Microsoft Sentinel の脅威インテリジェンスで作業するための詳細については、次の記事を参照してください。
- 脅威インテリジェンスを理解する
- 脅威インジケーターの操作
- 照合分析を使用して脅威を検出する
- Microsoft のインテリジェンス フィードを利用して、MDTI データ コネクタを有効にする