Event categorisation fields

.gitignore

@@ -1,3 +1,4 @@
 .DS_Store
 *.pyc
 env
+*.sw?

CHANGELOG.md

@@ -9,6 +9,7 @@ All notable changes to this project will be documented in this file based on the
   to `network.packets`. #179
 * Remove `network.inbound.bytes`, `network.inbound.packets`,
   `network.outbound.bytes` and `network.outbound.packets`. #179
+* Changed the `event.type` definition to be only reserved. #242
 
 ### Bugfixes
 
@@ -31,16 +32,16 @@ All notable changes to this project will be documented in this file based on the
 * Add `user.full_name` field. #201
 * Add `network.community_id` field. #208
 * Add fields `geo.country_name` and `geo.region_iso_code`. #214
+* Add `event.kind` and `event.outcome`. #242
 
 ### Improvements
 * Improved the definition of the file fields #196
 * Improved the definition of the agent fields #192
 * Improve definition of events, logs, and metrics in event section #194
 * Improved the definition of network fields in intro section #197
 * Improved the definition of host fields #195
-
+* Improved the definitions for `event.category` and `event.action`. #242
 * Clarify the semantics of `network.direction`. #212
-
 * Add `source.bytes`, `source.packets`, `destination.bytes` and `destination.packets`. #179
 
 ### Deprecated

README.md

@@ -197,9 +197,11 @@ The event fields are used for context information about the log or metric event
 | Field  | Description  | Level  | Type  | Example  |
 |---|---|---|---|---|
 | <a name="event.id"></a>event.id | Unique ID to describe the event. | core | keyword | `8a4f500d` |
-| <a name="event.category"></a>event.category | Event category.<br/>This can be a user defined category. | core | keyword | `metrics` |
-| <a name="event.type"></a>event.type | A type given to this kind of event which can be used for grouping.<br/>This is normally defined by the user. | core | keyword | `nginx-stats-metrics` |
-| <a name="event.action"></a>event.action | The action captured by the event. The type of action will vary from system to system but is likely to include actions by security services, such as blocking or quarantining; as well as more generic actions such as login events, file i/o or proxy forwarding events.<br/>The value is normally defined by the user. | core | keyword | `reject` |
+| <a name="event.kind"></a>event.kind | The kind of the event.<br/>This gives information about what type of information the event contains, without being specific to the contents of the event.  Examples are `event`, `state`, `alarm`. Warning: In future versions of ECS, we plan to provide a list of acceptable values for this field, please use with caution. | core | keyword | `state` |
+| <a name="event.category"></a>event.category | Event category.<br/>This contains high-level information about the contents of the event. It is more generic than `event.action`, in the sense that typically a category contains multiple actions. Warning: In future versions of ECS, we plan to provide a list of acceptable values for this field, please use with caution. | core | keyword | `user-management` |
+| <a name="event.action"></a>event.action | The action captured by the event.<br/>This describes the information in the event. It is more specific than `event.category`. Examples are `group-add`, `process-started`, `file-created`. The value is normally defined by the implementer. | core | keyword | `user-password-change` |
+| <a name="event.outcome"></a>event.outcome | The outcome of the event.<br/>If the event describes an action, this fields contains the outcome of that action. Examples outcomes are `success` and `failure`. Warning: In future versions of ECS, we plan to provide a list of acceptable values for this field, please use with caution. | core | keyword | `success` |
+| <a name="event.type"></a>event.type | Reserved for future usage.<br/>Please avoid using this field for user data. | core | keyword |  |
 | <a name="event.module"></a>event.module | Name of the module this data is coming from.<br/>This information is coming from the modules used in Beats or Logstash. | core | keyword | `mysql` |
 | <a name="event.dataset"></a>event.dataset | Name of the dataset.<br/>The concept of a `dataset` (fileset / metricset) is used in Beats as a subset of modules. It contains the information which is currently stored in metricset.name and metricset.module or fileset.name. | core | keyword | `stats` |
 | <a name="event.severity"></a>event.severity | Severity describes the severity of the event. What the different severity values mean can very different between use cases. It's up to the implementer to make sure severities are consistent across events. | core | long | `7` |

fields.yml

@@ -396,35 +396,64 @@
             Unique ID to describe the event.
           example: 8a4f500d
 
+        - name: kind
+          level: core
+          type: keyword
+          description: >
+            The kind of the event.
+
+            This gives information about what type of information the event
+            contains, without being specific to the contents of the event.  Examples
+            are `event`, `state`, `alarm`. Warning: In future versions of ECS, we
+            plan to provide a list of acceptable values for this field, please use
+            with caution.
+          example: state
+
         - name: category
           level: core
           type: keyword
           description: >
             Event category.
 
-            This can be a user defined category.
-          example: metrics
+            This contains high-level information about the contents of the event. It
+            is more generic than `event.action`, in the sense that typically a
+            category contains multiple actions. Warning: In future versions of ECS,
+            we plan to provide a list of acceptable values for this field, please
+            use with caution.
 
