Terminal
Terminal/Skill
Maps vendor fields to ECS entity fields for entity inventory data streams, and audits entity field coverage in existing packages.
By Elastic
Works with
npx skills add elastic/integration-skills --skill entity-mappingsThe 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.
entity.type value for a new streamuser.entity.*, host.entity.*, or other nested entity prefixesevent.kind: asset usage or entity.* field errorsevent.kind: state, not asset. Use ecs-field-mappings/references/cdr-field-requirements.md
and ingest-pipelines/references/cdr-pipeline-requirements.md instead.ecs-field-mappings skill.ingest-pipelines skill.cel-programs skill.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.
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.
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.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"ecs.version: 9.5.0The two must match. Standard (non-entity) packages keep git@v9.3.0.
To verify at any tag:
curl -s https://raw.githubusercontent.com/elastic/ecs/<tag>/generated/csv/fields.csv \
| awk -F, '$3=="entity"' | cut -d, -f4,5 | sort -u
| 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. |
The following topics are out of scope for this skill's v1:
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.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 checklistreferences/entity-pipeline-patterns.md — pipeline-side patterns: categorization processors, building entity.id, boolean coercion, array attributes, relationship objects, anti-patterns, pipeline review checklistreferences/entity-datastream-classification.md — research-time and review-time rules for classifying a data stream as entity vs event; worked examplesreferences/gap-analysis-workflow.md — 4-phase standalone analysis: classify streams → read package → fetch docs → map fields → investigate gaps → write reportreferences/gap-analysis-report-template.md — structured report template for gap analysis outputreferences/analysis-subagent-guidance.md — operating manual for per-stream analysis subagents dispatched during gap analysis