Clarify event.kind definitions re: vulnerabilities (#758)

CHANGELOG.next.md

@@ -26,6 +26,7 @@ Thanks, you're awesome :-) -->
 
 * Temporary workaround for Beats templates' `default_field` growing too big. #687
 * Identify which fields should contain arrays of values, rather than scalar values. #727, #661
+* Clarified examples and definitions regarding vulnerabilities #758
 * Updated definition of `event.outcome` based on community feedback #759
 
 #### Deprecated

docs/field-details.asciidoc

@@ -1449,7 +1449,7 @@ example: `java.lang.NullPointerException`
 
 The event fields are used for context information about the log or metric event itself.
 
-A log is defined as an event containing details of something that happened. Log events must include the time at which the thing happened. Examples of log events include a process starting on a host, a network packet being sent from a source to a destination, or a network connection between a client and a server being initiated or closed. A metric is defined as an event containing one or more numerical or categorical measurements and the time at which the measurement was taken. Examples of metric events include memory pressure measured on a host, or vulnerabilities measured on a scanned host.
+A log is defined as an event containing details of something that happened. Log events must include the time at which the thing happened. Examples of log events include a process starting on a host, a network packet being sent from a source to a destination, or a network connection between a client and a server being initiated or closed. A metric is defined as an event containing one or more numerical measurements and the time at which the measurement was taken. Examples of metric events include memory pressure measured on a host and device temperature. See the `event.kind` definition in this section for additional details about metric and state events.
 
 ==== Event Field Details
 

docs/field-values.asciidoc

@@ -78,11 +78,11 @@ This value is the most general and most common value for this field. It is used
 [[ecs-event-kind-metric]]
 ==== metric
 
-This value is used to indicate that this event that a numeric measurement was taken at given point in time.
+This value is used to indicate that this event describes a numeric measurement taken at given point in time.
 
-Examples include CPU utilization, memory usage, or a vulnerability scan result.
+Examples include CPU utilization, memory usage, or device temperature.
 
-Metric events are often collected on a predictable frequency, such as once every few seconds, or once a minute.
+Metric events are often collected on a predictable frequency, such as once every few seconds, or once a minute, but can also be used to describe ad-hoc numeric metric queries.
 
 
 
@@ -92,7 +92,13 @@ Metric events are often collected on a predictable frequency, such as once every
 [[ecs-event-kind-state]]
 ==== state
 
-This value is similar to metric, except that the entity being measured does not provide a numeric metric value, but rather one of a fixed set of conditions or states. For example a periodic event reporting a "fin_wait" state of a TCP connection on a host might use `event.type:state`.
+The state value is similar to metric, indicating that this event describes a measurement taken at given point in time, except that the measurement does not result in a numeric value, but rather one of a fixed set of categorical values that represent conditions or states.
+
+Examples include periodic events reporting Elasticsearch cluster state (green/yellow/red), the state of a TCP connection (open, closed, fin_wait, etc.), the state of a host with respect to a software vulnerability (vulnerable, not vulnerable), and the state of a system regarding compliance with a regulatory standard (compliant, not compliant).
+
+Note that an event that describes a change of state would not use `event.kind:state`, but instead would use 'event.kind:event' since a state change fits the more general event definition of something that happened.
+
+State events are often collected on a predictable frequency, such as once every few seconds, once a minute, once an hour, or once a day, but can also be used to describe ad-hoc state queries.
 
 
 

generated/beats/fields.ecs.yml

@@ -1116,9 +1116,10 @@
       events include a process starting on a host, a network packet being sent from
       a source to a destination, or a network connection between a client and a server
       being initiated or closed. A metric is defined as an event containing one or
-      more numerical or categorical measurements and the time at which the measurement
-      was taken. Examples of metric events include memory pressure measured on a host,
-      or vulnerabilities measured on a scanned host.'
+      more numerical measurements and the time at which the measurement was taken.
+      Examples of metric events include memory pressure measured on a host and device
+      temperature. See the `event.kind` definition in this section for additional
+      details about metric and state events.'
     type: group
     fields:
     - name: action

generated/ecs/ecs_flat.yml

@@ -2071,20 +2071,35 @@ event.kind:
 
       '
     name: event
-  - description: 'This value is used to indicate that this event that a numeric measurement
-      was taken at given point in time.
+  - description: 'This value is used to indicate that this event describes a numeric
+      measurement taken at given point in time.
 
-      Examples include CPU utilization, memory usage, or a vulnerability scan result.
+      Examples include CPU utilization, memory usage, or device temperature.
 
       Metric events are often collected on a predictable frequency, such as once every
-      few seconds, or once a minute.
+      few seconds, or once a minute, but can also be used to describe ad-hoc numeric
+      metric queries.
 
       '
     name: metric
-  - description: 'This value is similar to metric, except that the entity being measured
-      does not provide a numeric metric value, but rather one of a fixed set of conditions
-      or states. For example a periodic event reporting a "fin_wait" state of a TCP
-      connection on a host might use `event.type:state`.
+  - description: 'The state value is similar to metric, indicating that this event
+      describes a measurement taken at given point in time, except that the measurement
+      does not result in a numeric value, but rather one of a fixed set of categorical
+      values that represent conditions or states.
+
+      Examples include periodic events reporting Elasticsearch cluster state (green/yellow/red),
+      the state of a TCP connection (open, closed, fin_wait, etc.), the state of a
+      host with respect to a software vulnerability (vulnerable, not vulnerable),
+      and the state of a system regarding compliance with a regulatory standard (compliant,
+      not compliant).
+
+      Note that an event that describes a change of state would not use `event.kind:state`,
+      but instead would use ''event.kind:event'' since a state change fits the more
+      general event definition of something that happened.
+
+      State events are often collected on a predictable frequency, such as once every
+      few seconds, once a minute, once an hour, or once a day, but can also be used
+      to describe ad-hoc state queries.
 
       '
     name: state

generated/ecs/ecs_nested.yml

@@ -1999,9 +1999,10 @@ event:
     include a process starting on a host, a network packet being sent from a source
     to a destination, or a network connection between a client and a server being
     initiated or closed. A metric is defined as an event containing one or more numerical
-    or categorical measurements and the time at which the measurement was taken. Examples
-    of metric events include memory pressure measured on a host, or vulnerabilities
-    measured on a scanned host.'
+    measurements and the time at which the measurement was taken. Examples of metric
+    events include memory pressure measured on a host and device temperature. See
+    the `event.kind` definition in this section for additional details about metric
+    and state events.'
   fields:
     action:
       dashed_name: event-action
@@ -2327,21 +2328,35 @@ event:
 
           '
         name: event
-      - description: 'This value is used to indicate that this event that a numeric
-          measurement was taken at given point in time.
+      - description: 'This value is used to indicate that this event describes a numeric
+          measurement taken at given point in time.
 
-          Examples include CPU utilization, memory usage, or a vulnerability scan
-          result.
+          Examples include CPU utilization, memory usage, or device temperature.
 
           Metric events are often collected on a predictable frequency, such as once
-          every few seconds, or once a minute.
+          every few seconds, or once a minute, but can also be used to describe ad-hoc
+          numeric metric queries.
 
           '
         name: metric
-      - description: 'This value is similar to metric, except that the entity being
-          measured does not provide a numeric metric value, but rather one of a fixed
-          set of conditions or states. For example a periodic event reporting a "fin_wait"
-          state of a TCP connection on a host might use `event.type:state`.
+      - description: 'The state value is similar to metric, indicating that this event
+          describes a measurement taken at given point in time, except that the measurement
+          does not result in a numeric value, but rather one of a fixed set of categorical
+          values that represent conditions or states.
+
+          Examples include periodic events reporting Elasticsearch cluster state (green/yellow/red),
+          the state of a TCP connection (open, closed, fin_wait, etc.), the state
+          of a host with respect to a software vulnerability (vulnerable, not vulnerable),
+          and the state of a system regarding compliance with a regulatory standard
+          (compliant, not compliant).
+
+          Note that an event that describes a change of state would not use `event.kind:state`,
+          but instead would use ''event.kind:event'' since a state change fits the
+          more general event definition of something that happened.
+
+          State events are often collected on a predictable frequency, such as once
+          every few seconds, once a minute, once an hour, or once a day, but can also
+          be used to describe ad-hoc state queries.
 
           '
         name: state

schemas/event.yml

@@ -11,10 +11,11 @@
     Examples of log events include a process starting on a host,
     a network packet being sent from a source to a destination,
     or a network connection between a client and a server being initiated or closed.
-    A metric is defined as an event containing one or more numerical or
-    categorical measurements and the time at which the measurement was taken.
-    Examples of metric events include memory pressure measured on a host,
-    or vulnerabilities measured on a scanned host.
+    A metric is defined as an event containing one or more numerical measurements
+    and the time at which the measurement was taken. Examples of metric events include
+    memory pressure measured on a host and device temperature.
+    See the `event.kind` definition in this section for additional details about
+    metric and state events.
   type: group
   fields:
 
@@ -68,19 +69,33 @@
             It is used to represent events that indicate that something happened.
         - name: metric
           description: >
-            This value is used to indicate that this event that a numeric measurement
-            was taken at given point in time.
+            This value is used to indicate that this event describes a numeric measurement
+            taken at given point in time.
 
-            Examples include CPU utilization, memory usage, or a vulnerability scan result.
+            Examples include CPU utilization, memory usage, or device temperature.
 
             Metric events are often collected on a predictable frequency, such as once
-            every few seconds, or once a minute.
+            every few seconds, or once a minute, but can also be used to
+            describe ad-hoc numeric metric queries.
         - name: state
           description: >
-            This value is similar to metric, except that the entity being measured does not
-            provide a numeric metric value, but rather one of a fixed set of conditions or states.
-            For example a periodic event reporting a "fin_wait" state of a TCP connection
-            on a host might use `event.type:state`.
+            The state value is similar to metric, indicating that this event describes a
+            measurement taken at given point in time, except that the measurement does not
+            result in a numeric value, but rather one of a fixed set of categorical values
+            that represent conditions or states.
+
+            Examples include periodic events reporting Elasticsearch cluster state (green/yellow/red),
+            the state of a TCP connection (open, closed, fin_wait, etc.), the state of a host with respect
+            to a software vulnerability (vulnerable, not vulnerable), and the state of a system
+            regarding compliance with a regulatory standard (compliant, not compliant).
+
+            Note that an event that describes a change of state would not use `event.kind:state`,
+            but instead would use 'event.kind:event' since a state change fits the more general
+            event definition of something that happened.
+
+            State events are often collected on a predictable frequency, such as once
+            every few seconds, once a minute, once an hour, or once a day, but can also be used to
+            describe ad-hoc state queries.
         - name: pipeline_error
           description: >
             This value indicates that an error occurred during the ingestion of this event,