Chronicle Ingestion API

Chronicle Ingestion API を使用すると、ログを Chronicle インスタンスに直接転送できるため、環境にハードウェアやソフトウェア（フォワーダーなど）を追加する必要がなくなります。

Chronicle Ingestion API は、JSON ペイロードを使用する RESTful API です。マネージド セキュリティ サービス プロバイダ（MSSP）と技術パートナーは、Chronicle Ingestion API を直接呼び出して Chronicle にログを転送するシステムを開発できます。

Ingestion API は、以下をサポートしています。

  • UDM イベント
  • 非構造化ログ
  • ログタイプの取得

以下の Chronicle Ingestion API エンドポイント タイプのいずれかを使用して、データを Chronicle に転送できます。

  • 統合データモデル（UDM）イベント
  • 非構造化ログ

Chronicle の UDM を使用してログデータをフォーマットした場合、UDM API エンドポイントを使用して、UDM イベントを Chronicle アカウントに転送できます。UDM イベントは標準化されているため、Chronicle では効果的にデータを処理および解釈でき、企業内のセキュリティ侵害および脅威に対する Chronicle の認識能力を向上させることができます。未加工ログを UDM に変換する方法については、ログデータを UDM としてフォーマットするをご覧ください。

また、非構造化ログ API エンドポイントを使用して、データを非構造化ログとして Chronicle に転送することもできます。非構造化ログデータは Chronicleインフラストラクチャ内で正規化され、Chronicle UI を通じて入手できるようになります。ただし、一部の情報は非構造化ログデータからの抽出が難しく、未加工ログスキャンを使用した検索のみが有効な場合があります。

Ingestion API は、ログのバッチを取得すると、それらのログのバッチ ID を生成します。これらのログのバッチ ID が既存のバッチ ID と重複する場合、ログの新しいバッチは Chronicle インスタンスに転送されません。バッチの重複除去はバッチ ID によって異なります。バッチ ID は、それらのバッチに含まれるログが同じであれば、異なるバッチでも同じです。

可能であれば、UDM イベントとして Chronicle にデータを転送することをおすすめします。

Chronicle Ingestion API での認証方法

Chronicle API は、認証と認可に OAuth 2.0 プロトコルを使用します。作成するアプリケーションでは、次のいずれかを実装して認証と認可を行うことができます。

  • 使用するコンピュータ言語用の Google API クライアント ライブラリを利用する。

  • HTTP を使用して OAuth 2.0 システムと直接やり取りする。

Python の Google 認証ライブラリについては、リファレンス ドキュメントをご覧ください。

Google 認証ライブラリは Google API クライアント ライブラリのサブセットです。他の言語の実装をご覧ください。

API 認証情報の取得

API クライアントが API と通信できるようにするために、Chronicle の担当者から Google Developers サービス アカウント認証情報が提供されます。

また、API クライアントを初期化するときに認証スコープを指定する必要があります。OAuth 2.0 は、スコープを使用してアカウントに対するアプリケーションのアクセスを制限します。アプリケーションがスコープをリクエストした場合、そのアプリケーションに発行されたアクセス トークンは与えられたスコープに制限されます。

次のスコープを使用して Google API クライアントを初期化します。

https://www.googleapis.com/auth/malachite-ingestion

Python の例

次の Python の例は、google.oauth2 と googleapiclient を使用して OAuth2 認証情報と HTTP クライアントを使用する方法を示しています。

# Imports required for the sample - Google Auth and API Client Library Imports.
# Get these packages from https://pypi.org/project/google-api-python-client/ or run $ pip
# install google-api-python-client from your terminal
from google.oauth2 import service_account
from googleapiclient import _auth

SCOPES = ['https://www.googleapis.com/auth/malachite-ingestion']

# The apikeys-demo.json file contains the customer's OAuth 2 credentials.
# SERVICE_ACCOUNT_FILE is the full path to the apikeys-demo.json file
# ToDo: Replace this with the full path to your OAuth2 credentials
SERVICE_ACCOUNT_FILE = '/customer-keys/apikeys-demo.json'

# Create a credential using Google Developer Service Account Credential and Chronicle API
# Scope.
credentials = service_account.Credentials.from_service_account_file(SERVICE_ACCOUNT_FILE, scopes=SCOPES)

# Build an HTTP client to make authorized OAuth requests.
http_client = _auth.authorized_http(credentials)

# <your code continues here>

提供されるサービス アカウントの認証情報は、1 つの Chronicle インスタンスに対応します。Ingestion API に対して発行されるリクエストには、customer_id フィールドが含まれます。これは、Chronicle インスタンスの一意の識別子です。これは Chronicle の担当者から提供されます。リクエストの発行時に使用する認証情報と一意の識別子が一致している必要があります。

リージョン エンドポイント

Chronicle には、各 API のリージョン エンドポイントが用意されています。

よくある質問

おすすめのバッチサイズ（HTTP リクエストごと）は何ですか？

