コミュニティ レスポンスの統合に貢献する

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

このドキュメントでは、コミュニティの貢献を通じて Google SecOps にレスポンス統合を送信するためのガイドラインについて説明します。提出されたすべてのインテグレーションは、公式の Google SecOps チームによる審査プロセスを受けます。このドキュメントでハイライト表示されている要件に重点が置かれます。

レスポンス統合メタデータ

名前

[Name] は、統合が統合される商品名に対応している必要があります。特殊文字は使用しないでください。

表示名には、空白文字を含める必要があります（例: VertexAI ではなく Vertex AI）。

統合識別子

統合識別子は、統合の固有識別子です。統合の作成後にこの値を変更することはできません。この識別子は Name と同じ値にする必要がありますが、空白は削除します。

この ID は、プラットフォームのほとんどの場所で確認できます。

説明

[説明] には、統合が作成されるプロダクトの概要を 500 文字以内で入力します。次の情報が含まれている必要があります。

This integration is owned by the "{vendor name}". Support Contact: {email}.

説明文に URL を含めないようにします。

ロゴ

各統合には SVG アイコンを指定する必要があります。このアイコンは、プラットフォーム内のテーマに適応する必要があります。アイコンは、プラットフォームからのみテーマを継承する必要があります。

次のページでロゴを検証する必要があります。

以下は、Google のスタイルガイドに沿ってデザインされた SVG ロゴの例です。

        <?xml version="1.0" encoding="UTF-8"?><svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 21 23"> <defs> <style> .cls-1 { stroke-width: 0px; } </style> </defs> <path class="cls-1" d="M15.51,4.79H5.49c-.4,0-.72.32-.72.72v5.75c0,2.3,1.71,4.15,3.69,5.38.54.34,1.1.62,1.66.86l.09.04c.06.02.12.05.18.06.03,0,.07,0,.1,0,.1,0,.19-.03.28-.07l.09-.04c.76-.33,2.22-1.03,3.46-2.24,1.24-1.22,1.89-2.6,1.89-4v-5.75c0-.4-.32-.72-.72-.72ZM14.32,11.26c0,.88-.44,1.77-1.32,2.63-.65.64-1.55,1.22-2.5,1.68-.95-.46-1.84-1.04-2.5-1.68-.88-.86-1.32-1.75-1.32-2.63v-4.55h7.64v4.55ZM20.28,0H.72c-.4,0-.72.32-.72.72v10.77c0,2.56,1.18,4.99,3.51,7.21,2.29,2.18,5.12,3.56,6.61,4.2l.09.04s.1.04.15.05c.04,0,.09.01.13.01.1,0,.19-.02.28-.06l.09-.04c.53-.23,1.23-.55,2.02-.97,1.42-.75,3.11-1.82,4.59-3.23,2.33-2.22,3.51-4.64,3.51-7.21V.72c0-.4-.32-.72-.72-.72ZM16.17,17.31c-1.9,1.81-4.24,3.04-5.67,3.69-1.43-.65-3.77-1.88-5.67-3.69-1.94-1.84-2.92-3.8-2.92-5.82V1.92h17.18v9.57c0,2.02-.98,3.98-2.92,5.82Z"/></svg>

コンテンツ ハブの他の統合で見られるように、SVG を統合定義ファイルに追加する前にエンコードしてください。

統合の一環として、ユーザーをドキュメントに誘導するリンクを追加できます。このドキュメントは、パートナー様側でホストしていただく必要があります。

ユーザーは、[インスタンスの構成] ダイアログの [パラメータ] セクションからドキュメント リンクにアクセスできます。

構成パラメータ

基盤となる API で認証が不要で、API ルートをハードコードできる場合を除き、すべての統合に構成パラメータ（API ルート + 認証パラメータ）を含める必要があります。認証が必要なすべての統合には、Verify SSL パラメータが必要です。

すべてのパラメータに説明が必要です。説明は、ユーザーがプラットフォーム内から統合を構成するのに役立つものである必要があります。パラメータの説明に URL を含めないでください。

ping アクション

Ping アクションは、プラットフォームが API 接続性を検証するために使用する特別なアクションです。このアクションは、統合に他のアクションがない場合でも必須です。ユーザーが統合構成内の [テスト] ボタンを押すたびに、接続の正確なステータスが表示される必要があります。

リリースノート

リリースノートの一般的な構造は、次の形式に従う必要があります。

  • {integration item} - {update}
    • 例: Get Case Details - Added ability to fetch information about affected IOCs

