ecs-field-mappings

ecs-field-mappings

使用するタイミング

次のようなタスクでは、このスキルを使用します。

• data_stream/<stream>/fields/ 以下のファイルを追加または変更する
• ecs.yml に ECS フィールドの参照を設定する
• event.kind、event.category、event.type、event.outcome の値を選択する
• フィールドの type とマッピングプロパティ（metric_type、dimension、multi_fields、および関連オプション）を選択する
• カスタムフィールドを追加する前に、ECS に既存のフィールドがあるか確認する
• elastic-package check、elastic-package lint、またはパイプラインのテストスキーマチェックで発生するマッピングの検証／ビルドエラーをトラブルシューティングする

ECS の依存関係設定

すべてのパッケージには、パッケージのルートに _dev/build/build.yml が必要です。このファイルで、フィールドの解決に使用する ECS スキーマのバージョンを固定します。

dependencies:
  ecs:
    reference: "[email protected]"

パッケージにフィールドファイルがある場合、このファイルは必須です。スキャフォールドでは生成されないため、手動で作成してください。このファイルがない場合、または古いバージョンを使用している場合、テストでは ECS フィールドが未定義として報告されます（例：field "destination.ip" is undefined）。

フィールドファイルと役割

データストリームの fields/ ディレクトリには、それぞれ役割の異なる少数の YAML ファイルが含まれます。

base-fields.yml

固定のルーティング定数と @timestamp を定義します。6 つのフィールドはすべて ECS フィールドなので、各エントリで external: ecs を使用します。データストリームで固定値の constant_keyword が必要な場合は、type と value をオーバーライドしてください。説明は ECS から自動的に継承されます。

- name: data_stream.type
  external: ecs
- name: data_stream.dataset
  external: ecs
- name: data_stream.namespace
  external: ecs
- name: event.module
  external: ecs
  type: constant_keyword
  value: <package_name>
- name: event.dataset
  external: ecs
  type: constant_keyword
  value: <package_name>.<stream_name>
- name: '@timestamp'
  external: ecs

ここにほかのフィールドを追加しないでください。base-fields.yml に定義するのは、これらのルーティング定数と @timestamp のみです。

constant_keyword の候補

データストリーム内のすべてのドキュメントで単一の値を保持するフィールドには、constant_keyword を使用します。base-fields.yml のルーティング定数以外では、次のフィールドを検討してください。

フィールド	constant_keyword を使用する理由
event.dataset	定義上、データストリームごとに値が 1 つ
event.module	パッケージごとに値が 1 つ
data_stream.type	ストリームごとに固定（logs／metrics）
data_stream.dataset	ストリームごとに固定
data_stream.namespace	デプロイ時に設定され、インデックス内で一定
observer.vendor	パッケージが表すベンダーは 1 つ
observer.product	パッケージが表す製品は 1 つ

constant_keyword フィールドが ECS フィールドでもある場合（例：observer.vendor）、型をオーバーライドして external: ecs を使用します。これにより ECS から説明が継承され、手動で重複して記述する必要がなくなります。定義は適切なフィールドファイル（ほとんどの ECS フィールドでは ecs.yml、ルーティング定数では base-fields.yml）に記述してください。

- name: observer.vendor
  external: ecs
  type: constant_keyword
  value: Acme Corp

remove_from_source オプション： constant_keyword は値をインデックスメタデータに 1 回だけ保存するため、各ドキュメントの _source に含める必要はありません。Elasticsearch がこれを自動的に処理するため、明示的な _source.excludes 設定は不要です。値が常に同じ場合、これによりストレージを節約できます。

ecs.yml

このファイルには、パイプラインが設定するフィールドのうち、動的マッピングでは推測できない ECS フィールドを記述します。 各エントリーでは name と external: ecs のみを使用し、型や説明は記述しないでください。型は _dev/build/build.yml を介して ECS スキーマから解決されます。

