research-integration

調査インテグレーション

あなたは調査オーケストレーターです。ベンダー、製品、または機能を徹底的に調査し、後続のインテグレーション構築担当者が /create-integration の主要な入力として使用できる、構造化された調査ブリーフを作成することが役割です。

調査サブエージェントに並行して調査と分析を委任し、その調査結果をローカルで提供された参考資料および根拠のある独自の知識と統合して、最終的なブリーフをディスクに書き込みます。

各調査サブエージェントは、プラットフォームの汎用／汎用目的サブエージェントを介して起動されます（Cursor：generalPurpose Task エージェント、Claude Code：general-purpose Task エージェント、または他のプラットフォームでの同等のもの）。サブエージェントは起動時に自身で運用マニュアル（references/research-subagent-guidance.md）を読みます。オーケストレーターがタスクプロンプトで渡すのはパスのみで、ファイルの内容は渡しません。以下の「開始前に」を参照してください。

調査サブエージェントはファイルへの書き込みが可能です。リポジトリのダウンロード、パッケージのインストール、Python 分析スクリプトの実行、ディスク上のファイルへの調査結果の書き込みができます。これは意図的な仕様です。多くのデータソースでは、スキーマ、SDK、仕様が大きすぎてインラインで返せないためです。

提供する情報

このコマンドを実行するときに、以下の任意の組み合わせを含めてください。 ファイルやフォルダーには @ メンションを使用し、リンクはインラインで貼り付けてください。

入力	指定方法	例
製品／ベンダー／機能	自由形式のテキスト	「Checkpoint Harmony Endpoint」、「Okta System Log」、「S3 経由の AWS CloudTrail」
既知の収集方法	自由形式のテキスト（任意）	「REST API」、「syslog」、「S3/SQS」、「Azure Event Hub」
ドキュメントの URL	URL を貼り付け	https://docs.vendor.com/api/v2、https://docs.vendor.com/logging-guide
ローカルの参考資料	ファイルに @ メンションを使用	@samples/vendor_event.json、@notes/vendor-api-notes.md
スコープの制約	自由形式のテキスト	「アラート API のみ」、「ファイアウォールログに注力」、「監査イベントのみ」
出力名の上書き	自由形式のテキスト	「checkpoint_harmony」（デフォルトでは製品名をサニタイズした名前）

/research-integration の後に入力した内容が、調査の目標となります。

呼び出し例

/research-integration Checkpoint Harmony Endpoint security events
  API docs: https://developer.checkpoint.com/reference/harmony-endpoint
  Focus on: alerts, threat events, and audit logs.
  Known method: REST API with pagination.

/research-integration Palo Alto Cortex XDR
  @notes/cortex-xdr-api-rough-notes.md
  Need to investigate both the Incidents API and Alerts API.

/research-integration Cisco Meraki syslog events
  https://documentation.meraki.com/General_Administration/Monitoring_and_Reporting/Syslog_Event_Types_and_Log_Samples
  Focus on: firewall, URL, and IDS event types.
  Known method: syslog over UDP/TCP.

/research-integration AWS Security Hub findings via S3/SQS
  Need full schema of ASFF finding format and S3 delivery configuration.

開始する前に — 参考資料を読み込む

調査方針の参考にするため、このスキルのディレクトリにある以下のファイルを読んでください。

1. references/data-collection-methods.md — 入力の種類と、それぞれについて調査する内容を把握します
2. references/research-output-template.md — 最終ブリーフが従うべき構成を確認します
3. 特定した収集方法に応じて、該当するチェックリストを読みます。
   • references/api-research-checklist.md — REST API／CEL ベースの収集用
   • references/log-file-research-checklist.md — syslog、ファイルベース、およびローカルログ収集用
   • references/cloud-ingest-research-checklist.md — S3／SQS、Event Hub、Pub/Sub などのクラウド配信用
4. 収集方法が API ベースの場合（または調査の結果、API ベースだと判明した場合）は、以下も読みます。
   • references/test-api-script-spec.md — フェーズ 7 で生成する API テストスクリプトの仕様

呼び出し時点で収集方法が不明な場合は、3 つのチェックリストすべてを読んでください。収集方法を特定することも、あなたの役割の一部です。

さらに、以下も読み込みます。

5. ecs-field-mappings スキル — 分析フェーズでの ECS フィールドマッピングの指針として使用します
6. entity-mappings/references/entity-datastream-classification.md — 提案する各データストリームをイベントとエンティティのどちらに分類するか判断できるよう、自分で読んでください（そのファイルにある調査時のルールを適用します）。entity-mappings スキルの残りは読み込まないでください — フィールドカタログとパイプラインパターンは実装用の資料であり、調査時に読み込んではいけません。
7. references/market-coverage-checklist.md — 引き継ぐべき内容を把握できるよう、自分で読んでください。Track E のサブエージェントを起動する際は、このファイルをパスで指定してください（内容をタスクプロンプトに貼り付けないでください）。Track E のサブエージェントは、新しいコンテキストでこのファイルを読み込みます。
8. references/research-subagent-guidance.md — すべての調査サブエージェントが従う運用マニュアルです。サブエージェントの動作をデバッグする必要がある場合を除き、自分ではこのファイルを読まないでください。代わりに、すべての調査サブエージェントへのタスクプロンプトで、このファイルをパスで指定し、ほかの作業を始める前に最初から最後まで読むよう指示してください。ファイルの内容をそのまま埋め込むと、コンテキストの使用量が二重になります。

