カスタム コネクタを作成する

以下でサポートされています。

このドキュメントでは、SOAR SDK が Content Hub で利用できないサードパーティ ツール用のカスタム統合を構築する方法について説明します。コネクタは、通常はアラートキューがあるデータソースからデータを取り込むために使用されます。ケース、アラート、イベントは、コネクタと Google SecOps アプリケーションのやり取りを使用してプラットフォームで作成されます。コネクタは、ベースイベント データを取り込み、そのデータをアラートに割り当てて、アラートを Google SecOps アプリケーションとそのデータ処理パイプラインに送信します。

カスタム コネクタを作成する手順は次のとおりです。

  1. サードパーティ ツールの API ロジックを含むマネージャー クラスを作成します。
  2. IDE を使用してコネクタをビルドします。

マネージャーを作成する

コネクタを作成する最初の手順は、統合するテクノロジーに必要なすべての API ロジックを含む Manager クラスを構築することです。たとえば、Google SecOps の Netskope インテグレーションには、事前構築済みのマネージャーが含まれています。このマネージャーには、Netskope API とのやり取りに必要なすべてのロジックが含まれており、独自の実装のモデルとして使用できます。

コネクタを作成する

IDE で、カスタム統合の構築の手順に沿って新しいコネクタを作成します。IDE は、コネクタ スクリプトの基本的な構造と要件を説明するコード コメントを含む汎用テンプレートを生成します。

コネクタのロジックはさまざまですが、通常、このプロセスには次のコアステップが含まれます。

  1. サードパーティ製ツールの API を使用して、アラート、検出、イベントを取得します。Netskope の場合、これは get_alerts() メソッドによって処理されます。アラートが重複しないように、タイムスタンプでクエリを送信し、実行ごとに更新します。
  2. AlertInfo（以前は CaseInfo）クラスを使用してアラートを構築し、必要なすべてのフィールドを割り当てます。
  3. 関連するイベントデータを取得してフラット化し、ネストされたリストと辞書に関する問題を回避してから、フラット化されたイベントをアラートに追加します。
  4. アラートを時間で並べ替え、次のクエリで使用する最新のタイムスタンプを保存します。

インポートと SDK

すべてのコネクタは次の処理を行う必要があります。

  • SiemplifyConnectors から SiemplifyConnectorExecution クラスをインポートします。このクラスは通常、コネクタの main() 関数でインスタンス化されます。このオブジェクトが return_package() メソッドを使用してアラートのリストを Google SecOps アプリケーションに渡すと、スクリプトは終了します。
  • SiemplifyConnectorsDataModel から AlertInfo クラスをインポートします。このクラスをインスタンス化すると、アラート オブジェクトが作成されます。この例では、ソース システムの組み込みアラート オブジェクト（Netskope）との混同を避けるために SiemplifyAlertInfo に名前が変更されています。この名前変更は省略可能です。

SiemplifyUtils モジュールは、ロギング、データ形式の処理、時間変換などに一般的に使用されるメソッドを提供します。output_handler、dict_to_flat、unix_now は、時間処理などのコア機能に不可欠であるため、インポートすることをおすすめします。

ほとんどのコネクタは、統合の Manager クラスもインポートします。一部のインテグレーションには複数のマネージャーが含まれています。ユースケースによっては、追加の標準 Python ライブラリをインポートすることもできます。

定数変数

後で使用するために、いくつかの定数変数を宣言することをおすすめします。

custconnector2
図 1: 定数変数

Google SecOps アラートを作成するスクリプトの例

アラートは、前述のように AlertInfo クラスのオブジェクトをインスタンス化することで作成されます。この例では、ソースシステムとの混同を避けるため、SiemplifyAlertInfo() に名前が変更されています。alert_info オブジェクトには、アラートを正しく処理するためにアプリケーションで定義する必要がある必須プロパティがいくつか含まれています。build_alert_info 関数は、Netskope アラート（API から受信した未加工の JSON 形式）と Siemplify オブジェクトを入力として受け取ります。次に、Netskope アラートを解析し、関連する値を alert_info フィールドに割り当てます。