-        - name: type
+          example: user-management
+
+        - name: action
           level: core
           type: keyword
           description: >
-            A type given to this kind of event which can be used for grouping.
+            The action captured by the event.
 
-            This is normally defined by the user.
-          example: nginx-stats-metrics
+            This describes the information in the event. It is more specific than
+            `event.category`. Examples are `group-add`, `process-started`,
+            `file-created`. The value is normally defined by the implementer.
+          example: user-password-change
 
-        - name: action
+        - name: outcome
+          level: core
+          type: keyword
+          description: >
+            The outcome of the event.
+
+            If the event describes an action, this fields contains the outcome of
+            that action. Examples outcomes are `success` and `failure`. Warning: In
+            future versions of ECS, we plan to provide a list of acceptable values
+            for this field, please use with caution.
+
+          example: success
+
+        - name: type
           level: core
           type: keyword
           description: >
-            The action captured by the event. The type of action will vary from
-            system to system but is likely to include actions by security services,
-            such as blocking or quarantining; as well as more generic actions such
-            as login events, file i/o or proxy forwarding events.
+            Reserved for future usage.
 
-            The value is normally defined by the user.
-          example: reject
+            Please avoid using this field for user data.
 
         - name: module
           level: core

schema.csv

@@ -38,21 +38,23 @@ ecs.version,keyword,core,1.0.0-beta1
 error.code,keyword,core,
 error.id,keyword,core,
 error.message,text,core,
-event.action,keyword,core,reject
-event.category,keyword,core,metrics
+event.action,keyword,core,user-password-change
+event.category,keyword,core,user-management
 event.created,date,core,
 event.dataset,keyword,core,stats
 event.duration,long,core,
 event.end,date,extended,
 event.hash,keyword,extended,123456789012345678901234567890ABCD
 event.id,keyword,core,8a4f500d
+event.kind,keyword,core,state
 event.module,keyword,core,mysql
 event.original,keyword,core,Sep 19 08:26:10 host CEF:0|Security| threatmanager|1.0|100| worm successfully stopped|10|src=10.0.0.1 dst=2.1.2.2spt=1232
+event.outcome,keyword,core,success
 event.risk_score,float,core,
 event.risk_score_norm,float,extended,
 event.severity,long,core,7
 event.start,date,extended,
-event.type,keyword,core,nginx-stats-metrics
+event.type,keyword,core,
 file.ctime,date,extended,
 file.device,keyword,extended,
 file.extension,keyword,extended,png

schemas/event.yml

@@ -14,35 +14,64 @@
         Unique ID to describe the event.
       example: 8a4f500d
 
+    - name: kind
+      level: extended
+      type: keyword
+      description: >
+        The kind of the event.
+
+        This gives information about what type of information the event
+        contains, without being specific to the contents of the event.  Examples
+        are `event`, `state`, `alarm`. Warning: In future versions of ECS, we
+        plan to provide a list of acceptable values for this field, please use
+        with caution.
+      example: state
+
     - name: category
       level: core
       type: keyword
       description: >
         Event category.
 
-        This can be a user defined category.
-      example: metrics
+        This contains high-level information about the contents of the event. It
+        is more generic than `event.action`, in the sense that typically a
+        category contains multiple actions. Warning: In future versions of ECS,
+        we plan to provide a list of acceptable values for this field, please
+        use with caution.
 
-    - name: type
+      example: user-management
+
+    - name: action
       level: core
       type: keyword
       description: >
-        A type given to this kind of event which can be used for grouping.
+        The action captured by the event.
 
-        This is normally defined by the user.
-      example: nginx-stats-metrics
+        This describes the information in the event. It is more specific than
+        `event.category`. Examples are `group-add`, `process-started`,
+        `file-created`. The value is normally defined by the implementer.
+      example: user-password-change
 
-    - name: action
+    - name: outcome
+      level: extended
+      type: keyword
+      description: >
+        The outcome of the event.
+
+        If the event describes an action, this fields contains the outcome of
+        that action. Examples outcomes are `success` and `failure`. Warning: In
+        future versions of ECS, we plan to provide a list of acceptable values
+        for this field, please use with caution.
+
+      example: success
+
+    - name: type
       level: core
       type: keyword
       description: >
-        The action captured by the event. The type of action will vary from
-        system to system but is likely to include actions by security services,
-        such as blocking or quarantining; as well as more generic actions such
-        as login events, file i/o or proxy forwarding events.
+        Reserved for future usage.
 
-        The value is normally defined by the user.
-      example: reject
+        Please avoid using this field for user data.
 
     - name: module
       level: core

template.json

@@ -232,6 +232,10 @@
               "ignore_above": 1024,
               "type": "keyword"
             },
+            "kind": {
+              "ignore_above": 1024,
+              "type": "keyword"
+            },
             "module": {
               "ignore_above": 1024,
               "type": "keyword"
@@ -242,6 +246,10 @@
               "index": false,
               "type": "keyword"
             },
+            "outcome": {
+              "ignore_above": 1024,
+              "type": "keyword"
+            },
             "risk_score": {
               "type": "float"
             },