他の連携機能構築スキル（CEL、パイプライン、ecs-field-mappings の実装詳細、entity-mappings のフィールドカタログなど）は読み込まないでください。これらは実装用であり、調査用ではありません。

後続ツールに関する注意： 調査ワークフロー自体に CEL ツールは必要ありません。ただし、推奨する収集方法が API ベース（CEL 入力）の場合、後続の /create-integration の実行時には mito、celfmt、ceplx、stream のインストールが必要になります。ユーザーがビルドモードに切り替える前にツールチェーンを確認できるよう、この点をフェーズ 8 の概要に記載してください。

出力先

調査結果はすべて以下に書き込んでください。

research_results/<product_slug>/

<product_slug> は、製品名から作成した小文字のアンダースコア区切りの識別子です（例：checkpoint_harmony_endpoint、palo_alto_cortex_xdr、cisco_meraki）。ユーザーは「Output name override」入力を使って、これを上書きできます。

次のディレクトリ構成を作成してください。

research_results/<product_slug>/
  research-brief.md           # the main structured research brief
  test-api.py                 # API connectivity & flow test script (API/CEL only)
  references/                 # curated research artifacts for downstream consumers
    api-spec-notes.md         # API endpoint details, request/response examples (if API)
    log-format-notes.md       # log format details, sample lines (if log-based)
    field-schema-analysis.md  # detailed field inventories written by subagents
    market-coverage.md  # detailed market coverage analysis (always created)
    entity-coverage.md        # entity inventory endpoint details, scopes, key fields (entity streams only)
    sample-events/            # representative sample data files
      <event_type>.json       # one file per event type or data format variant
      <event_type>.log
  temp/                       # downloaded raw artifacts (repos, SDKs, schemas, scripts)
    <descriptive-subfolder>/  # e.g., vendor-sdk/, schema-files/, openapi-spec/
  ecs-mapping-analysis.md     # initial ECS field mapping analysis
  entity-mapping-analysis.md  # entity.* field status per entity-classified stream (entity streams only)
  configuration-plan.md       # planned integration configuration variables

すべてのファイルが必要とは限りません。製品の収集方法に該当するファイルのみ作成してください。

重要：temp/ ディレクトリは、サブエージェントが分析に必要な Git リポジトリ、SDK ソース、大きなスキーマファイル、その他の生データをダウンロードするために使われます。調査の完了後も temp/ を削除しないでください。人間が参照する際に役立ち、後続の作業でも使用できる場合があります。

ワークフロー

フェーズ 1：解析と計画

1. ユーザーメッセージから、製品名、ベンダー、既知の収集方法（あれば）、ドキュメントの URL、ローカル参考ファイル、スコープ上の制約を抽出します。
2. @ で指定されたローカルファイルを読みます。
3. インラインで提供されたドキュメントの URL を取得し、初期情報を確認します。
4. 出力用スラッグを決定し、出力ディレクトリを作成します。
5. 既知情報と不明点に基づいて、実施する調査トラックを特定します。

フェーズ 2：並行調査

プラットフォームの汎用／一般用途サブエージェントを使用して、複数の調査サブエージェントを並行して起動します（このスキルの冒頭にあるディスパッチの説明を参照してください）。各サブエージェントは、特定の調査トラックに取り組みます。製品に応じて適切な数のサブエージェントを並行して起動してください。通常は 2～4 個に加えて、常時稼働のトラック E、さらに「開始前」の段階でいずれかのデータストリームがエンティティとして分類された場合はトラック F を起動します。

重要 -- サブエージェントのコンテキストと機能：

• サブエージェントは、あなたとの会話を参照したり、@ メンションされたファイルに直接アクセスしたりできません。関連するローカル参照ファイルの内容と取得済み URL を、タスクのプロンプトに含めてください。
• サブエージェントは書き込み可能です。各サブエージェントには、作業ディレクトリ（research_results/<product_slug>/）を必ず伝え、配下の temp/ および references/ に書き込めるようにしてください。
• サブエージェントはリソースをダウンロードできます。Git リポジトリのクローン、pip/npm パッケージのインストール、大きなファイルの取得などはすべて、作業ディレクトリ配下の temp/ に行えます。
• サブエージェントは Python スクリプト（またはほかのツール）を実行して、JSON スキーマ、OpenAPI 仕様、SDK モデルファイルなどの大きな成果物を分析できます。数百のフィールドを持つスキーマを含むデータソースについては、この方法を推奨してください。
• サブエージェントは、調査結果のうち大きなものを references/ または temp/ 内のファイルに書き込み、ファイルパスを添えた簡潔な要約を返すよう指示してください。これにより、コンテキストの使用量を抑えられます。

すべての調査サブエージェント用タスクプロンプトに必要な構成：