非圧縮の場合は 1 MB（受信バッチが圧縮されている場合）。

お客様は許可リストを作成して、コレクタ API エンドポイントへの接続が許可されている特定のパブリック IP アドレスを含めることができますか？または他の形式のクライアント認証をサポートしていますか？

Chronicle は、特定の IP アドレスの一覧表示をサポートしていません。API キーを所有している限り、どの接続も有効です。

API エンドポイントはリージョンによって異なりますか？

はい。API エンドポイントは、顧客アカウントがプロビジョニングされる場所によって異なります。リージョン エンドポイントをご覧ください。

リクエスト タイムアウトはどのように設定すればよいですか？

クライアントは 90 秒のリクエスト タイムアウトを使用する必要があります。

HTTP リクエストが失敗した場合、何をする必要がありますか？エラーコードとは何ですか？

Cloud API 設計ガイドのエラーの処理で、特に次の情報をご覧ください。

クライアントは指数バックオフを使用して 5XX エラーの発生時に再試行する必要があります。最小遅延は、別途ドキュメント化されていない限り、1 秒にします。429 エラーの場合、クライアントは最小 30 秒の遅延で再試行することができます。それ以外のすべてのエラーでは、再試行を行えない場合があります。

標準的な HTTP gzip 圧縮（Accept-Encoding: gzip ヘッダーなど）に対応していますか？

はい、Chronicle は標準の HTTP gzip 圧縮をサポートしています。

Ingestion API リファレンス

udmevents

このメソッドを使用して、UDM イベントを Chronicle に一括で転送します。

リクエスト

POST https://malachiteingestion-pa.googleapis.com/v2/udmevents:batchCreate

リクエストの本文

次の例は、udmevents API エンドポイントを使用してログデータをフォーマットする方法を示しています。UDM を使用してエンタープライズ ログデータをフォーマットする方法を示します。

{
  "customer_id": "c8c65bfa-5f2c-42d4-9189-64bb7b939f2c",
  "events": [
    {
      "metadata": {
        "event_timestamp": "2019-10-22T12:00:00.000Z",
        "event_type": "USER_LOGIN",
        "product_name": "Acme SSO",
        "vendor_name": "Acme"
      },
      "principal": {
        "ip": [
          "10.1.2.3"
        ]
      },
      "target": {
        "application": "Acme Connect",
        "user": {
          "user_display_name": "Mary Jane",
          "userid": "mary@altostrat.com"
        }
      },
      "extensions": {
        "auth": {
          "type": "MACHINE",
          "mechanism": [
            "NETWORK"
          ]
        }
      }
    },
    {
      "metadata": {
        "event_timestamp": "2019-10-23T04:00:00.000Z",
        "event_type": "NETWORK_HTTP",
        "product_name": "Acme Proxy",
        "vendor_name": "Acme"
      },
      "network": {
        "http": {
          "method": "GET",
          "response_code": 200
        }
      },
      "principal": {
        "hostname": "host0",
        "ip": [
          "10.1.2.3"
        ],
        "port": 60000
      },
      "target": {
        "hostname": "www.altostrat.com",
        "ip": [
          "198.51.100.68"
        ],
        "port": 443,
        "url": "www.altostrat.com/images/logo.png"
      }
    }
  ]
}

本文パラメータ

フィールド 値 必須 説明
customer_id 文字列 ○ 特定の Chronicle インスタンスに対応する一意の識別子（UUID）。Chronicle の担当者から提供されます。
events[] 配列 ○ UDM イベントの配列。

レスポンス

メソッド構文にエラーが発生していない場合、レスポンスを受信することはありません。

unstructuredlogentries

このメソッドを使用して、非構造化ログエントリを Chronicle に一度に一括で転送します。

ログデータの各バッチサイズの上限は、1 MB です。複数のタイムスタンプ タイプを送信しないでください（「ts_epoch_microseconds」または「ts_rfc3339」のどちらかのみを使用し、両方使用しない）。個別にタイムスタンプを入力しない場合、必ず log_text フィールド内にタイムスタンプを含めてください。

リクエスト

POST https://malachiteingestion-pa.googleapis.com/v2/unstructuredlogentries:batchCreate

リクエストの本文

次の例は、unstructuredlogentries API エンドポイントを使用してログデータをフォーマットする方法を示しています。3 つの BIND DNS ログをフォーマットする方法を示します。

タイムスタンプを別の名前と値のペアとして送信する場合は、バッチ内のすべてのエントリに同じキーを使用します。たとえば、単一のバッチの場合、1 つのエントリに ts_epoch_microseconds を、別のエントリに ts_rfc3339 を使用しないでください。

たとえば、このペイロードには ts_epoch_microseconds と ts_rfc3339 の両方が含まれているため、エラーが返されます。