この関数は、以前に定義した定数も使用します。alert_info オブジェクトに設定されたすべてのプロパティは、Google SecOps アプリケーション内のアラート オブジェクトの一部になります。

図 2 の 35 行目は、このプロセスの重要な部分を示しています。アラートは dict_to_flat メソッドを使用してフラット化され、events プロパティに追加されます。

custconnector3
図 2: アラートを作成するスクリプトの例
 

アラートに複数のイベントが含まれる場合があります。その場合は、各イベントを適切に処理するロジックを含める必要があります。この例では、各アラートにイベントが 1 つしか含まれていないため、デフォルトの実装で十分です。

dict_to_flat メソッドは、未加工の JSON 構造をフラット化するために使用されます。これにより、ネストされたリストや辞書に関する問題を回避できます。フラット化された Key-Value ペアは、元のバージョンを少し変更したものです。

図 2 の次のロジックを確認します。

  • display_id には、uuid ライブラリを使用してランダムに生成された値が割り当てられます。Netskope アラートには UUID フィールドがありませんが、使用可能な場合は代わりに使用できます。
  • ticket_id は display_id と一致するように設定されます。両方のフィールドは、システム内のアラートごとに一意である必要があります。この一意性は、ランダムな UUID を生成することで保証されます。
  • name はアラート名で、GUI に表示されます。
  • rule_generator は、ソースシステムでアラートを生成したルールを指します。このフィールドは、常に元データに存在するとは限りません。欠落している場合は、任意の文字列値を割り当てることができますが、空のままにすることはできません。
  • start_time と end_time はアラートのタイムスタンプを表します。この例では、Netskope アラートは Unix エポック タイムスタンプを提供します。これをミリ秒に変換するには、1,000 を掛ける必要があります。これは Google SecOps で想定されている形式です。ソースが別の形式を使用している場合は、変換する必要があります。便利な時間変換方法については、SiemplifyUtils.py モジュールを参照してください。
  • priority: Google SecOps アプリケーションは、アラートの優先度に基づいて各ケースに優先度を割り当てます。Google SecOps API は、次のスキームを使用して数値と視覚的なラベルをマッピングします。ここで、整数値はコネクタで渡されます。{"Informative": -1, "Low": 40, "Medium": 60, "High": 80, "Critical": 100}（整数値はコネクタで渡される値です）。たとえば、`100` を渡すと、GUI でアラートが「重大」とマークされます。このコネクタでは、追加のヘルパー関数が `SEVERITY_MAP` 定数を使用して、Netskope の重大度値をこの優先度スケールにマッピングします。ただし、Netskope の重大度フィールドは一貫性がないため、マッピングには複数のフィールドを評価するための追加のロジックが必要です。
  • device_vendor と device_product には、スクリプトの前の部分で定義された定数の値が割り当てられます。
  • environment は、Google SecOps で複数の環境を使用する場合に重要です。この場合、siemplify オブジェクトから取得され、プラットフォームでコネクタ用に選択された環境と一致します。
  • 37 行目（図 3）で、コネクタは新しいキー product_name を値「Netskope」とともに追加して、ベース イベント ディクショナリを変更します。これは、プラットフォームのオントロジーでのマッピングとモデリングに使用できる一貫したプロダクト フィールドが、元データに含まれていないためです。
    custconnector4
    図 3: 基本イベントの変更

コネクタを実行するスクリプトの例

main 関数には、コネクタのコア実行ロジックが含まれています。

  • output_handler デコレータはデバッグ目的で使用されるため、このドキュメントでは説明しません。
  • main 関数には、デフォルトで False に設定される省略可能なパラメータ is_test_run が含まれています。名前のとおり、このパラメータは、コネクタが本番環境でアラートを取り込むか、アプリケーションの [Connector Testing] タブからテストモードで実行するかを決定します。

