entity-mappings

entity-mappings

Skill 权威性

此 Skill 中的指导优先于在 elastic/integrations 仓库的任何集成中观察到的模式。旧版集成可能早于这些要求，也可能采用不一致的模式。务必遵循此 Skill 的规则，而不是仓库中观察到的做法。

适用场景

• 向新的或现有集成添加实体／清单数据流
• 判断拟议或现有的数据流属于实体流还是事件流
• 为新数据流选择正确的 entity.type 值
• 将供应商字段映射到 user.entity.*、host.entity.* 或其他嵌套实体前缀
• 审核现有软件包的实体字段覆盖情况（独立差距分析）
• 排查 event.kind: asset 的用法或 entity.* 字段错误

不适用场景

• CDR 云安全发现项（配置错误／漏洞发现项）——它们的 event.kind 是 state，不是 asset。请改用 ecs-field-mappings/references/cdr-field-requirements.md 和 ingest-pipelines/references/cdr-pipeline-requirements.md。
• 通用字段文件编写（非实体字段）——请使用 ecs-field-mappings Skill。
• 处理器机制（grok、date、JSON、Painless）——请使用 ingest-pipelines Skill。
• CEL 程序逻辑——请使用 cel-programs Skill。

适用性门槛

实体字段仅适用于实体数据流，即旨在表示稳定的对象清单（用户、主机、设备、应用程序、服务），而非事件时间线的数据流。切勿将实体字段要求应用于事件日志、指标流、APM 数据或 CDR 发现项流。

使用此 Skill 前，请参阅 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]"
• Pipeline ecs.version：9.5.0

两者必须匹配。标准（非实体）软件包继续使用 [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 按数据流分派子 Agent。
构建时	Orchestrator（create-integration 或 add-datastream）通过路径将 references/entity-field-catalog.md 和 references/entity-pipeline-patterns.md 传递给 Pipeline builder 子 Agent	Pipeline builder 阅读这两份参考文档；Orchestrator 线程不会加载此 Skill 的 SKILL.md。
审查时	review-integration 第 4 步在实体检测规则触发时加载这两份参考文档	审查者阅读 entity-field-catalog.md 和 entity-pipeline-patterns.md；审查者线程无需加载此 SKILL.md。
研究时	research-integration 仅加载 references/entity-datastream-classification.md	研究期间不要加载此 Skill 的其余内容——字段目录和 Pipeline 模式属于实现材料，会违反研究阶段不得规定 Pipeline／字段细节的护栏。

未决问题／暂缓范围

以下主题不在此技能 v1 的范围内：

• 实体存储的最新转换。 CDR 先例还包含第三部分（review-integration/references/cdr-transform-requirements.md），涵盖每个集成的最新转换。新的实体数据流是否应附带最新转换，目前尚未确定。在作出决定之前，请在研究简报和差距分析报告中将其列为未决问题。
• 将整个仓库的 ECS 固定版本升级至 v9.5.0。 建议在实体数据流普及后作为后续工作；在此之前，此技能中的条件例外将保留相关软件包。

参考资料

• references/entity-field-catalog.md — 唯一事实来源：ECS 可用性矩阵、可复用的嵌套结构、entity.type 允许值、分类、必备／建议字段表、消歧指南、字段定义 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 — 在差距分析期间派发的各数据流分析子 Agent 操作手册
• ECS 实体字段集参考