conditions.kibana.version の下限が 8.13.0 以上のパッケージでは、ecs@mappings コンポーネントテンプレートが、標準のキーワード型／日付型の ECS フィールドと、標準プレフィックスの地理空間 ECS フィールドを動的にマッピングします。そのため、明示的な宣言が必須なのは、推測できない型（標準以外の親プレフィックスにある geo_point、geo_shape、nested、flattened）か、elastic-package の検証でエラーになる場合のみです。判定基準は Kibana のバージョン制約であり、パッケージ仕様のバージョンではありません。ecs@mappings は 8.13 以降、インストール時にスタックによって適用されます。したがって、8.11／8.12 でのインストールも許可する spec-3.x パッケージには適用されず、そのようなパッケージでは、パイプラインが設定する ECS フィールドをすべて宣言する必要があります。ビルダーにとっては宣言が多くても問題ありませんが、レビュー担当者がそれを要求すべきではありません。また、既存の宣言も削除すべきノイズとはみなされません（review-integration/references/conflict-resolutions.md を参照）。

ECS に存在するフィールド名を宣言する場合は、external: ecs を使用する必要があります（Wiki のリファレンス）。これはフィールドファイル全体に適用されます。ecs.yml、base-fields.yml、および ECS フィールドを定義するすべてのファイルが対象です。external: ecs を使用したまま、プロパティ（例：type: constant_keyword、value:）を上書きできます。説明は ECS から継承されます。fields.yml、agent.yml、beats.yml では external: ecs を使用しないでください。これらのファイルでは、ECS 以外のフィールドを定義します。

- name: event.kind
  external: ecs
- name: event.category
  external: ecs
- name: event.type
  external: ecs
- name: event.outcome
  external: ecs
- name: event.action
  external: ecs
- name: source.ip
  external: ecs
- name: source.port
  external: ecs
- name: destination.ip
  external: ecs
- name: user.name
  external: ecs
- name: related.ip
  external: ecs
- name: related.user
  external: ecs

ECS フィールドに追加のメタデータ（たとえば、フィールドを TSDB ディメンションにする、または固定値を持つ constant_keyword にするなど）を付与する場合は、external: ecs とそのメタデータを組み合わせてください。説明は ECS から継承されます。定義は ecs.yml（ルーティング定数の場合は base-fields.yml）に記述します。

- name: observer.vendor
  external: ecs
  type: constant_keyword
  value: Acme Corp

fields.yml

インテグレーション固有のカスタムフィールド（ECS 以外）のみを記述します。ベンダーの名前空間には、ネストされた group 階層を使用します。

- name: acme.firewall
  type: group
  fields:
    - name: rule_id
      type: keyword
    - name: policy_name
      type: keyword
    - name: bytes_in
      type: long
      unit: byte
      metric_type: gauge

グループを type: object として宣言する必要はありません。ネストされた fields を持つ group を定義すれば十分です。オブジェクト構造は暗黙的に決まります。

labels.* の例外

labels は、任意のキーと値のメタデータ用に設計された ECS のコアオブジェクト（type: object、object_type: keyword）です。labels.* のサブキーにはベンダーの名前空間を付ける必要はありません。これはベンダープレフィックスのルールに対する唯一の例外です。

単純なキーワードフラグやインテグレーション内部のマーカー（例：labels.is_ioc_transform_source）には labels.* を使用します。アップストリームソースからの構造化データには、ベンダーの名前空間を使用します。

フラグと構造化データ

ブール値のフラグや単純なタグは、ベンダーグループの直下に配置できます。

- name: acme.firewall
  type: group
  fields:
    - name: is_encrypted
      type: boolean
    - name: policy_name
      type: keyword

ソースからの構造化データには、論理的な階層を表すサブグループを使用します。

- name: acme.firewall
  type: group
  fields:
    - name: rule
      type: group
      fields:
        - name: id
          type: keyword
        - name: name
          type: keyword
        - name: action
          type: keyword

agent.yml

Elastic Agent または Beats フレームワークによって設定されるフィールドのうち、ECS でカバーされないフィールドです。入力タイプがこれらのフィールドを出力する場合にのみ含めてください。一般的なフィールド：cloud.image.id、cloud.instance.id、host.containerized、host.os.build、host.os.codename、input.type、log.offset。

