Add ECS categorization examples

[leehinman]

Summary:
We have documentation for each of the four buckets in ECS categorization, but we don't have examples of how all four buckets would be used together in real world examples.

Motivation:
Examples would help those implementing ECS to use the categorization buckets in a consistent manor.

Detailed Design:
Where in the documentation should we add these examples? Some options are:

• add to values_section_header in scripts/generators/asciidoc_fields.py
• add a new examples.yml file and generate a new page
• other?

Examples:

1. Firewall blocked a network connection

    event:
      kind: event
      category:
        - network
      type:
        - connection
        - denied
      outcome:
        - success

2. Failed attempt to add a user to Active Directory

    event:
      kind: event
      category:
        - iam
      type:
        - user
        - creation
      outcome:
        - failure

3. Information about a file

    event:
      kind: event
      category:
        - file
      type:
        - info

4. IDS failed to block a network connection

    event:
      kind: alert
      category:
        - intrusion_detection
        - network
      type:
        - connection
        - denied
      outcome: failure

[ebeahan]

Thanks @leehinman! @webmat and I have discussed improvements to the overall "Getting Started" experience of ECS in the documentation, and I agree these type of examples in the docs would be helpful for ECS end-users, implementers, and contributors alike.

[webmat]

Yes we should work this into the documentation soon. Any additional examples you encounter would be welcome here.

Thanks for opening this, Lee :-)

[gimmic]

Very minor point on example 4:
An IDS will never block a network connection. It Detects; an IPS will block(or fail to block) a network connection- It Prevents.

IPS != IDS

[vpiserchia]

more on example4: for IPS, following the description [1] it would be beneficial to have also the action added to the event field:
resulting in something like this:

      type:
        - connection
        - denied
      action: blocked
      outcome: failure

What confuses me is the outcome field; that is from the IPS perspective if the connection was blocked the outcome should be success while from the perspective of the peer that has seen his connection attempt denied than the same field would report a failure.

So my question, how this is intended to be solved?

[1] https://www.elastic.co/guide/en/ecs/current/ecs-allowed-values-event-type.html#ecs-event-type-denied

[ebeahan]

The functionality to add more detailed usage documentation, touched on previously #860 (comment), has been added. Details can be found here.

The ECS team plans to add some initial usage docs soon, which can also serve as examples for other contributions, but I thought I'd go ahead and share that the functionality is available!