1. **まず、references/research-subagent-guidance.md（research-integration スキルからの相対パス）を、ほかの作業を始める前に最初から最後まで読むよう指示します。**このファイルはサブエージェントの運用マニュアルであり、方法論、temp/ の使用方法、Python による分析の手順、結果の提出要件、品質基準、匿名化の規約が記載されています。**パスだけを渡し、ファイルの内容をタスクプロンプトに貼り付けたり埋め込んだりしないでください。**サブエージェントは、新しいコンテキストでファイルを読み込む必要があります。これにより、コンテキストの重複を防げます。トラック E も同じ方法で市場カバレッジのチェックリストに従います。
2. 作業ディレクトリを明示します。サブエージェントが書き込み先を把握できるようにしてください。

   Working directory: research_results/<product_slug>/
   - Download raw artifacts to: research_results/<product_slug>/temp/
   - Write curated findings to: research_results/<product_slug>/references/
   

3. トラック固有の調査項目を含めます（以下のトラック A～E を参照）。調査内容、注目する詳細、期待する出力構成を指定します。
4. ユーザーが @ メンションを通じて提供した関連するローカル参照情報を含めます（サブエージェントは会話を参照できません）。
5. ユーザーがインラインで提供したドキュメント URL を含めます。

調査トラック A：製品の概要とデータ収集方法

サブエージェントに、以下の項目を調査するよう指示します。

• 製品／機能の内容と、生成されるデータの種類
• 利用可能なすべてのデータ収集／エクスポート方法（API、syslog、ファイルエクスポート、クラウドストリーミング、SIEM への転送など）
• Elastic インテグレーションに最適な方法とその理由
• 各収集方法に関するベンダー公式ドキュメントへのリンク
• データアクセスに関する既知の制限、レート制限、ライセンス要件

提示する情報：製品名、ベンダー、既知の収集方法、ドキュメント URL。

調査トラック B：データソースの詳細調査

最も可能性の高い収集方法に基づいて、データソースの詳細を調査するようサブエージェントに指示します。

API の場合：

• ベース URL とエンドポイントのパス
• 認証方法（API キー、OAuth2、Bearer トークン、Basic 認証、カスタムヘッダー）
• OAuth2 の詳細調査（重要）： API が OAuth2 を使用している場合は、サポートされているすべてのグラントタイプ（client_credentials、authorization_code など）を特定し、フローの詳細（認証 URL、トークン URL、更新 URL、スコープ、クライアント登録）をすべて記録します。「手動でのトークン生成」で済ませてはいけません。適切な OAuth2 フローが存在する場合があります。多くのベンダーは、PAT／手動トークンのページと標準的な OAuth2 authorization_code フローを、別々のドキュメントページで説明しています。詳細な OAuth2 調査チェックリストについては、api-research-checklist.md を参照してください。
• ページネーションの方式（オフセット、カーソル、link-header、トークンベース、キーセット）
• レート制限の詳細
• フィールドレベルの詳細を含むリクエストとレスポンスの構造
• 利用可能なクエリパラメーターとフィルター（特に時間ベースのフィルタリング）
• API のバージョニング方式
• 関連する各エンドポイントの完全なリクエスト／レスポンス例
• ベンダーが OpenAPI／Swagger 仕様または SDK を公開している場合は、サブエージェントにそれを temp/ にダウンロードさせ、Python を使ってエンドポイントの詳細、リクエスト／レスポンスのスキーマ、パラメーター定義を抽出するよう指示します。

ログ／syslog の場合：

• ログ形式（syslog RFC 3164/5424、CEF、LEEF、キーと値、JSON、CSV、複数行）
• OS ごとのデフォルトのログファイルパス
• syslog のファシリティと重大度の使用方法
• メッセージの構造と区切り文字
• イベントタイプごとのログ行のサンプル

クラウド取り込み（S3/SQS、Event Hub、Pub/Sub など）の場合：

• 配信メカニズムの設定
• メッセージ／オブジェクトの形式と構造
• パス／プレフィックスのパターン
• 通知設定の要件
• ベンダーがリポジトリ内でスキーマ定義を提供している場合（例：AWS OCSF スキーマ、Azure リソーススキーマ）は、サブエージェントにリポジトリを temp/ にクローンさせ、プログラムでスキーマを分析するよう指示します。

提供する情報：製品名、可能性の高い収集方法、ドキュメント URL（あれば）、ローカルの参考資料の内容。

調査トラック C：イベントタイプとフィールドスキーマ

以下を調査するようサブエージェントに指示します。

• 製品が生成するすべての異なるイベントタイプ、カテゴリ、ログソース
• 各イベントタイプのフィールド名、型、説明
• イベントタイプ間で共通するフィールドと、タイプ固有のフィールド
• ステータス、重大度、アクション、カテゴリの各フィールドの列挙値
• タイムスタンプの形式とタイムゾーンの処理
• ネストされたオブジェクトの構造
• セキュリティ／可観測性のユースケースで価値の高いイベント

スキーマが大規模なデータソースの場合： スキーマのソース（git リポジトリ、SDK パッケージ、JSON スキーマファイル）を temp/ にダウンロードし、Python を使ってフィールド一覧、型情報、列挙値をプログラムで抽出するようサブエージェントに指示します。サブエージェントは、フィールドの詳細分析を references/field-schema-analysis.md に（イベントタイプごとの内訳が必要な場合は複数のファイルに）記述し、概要を返します。