スクリプト行ごとのコア実行ロジックの内訳を確認します。

custconnector4
図 3: ベースイベントの変更
  • 56 行目と 57 行目は、実行中に使用される 2 つの空のリストを初期化します。
  • 58 行目で、SiemplifyConnectorExecution クラスが siemplify オブジェクトをインスタンス化します。このオブジェクトは、コネクタのランタイム動作のほとんどを管理します。
  • 61 行目で、コネクタの許可リストのインスタンスが作成されます。このコネクタでは使用されていませんが、他のコネクタでは一般的に使用されており、このガイドでは説明しません。
  • 67 ～ 69 行目では、認証情報や構成設定などのコネクタ パラメータの変数が定義されています。
  • 71 行目では、NetskopeManager オブジェクトをインスタンス化し、関連するパラメータを渡して認証を成功させています。この例では、認証を処理する内部の Manager ロジックは示されていません。
  • 73 行目では、以前のコネクタ実行時に作成されたローカル ファイルからタイムスタンプを取得します。このタイムスタンプは、同じアラートの再処理を回避するために使用されます。
  • 74 行目と 75 行目では、コネクタが初めて実行され、タイムスタンプがまだ設定されていない場合（デフォルトが `0` の場合など）を処理します。Netskope では Unix エポック時刻が必要で、`0` は有効な開始時刻として受け入れられないため、`unix_now` 関数を使用して現在の時刻をミリ秒単位で取得します。この値は `1,000` で除算され、Unix エポック秒に変換されます。結果の開始時刻と終了時刻は、Manager の get_alerts メソッドに渡されます。多くの API は開始時刻のみを受け入れますが、Netskope API では、時間ベースのアラートクエリに開始時刻と終了時刻の両方が必要です。
  • 77 行目で、Netskope からアラートのリストを取得します。コネクタがテストモードで実行されている場合、リストの最後のアラートのみが選択されます（79 ～ 80 行）。

オーバーフロー ロジック

次に、コネクタは取得したアラートを反復処理し、前に定義した build_alert_info 関数を使用して各アラートからアラートを構築します。以前に初期化された all_alerts リストに各アラートを追加します。コネクタ ロジックの次の部分では、オーバーフローを処理します。
オーバーフローは、特にアラートが同じ環境、プロダクト、ルール ジェネレータを共有している場合に、短期間に大量のアラートが取り込まれるのを防ぐしきい値メカニズムです。必須ではありませんが、パフォーマンスの低下を防ぐためのベスト プラクティスとして、オーバーフロー ロジックを実装することをおすすめします。

図 4 のスクリプト行ごとのオーバーフロー ロジックの内訳を確認します。

  • 104 ～ 105 行で、alert がオーバーフローとして分類されていない場合、取り込むアラートのリストに追加されます。

    • custconnector5
    図 4: オーバーフロー メカニズム。

コネクタの実行を終了する

コネクタがテストモードで実行されていない場合は、最後に取得されたアラートを反映するようにタイムスタンプを更新する必要があります。これにより、次の実行サイクルで同じアラートが再取り込みされることはありません。all_alerts リストはタイムスタンプで並べ替えられるため、オーバーフローしたアラートも最新のタイムスタンプの決定に貢献します。

図 5 で、スクリプト行ごとのコネクタ実行ロジックの内訳を確認します。

  • 126 行目で、オーバーフローしていないアラートのリストがアプリケーションに送信され、アラートが作成されて GUI に表示されます。
  • 128 ～ 131 行目では、コネクタがテストモードで実行されているかどうかを判断しています。この判断には、アプリケーションから渡されたシステム引数（[テスト] タブで [コネクタを 1 回実行] をクリックした場合など）が使用されます。
    custconnector6
    図 5: コネクタの実行を終了する

さらにサポートが必要な場合 コミュニティ メンバーや Google SecOps のプロフェッショナルから回答を得ることができます。