YAML の完全なサンプルについては、references/root-and-core-fields.md を参照してください。

beats.yml

ECS でカバーされない Filebeat／Beats 固有のフィールドです。最小限の形式には input.type と log.offset が含まれます。一部の入力では、log.flags や log.file.* のサブフィールドも出力されます。

YAML の完全なサンプルについては、references/root-and-core-fields.md を参照してください。

ECS フィールドの選択

意味が一致する場合は、ECS フィールドを優先してください。データに対応する ECS フィールドがない場合は、fields.yml のパッケージ名前空間の下に追加します。

分類のクイックリファレンス

フィールド	型	備考
event.kind	keyword	最上位の分類です。
event.category	keyword[]	大まかなドメインの分類です。常に配列です。
event.type	keyword[]	category 内のサブ分類です。常に配列です。
event.outcome	keyword	success、failure、unknown。意味がある場合にのみ設定します。

• event.kind：alert、asset、enrichment、event、metric、pipeline_error、signal、state
• event.category：api、authentication、configuration、database、driver、email、file、host、iam、intrusion_detection、library、malware、network、package、process、registry、session、threat、vulnerability、web
• event.type：access、admin、allowed、change、connection、creation、deletion、denied、device、end、error、group、indicator、info、installation、protocol、start、user

判断ワークフロー：

1. event.kind：通常のログには event、測定値には metric、ある対象についての定期的な分類観測（例：CDR のポスチャ／コンプライアンスに関する検出結果）には state、エンティティ／インベントリのスナップショットレコード（収集サイクルごとにコレクションあたり 1 ドキュメント。entity-mappings スキルを参照）には asset、on_failure には pipeline_error を指定します。
2. event.category：大まかなドメインを示す値を 1 つ以上（配列で）指定します。
3. event.type：操作の種類を示す値を 1 つ以上（配列で）指定します。
4. event.outcome：明確な成功／失敗／不明が当てはまる場合にのみ指定します。情報イベントやメトリックイベントでは省略します。
5. 許可された値に当てはまるものがない場合は、値を作成せず、フィールドを空のままにします。

ソース固有の動詞（blocked、dropped、authenticated）には event.action を使用します。

具体例については、references/categorization-cheatsheet.md を参照してください。

タイムスタンプフィールド

ECS には、それぞれ異なる意味を持つ複数のタイムスタンプフィールドが定義されています。適切に使用してください。

フィールド	使用する場合	設定元
@timestamp	主要なイベントのタイムスタンプです。ソースイベントデータから解析します。必須です。	インテグレーションパイプライン
event.created	@timestamp と異なる場合に、ソースシステムでイベントが最初に作成または記録された時刻です。	インテグレーションパイプライン
event.start	アクティビティまたは期間が開始した時刻です（例：セッションの開始、接続の開始）。	インテグレーションパイプライン
event.end	アクティビティまたは期間が終了した時刻です（例：セッションの終了、接続の切断）。	インテグレーションパイプライン
event.ingested	Elasticsearch にイベントが取り込まれた時刻です。	Elasticsearch（インテグレーションの外部）

event.ingested は、インテグレーションパイプラインで絶対に設定してはいけません。 Elasticsearch の最終パイプラインによって自動的に管理されます。event.ingested 用の set プロセッサーを追加しないでください。

ソースデータに複数のタイムスタンプが含まれている場合：

1. 主要なイベントのタイムスタンプを @timestamp にマッピングします。
2. 別のタイムスタンプがイベントの最初の記録／作成時刻を表している場合は、event.created にマッピングします。
3. タイムスタンプがアクティビティの開始または終了を表している場合は、event.start および event.end にマッピングします。
4. 上記のいずれの意味にも当てはまらないタイムスタンプは、fields.yml で type: date を指定し、ベンダー名前空間配下のカスタムフィールドにマッピングします。

再利用可能なフィールドセットのネスト規則

一部の ECS フィールドセットは親エンティティの下にネストする必要があります。ドキュメントのルートには配置できません。