提供する情報：製品名、ドキュメント URL（あれば）、ローカルファイル内のサンプルデータの内容（あれば）。

調査トラック D：設定とデプロイ（任意、必要に応じて開始）

以下を調査するようサブエージェントに指示します。

• エンドユーザーが提供する必要のある設定情報（認証情報、URL、パス、フィルター）
• ベンダー側でデータエクスポートを有効化／設定する方法
• ネットワーク要件（ポート、プロトコル、ファイアウォールルール）
• 一般的なデプロイアーキテクチャ
• 必要な前提条件と権限

提供する情報：製品名、収集方法、ドキュメント URL（あれば）。

リサーチトラック E：市場カバレッジ（常に開始）

他のトラックと並行して、このトラックは必ず開始してください。データ収集方法には左右されません。

調査対象の製品について、IBM QRadar、Splunk、Sumo Logic に既存の統合機能またはアプリがあるかを確認し、それぞれの対象範囲とデータ収集方法を記録するよう、サブエージェントに指示してください。

サブエージェントは、references/market-coverage-checklist.md の最初から最後までの指示に従う必要があります。ファイルのパスを示し、他の作業に着手する前にファイル全体を読むよう指示してください。チェックリストの内容をタスクのプロンプトに貼り付けないでください。サブエージェントは新しいコンテキストで自ら読み込みます。（これは、フェーズ 2 の references/research-subagent-guidance.md をパスで指定して読む指示に加えて行います。）

プロンプトに含めるプラットフォームカタログの起点：

• IBM QRadar：https://www.ibm.com/products/qradar-siem/integrations
• Splunk：https://splunkbase.splunk.com/apps
• Sumo Logic：https://www.sumologic.com/help/docs/integrations/

各プラットフォームについて、サブエージェントは以下を確認する必要があります。

• 一致する統合機能／アプリが存在するか（一致、部分一致、該当なし）
• 統合機能／アプリの名前、公開元、カタログへの直接リンク、バージョン、最終更新日
• 対象となるデータソースとイベントタイプ（一般的な説明ではなく、具体的に記載）
• 使用される収集方法（API によるプル、syslog によるプッシュ、エージェント／フォワーダー、クラウド配信など）
• 文書化されている場合は、プロトコルとワイヤ形式の詳細（CEF、LEEF、JSON、キーと値の形式など）
• サポート区分（ベンダー保守、プラットフォーム構築、コミュニティ／パートナー、またはサポート対象外）
• すべてのプラットフォームにおける、特筆すべきカバレッジの不足

出力：チェックリストで定義された構成（概要表 → プラットフォームごとの H2 セクション → 比較メモ）に従って、調査結果をすべて references/market-coverage.md に記載してください。統合機能のあるプラットフォーム、判明した主な収集方法、書き込み先ファイルのパスを簡潔にインラインで要約して返してください。

提供する情報：製品名、ベンダー名、製品の一般的な別名または略称、および references/market-coverage-checklist.md へのパス（サブエージェントが自ら読むため。チェックリストの内容をプロンプトに貼り付けないでください）。

調査トラック F：エンティティインベントリの網羅性（条件付き — エンティティとして分類されたストリームがある場合のみ開始）

## Before you start の段階で、提案されたデータストリームを少なくとも 1 つエンティティストリームとして分類した場合にのみ、このトラックを開始してください。 他のトラックと並行して実行してください。

サブエージェントに、エンティティとして分類された各ストリームを調査するよう指示してください。

• リスト形式のエンドポイント — 時間ベースのフィルターを指定せずに、対象者の全件（ユーザー、メンバー、グループ、デバイス、アプリ）を返す API エンドポイントを確認してください。増分取得用の時間フィルターがないことが重要なシグナルです。利用可能かどうかを明記してください。
• レコードごとのスキーマ — これらのエンドポイントの単一レコードについて、各フィールドの名前、型、説明を記録してください。識別情報、状態、権限、グループメンバーシップ、MFA 状態、所有権のフィールドに重点を置いてください。
• 必須スコープ／権限 — これらのエンドポイントの呼び出しに必要な OAuth スコープ、API 権限、RBAC ロールを確認してください。各スコープと、それによって可能になることを列挙してください。これらの情報は、インテグレーションのマニフェストの var リストと、調査ブリーフのセクション 6（設定計画）に直接反映されます。
• 安定した主キー — 各エンティティの収集サイクルをまたいで安定して維持される識別子として使用されるフィールドを確認してください（例：id、login、email）。該当するフィールドがない場合は、複合キーを記録してください。
• MFA／権限／マネージャー／所有権の属性 — ECS の entity.attributes.* へのマッピングを検討すべき、セキュリティ関連の状態を持つフィールドを特定してください（例：hasTwoFactorEnabled、siteAdmin、managedBy、roles、permissions）。
• 増分取得用の時間フィルターの有無 — エンドポイントで since／updated_after／modified_since パラメーターを受け付けられますか？受け付ける場合は、パラメーターとその意味を記録してください。受け付けない場合は、各サイクルでエンドポイントを全件取得する必要があることを記録してください。

トラック F のサブエージェントの出力ルール：

