カスタム インテグレーションを構築する
このドキュメントでは、商用インテグレーションと同じ構造を使用して、統合開発環境（IDE）内にカスタム インテグレーションを作成する方法について説明します。さまざまな環境のカスタム統合は、コンテンツ ハブで確認して構成できます。作成したラベルは、ハンドブック、手動アクション、リモート エージェントで使用できます。他の IDE アイテムと同様に、インポートとエクスポートの機能もサポートされています。
IDE でカスタム インテグレーションを作成する
Armis プロダクトのカスタム統合を構築し、Ping アクションとともにマネージャーを作成できます。この手順では、Python とオブジェクト指向プログラミングの知識があることを前提としています。
ユースケース: カスタムの Armis インテグレーションを構築する
IDE でカスタム統合を作成する手順は次のとおりです。
- メインメニューで、[レスポンス] > [IDE] に移動します。
- [Create New Item] をクリックし、[Integration] を選択します。
- 名前を入力して [Create] をクリックします。
統合が [ 設定 ] [設定] オプションに表示され、カスタム統合であることが示されます。
[ settings 設定] をクリックして、アイコン、説明、Python の依存関係、統合パラメータを定義できる統合設定を表示します。
依存関係パッケージに manylinux_2_17_x86_64 アーキテクチャで使用できる事前コンパイル済み wheel（.WHL）ファイルがない場合や、特定のソースコード バージョンが必要な場合は、ソースコード（.tar.gz ファイルなど）への直接 URL を指定できます。プラットフォームの依存関係リゾルバである uv は、pyproject.toml ファイル内の [tool.uv.sources] テーブルでこれらのソース URL を定義することをサポートしています。次に例を示します。
[project] # ... other project fields ... [tool.uv.sources] compressed-rtf = { url = "https://files.pythonhosted.org/packages/.../compressed_rtf-1.0.6.tar.gz" } dkimpy = { url = "https://files.pythonhosted.org/packages/.../dkimpy-1.1.8.tar.gz" }
uv を使用してさまざまなタイプの依存関係を定義する方法の詳細については、依存関係の管理に関する uv のドキュメントをご覧ください。
推奨されるワークフロー: mp CLI を使用した高度な依存関係の管理
TIPCommon などの複雑な多層外部ライブラリを必要とする統合の場合、Google は、手動の IDE アップロードを完全にバイパスし、Marketplace CLI（mp）ツールを使用してローカルで開発することをおすすめします。このツールは、uv パッケージ マネージャーを使用して、ネストされた依存関係を自動的に追跡してパッケージ化します。
前提条件
- ローカル開発マシンに Python 3.11 以降がインストールされている。
uvPython パッケージ マネージャーがインストールされている（uv インストール ガイドを参照）。
初期設定
- 公式の Content Hub リポジトリをフォークしてローカル環境にクローンします。
-
uvを使用してmpツールをインストールします。uv tool install mp --from git+https://github.com/chronicle/content-hub.git#subdirectory=packages/mp
-
インスタンスのルート URL と以前の API キーを使用して、Google SecOps 環境にログインします。
mp login --api-root https://{YOUR_INSTANCE}.siemplify-soar.com --api-key {YOUR_LEGACY_API_KEY}
-
ローカル ルート リポジトリのパスを構成します。
mp config --root-path /path/to/cloned/content-hub
-
リポジトリ レイアウト内の
content-hub/content/response_integrations/custom/に、独自のインテグレーション用のカスタム サブディレクトリを作成します。
統合に TIPCommon または Complex の依存関係を追加する
TIPCommon やその他の多層ライブラリを必要とする統合を IDE で作成した場合は、次のローカル ワークフローを使用して依存関係を安全に管理します。
-
クローン作成したリポジトリ内のカスタム統合ディレクトリに移動します。
cd content-hub/content/response_integrations/custom/
-
既存のインテグレーション構造を Google SecOps インスタンスから取得します。
mp pull --type integration --name "{INTEGRATION_NAME}"
-
ディレクトリを変更して、新しく pull した統合フォルダに移動します。
cd {INTEGRATION_NAME}
-
uvを使用して、必要なTIPCommonwheel ファイル パッケージを挿入します。これにより、ネストされたサブ依存関係ホイールが自動的に追跡され、ローカル環境パッケージ構成にダウンロードされます。uv pip install /path/to/wheels/TIPCommon-your-version-py3-none-any.whl
-
完全にコンパイルされたインテグレーションと、新しく追跡された依存関係ツリーを Google SecOps インスタンスにプッシュします。
mp push --type integration --name "{INTEGRATION_NAME}"
インストールの確認
errorCode: 2000 ループが発生せずに依存関係が正常にパッケージ化されたことを確認するには、次の操作を行います。
- IDE 内でカスタム統合を開きます。
- パッケージからモジュールをインポートするテスト行を追加します（例:
from TIPCommon.extraction import extract_action_param）。 - [Test/Play] ボタンをクリックして実行をデバッグします。スクリプトが
ModuleNotFoundErrorをスローせずに正常にコンパイルされる場合、ネストされた依存関係は正しく解決されています。
カスタム マネージャーを作成する
マネージャーは、サードパーティ製ツールの API のラッパーです。必須ではありませんが、外部ツールとやり取りする統合にはおすすめします。マネージャーは SDK からインポートしないでください。作成したら、コネクタ、アクション、ジョブにインポートします。
カスタム マネージャーを作成する手順は次のとおりです。
- IDE で、 [Create New Item] をクリックし、[Manager] を選択します。
- [Armis] 統合を選択し、管理者の名前を入力します。
- 次のスクリプトを編集して実行します。
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] チェックボックス: コードまたはタスクをローカルではなくリモート サーバーで実行するかどうかを決定する設定。このオプションを有効にすると、必要な指示とデータが処理専用のサーバーに送信されます。
パラメータを更新する手順は次のとおりです。
- 正しい認証情報を入力してください。
- [保存] > [テスト] をクリックします。
Ping アクションがない場合、[テスト] ボタンが失敗し、赤い X が表示されます。
Ping アクションを実装する
Ping アクションのロジックは、認証が成功した場合と同様に動作します。
Ping アクションを実装する手順は次のとおりです。
- IDE で、
Pingという名前の Armis 統合に新しいアクションを作成します。 ArmisManagerauthメソッドを使用して認証を検証します。
統合を有効にする
統合を有効にする手順は次のとおりです。
- [Response > IDE] で、[Enable/Disable] 切り替えを [ON] の位置にクリックします。
- [保存] をクリックします。緑色の切り替えボタンは、成功したことを示します。Content Hub の認証情報は ArmisManager に渡されます。
authがエラーなく完了すると、[テスト] ボタンに緑色のチェックマークが表示されます。
extract_configuration_param メソッドを使用して、統合構成からパラメータをインポートします。または、extract_action_param を使用してアクション自体の中でパラメータを定義します。ただし、Ping アクションは、Content Hub によってテストされるため、常に構成パラメータを使用する必要があります。
カスタム統合を表示する
コンテンツ ハブに移動し、作成したカスタム統合を検索します。初期構成時にイメージを作成しなかった場合、デフォルトのカスタム イメージが割り当てられます。コンテンツ ハブの更新によって、カスタム統合がオーバーライドされたり削除されたりすることはありません。
IDE でのエクスポートとインポート
次のいずれかの操作を行います。
- 統合をインポートするには、次の操作を行います。
- 正しいフォルダ構造の ZIP ファイルをアップロードします。統合が IDE と Content Hub に表示されます。
- [インポート] をクリックすると、統合は IDE と Content Hub の両方に表示されます。
- システムは、定義、スクリプト、構成を含む ZIP ファイルを生成します。Managers フォルダは自動的に含まれません。
- 統合をエクスポートする手順は次のとおりです。
- [エクスポート] をクリックしてパッケージをダウンロードします。
さらにサポートが必要な場合 コミュニティ メンバーや Google SecOps のプロフェッショナルから回答を得ることができます。