Add event.reason field

CHANGELOG.next.md

@@ -26,6 +26,7 @@ Thanks, you're awesome :-) -->
 * Added more account and project cloud metadata. (#816)
 * Added missing field reuse of `pe` at `process.parent.pe` #868
 * Added `span.id` to the tracing fieldset, for additional log correlation (#882)
+* Added `event.reason` for the reason why an event's outcome or action was taken. #907
 
 #### Improvements
 

docs/field-details.asciidoc

@@ -1776,6 +1776,21 @@ example: `kernel`
 
 // ===============================================================
 
+| event.reason
+| Reason why this event happened, according to the source.
+
+This describes the why of a particular action or outcome captured in the event. Where `event.action` captures the action from the event, `event.reason` describes why that action was taken. For example, a web proxy with an `event.action` which denied the request may also populate `event.reason` with the reason why (e.g. `blocked site`).
+
+type: keyword
+
+
+
+example: `Terminated an unexpected process`
+
+| extended
+
+// ===============================================================
+
 | event.reference
 | Reference URL linking to additional information about this event.
 

generated/beats/fields.ecs.yml

@@ -1350,6 +1350,19 @@
         the event (e.g. Sysmon, httpd), or of a subsystem of the operating system
         (kernel, Microsoft-Windows-Security-Auditing).'
       example: kernel
+    - name: reason
+      level: extended
+      type: keyword
+      ignore_above: 1024
+      description: 'Reason why this event happened, according to the source.
+
+        This describes the why of a particular action or outcome captured in the event.
+        Where `event.action` captures the action from the event, `event.reason` describes
+        why that action was taken. For example, a web proxy with an `event.action`
+        which denied the request may also populate `event.reason` with the reason
+        why (e.g. `blocked site`).'
+      example: Terminated an unexpected process
+      default_field: false
     - name: reference
       level: extended
       type: keyword

generated/csv/fields.csv

@@ -149,6 +149,7 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Normalization,Example,Description
 1.6.0-dev,false,event,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,Raw text message of entire event.
 1.6.0-dev,true,event,event.outcome,keyword,core,,success,The outcome of the event. The lowest level categorization field in the hierarchy.
 1.6.0-dev,true,event,event.provider,keyword,extended,,kernel,Source of the event.
+1.6.0-dev,true,event,event.reason,keyword,extended,,Terminated an unexpected process,"Reason why this event happened, according to the source"
 1.6.0-dev,true,event,event.reference,keyword,extended,,https://system.vendor.com/event/#0001234,Event reference URL
 1.6.0-dev,true,event,event.risk_score,float,core,,,Risk score or priority of the event (e.g. security solutions). Use your system's original value here.
 1.6.0-dev,true,event,event.risk_score_norm,float,extended,,,Normalized risk score or priority of the event (0-100).

generated/ecs/ecs_flat.yml

@@ -2053,6 +2053,23 @@ event.provider:
   normalize: []
   short: Source of the event.
   type: keyword
+event.reason:
+  dashed_name: event-reason
+  description: 'Reason why this event happened, according to the source.
+
+    This describes the why of a particular action or outcome captured in the event.
+    Where `event.action` captures the action from the event, `event.reason` describes
+    why that action was taken. For example, a web proxy with an `event.action` which
+    denied the request may also populate `event.reason` with the reason why (e.g.
+    `blocked site`).'
+  example: Terminated an unexpected process
+  flat_name: event.reason
+  ignore_above: 1024
+  level: extended
+  name: reason
+  normalize: []
+  short: Reason why this event happened, according to the source
+  type: keyword
 event.reference:
   dashed_name: event-reference
   description: 'Reference URL linking to additional information about this event.

generated/ecs/ecs_nested.yml

@@ -2450,6 +2450,23 @@ event:
       normalize: []
       short: Source of the event.
       type: keyword
+    event.reason:
+      dashed_name: event-reason
+      description: 'Reason why this event happened, according to the source.
+
+        This describes the why of a particular action or outcome captured in the event.
+        Where `event.action` captures the action from the event, `event.reason` describes
+        why that action was taken. For example, a web proxy with an `event.action`
+        which denied the request may also populate `event.reason` with the reason
+        why (e.g. `blocked site`).'
+      example: Terminated an unexpected process
+      flat_name: event.reason
+      ignore_above: 1024
+      level: extended
+      name: reason
+      normalize: []
+      short: Reason why this event happened, according to the source
+      type: keyword
     event.reference:
       dashed_name: event-reference
       description: 'Reference URL linking to additional information about this event.

generated/elasticsearch/6/template.json

@@ -726,6 +726,10 @@
               "ignore_above": 1024,
               "type": "keyword"
             },
+            "reason": {
+              "ignore_above": 1024,
+              "type": "keyword"
+            },
             "reference": {
               "ignore_above": 1024,
               "type": "keyword"

generated/elasticsearch/7/template.json

@@ -725,6 +725,10 @@
             "ignore_above": 1024,
             "type": "keyword"
           },
+          "reason": {
+            "ignore_above": 1024,
+            "type": "keyword"
+          },
           "reference": {
             "ignore_above": 1024,
             "type": "keyword"

schemas/event.yml

@@ -704,3 +704,16 @@
         Alert events, indicated by `event.kind:alert`, are a common use case for this field.
 
       example: https://mysystem.mydomain.com/alert/5271dedb-f5b0-4218-87f0-4ac4870a38fe
+
+    - name: reason
+      level: extended
+      type: keyword
+      short: Reason why this event happened, according to the source
+      description: >
+        Reason why this event happened, according to the source.
+
+        This describes the why of a particular action or outcome captured in the event. Where
+        `event.action` captures the action from the event, `event.reason` describes why that action
+        was taken. For example, a web proxy with an `event.action` which denied the request may also
+        populate `event.reason` with the reason why (e.g. `blocked site`).
+      example: "Terminated an unexpected process"