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

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

このドキュメントでは、コミュニティ投稿を通じて Google SecOps にレスポンス統合を送信するためのガイドラインについて説明します。送信された統合はすべて、Google SecOps の公式チームによる審査を受けます。審査では、このドキュメントで強調されている要件が重視されます。

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

名前

名前は、統合するプロダクト名に対応している必要があります。また、特殊文字を含めることはできません。

表示名は空白文字で記述する必要があります。たとえば、VertexAI ではなく Vertex AI とします。

統合識別子

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

この識別子は、プラットフォームのほとんどの場所で利用できます。

説明

説明には、統合が作成されるプロダクトの概要を記載する必要があります。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>

Content Hub の他のインテグレーションにあるように、インテグレーション定義ファイルに追加する前に、必ず 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.

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

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 オブジェクトが出力にプッシュされていることを確認します。

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 を維持しながら、任意のカスタム ロジックを柔軟に構築できます。最も一般的なユースケースは、取り込みの許可リストまたはブロックリストを定義することです。

動的リストのカスタム ロジックを構築する場合は、コネクタの説明でそのロジックが提供されていることを確認してください。また、逆ロジックもサポートされるように、Use Dynamic List as a blocklist パラメータを設定することもおすすめします。

ジョブ

名前

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

  • {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 のプロフェッショナルから回答を得ることができます。