レガシ アップロード インジケーター API を参照する

Microsoft Sentinelのアップロード インジケーター API では、脅威インテリジェンス プラットフォームまたはカスタム アプリケーションが STIX 形式の侵害のインジケーターをMicrosoft Sentinel ワークスペースにインポートすることができました。 このドキュメントは、レガシ API への参照として機能します。

アップロード インジケーター API 呼び出しには、次の 5 つのコンポーネントがあります。

1. 要求 URI
2. HTTP 要求メッセージ ヘッダー
3. HTTP 要求メッセージ本文
4. 必要に応じて HTTP 応答メッセージ ヘッダーを処理する
5. 必要に応じて HTTP 応答メッセージ本文を処理する

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

Microsoft Sentinelに対する認証を行うには、アップロード インジケーター API への要求に有効なMicrosoft Entraアクセス トークンが必要です。 アプリケーションの登録の詳細については、「Microsoft ID プラットフォームにアプリケーションを登録する」を参照するか、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 認証ライブラリ 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 のクライアント ID}
• client_secret: {secret of Microsoft Entra App}
• スコープ： "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 つのバージョンでも表されていました。

1. コネクタ アクション名: 脅威インテリジェンス - 侵害のインジケーターのアップロード (非推奨)
   • エンドポイント： 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 オブジェクトには、次のフィールドが含まれています。

STIX 2.1 インジケーター形式仕様を使用してインジケーターの配列を作成します。これは、重要なセクションへのリンクを使用して便宜上ここで圧縮されています。 また、一部のプロパティは STIX 2.1 で有効ですが、Microsoft Sentinelに対応するインジケーター プロパティはありません。

応答メッセージを処理する

応答ヘッダーには HTTP 状態コードが含まれています。 API 呼び出し結果を解釈する方法の詳細については、この表を参照してください。

応答本文は、JSON 形式のエラー メッセージの配列です。

Error オブジェクト

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から始まります。

次の手順

この API はレガシです。 STIX オブジェクト API を使用して脅威インテリジェンスをアップロードするように移行してください。 詳細については、「 STIX オブジェクト API」を参照してください。