カスタム統合を構築する

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

Google SecOps SOAR

このドキュメントでは、Google SecOps のカスタム統合を構築するワークフローについて説明します。現在のベスト プラクティスは、任意の IDE を使用してローカルで統合を開発し、最新の GitOps ワークフローを使用して GitHub 経由で管理することです。以前の環境やクイック プロトタイプの場合は、組み込みの SOAR IDE 内で直接統合を構築することもできます。

注: 標準化された開発フレームワーク、品質保証ガイドライン、カスタム統合の構築と送信に関するベスト プラクティスについては、カスタム統合ガイドをご覧ください。

ローカル IDE と GitHub ワークフロー（推奨）

ローカルで統合を開発し、GitHub を介して管理することをおすすめします。このアプローチは最新の GitOps プラクティスに沿っており、バージョン管理、コラボレーション、依存関係の自動管理を改善できます。

詳細な技術手順、インストール ガイド、Marketplace CLI ツールと uv パッケージ マネージャーを使用した最新のコマンドについては、公式の Chronicle Content Hub GitHub リポジトリをご覧ください。

コンセプト ワークフローの概要

カスタム統合をローカルで開発する場合は、この GitOps ライフサイクルに従うことをおすすめします。これらのコマンドの正確な最新の構文については、GitHub の公式 MP CLI ドキュメントをご覧ください。

1. フォークとクローン: 公式の content-hub リポジトリをローカルの開発マシンにクローンします。
2. ツールをインストールする: mp CLI ツールと uv Python パッケージ マネージャーをインストールします。
3. 認証: インスタンス URL と API キーを使用して、MP CLI 経由で Google SecOps 環境にログインします。
4. ローカルで開発する: お好みの IDE（VS Code や PyCharm など）を使用して統合コードを記述し、ローカルのデバッグツールとテストツールを活用します。
5. 依存関係を管理する: uv を使用して、ローカルの pyproject.toml ファイルで依存関係（TIPCommon など）を宣言して管理します。
6. 同期: mp pull コマンドと mp push コマンドを使用して、ローカルコードを Google SecOps インスタンスと同期し、テストとデプロイを行います。

代替方法: 組み込み IDE でカスタム統合を作成する

以前の統合を維持している場合、スクリプトをすばやくテストする場合、またはローカル開発が制限されている環境で作業している場合は、組み込みの IDE を使用できます。

ユースケース: カスタム Armis 統合を構築する

IDE でカスタム統合を作成する手順は次のとおりです。

1. メインメニューで、[Automation] > [IDE] に移動します。
2. [Create New Item] をクリックし、[Integration] を選択します。
3. 名前を入力して [Create] をクリックします。

統合が 設定設定オプションとともに表示され、カスタム統合であることが示されます。

設定 [設定] をクリックして、統合設定を表示します。ここで、アイコン、説明、Python 依存関係、統合パラメータを定義できます。

注: スクリプトの依存関係は、カスタム統合に必要な Python ライブラリです。依存関係は、.WHL、.TAR、.GZ、.PY ファイルとしてアップロードできます。各統合は独自の仮想環境で実行されるため、基盤となるシステムにインストールされているものに関係なく、特定のライブラリ バージョンを使用できます。

ネストされたサブ依存関係を必要とするカスタムまたは独自の .WHL ファイル（TIPCommon など）を使用している場合は、保存する前に、依存関係ツリー全体の個々の wheel ファイルを**手動アップロード**する必要があります。ネストされた依存関係を解決できないと、一般的な errorCode: 2000 エラーが発生します。高度な依存関係トラッキングを行う場合は、ローカル IDE と GitHub ワークフローの使用を検討してください。

カスタム マネージャーを作成する

マネージャーは、サードパーティ製ツール API のラッパーです。必須ではありませんが、外部ツールとやり取りする統合には、これらを使用することをおすすめします。マネージャーは SDK からインポートしないでください。作成したら、コネクタ、アクション、ジョブにインポートします。

カスタム マネージャーを作成する手順は次のとおりです。

1. IDE で、 [Create New Item] をクリックし、[Manager] を選択します。
2. [Armis] 統合を選択し、マネージャーの名前を入力します。
   
3. 次のスクリプトを編集して実行します。

import requests