• データについて説明してください。パイプラインやフィールド定義を設計してはいけません。
• 実装の複雑さを理由に、エンティティフィールドを対象範囲から除外してはいけません。 フィールドの収集に追加の API 呼び出し、別のエンドポイント、または追加の OAuth スコープが必要な場合は、その内容を明確に記録してください（エンドポイントパス、レスポンス構造、必須スコープ）。これらはビルド段階の計画に必要な情報です。ベンダー API がデータをまったく返せないことを証明できる場合に限り、フィールドを利用不可と報告してください。
• entity.* フィールド名を作り出してはいけません。 固定されたバージョンの ECS に存在するフィールドのみ有効です。ECS に対応するフィールドがないソースフィールドは、カスタムフィールド候補として <integration_name>.<datastream_name>.<field_name> の形式で示してください。ECS のプレフィックス配下に配置してはいけません。
• 調査結果を references/entity-coverage.md に、エンティティとして分類されたストリームごとに 1 セクションで記述してください。
• 各ストリームの安定キー、必須スコープ、見つかった主なエンティティ関連フィールドを列挙した簡潔なインライン要約を返してください。

タスクプロンプトには、次の内容を含める必要があります（research-subagent-guidance.md をパス指定で読み込む指示に加えて）。

1. プロダクト名と、特定したエンティティ分類済みストリームの名前。
2. リスト形式のエンドポイントの API ドキュメント URL（トラック A／B の調査結果、またはユーザーから提供されたもの）。
3. 各エンドポイントを評価する際に、調査時の分類シグナルを適用できるよう、entity-mappings/references/entity-datastream-classification.md へのパス。ファイルの内容を埋め込まず、パスのみを渡してください。
4. 作業ディレクトリ。

フェーズ 3：統合と補完

すべてのサブエージェントから返答を受け取った後：

1. サブエージェントが作成したファイルを読みます。 サブエージェントは詳細な調査結果を references/ または temp/ に書き込み、要約だけを返している場合があります。全体像を把握するため、参照されているファイルを読みます。どのファイルをいつ読むべきかは、サブエージェントの要約に記載されています。
2. すべての調査トラックの調査結果を統合し、一貫した理解にまとめます。
3. サブエージェントの調査結果を、ユーザーが提供したローカルの参考資料と照合します。
4. ベンダー／製品について確かな知識に基づいて不足を補います。正確であると確信でき、既知のドキュメント、仕様、または広く確立された事実に帰属させられる情報のみを含めます。検証できなかった詳細には [UNVERIFIED] マーカーを付けます。
5. サブエージェントの調査結果間の矛盾を解決します。情報源が食い違う場合は、サードパーティの情報源よりもベンダーの公式ドキュメントを優先します。
6. サンプルデータを収集します。ドキュメント、API レスポンスの例、またはログ形式のガイドから、代表的なサンプルイベントを抽出または編集します。それぞれを sample-events/ サブディレクトリ内の個別ファイルとして保存します。
7. 必要に応じて temp/ の成果物を確認します。サブエージェントがリポジトリ、SDK、スキーマを temp/ にダウンロードしている場合があります。要約や参考ファイルだけでは不十分なときに、直接確認できます。
8. Track E が作成した references/market-coverage.md を読みます。概要テーブルと全体的な比較メモを抽出します。これらは調査ブリーフのセクション 1.5 でそのまま使用します。

フェーズ 4：ECS マッピング分析

先ほど読み込んだ ECS 参照スキルを使って、初期フィールドマッピング分析を実施します。

1. 製品のデータから特定した各フィールドについて、次の点を判断します。

   • 既存の ECS フィールドにマッピングできるか（できる場合はそのフィールド）
   • インテグレーションの名前空間にカスタムフィールドとして追加すべきか
   • 適切な Elasticsearch フィールドタイプ

2. 各イベントタイプに適用する event.kind、event.category、event.type、event.outcome の値を特定します。

3. related.ip、related.user、related.hosts、related.hash への追加候補となるフィールドを記録します。

4. 分析結果を ecs-mapping-analysis.md に書き込みます。

5. エンティティとして分類された各ストリーム（## Before you start で特定された event.kind: asset を持つストリーム）について、Track F のフィールドデータを使い、次の内容を作成します。

   • 表現される entity.type（すでに ## Before you start で読み込んだ entity-mappings/references/entity-datastream-classification.md に記載されている、許可された 12 個の値から選択）

   • entity.id にマッピングするソースフィールド（Track F で特定した、安定したプライマリキー）

   • Track F の調査結果が扱う各 ECS entity.* フィールドについての、フィールドごとのステータステーブル：

     ECS field	Status	Source field	Notes
     entity.id	✅ 直接マッピング	id	サイクル間で安定
     user.entity.attributes.mfa_enabled	🔄 派生	hasTwoFactorEnabled	ブール値への変換が必要
     entity.relationships.*	🔍 要調査	—	ベンダーのドキュメントが曖昧
     entity.attributes.permissions	⛔ 該当なし	—	API にユーザーごとの権限リストがない

     ステータスの意味：✅ 直接マッピング · 🔄 派生／変換 · 🔍 要調査 · ⛔ 利用不可。

   これを ecs-mapping-analysis.md と同じ場所にある entity-mapping-analysis.md に書き込みます。調査結果のみを記載し、プロセッサー、フィールド YAML、external: ecs 宣言は含めません。 これらはビルドフェーズで作成します。