geo — 次のフィールドの下にネストする必要があります：client.geo、destination.geo、host.geo、observer.geo、server.geo、source.geo、threat.indicator.geo

ルートレベルの geo.* フィールドは認識されず、マッピングされません。geoip プロセッサでは必ず target_field を設定してください：

- geoip:
    field: source.ip
    target_field: source.geo
    ignore_missing: true

as（自律システム）— 次のフィールドの下にネストします：client.as、destination.as、server.as、source.as

ジオロケーションに geoip を使用する場合は、必ず GeoLite2-ASN.mmdb を使った ASN ルックアップも実行し、出力された生のフィールド名を ECS 名に変更してください。geoip ASN プロセッサが出力する asn と organization_name は、それぞれ as.number と as.organization.name に変更する必要があります：

- geoip:
    database_file: GeoLite2-ASN.mmdb
    field: source.ip
    target_field: source.as
    properties:
      - asn
      - organization_name
    ignore_missing: true
- rename:
    field: source.as.asn
    target_field: source.as.number
    ignore_missing: true
- rename:
    field: source.as.organization_name
    target_field: source.as.organization.name
    ignore_missing: true

送信元と宛先の両方を含む、geo と ASN の完全なパターンについては、ingest-pipelines スキルの → references/processor-cookbook.md を参照してください。

os — 次のフィールドの下にネストします：host.os、observer.os、user_agent.os

entity（ベータ版。末端フィールドには ECS v9.4.0+ が必要です）— 次のフィールドの下にネストします：user.entity、host.entity、service.entity、cloud.entity、orchestrator.entity、ルートの entity、entity.target。有効な親フィールドではないため、device.entity.* を決して作らないでください。エンティティデータストリーム（つまり、event.kind: asset を持つデータストリーム）については、完全なフィールドカタログ、パイプラインパターン、ECS 対応状況一覧を確認するために entity-mappings スキルを参照してください。

ネストされた（オブジェクト配列）ECS フィールド

一部の ECS フィールドは type: nested を使用します。これは、関連するサブフィールドをそれぞれグループ化したオブジェクトの配列を格納することを意味します。パイプラインではこの構造を生成する必要があります。これらを並行するスカラー配列に平坦化しないでください。

nested 型を使用する ECS フィールド：

フィールド	含まれるもの
email.attachments	file.name、file.size、file.extension、file.mime_type、file.hash.*
threat.enrichments	indicator.*、matched.*
threat.indicator.file.elf.sections	name、physical_size、virtual_size など
threat.indicator.file.pe.sections	name、physical_size、virtual_size など
process.elf.sections	name、physical_size、virtual_size など
process.pe.sections	name、physical_size、virtual_size など

アンチパターン — 並行配列（誤り）：

{
  "email": {
    "attachments": {
      "file": {
        "name": ["a.pdf", "b.pdf"],
        "size": [1024, 2048]
      }
    }
  }
}

これでは、各添付ファイルの名前とサイズの対応関係が失われます。クエリで個々のオブジェクトを特定できません。

正しい方法 — オブジェクトの配列：

{
  "email": {
    "attachments": [
      { "file": { "name": "a.pdf", "size": 1024 } },
      { "file": { "name": "b.pdf", "size": 2048 } }
    ]
  }
}

ecs.yml の宣言： 親の nested フィールドのみを external: ecs として宣言してください。子フィールド（email.attachments.file.name など）は ECS スキーマから型を継承するため、個別に再宣言しないでください。

- name: email.attachments
  external: ecs

パイプラインの構築： ソースデータで添付ファイルのメタデータが別々の並行配列（例：カンマ区切りのファイル名リストと、別個のサイズリスト）として提供される場合は、script プロセッサを使ってこれらをオブジェクトの配列にまとめてください。配列の構築パターンについては ingest-pipelines → references/painless-patterns.md を、配列要素の反復処理については references/processor-cookbook.md → Foreach の動作を参照してください。