class ArmisManager:
   def init(self, api_root, api_token):
       self.api_root = api_root
       self.api_token = api_token
       self.session = requests.session()
       self.session.headers = {"Accept": "application/json"}


   def auth(self):
       endpoint = "{}/api/vi/access_token/*"
       params = {"secret_key" : self.api_token}
       response = self.session.post(endpoint.format(self.api_root), params=params)
       self.validate_response(response)
       access_token = response.json()["data"]["access_token"]
       self.session.headers.update({"Authorization": access_token})
       return True


   def get_device_by_ip(self, device_ip):
       endpoint = "{}/api/vi/devices/"
       params = {"ip": device_ip}
       response = self.session.get(endpoint.format(self.api_root), params=params)
       self.validate_response(response)
       return response.json()["data"]["data"]


   @staticmethod
   def validate_response(res, error_msg="An error occurred"):
       """Validate a response


       :param res: (requests. Response) 検証するレスポンス
       :param error_msg: (str) 表示するエラー メッセージ
       """
       try:
           res.raise_for_status()
       except requests.HTTPError as error:
           raise Exception("(error_msg): (error) (text)".format(
               error_msg=error_msg,
               error=error,
               text=error.response.content
           ))

注: 基本的な操作にマネージャーは必要ありません。ただし、データの解析と変換のために小さなアクションをグループ化する場合は、作成することをおすすめします。

パラメータ、Google SecOps Content Hub の構成、ping アクション

統合設定で定義されたパラメータは、Google SecOps Content Hub の構成に表示されます。パラメータには次のものがあります。

• API ルート: 接続するサービスのベース URL。
• API Secret: サービスでアプリケーションを認証するために使用される機密キー。
• [SSL を検証] チェックボックス: 有効にすると、Armis サーバーへの接続用の SSL 証明書が有効であることを確認します。
• [Run Remotely] チェックボックス: コードまたはタスクをローカルではなくリモート サーバーで実行するかどうかを決定する設定。このオプションを有効にすると、システムは必要な指示とデータを専用サーバーに送信して処理します。

パラメータを更新する手順は次のとおりです。

1. 正しい認証情報を入力してください。
2. [保存] > [テスト] をクリックします。

注: 認証情報を更新した後は、必ず [保存] をクリックしてください。すべてのサードパーティ統合で Ping アクションを実装する必要があります。[テスト] ボタンをクリックすると、このアクションが実行され、接続が検証されます。

Ping アクションがない場合、[Test] ボタンは失敗し、赤い X が表示されます。

Ping アクションを実装する

Ping アクションのロジックは、認証が成功したかのように動作します。

Ping アクションを実装する手順は次のとおりです。

1. IDE で、Armis 統合に Ping という名前の新しいアクションを作成します。
2. ArmisManager auth メソッドを使用して認証を確認します。

統合を有効にする

統合を有効にする手順は次のとおりです。

1. [Automation> IDE] で、[Enable/Disable] の切り替えを [ON] にします。
2. [保存] をクリックします。緑色の切り替えボタンが表示されれば成功です。Content Hub の認証情報は ArmisManager に渡されます。auth がエラーなしで完了すると、[テスト] ボタンに緑色のチェックマークが表示されます。

extract_configuration_param メソッドを使用して、統合構成からパラメータをインポートします。または、extract_action_param を使用してアクション自体の中でパラメータを定義します。ただし、Ping アクションでは、Content Hub でテストされるため、常に構成パラメータを使用する必要があります。

カスタム統合を表示する

Content Hub に移動し、作成したカスタム統合を検索します。初期構成時にイメージを作成しなかった場合は、デフォルトのカスタム イメージが割り当てられます。Content Hub の更新によって、カスタム統合がオーバーライドされたり削除されたりすることはありません。

IDE でのエクスポートとインポート

次のいずれかの操作を行います。

• 統合をインポートするには、次の操作を行います。
1. 正しいフォルダ構造の ZIP ファイルをアップロードします。統合が IDE と Content Hub に表示されます。
2. [インポート] をクリックすると、この統合は、IDE と Content Hub の両方に表示されます。
3. 定義、スクリプト、構成を含む ZIP ファイルが生成されます。Managers フォルダは自動的に含まれません。
• 統合をエクスポートする手順は次のとおりです。
• [エクスポート] をクリックしてパッケージをダウンロードします。

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