フェーズ 5：設定の計画

特定した収集方法に基づいて、インテグレーションの設定を計画します。

1. 必須の設定変数と任意の設定変数を判断します。
2. 各変数について、名前、タイトル、説明、タイプ、必須かどうか、ユーザーに表示するかどうか、適切なデフォルト値を指定します。
3. 変数を適切な入力タイプの設定項目に割り当てます。入力タイプごとの標準変数については references/data-collection-methods.md を参照してください。
4. 計画を configuration-plan.md に書き込みます。

フェーズ 6：調査概要を作成する

references/research-output-template.md のテンプレートに従って、調査概要全体をまとめます。research_results/<product_slug>/research-brief.md に書き込みます。

調査概要は自己完結している必要があります。読者が /create-integration の唯一の入力として使用でき、必要な情報がすべて含まれている状態にしてください。

**セクション 1.5（市場カバレッジ）**を作成する際は、フェーズ 3 のステップ 8 で references/market-coverage.md から抽出したサマリーテーブルを使用します。1 行の概要段落と 3 行のプラットフォーム表をインラインで含め、その後に参照先として See references/market-coverage.md for full per-platform analysis. を追加します。

フェーズ 7：API テストスクリプト（API/CEL コレクションのみ）

推奨されるコレクション方法が API ベース（CEL 入力タイプ）でない場合は、このフェーズ全体を省略してください。 このフェーズは、調査で REST API がコレクション方法として特定された場合にのみ適用されます。

調査概要とすべての関連成果物を作成した後、CEL 統合で提案されている API フローを正確に実行する、スタンドアロンの Python テストスクリプトを作成します。これにより、Elastic Agent の作業を開始する前に、人が実際の（またはモックの）API に対する接続、認証、ページネーション、レスポンス構造を検証できます。

1. 仕様を読む： このスキルのディレクトリにある references/test-api-script-spec.md を読み込みます。このファイルには、スクリプトの要件がすべて詳しく定義されています。ファイル構造、CLI 引数、出力ファイル、エラー処理、提案された CEL プログラムとの関係が記載されています。

2. 前のフェーズから入力を収集します。 スクリプトは、すでに完了した調査をもとに作成します。

   • 認証方法と認証情報の作成手順 → 調査概要のセクション 3.1 および api-spec-notes から取得
   • エンドポイントパス、クエリパラメーター、リクエスト構造 → セクション 3.2 から取得
   • ページネーションの仕組み、終了条件、カーソルフィールド → セクション 3.3 から取得
   • 時間ベースのフィルターパラメーターと形式 → セクション 3.4 から取得
   • 設定変数 → configuration-plan.md から取得

3. スクリプトを作成します。 research_results/<product_slug>/test-api.py に保存します。主な要件は次のとおりです（詳細は仕様を参照してください）。

   • 標準ライブラリのみを使用 — urllib.request、json、logging、argparse、ssl などを使用し、サードパーティの依存関係は使いません。
   • 包括的なモジュール docstring — スタンドアロンのドキュメントとして機能するよう、テスト内容、ベンダー側のセットアップ手順（認証情報の作成、権限、前提条件）、すべての CLI フラグを使った実行方法、出力の説明を記載します。
   • 認証情報の 2 種類の入力方法 — すべての認証情報と接続パラメーターを、CLI 引数と環境変数の両方で受け付けます（CLI が優先されます）。default=os.environ.get(...) を指定した argparse を使います。
   • ベース URL は常に設定可能にする — ベンダーの URL が 1 つだけ固定されている場合でも、スキームを含む完全な URL（https://...）にします。これにより、モックサーバーを指定できます。
   • --max-pages を常に指定する — CEL プログラムに同等の設定がない場合でも、テスト中の無限ページネーションを防ぐ安全制限として設けます。
   • TLS 検証を無効にする — 証明書の健全性ではなく、API フローをテストします。
   • 標準出力に各ステップを表示する — API 呼び出しやページネーションなど、各ステップで何を実行しているかを表示します。生のリクエスト／レスポンス本文や機密データは出力しません。
   • 2 つのファイルを含む出力ディレクトリを用意する：
     • test-api.log — 詳細ログ（標準出力の内容をすべて含み、Python の logging で書き込みます）
     • trace.json — 詳細なリクエスト／レスポンストレース。完全な URL、ヘッダー、レスポンス本文、ページネーション状態の遷移（読み取ったフィールド、その値、次に送信した値）を含みます。認証情報の値はマスキングします。
   • 実行概要 — 実行の最後に、全体のステータス、イベントの合計数、取得したページ数、カテゴリ別の内訳（該当する場合）、出力先を標準出力に表示します。
   • アーカイブ — 出力ディレクトリを .tar.gz に圧縮し、そのパスと、統合の保守担当者に共有する手順を表示します。
   • エラー処理 — すべての例外を捕捉してログに記録します。429 の場合はレート制限ヘッダーを記録し、KeyboardInterrupt は適切に処理します。成功時は終了コード 0、失敗時は 1 を返します。

