diff --git a/rfcs/text/0000-event-entities.md b/rfcs/text/0000-event-entities.md new file mode 100644 index 0000000000..a751199ec4 --- /dev/null +++ b/rfcs/text/0000-event-entities.md @@ -0,0 +1,134 @@ +# 0000: Event Entities + +- Stage: **0 (strawperson)** +- Date: **TBD** + + +This RFC proposes enhancements to the Elastic Common Schema (ECS) to improve how we capture actor and target information in events, particularly for security use cases. The proposal aims to address current limitations in representing and querying this information, especially for cloud-based events (but this is broadly applicable). + + + + + +## Fields + +Field | Type | Description /Usage +-- | -- | -- +source.entity.id | keyword | All the entity identifiers that triggered the event. If the document contains multiple source entities, identifiers belonging to different entities will be present. Example identifiers include cloud resource IDs, ARNs, email addresses, or hostnames. +target.entity.id | keyword | All the entity identifiers that were affected by the event. If the document contains multiple target entities, identifiers belonging to different entities will be present. Example identifiers include cloud resource IDs, ARNs, email addresses, or hostnames. + + +### Proposed Changes +- Extend source.entity.id to capture actor information within the existing source.* fields. +- Introduce a new top-level target.* field set to explicitly represent the target of an action. +- Allow nesting of entity fields under target.*, such as target.user, target.entity, and target.group. +- Provide guidelines for consistently mapping common cloud event information (like role names, instance IDs, etc.) to these standardized fields. + + + + +## Usage + +Currently, ECS lacks a standardized way to explicitly capture/distinguish between the actor (entity performing an action) and the target (entity being acted upon) in events. This limitation makes it challenging to represent certain security events accurately and consistently across different data sources and cloud providers. Specific issues include: + +1. Difficulty in querying nested JSON objects containing critical information. +2. Inconsistent data structures across different services and API calls. +3. Field length limitations preventing effective searching and filtering. +4. Challenges in correlating related events involving the same actors or targets. + +These issues are exemplified in the AWS CloudTrail integration (see [Issue #9586](https://github.com/elastic/integrations/issues/9586) and [Issue #10818](https://github.com/elastic/integrations/issues/10818)), but are not limited to AWS and likely affect other cloud providers and services. + +What we expect to gain with this proposal: + +- Improved clarity and consistency in representing security events across different platforms and data sources. +- Enhanced ability to query and analyze events without relying on complex string parsing or wildcard searches. +- Better correlation of related events, particularly in cloud environments with complex identity and access management scenarios. +- Avoidance of field length limitations by extracting key information into separate fields. +- Improved capability for creating effective detection rules and performing security analysis. +- Maintains compatibility with existing ECS structure while expanding capabilities. + + + +## Source data + + + + + + + +## Scope of impact + + + +## Concerns + +- Asymmetry between using source.* for actor and target.* for target + + + + + + + +## People + +The following are the people that consulted on the contents of this RFC. + +* @romulets | author +* @tinnytintin10 | sponsor, subject matter expert +* @terrancedejesus | subject matter expert + + + + +## References + + + +### RFC Pull Requests + + + +* Stage 0: https://github.com/elastic/ecs/pull/2384 + + \ No newline at end of file