{
  "customer_id": "c8c65bfa-5f2c-42d4-9189-64bb7b939f2c",
  "log_type": "BIND_DNS",
  "labels" : [
    {
      "key" : "key_name_one",
      "value" : "value_one"
    },
    {
      "key" : "key_name_two",
      "value" : "value_two"
    }
  ]
  "entries": [
    {
      "log_text": "26-Feb-2019 13:35:02.187 client 10.120.20.32#4238: query: altostrat.com IN A + (203.0.113.102)",
      "ts_epoch_microseconds": 1551188102187000
    },
    {
      "log_text": "26-Feb-2019 13:37:04.523 client 10.50.100.33#1116: query: examplepetstore.com IN A + (203.0.113.102)",
      "ts_rfc3339": "2019-26-02T13:37:04.523-08:00"
    },
    {
      "log_text": "26-Feb-2019 13:39:01.115 client 10.1.2.3#3333: query: www.example.com IN A + (203.0.113.102)"
    }
  ];
}

本文パラメータ

フィールド 値 必須 説明
customer_id 文字列 ○ 特定の Chronicle インスタンスに対応する一意の識別子（UUID）。Chronicle の担当者から提供されます。
log_type 文字列 ○ ログエントリを一括で識別します（WINDOWS_DNS など）。
namespace 文字列 ○ ログの取得元のデータドメインを識別するための、ユーザーが構成した環境名前空間。インデックス登録と拡充機能に適したデータドメインを識別するために、名前空間をタグとして使用します。
entries[] 配列 ○ 未加工のログとタイムスタンプのフィールドを含むオブジェクトの配列。
entries[].log_text 文字列 ○ 未加工のログエントリのテキスト。これには、バイナリデータを含めることはできず、UTF-8 文字列のみを使用する必要があります。
entries[].ts_epoch_microseconds uint64 省略可 ログエントリと関連付けられている、マイクロ秒単位の UNIX タイムスタンプ。
entries[].ts_rfc3339 文字列 省略可 ログエントリと関連付けられている、RFC 3339 形式のタイムスタンプ。
labels[] 配列 省略可 ログに適用するラベルの Key-Value ペアを含むオブジェクトの配列。
labels[].key 文字列 省略可 ラベルを適用するためのキーの名前。
labels[].value 文字列 省略可 ラベルを適用する値。

レスポンス

メソッド構文にエラーが発生していない場合、レスポンスを受信することはありません。

createentities

エンティティを作成します。リクエストごとに 1 MB のデータに制限されます。

リクエスト

POST https://malachiteingestion-pa.googleapis.com/v2/entities:batchCreate

リクエストの本文

{
  "customer_id": "<customer UUID>",
  "log_type": "<log type goes here>",
  "entities": [<array of Entities>],
}

本文パラメータ

フィールド 値 必須 説明
customer_id 文字列 ○ 特定の Chronicle インスタンスに対応する一意の識別子（UUID）。Chronicle の担当者から提供されます。
log_type 文字列 ○ logtypes エンドポイントによって返される任意の log_type 値。
entities[] 配列 ○ エンティティの配列。

リクエストの本文の例

{
 "log_type": "AZURE_AD_CONTEXT",
 "entities": [{
   "metadata": {
      "collected_timestamp":"2021-11-14T15:30:18.142265Z",
      "entity_type": "USER",
      "vendor_name": "vendor",
      "product_name": "product"
   },
   "entity": {
      "user": {
        "userid": "johndoe",
        "product_object_id": "doejohn"
      }
   }
  },
  {
   "metadata": {
      "collected_timestamp":"2021-11-14T16:30:18.142265Z",
      "entity_type": "USER",
      "vendor_name": "vendor",
      "product_name": "product"
   },
   "entity": {
      "user": {
        "userid": "janedoe",
        "product_object_id": "doejane"
      }
   }
  }]
}

レスポンス

空の JSON と、オペレーションが正常に完了したことを示す 200 OK を返します。

logtypes

このメソッドを使用して、サポートされているログタイプの一覧を取得します。ログタイプは次の要素に基づいてフォーマットされます。

リクエスト

GET https://malachiteingestion-pa.googleapis.com/v2/logtypes

レスポンス

次の例は、logtypes API エンドポイントを呼び出した場合に返される情報の形式を示しています。

{
  "logtypes": [
    {
     "log_type": "BIND_DNS",
     "description": "BIND DNS Server"
    },
    {
      "log_type": "WINDOWS_DNS",
      "description": "Windows DNS"
    },
    {
      "log_type": "WINDOWS_DHCP",
      "description": "Windows DHCP"
    },
    {
      "log_type": "WINEVTLOG",
      "description": "Windows Event Log"
    }
  ]
}

レスポンスのフィールド

フィールド 値 説明
logtypes[] 配列 現在サポートされているログタイプの配列を返します。
logtypes[].log_type 文字列 ログタイプ。レスポンスにのみ含まれます。
logtypes[].description 文字列 人が読める、ログタイプの説明。レスポンスにのみ含まれます。