entity-mappings

entity-mappings

スキルの優先順位

このスキルのガイダンスは、elastic/integrations リポジトリ内のインテグレーションで見られるパターンより優先されます。以前からあるインテグレーションは、これらの要件が定められる前に作成されていたり、一貫性のないパターンを使用していたりする場合があります。リポジトリ内で見られる内容よりも、必ずこのスキルのルールに従ってください。

使用する場合

• 新しいインテグレーションまたは既存のインテグレーションにエンティティ／インベントリデータストリームを追加する場合
• 提案中または既存のデータストリームがエンティティストリームかイベントストリームかを判断する場合
• 新しいストリームに適切な entity.type の値を選択する場合
• ベンダーフィールドを user.entity.*、host.entity.*、またはその他のネストされたエンティティプレフィックスにマッピングする場合
• 既存パッケージのエンティティフィールドの網羅性を監査する場合（単独のギャップ分析）
• event.kind: asset の使用や entity.* フィールドのエラーを調査する場合

使用しない場合

• CDR クラウドセキュリティの検出結果（設定ミス／脆弱性の検出結果） — これらは asset ではなく event.kind: state です。代わりに ecs-field-mappings/references/cdr-field-requirements.md と ingest-pipelines/references/cdr-pipeline-requirements.md を使用してください。
• 一般的なフィールドファイルの作成（エンティティ以外のフィールド） — ecs-field-mappings スキルを使用してください。
• プロセッサの仕組み（grok、date、JSON、Painless） — ingest-pipelines スキルを使用してください。
• CEL プログラムのロジック — cel-programs スキルを使用してください。

適用条件

エンティティフィールドを適用するのは、安定した対象（ユーザー、ホスト、デバイス、アプリケーション、サービス）のインベントリを表すことを目的としたエンティティデータストリームに限られます。イベントの時系列を表すデータストリームには適用しません。イベントログ、メトリックストリーム、APM データ、CDR 検出結果ストリームにエンティティフィールドの要件を適用しないでください。

このスキルを使用する前に、references/entity-datastream-classification.md を参照してデータストリームを分類してください。確信が持てない場合は、最初に分類リファレンスを確認してください。

ECS の利用可否 — 最初にお読みください

entity.attributes.*、entity.lifecycle.last_activity、およびすべての entity.relationships.* リーフフィールドは、ECS v9.3.0（リポジトリのデフォルトのピン留めバージョン）には存在しません。これらは ECS v9.4.0 で初めて追加されました。

• [email protected] の場合：entity.attributes はサブフィールドのない単なる object であり、schemas/entity_reference.yml は存在しません。このピン留めバージョンでこれらのリーフフィールドに external: ecs を使用すると、field is undefined ビルドエラーが発生します。
• [email protected]+／[email protected] の場合（推奨）：すべてのリーフフィールドが存在し、external: ecs が正しく解決されます。

条件付きピン留めルール： エンティティデータストリームを含むパッケージでは、次のように設定する必要があります。

• _dev/build/build.yml：dependencies.ecs.reference: "[email protected]"
• パイプラインの ecs.version：9.5.0

この2つは一致している必要があります。標準（エンティティ以外の）パッケージでは、[email protected] を維持してください。

任意のタグで確認するには：

curl -s https://raw.githubusercontent.com/elastic/ecs/<tag>/generated/csv/fields.csv \
  | awk -F, '$3=="entity"' | cut -d, -f4,5 | sort -u

モード

モード	起動方法	読み込むもの
単独のギャップ分析	ユーザーが /entity-mappings @packages/<name> を実行	references/gap-analysis-workflow.md と references/entity-field-catalog.md を読み込みます。references/analysis-subagent-guidance.md を介して、ストリームごとにサブエージェントを起動します。
ビルド時	オーケストレーター（create-integration または add-datastream）が、パスを指定して references/entity-field-catalog.md と references/entity-pipeline-patterns.md をパイプラインビルダーのサブエージェントに渡します	パイプラインビルダーは両方のリファレンスを読み込みます。このスキルの SKILL.md は、オーケストレーターのスレッドには読み込まれません。
レビュー時	エンティティ検出ルールが実行されると、review-integration のステップ4で2つのリファレンスが読み込まれます	レビュアーは entity-field-catalog.md と entity-pipeline-patterns.md を読み込みます。このスキルの SKILL.md をレビュアーのスレッドに読み込む必要はありません。
調査時	research-integration は references/entity-datastream-classification.md のみを読み込みます	調査中はこのスキルの残りの部分を読み込まないでください — カタログとパイプラインパターンは実装資料であり、パイプライン／フィールドの詳細を指定しないという調査ガードレールに違反します。

未解決の質問／対象範囲外

以下のトピックは、このスキルの v1 では対象範囲外です。

• エンティティーストアの最新変換。 CDR の前例には、統合ごとの最新変換を扱う第 3 の要素（review-integration/references/cdr-transform-requirements.md）があります。新しいエンティティーデータストリームに最新変換を付属させるべきかどうかは、まだ決まっていません。その決定がなされるまでは、調査ブリーフとギャップ分析レポートで未解決の質問として記載してください。
• リポジトリー全体の ECS ピンを v9.5.0 に更新。 エンティティーストリームが一般的になった後のフォローアップとして推奨されます。それまでは、このスキルの条件付き例外によってパッケージを維持します。

参考資料

• references/entity-field-catalog.md — 信頼できる唯一の情報源：ECS の利用可能性マトリックス、再利用可能なネスト、entity.type の許可値、分類、Must Have／Should Have フィールドの表、判別ガイド、フィールド定義の YAML 例、レビュー用チェックリスト
• references/entity-pipeline-patterns.md — パイプライン側のパターン：分類プロセッサー、entity.id の構築、ブール値の強制変換、配列属性、リレーションシップオブジェクト、アンチパターン、パイプラインレビュー用チェックリスト
• references/entity-datastream-classification.md — 調査時およびレビュー時に、データストリームをエンティティーとイベントに分類するルール、詳細な例
• references/gap-analysis-workflow.md — 単独で実行できる 4 フェーズの分析：ストリームを分類 → パッケージを読む → ドキュメントを取得 → フィールドをマッピング → ギャップを調査 → レポートを作成
• references/gap-analysis-report-template.md — ギャップ分析の出力用の構造化レポートテンプレート
• references/analysis-subagent-guidance.md — ギャップ分析中にディスパッチされるストリームごとの分析サブエージェント向け運用マニュアル
• ECS エンティティーフィールドセットのリファレンス