Skip to content

Definition of the taxomony

The taxonomy of structured events is based on the ECS specifications. This taxonomy defines a set of fields available for values in parsers.

Best Practices

  • When a raw event encompasses a datetime, parse this information with a stage date and set the result in the field @timestamp
  • Define event.category, event.type and event.kind according to the event categorization fields
  • Define event.category and event.type as arrays
  • If possible, define event.dataset
  • If possible, define observer information in observer.*
  • For events collected from cloud services, provide cloud information in cloud.* (The cloud account id must land in cloud.account.id)
  • The name of an action must be hosted in event.action
  • The reason of the event must be hosted in event.reason
  • Error code and error message must land in error.code and error.message
  • email.to.address, email.from.address and email.cc.address are arrays
  • As documented in the ECS specification, host.hostname must contain the hostname as return by the command hostname on the host. host.name is more permissive

Note

The related field aggregate various pieces of information, like IP addresses, into an array to facilitate searching, regardless of their location within an ECS event. With our custom module called ingest, additional fields like source.user.name or user.target.name can also be included in this field.

Custom Taxomony

When a valuable information is present in the raw event, and no ECS fields is suitable to host the information, a custom field may be defined.

The custom taxonomy is defined in the directory _meta/fields.yml in the format. The document is written in JSON dialect.

Custom field

Warning

Please ensure that no field from the ECS taxonomy is suitable before creating a new field.

A custom field consists of three elements:

  • name: The name of the field. It corresponds to the path (dot-notation) of the field in the structured event.

Note

We recommend prefixing the field with the vendor and the name of the product (e.g for AWS cloud trail, custom taxonomy is prefixing with aws.cloudtrail).

  • type: The type of the field.

    Available types are:

    • keyword for textual values
    • boolean for boolean values
    • long for integer and long values
    • float for float values
    • array for list
    • dict for dictionaries

  • description: a short description to understand the value of the field

Example

See AWS CloudTrail.