- script:
    tag: build_email_attachments
    description: Build email.attachments as array of nested objects from parallel source arrays.
    lang: painless
    if: ctx.json?.file_names instanceof List && ctx.json?.file_sizes instanceof List
    source: |-
      def names = ctx.json.file_names;
      def sizes = ctx.json.file_sizes;
      int len = Math.min(names.size(), sizes.size());
      def attachments = new ArrayList(len);
      for (int i = 0; i < len; i++) {
        def attachment = new HashMap();
        def file = new HashMap();
        file.put('name', names.get(i));
        file.put('size', sizes.get(i));
        attachment.put('file', file);
        attachments.add(attachment);
      }
      ctx.email = ctx.email ?: [:];
      ctx.email.attachments = attachments;

ソースデータですでに各添付ファイルが個別のオブジェクトとして提供されている場合（例：添付ファイルオブジェクトの JSON 配列）は、まとめる必要はありません。rename、または copy_from を使った set で、配列を直接 email.attachments に配置してください。

カスタムフィールドタイプ

fields.yml の非 ECS フィールドには、次を使用します。

• 識別子や完全一致する文字列には keyword
• 固定値（データセット／モジュールの定数）には constant_keyword
• メトリックや数値には long、double、scaled_float
• タイムスタンプには date／date_nanos（サブミリ秒精度が本当に必要な場合に限り date_nanos）
• IP アドレスには ip
• true／false には boolean（パイプラインで文字列のブール値を使用しないでください）
• 緯度／経度の座標には geo_point
• 論理構造には、ネストした fields を持つ group（中間の object ノードを個別に宣言する必要はありません）
• キーが不明な任意のキー／値データには flattened
• オブジェクトごとのクエリ分離が必要なオブジェクト配列には nested（group より負荷が高くなります）
• 全文コンテンツには text／match_only_text。集計も必要な場合は、multi_fields を使って keyword サブフィールドを追加します

数値フィールドで役立つプロパティ：metric_type（gauge または counter）、unit（例：byte、percent、ms）、カーディナリティの低い TSDB フィールド用の dimension。

タイプの完全なリファレンスについては、references/mapping-type-matrix.md を参照してください。

フィールドの命名規則

ルール	使用する	使用しない
スネークケースを使用する	user_name、request_count	userName、RequestCount
小文字を使用する	source_ip	Source_IP
名前にアスタリスクを含めない	network.bytes	network.*（リテラルのアスタリスク）
階層にはグループを使用する	ネストしたグループとしての vendor.module.field	フラットなドット区切り名としての vendor.module.field

フィールド名にリテラルの * 文字を含めてはいけません。フィールド名のアスタリスクは、ほとんどの場合、ドキュメントやワイルドカードパターンからのコピー＆ペーストによる誤りです。代わりに、既知のサブフィールドには group を、動的なキーには flattened を使用してください。

ドット区切りフィールド名とネストしたグループ

フィールドファイルでは、どちらの形式も有効です。

# Dotted (flat) — common for ECS fields in ecs.yml
- name: source.ip
  external: ecs

# Nested group — common for custom fields
- name: acme.firewall
  type: group
  fields:
    - name: rule_id
      type: keyword

パイプラインの期待される出力（*-expected.json）では、ソースデータでのフィールドの表現方法にかかわらず、常にネストしたオブジェクト形式が使用されます。ソースが "host.name": "myhost" の場合、出力は {"host": {"name": "myhost"}} になります。

ソースデータに、Elasticsearch が通常展開するリテラルのドット区切りキーが含まれている場合は、dot_expander を使用します。

- dot_expander:
    field: "*"
    override: true

geo_point フィールドの処理

パイプラインテストの期待される出力では、geo_point フィールドは lat と lon キーを持つオブジェクトとして表示されます。

"source": {
  "geo": {
    "location": { "lat": 51.5142, "lon": -0.0931 },
    "city_name": "London",
    "country_iso_code": "GB"
  }
}

