entity-mappings

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

entity-mappings

Skill authority

技能权威性

The guidance in this skill takes precedence over patterns observed in any integration in the

elastic/integrations

repository. Legacy integrations may predate these requirements or use inconsistent patterns. Always follow this skill's rules over what you observe in the repo.

本技能中的指导优先级高于

elastic/integrations

仓库中任何集成所采用的模式。旧版集成可能早于这些要求或使用不一致的模式。请始终遵循本技能的规则，而非仓库中已有的实现方式。

When to use

适用场景

Adding entity/inventory data streams to a new or existing integration
Deciding whether a proposed or existing data stream is an entity stream or an event stream
Selecting the correct
```
entity.type
```
value for a new stream
Mapping vendor fields to
```
user.entity.*
```
,
```
host.entity.*
```
, or other nested entity prefixes
Auditing an existing package's entity field coverage (standalone gap analysis)
Troubleshooting
```
event.kind: asset
```
usage or
```
entity.*
```
field errors

为新集成或现有集成添加实体/清单数据流
判断拟开发或已有的数据流属于实体流还是事件流
为新流选择正确的
```
entity.type
```
值
将厂商字段映射到
```
user.entity.*
```
、
```
host.entity.*
```
或其他嵌套实体前缀
审计现有包的实体字段覆盖情况（独立缺口分析）
排查
```
event.kind: asset
```
使用问题或
```
entity.*
```
字段错误

When not to use

不适用场景

CDR cloud security findings (misconfiguration / vulnerability findings) — these are

event.kind: state

, not

asset

. Use

ecs-field-mappings/references/cdr-field-requirements.md

and

ingest-pipelines/references/cdr-pipeline-requirements.md

instead.

Generic field file authoring (non-entity fields) — use the
```
ecs-field-mappings
```
skill.
Processor mechanics (grok, date, JSON, Painless) — use the
```
ingest-pipelines
```
skill.
CEL program logic — use the
```
cel-programs
```
skill.

CDR云安全发现结果（配置错误/漏洞发现）——这些属于

event.kind: state

，而非

asset

。请改用

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
```
技能。

Applicability gate

适用性门槛

Entity fields apply only to entity data streams — those whose purpose is to represent a stable inventory of subjects (users, hosts, devices, applications, services) rather than a timeline of events. Never apply entity field requirements to event logs, metric streams, APM data, or CDR findings streams.

See

references/entity-datastream-classification.md

to classify a data stream before using this skill. If you are not sure, check the classification reference first.

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

在使用本技能之前，请参阅

references/entity-datastream-classification.md

对数据流进行分类。若不确定，请先查看分类参考文档。

ECS availability — read this first

ECS可用性说明——请先阅读本节

The

entity.attributes.*

entity.lifecycle.last_activity

, and all

entity.relationships.*

leaf fields do not exist at ECS v9.3.0 (the repo default pin). They first appear at ECS v9.4.0.

At
```
git@v9.3.0
```
:
```
entity.attributes
```
is a bare
```
object
```
with no subfields;
```
schemas/entity_reference.yml
```
does not exist. Using
```
external: ecs
```
on these leaves at that pin causes
```
field is undefined
```
build failures.
At
```
git@v9.4.0+
```
/
```
git@v9.5.0
```
(recommended): all leaf fields exist and
```
external: ecs
```
resolves correctly.

Conditional pin rule: packages with entity data streams must set:

_dev/build/build.yml

dependencies.ecs.reference: "git@v9.5.0"

Pipeline
```
ecs.version
```
:
```
9.5.0
```

The two must match. Standard (non-entity) packages keep

git@v9.3.0

To verify at any tag:

bash

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

entity.attributes.*

、

entity.lifecycle.last_activity

以及所有

entity.relationships.*

叶子字段在ECS v9.3.0（仓库默认固定版本）中不存在。这些字段首次出现在ECS v9.4.0中。

在
```
git@v9.3.0
```
版本下：
```
entity.attributes
```
是一个无子字段的裸
```
object
```
；
```
schemas/entity_reference.yml
```
不存在。在此版本下对这些叶子字段使用
```
external: ecs
```
会导致“字段未定义”的构建失败。
在
```
git@v9.4.0+
```
/
```
git@v9.5.0
```
版本下（推荐使用）：所有叶子字段均存在，且
```
external: ecs
```
可正确解析。

**条件固定版本规则：**包含实体数据流的包必须设置：

_dev/build/build.yml

：

dependencies.ecs.reference: "git@v9.5.0"

管道
```
ecs.version
```
：
```
9.5.0
```

两者必须保持一致。标准（非实体）包保留

git@v9.3.0

版本。

如需在任意标签版本下验证：

bash

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

Modes

模式

Mode	How it's triggered	What to load
Standalone gap analysis	User invokes `/entity-mappings @packages/<name>`	Read `references/gap-analysis-workflow.md` and `references/entity-field-catalog.md` . Dispatch per-stream subagents via `references/analysis-subagent-guidance.md` .
Build-time	Orchestrator ( `create-integration` or `add-datastream` ) passes `references/entity-field-catalog.md` and `references/entity-pipeline-patterns.md` by path to the pipeline builder subagent	Pipeline builder reads both references; this skill's SKILL.md is not loaded into the orchestrator thread.
Review-time	`review-integration` Step 4 loads the two references when the entity detection rule fires	Reviewer reads `entity-field-catalog.md` + `entity-pipeline-patterns.md` ; this SKILL.md is not required in the reviewer thread.
Research-time	`research-integration` loads only `references/entity-datastream-classification.md`	Do not load the rest of this skill during research — the catalog and pipeline patterns are implementation material and violate the research guardrail against prescribing pipeline/field details.

模式	触发方式	需加载内容
独立缺口分析	用户调用 `/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在实体检测规则触发时加载这两份参考文档	评审人员阅读 `entity-field-catalog.md` + `entity-pipeline-patterns.md` ；评审线程中无需本SKILL.md。
调研阶段	`research-integration` 仅加载 `references/entity-datastream-classification.md`	调研期间请勿加载本技能的其余内容——字段目录和管道模式属于实现材料，违反了调研阶段禁止指定管道/字段细节的约束。