状況に応じて、特定のシナリオに固有のリリースノートがあります。

  • 新しい統合の場合: New Integration Added - {integration name}
  • 新しいアクションが追加された場合: New Action Added - {action name}
  • 新しいコネクタが追加された場合: New Connector Added - {connector name}
  • 新しいジョブが追加された場合: New Job Added - {job name}
  • 事前定義済みウィジェットがアクションに追加されている場合: {action name} - Added Predefined Widget.
  • 事前定義ウィジェットが更新された場合: {action name} - Updated Predefined Widget.
  • すべての統合アイテムに影響する変更の場合: Integration - {Update}
  • すべてのアクションに影響する変更の場合: Integration's Actions - {Update}
  • すべてのコネクタに影響する変更の場合: Integration's Connectors - {Update}
  • すべてのジョブに影響する変更の場合: Integration's Jobs - {Update}

リリースに回帰的な変更が含まれている場合は、リリースノートで REGRESSIVE! を指定する必要があります。例: Google Chronicle - Chronicle Alerts Connector - REGRESSIVE! Updated mapping.

リリースノートは、統合の [詳細] ボタンをクリックすると表示される [統合の詳細] サイドドロワーで確認できます。

バージョニング

統合を更新するたびに、統合バージョンを +1 更新する必要があります。バージョンは整数で表す必要があります。11.1.3 や 11.1 などのマイナー バージョンは使用できません。

タグ

必要に応じて、統合にタグを追加できます。新しいタイプのタグを作成することは避け、プラットフォームにすでに存在するタグを使用してください。適切なタグが見つからない場合は、審査チームにコンサルトしてください。

一般的な注意事項

  • 送信する前に、すべての統合コンテンツをテストします。
  • すべての統合コンテンツで、潜在的な脆弱性と脆弱な依存関係がないか確認します。
  • 開発中は、サポートされている最新バージョンの Python（Python 3.11）を常に使用してください。

操作

名前

アクションの名前は、実行されているアクティビティ（ケースの詳細を取得、エンティティ イベントを一覧表示、検索を実行など）を指す必要があります。

アクションが主にエンティティを操作するように設計されている場合は、名前に Entity を含めることをおすすめします（例: Enrich Entities）。

アクション名は 2 ～ 3 語で表現する必要があります。

説明

アクションの説明では、アクションの実行結果をユーザーに強調する必要があります。

アクションがエンティティを操作する場合は、サポートされているエンティティのタイプに関する情報を追加する必要があります。次に例を示します。

Add a vote to entities in VirusTotal. Supported entities: File Hash, URL, Hostname, Domain, IP Address. Note: only MD5, SHA-1 and SHA-256 Hash types are supported.

アクションが非同期モードで動作する場合は、説明に次の注記を記載する必要があります。

Note: Action is running as async, adjust script timeout value in Google SecOps IDE for action, as needed.

説明は 500 文字以内にしてください。

アクション パラメータ

アクション構成パラメータには、直感的な名前を付ける必要があります。特殊文字の使用を避け、アクション パラメータ名は 2 ～ 4 語に制限してください。

パラメータの説明では、そのパラメータがアクションの実行にどのような影響を与えるかをユーザーに説明する必要があります。パラメータが、サポートされている値の所定の量をサポートしている場合は、説明内に次のセクションを指定します。 Possible Values: {value 1}, {value 2}

アクションの出力（スクリプトの結果）

スクリプトの結果は、アクションの単純な結果を表す必要があります。ほとんどの場合、is_success という変数（値は true または false）を指す必要があります。

一般に、アクションが実行を終了してオペレーションを実行した場合、is_success は true になります。

アクションの出力（JSON の結果）

JSON の結果は、アクションの最も重要な出力です。JSON の結果で利用可能なすべてのデータは、ハンドブックの実行中にアクセスできます。有効な JSON オブジェクトが出力に push されていることを確認します。

JSON の結果のサイズ上限は 15 MB です。

JSON の結果を作成する際は、実行中に一意になるキーがないことを確認してください。たとえば、次の JSON オブジェクトは、ハンドブック内で使用できないため、不適切な構造を表しています。


{
   "10.10.10.10": {
      "is_malicious": "false"
   }
}

代わりに、次のようにフォーマットします。


[
   {
      "is_malicious": "false",
      "ip": "10.10.10.10"
   }
]

アクション内でエンティティを使用し、エンティティごとに結果を返す場合は、JSON の結果を次のように構造化することをおすすめします。


[
   {
       "Entity": "10.10.10.10",
       "EntityResult": {
           "is_malicious": "false",
       }
   }
]

アクションの出力が自動化内でどのように使用されるかを常に考慮してください。

アクションに JSON サンプルがあることを確認します。

JSON サンプルは、ハンドブックの作成プロセス中に Expression Builder 内のプラットフォームで使用されます。正確な JSON サンプルを使用すると、ハンドブックの作成エクスペリエンスが大幅に向上します。JSON サンプルから PII 情報を削除します。

アクションの出力（エンティティの拡充）

エンティティに対してアクションが実行されている場合は、アクションの実行中に追加のメタデータをエンティティに追加できます。このメタデータの構造は、{integration identifier}_{key} の形式にする必要があります。例: WebRisk_is_malicious。

追加されたメタデータは、エンティティの詳細ページで確認できます。

