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

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

Google SecOps SOAR

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

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

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

マネージャーを作成する

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

コネクタを作成する

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

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

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

インポートと SDK

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

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

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

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

注: 古いコネクタは SiemplifyConnectors から CaseInfo を使用できます。これは AlertInfo と同じクラスで、非推奨の命名規則を反映しています。

定数変数

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

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 プロパティに追加されます。

アラートには複数のイベントを含めることができます。その場合は、各イベントを適切に処理するロジックを含める必要があります。この例では、各アラートに 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」とともに追加して、ベースイベントディクショナリを変更します。これは、プラットフォームのオントロジーでマッピングとモデリングに使用できる一貫したプロダクトフィールドが、生データに含まれていないためです。

図 3: ベースイベントの変更

Connector を実行するスクリプトの例

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

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

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

56 行目と 57 行目は、実行中に使用される 2 つの空のリストを初期化します。
58 行目で、SiemplifyConnectorExecution クラスが siemplify オブジェクトをインスタンス化します。このオブジェクトは、コネクタのランタイム動作のほとんどを管理します。
61 行目で、Connector Allowlist のインスタンスが作成されます。このコネクタでは使用されていませんが、他のコネクタでは一般的に使用されており、このガイドでは説明しません。
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 がオーバーフローとして分類されていない場合、取り込むアラートのリストに追加されます。

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

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

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

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

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

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