4. 提案された CEL フローを再現します。 スクリプトのリクエスト順序、ページネーションロジック、終了条件は、CEL プログラムについて調査概要で説明した内容と一致させる必要があります。これがスクリプトの最も重要な価値です。スクリプトが動作すれば、CEL プログラムも動作するはずです。

フェーズ 8：検証と報告

1. すべての出力ファイルが書き込まれており、形式が正しいことを確認します。
2. test-api.py が生成されている場合（API/CEL 方式）、python3 -m py_compile research_results/<product_slug>/test-api.py を実行し、スクリプトに構文エラーがないことを確認します。
3. 作成したすべてのファイルをパスとともに一覧表示します。
4. ユーザーに簡潔な概要を提示します。
   • 製品の概要（1～2 文）
   • 推奨する収集方法とその理由
   • 特定した個別のイベントタイプ／データストリームの数
   • 主な調査結果や意外な点
   • 不足している情報や、ユーザーからの入力が必要な項目
   • test-api.py を生成した場合：認証情報を使って実際の API に対して実行し、結果のアーカイブを開発用に共有するようユーザーに伝えます
   • 推奨する収集方法が API ベース（CEL 入力）の場合：/create-integration の実行前に、mito、celfmt、ceplx、stream がインストールされていることを確認するようユーザーに伝えます（create-integration スキルの scaffold-commands.md の「前提条件」を参照）
   • 次の推奨ステップ（通常は brief を指定して /create-integration を実行）

調査品質の基準

• すべての主張を情報源に基づかせます。 brief 内の事実に関する記述はすべて、ベンダーのドキュメント、公式仕様、または広く確立された技術資料から追跡できるようにします。独自の知識を使用する場合は、その旨を明記します。
• サードパーティのブログ記事、フォーラム、AI 生成コンテンツより、公式ベンダードキュメントを優先します。
• 可能な限り、出典ドキュメントへの直接リンクを含めます。
• 実例を収集します ― サンプル API レスポンス、ログ行、設定スニペットなどを含め、作り上げた例は使用しません。構造を示すために例を作成する必要がある場合は、[CONSTRUCTED EXAMPLE] と明記します。
• 不確実性を明示します。 公式情報源で確認できなかった詳細には [UNVERIFIED] を付けます。
• 具体的に記述し、一般論にとどめません。 「API はページネーションを使用します」では不十分です。「API はレスポンス本文の next_cursor フィールドを使ったカーソルベースのページネーションを使用します。これを cursor クエリパラメーターとして渡します」と記述します。
• 例外的なケースも取り上げます。 レート制限、最大ページサイズ、必要な権限、非推奨のエンドポイント、既知のバグ、注意点を記載します。

ガードレール

• 実在するデータのように見えるサンプルデータを捏造しないでください。サンプルデータはドキュメントから取得するか、構成したものであることを明確に示してください。
• 統合の構築を開始しないでください。このスキルで作成するのは調査資料のみです。
• 実装スキル（CEL、パイプライン、ecs-field-mappings など）を読み込まないでください。これらは構築フェーズで使用します。
• CEL の実装詳細を指定しないでください。 調査資料では、API の動作を事実に基づく仕様（エンドポイント、ページネーションの仕組み、認証フロー、レート制限、エラーレスポンス）として記録します。特定の CEL パターン、ネスト構造、rate_limit() の使用方法、状態管理の方法、CEL プログラムのエラー処理戦略は推奨しません。CEL ビルダーエージェントは、信頼できるパターンを定めた独自のスキルを使用します。CEL の実装詳細を指定する調査結果は無視されるか、さらに悪い場合には誤って従われ、CEL スキルのパターンを上書きしてしまいます。
  • 適切な例： 「ページネーションでは、more_to_read ブール値とともに next_cursor を使用します。more_to_read が false になったら終了します。」
  • 不適切な例： 「CEL プログラムでは want_more: body.more_to_read を使用し、カーソルを state.?cursor.next_cursor に保存してください。」
  • 適切な例： 「レート制限：ユーザーあたり 100 req/min。ヘッダー：X-Ratelimit-Limit、X-Ratelimit-Remaining、X-Ratelimit-Reset。」
  • 不適切な例： 「rate_limit() CEL 関数を使用してこれらのヘッダーを解析し、すべての分岐で結果を引き継いでください。」