アクションの出力（出力メッセージ）

出力メッセージでは、アクションの実行がどのように行われたかを、よりわかりやすくユーザーに説明する必要があります。アクションの実行結果をユーザーに示す必要があります。

一部のエンティティは正常に拡充されたものの、他のエンティティは拡充されなかった場合は、メッセージ内の指定された各エンティティのステータス情報を提供することをおすすめします。

アクションの実行中に重大なエラーが発生したと思われる場合は、この状況に関する詳細なメッセージがあることを確認し、アクションを失敗させます。アクションが失敗すると、エラーが解決されるか手動でスキップされるまで、対応するハンドブックの実行が停止します。

出力メッセージの例を次に示します。

  • Successfully enriched the following entities using information from VirusTotal: {entity.identifier}
  • Action wasn't able to find any information for the following entities using VirusTotal: {entity.identifier}
  • None of the provided entities were found in VirusTotal.
  • Successfully executed query "{query}" in Google SecOps.

アクションが失敗し、ハンドブックの実行を停止する必要がある場合は、出力メッセージを次の構造にすることをおすすめします。

"Error executing action "{action name}". Reason: {error}'

エラーのトレースバック全体を記載することは避けてください。代わりに、自然言語で実際の問題をユーザーに伝えるようにしてください。

コネクタ

名前

コネクタの名前は、取り込まれるデータをユーザーに示す必要があります。一般に、名前の構造は次のようになります。

  • {integration display name} - {data that is being ingested} Connector
    • 例: Crowdstrike - Pull Alerts Connector

説明

コネクタの説明では、コネクタによって取り込まれる内容（Pull alerts from Crowdstrike など）をユーザーに強調する必要があります。また、動的リストのサポートに関する情報（Dynamic List works with the display_name parameter. など）を提供する必要があります。

この場合、最終的な説明は次のようになります。

Pull alerts from Crowdstrike. Dynamic List works with the display_name parameter.

説明は 500 文字以内にしてください。

コネクタ パラメータ

コネクタの設定パラメータには、直感的な名前を付ける必要があります。 特殊文字の使用を避け、アクション パラメータ名は 2 ～ 4 語に制限してください。

パラメータの説明では、そのパラメータがコネクタの実行にどのような影響を与えるかをユーザーに説明する必要があります。

パラメータが、サポートされている値の所定の量をサポートしている場合は、説明内に Possible Values: {value 1}, {value 2} セクションを指定します。には、次のパラメータが必要です。

  • 取得するアラートの最大数: 1 回のコネクタの反復処理で処理する {object} の数を指定します。
  • Max {Hours/Days} Backwards: コネクタの最初のイテレーションの開始時間を指定します。たとえば、[Max Hours Backwards] が 1 に設定されている場合、コネクタは 1 時間前からデータの取得を開始します。
  • SSL の検証: API / インスタンスへの接続を確認します。

オントロジー マッピング

作成されたコネクタごとに、オントロジー マッピングを提供して、相互のお客様が最適なエクスペリエンスを得られるようにすることをおすすめします。

オントロジー マッピングは、エンティティ（IOC とアセット）を自動的に作成するために使用されます。また、開始時間や終了時間などのシステム フィールドの重要なメタデータも定義されています。

動的リスト

動的リストは、取り込み用の高度なフィルタを作成できるオプション機能です。独自の UX を実現しながら、任意のカスタム ロジックを柔軟に構築できます。最も一般的なユースケースは、取り込みの許可リストまたは拒否リストを定義することです。

動的リストのカスタム ロジックを構築する場合は、コネクタの説明に記載されていることを確認してください。また、逆ロジックもサポートされるように、動的リストをブロックリストとして使用するパラメータを設定することをおすすめします。

ジョブ

名前

ジョブの名前は、このジョブが何を実行しているかをユーザーに説明するものである必要があります。一般に、名前の構造は次のようになります。

  • {integration display name} - {process} Job
    • 例: ServiceNow - Sync Incidents Job

説明

ジョブの説明では、イテレーション中にジョブが行っていることをユーザーに強調する必要があります（例: This job will synchronize Security Command Center based cases created by the Urgent Posture Findings connector.）。

説明は 500 文字以内にしてください。

ジョブ パラメータ

ジョブ構成パラメータには、わかりやすい名前を付ける必要があります。特殊文字は使用せず、アクション パラメータ名は 2 ～ 4 語に制限してください。

パラメータの説明では、そのパラメータがジョブの実行に与える影響をユーザーに説明する必要があります。

パラメータが、サポートされている値の所定の量をサポートしている場合は、説明内に次のセクションを指定します。

Possible Values: {value 1}, {value 2}。

認証パラメータに加えて、すべてのジョブに次のパラメータが必要です。

  • Max {Hours/Days} Backwards: ジョブの最初のイテレーションの開始時間を指定します。
  • SSL の検証: API / インスタンスへの接続を確認します。

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