Upload Indicators API (プレビュー) を参照して、脅威インテリジェンスを Microsoft Sentinel にインポートする

[アーティクル]
05/31/2024

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.net
https://management.azure.com/
https://management.azure.com

要求メッセージをアセンブルする

アップロードインジケーター API には 2 つのバージョンがあります。エンドポイントに応じて、要求本文には異なる配列名が必要です。これは、ロジックアプリコネクタアクションの 2 つのバージョンでも表されます。

Microsoft Sentinel アップロードインジケーター 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 (必須)	string	ソースシステム名を識別します。値 `Microsoft Sentinel` は制限されています。
インジケーター (必須)	配列	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", 
    "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 状態が空の応答本文で返されます。

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 データコネクタを有効にする

次の方法で共有

Upload Indicators API (プレビュー) を参照して、脅威インテリジェンスを Microsoft Sentinel にインポートする

Microsoft Entra ID にクライアントアプリケーションを登録する

アクセス許可

要求を作成する

アクセストークンの取得

要求メッセージをアセンブルする

要求 URI

要求ヘッダー

要求本文

応答メッセージの処理

API のスロットリング制限

要求本文の例

検証エラーを含む応答本文のサンプル

次のステップ

フィードバック

その他のリソース

次の方法で共有

Upload Indicators API (プレビュー) を参照して、脅威インテリジェンスを Microsoft Sentinel にインポートする

Microsoft Entra ID にクライアント アプリケーションを登録する

アクセス許可

要求を作成する

アクセス トークンの取得

要求メッセージをアセンブルする

要求 URI

要求ヘッダー

要求本文

応答メッセージの処理

API のスロットリング制限

要求本文の例

検証エラーを含む応答本文のサンプル

次のステップ

フィードバック

その他のリソース

Microsoft Entra ID にクライアントアプリケーションを登録する

アクセストークンの取得