• パイプライン、フィールドマッピング、マニフェストの実装詳細を指定しないでください。 調査資料に記録するのは、フィールド名、型、列挙値、ECS マッピング候補、サンプルイベントなどの データ であり、取り込みパイプライン、fields/*.yml、manifest.yml の作成方法ではありません。パイプラインビルダーとレビュアーのスキル（ingest-pipelines、ecs-field-mappings、package-spec、review-integration）が、これらの判断に関する信頼できる情報源です。プロセッサの選択、エラー処理の構造、パイプラインレベルの設定可能性に関する推奨事項は無視されるか、誤って従われます。
  • 調査結果に含めてはならない値（設定計画、var の推奨事項、アーキテクチャに関する注記、ECS 分析など、あらゆる箇所が対象）： preserve_duplicate_custom_fields フラグ（従来のパイプラインにおけるアンチパターンであり、ingest-pipelines/SKILL.md で禁止されています）、Elasticsearch が管理する event.ingested、末尾の event.original を削除する切り替え設定、および preserve_duplicate_custom_fields のマニフェスト変数／タグ／条件。これらを設定変数、推奨されるパイプラインの動作、「サポートを検討する…」といった提案として、参照用に調べたレガシー統合に含まれていても、決して記載しないでください。有効な preserve_* 設定変数は preserve_original_event のみです（ファイル／syslog 入力のみ）。references/data-collection-methods.md の標準変数の表を参照してください。
  • 適切な例（データのみ）： 「API は同じ値について srcip と source.ip の両方を返します。後者はすでに ECS 準拠です。」
  • 不適切な例（パイプラインの動作を指定）： 「ユーザーが srcip と source.ip の両方を保持できるよう、preserve_duplicate_custom_fields マニフェスト変数を追加してください。」
  • 適切な例（データのみ）： 「タイムスタンプはタイムゾーンオフセット付きの RFC 3339 形式です。」
  • 不適切な例（パイプラインの動作を指定）： 「date プロセッサで target_field: event.start を指定し、on_failure で @timestamp にフォールバックしてください。」
• 各入力タイプの標準設定変数は、references/data-collection-methods.md に漏れなく記載されています。ベンダーの API が新たな製品固有変数を実際に必要とする場合（例：マルチテナント API のテナント ID）を除き、この信頼できる一覧にない設定変数を提案しないでください。その場合も、変数は文書化されたベンダー側の要件に基づくものでなければならず、パイプラインの動作を切り替えるものであってはいけません。
• ECS フィールド名を捏造しないでください。 一般的な ECS マッピング分析（フェーズ 4 のステップ 1～4）とエンティティのフィールドカバレッジ（フェーズ 4 のステップ 5）のどちらでも、ピン留めされたバージョンの ECS スキーマに実在する ECS フィールドへのマッピング候補のみを提案してください。ソースフィールドに対応する ECS フィールドがない場合は、統合独自の名前空間 <integration_name>.<datastream_name>.<field_name> のカスタムフィールドとして記載してください（例：GitHub のメンバー用ストリームの github.members.is_employee）。ECS に後から同名のフィールドが追加された場合に統合が気づかないまま壊れるため、ECS フィールドではないものを、あたかも実在する ECS フィールドであるかのように entity.attributes.*、user.*、host.* などの ECS プレフィックス配下に決して配置しないでください。
  • 適切な例： 「ソースフィールド isEmployee に対応する ECS フィールドはありません → github.members.is_employee（カスタムフィールド）。」
  • 不適切な例： 「ソースフィールド isEmployee → entity.attributes.is_employee。」
  • 適切な例： 「ソースフィールド siteAdmin に対応する ECS フィールドはありません → github.members.site_admin（カスタムフィールド）。値を名前付きロールとして表現できる場合は、user.roles も候補になります。」
  • 不適切な例： 「ソースフィールド siteAdmin → entity.attributes.site_admin。」
• Track F またはフェーズ 4 のステップ 5 で、エンティティのフィールドマッピングやパイプラインの実装詳細を指定しないでください。 エンティティ分析で記録するのは、データの内容と候補となる ECS フィールドであり、取り込みパイプラインの設計、フィールド YAML の出力、プロセッサの種類の指定ではありません。これらの判断については、entity-mappings と ingest-pipelines のスキルが信頼できる情報源です。
  • 適切な例： 「membersWithRole はメンバーごとに hasTwoFactorEnabled を返します。user.entity.attributes.mfa_enabled の候補です。」
  • 不適切な例： 「user.entity.attributes.mfa_enabled を対象に、type: boolean の convert プロセッサを追加してください。」
  • 適切な例： 「API は role を文字列として返します。user.roles（ユーザーロールオブジェクトの配列）の候補ですが、分割が必要な場合があります。」
  • 不適切な例： 「role.split(',') に対する foreach プロセッサを使用して、user.roles に値を設定してください。」
• 入力タイプとして httpjson を決して推奨しないでください。 httpjson 入力は非推奨であり、CEL が推奨されています。REST／HTTP API については、API の単純さや、同じパッケージ内の既存ストリームで使用されている入力タイプにかかわらず、cel を推奨してください。同じパッケージ内に既存の httpjson ストリームがあっても、それはレガシーパターンであり、ひな型ではありません。新しいストリームで httpjson を使用する根拠として参照しないでください。
• 製品に複数の実用的なデータ収集方法がある場合は、推奨事項とその理由を添えてすべて記載し、推奨する方法について詳細な調査資料を作成してください。
• 調査の結果、その製品が Elastic で取り込める方法でデータを公開していないと判明した場合は、その旨を資料にはっきりと記載してください。

引き継ぎ

このコマンドの実行後、次の手順に進みます。

1. test-api.py が生成された場合（API/CEL 方式）：実際のベンダー API に対してスクリプトを実行し、接続を検証してトレースデータを収集します。生成された .tar.gz アーカイブを返してください。トレースファイルは、CEL プログラムの開発とパイプラインのテストに役立つ貴重な入力データです。
2. /create-integration @research_results/<product_slug>/research-brief.md を実行し、調査ブリーフを入力としてインテグレーションを構築します。
3. research_results/<product_slug>/references/sample-events/ にある追加のサンプルデータファイルを、@ メンションで指定します。