Open questions / deferred scope

待解决问题/延迟范围

The following topics are out of scope for this skill's v1:

Entity-store latest transforms. The CDR precedent has a third leg (
```
review-integration/references/cdr-transform-requirements.md
```
) covering latest transforms per integration. Whether new entity data streams should ship an accompanying latest transform is not yet resolved. Note it as an open question in research briefs and gap analysis reports until that decision is made.
Repo-wide ECS pin bump to v9.5.0. Recommended as a follow-up once entity streams are common; the conditional exception in this skill carries packages until then.

以下主题不属于本技能v1的范围：

实体存储最新转换规则。CDR先例有第三部分（
```
review-integration/references/cdr-transform-requirements.md
```
）涵盖每个集成的最新转换规则。新的实体数据流是否应附带对应的最新转换规则尚未确定。在该决策作出前，请在调研简报和缺口分析报告中将其标注为待解决问题。
仓库全局ECS版本升级至v9.5.0。建议在实体流普及后作为后续工作推进；本技能中的条件例外规则将暂时适用于相关包。

References

参考文档

```
references/entity-field-catalog.md
```
— single source of truth: ECS availability matrix, reusable nesting,
```
entity.type
```
allowed values, categorization, Must Have / Should Have field tables, disambiguation guide, field definition YAML examples, review checklist
```
references/entity-pipeline-patterns.md
```
— pipeline-side patterns: categorization processors, building
```
entity.id
```
, boolean coercion, array attributes, relationship objects, anti-patterns, pipeline review checklist
```
references/entity-datastream-classification.md
```
— research-time and review-time rules for classifying a data stream as entity vs event; worked examples
```
references/gap-analysis-workflow.md
```
— 4-phase standalone analysis: classify streams → read package → fetch docs → map fields → investigate gaps → write report
```
references/gap-analysis-report-template.md
```
— structured report template for gap analysis output
```
references/analysis-subagent-guidance.md
```
— operating manual for per-stream analysis subagents dispatched during gap analysis
ECS entity fieldset reference

```
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
```
—— 四阶段独立分析：分类流→读取包→获取文档→映射字段→调查缺口→撰写报告
```
references/gap-analysis-report-template.md
```
—— 缺口分析输出的结构化报告模板
```
references/analysis-subagent-guidance.md
```
—— 缺口分析期间调度的每个流分析子代理的操作手册
ECS entity字段集参考