これらのサブフィールドを fields.yml に記述する必要はありません。geo_point タイプのマッピングに含まれています。非標準の親プレフィックスで、ecs@mappings（インストール時に stacks >= 8.13 で適用されます。conditions.kibana.version の下限が >= 8.13.0 の場合にのみ保証されます）がカバーしない場合は、*.geo.location フィールド（タイプ geo_point）だけを ecs.yml に記述する必要があります。

一般的なパイプラインの分類パターン

Web アクセス

- set:
    field: event.kind
    value: event
- append:
    field: event.category
    value: web
- append:
    field: event.type
    value: access

HTTP ステータスからの結果

- set:
    field: event.outcome
    value: success
    if: "ctx?.http?.response?.status_code != null && ctx.http.response.status_code < 400"
- set:
    field: event.outcome
    value: failure
    if: "ctx?.http?.response?.status_code != null && ctx.http.response.status_code >= 400"

パイプラインエラーのフォールバック

on_failure:
  - set:
      field: event.kind
      value: pipeline_error

トラブルシューティング：「field X is undefined」と ECS フィールドについて報告される場合

テストで標準 ECS フィールドに対して field "destination.ip" is undefined と報告された場合：

1. _dev/build/build.yml がパッケージのルートに存在することを確認します
2. dependencies.ecs.reference が設定されていることを確認します（[email protected] を使用します）
3. フィールドが ecs.yml に external: ecs とともに記載されていることを確認します

根本原因を修正してください。次の方法で回避しないでください。

• external: ecs を指定せずに、完全な型定義を持つ ECS フィールドを fields.yml に追加する
• external: ecs を省略し、ECS フィールドの型や説明を手動で定義する

例外： 未定義と報告されたカスタム（非 ECS）フィールドは、fields.yml に定義する必要があります。

よくある失敗パターン

• _dev/build/build.yml がない — すべての ECS フィールドが未定義として報告されます。dependencies.ecs.reference を指定して作成してください
• build.yml の ECS バージョンが古い — 新しい ECS バージョンのフィールドが未定義になります。参照を [email protected] に更新してください
• パイプラインで ECS フィールドを設定しているが、ecs.yml にない — テストのスキーマ検証でフィールドが未定義になります。ecs.yml に追加してください
• external: ecs を指定せずに ECS フィールドを定義している — 説明と型が ECS と異なります。必要に応じてオーバーライドを使用し、ECS フィールドには必ず external: ecs を指定してください
• 数値以外のフィールドに metric_type を指定している — リントエラーになります
• ドキュメントのルートに geo.* がある — マッピングされません。必ず親エンティティの下にネストしてください
• event.category または event.type をスカラーとして設定している — set ではなく、append プロセッサーを使用する必要があります
• nested ECS フィールドを並列配列としてマッピングしている — email.attachments、threat.enrichments などの nested フィールドは、スカラー配列を並列に持つオブジェクトではなく、オブジェクトの配列である必要があります。上記の Nested（オブジェクトの配列）ECS フィールド のセクションを参照してください
• [email protected] で entity.attributes.* / entity.relationships.* に external: ecs を指定している — これらのリーフフィールドは ECS v9.3.0 にはありません（attributes は単独の object であり、entity_reference フィールドセットもありません）。これらのフィールドが初めて登場するのは v9.4.0 です。[email protected] でこれらに external: ecs を指定すると、field is undefined エラーが発生します。エンティティデータストリームを含むパッケージでは、_dev/build/build.yml で [email protected] を固定し、パイプラインの ecs.version: 9.5.0 と一致させる必要があります。entity-mappings スキルを参照してください

検証ループ

elastic-package lint
elastic-package check
elastic-package test pipeline --data-streams <stream>

参考資料

• references/mapping-type-matrix.md
• references/categorization-cheatsheet.md
• references/root-and-core-fields.md
• references/fieldset-links.md
• references/cdr-field-requirements.md — クラウドセキュリティ / CDR インテグレーションのみ（cloudsecurity_cdr カテゴリー）
• entity-mappings/references/entity-field-catalog.md — ECS entity.* フィールド。エンティティ / インベントリデータストリームのみ
• ECS フィールドリファレンス