Improve descriptions for network.* fields (elastic#1645) (elastic#1648

) * improve network.protocol description * improve network.application description * remove remaining references to 'Implementing ECS' * artifacts * adjust network.application description
ebeahan · Nov 1, 2021 · b3dace4 · b3dace4
1 parent ccfb964
commit b3dace4
Show file tree

Hide file tree

Showing 10 changed files with 109 additions and 114 deletions.
diff --git a/docs/field-details.asciidoc b/docs/field-details.asciidoc
@@ -5004,9 +5004,11 @@ The network.* fields should be populated with details about the network activity
 [[field-network-application]]
 <<field-network-application, network.application>>
 
-| A name given to an application level protocol. This can be arbitrarily assigned for things like microservices, but also apply to things like skype, icq, facebook, twitter. This would be used in situations where the vendor or service can be decoded such as from the source/dest IP owners, ports, or wire format.
+| When a specific application or service is identified from network connection details (source/dest IPs, ports, certificates, or wire format), this field captures the application's or service's name.
 
-The field value must be normalized to lowercase for querying. See the documentation section "Implementing ECS".
+For example, the original event identifies the network connection being from a specific web service in a `https` network connection, like `facebook` or `twitter`.
+
+The field value must be normalized to lowercase for querying.
 
 type: keyword
 
@@ -5180,9 +5182,9 @@ example: `24`
 [[field-network-protocol]]
 <<field-network-protocol, network.protocol>>
 
-| L7 Network protocol name. ex. http, lumberjack, transport protocol.
+| In the OSI Model this would be the Application Layer protocol. For example, `http`, `dns`, or `ssh`.
 
-The field value must be normalized to lowercase for querying. See the documentation section "Implementing ECS".
+The field value must be normalized to lowercase for querying.
 
 type: keyword
 
@@ -5200,7 +5202,7 @@ example: `http`
 
 | Same as network.iana_number, but instead using the Keyword name of the transport layer (udp, tcp, ipv6-icmp, etc.)
 
-The field value must be normalized to lowercase for querying. See the documentation section "Implementing ECS".
+The field value must be normalized to lowercase for querying.
 
 type: keyword
 
@@ -5218,7 +5220,7 @@ example: `tcp`
 
 | In the OSI Model this would be the Network Layer. ipv4, ipv6, ipsec, pim, etc
 
-The field value must be normalized to lowercase for querying. See the documentation section "Implementing ECS".
+The field value must be normalized to lowercase for querying.
 
 type: keyword
 

diff --git a/experimental/generated/beats/fields.ecs.yml b/experimental/generated/beats/fields.ecs.yml
@@ -4167,14 +4167,15 @@
       level: extended
       type: keyword
       ignore_above: 1024
-      description: 'A name given to an application level protocol. This can be arbitrarily
-        assigned for things like microservices, but also apply to things like skype,
-        icq, facebook, twitter. This would be used in situations where the vendor
-        or service can be decoded such as from the source/dest IP owners, ports, or
-        wire format.
-
-        The field value must be normalized to lowercase for querying. See the documentation
-        section "Implementing ECS".'
+      description: 'When a specific application or service is identified from network
+        connection details (source/dest IPs, ports, certificates, or wire format),
+        this field captures the application''s or service''s name.
+
+        For example, the original event identifies the network connection being from
+        a specific web service in a `https` network connection, like `facebook` or
+        `twitter`.
+
+        The field value must be normalized to lowercase for querying.'
       example: aim
     - name: bytes
       level: core
@@ -4266,10 +4267,10 @@
       level: core
       type: keyword
       ignore_above: 1024
-      description: 'L7 Network protocol name. ex. http, lumberjack, transport protocol.
+      description: 'In the OSI Model this would be the Application Layer protocol.
+        For example, `http`, `dns`, or `ssh`.
 
-        The field value must be normalized to lowercase for querying. See the documentation
-        section "Implementing ECS".'
+        The field value must be normalized to lowercase for querying.'
       example: http
     - name: transport
       level: core
@@ -4278,8 +4279,7 @@
       description: 'Same as network.iana_number, but instead using the Keyword name
         of the transport layer (udp, tcp, ipv6-icmp, etc.)
 
-        The field value must be normalized to lowercase for querying. See the documentation
-        section "Implementing ECS".'
+        The field value must be normalized to lowercase for querying.'
       example: tcp
     - name: type
       level: core
@@ -4288,8 +4288,7 @@
       description: 'In the OSI Model this would be the Network Layer. ipv4, ipv6,
         ipsec, pim, etc
 
-        The field value must be normalized to lowercase for querying. See the documentation
-        section "Implementing ECS".'
+        The field value must be normalized to lowercase for querying.'
       example: ipv4
     - name: vlan.id
       level: extended

diff --git a/experimental/generated/csv/fields.csv b/experimental/generated/csv/fields.csv
@@ -471,7 +471,7 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Normalization,Example,Description
 8.0.0-dev+exp,true,network,network.inner.vlan.name,keyword,extended,,outside,Optional VLAN name as reported by the observer.
 8.0.0-dev+exp,true,network,network.name,keyword,extended,,Guest Wifi,Name given by operators to sections of their network.
 8.0.0-dev+exp,true,network,network.packets,long,core,,24,Total packets transferred in both directions.
-8.0.0-dev+exp,true,network,network.protocol,keyword,core,,http,L7 Network protocol name.
+8.0.0-dev+exp,true,network,network.protocol,keyword,core,,http,Application protocol name.
 8.0.0-dev+exp,true,network,network.transport,keyword,core,,tcp,Protocol Name corresponding to the field `iana_number`.
 8.0.0-dev+exp,true,network,network.type,keyword,core,,ipv4,"In the OSI Model this would be the Network Layer. ipv4, ipv6, ipsec, pim, etc"
 8.0.0-dev+exp,true,network,network.vlan.id,keyword,extended,,10,VLAN ID as reported by the observer.

diff --git a/experimental/generated/ecs/ecs_flat.yml b/experimental/generated/ecs/ecs_flat.yml
@@ -6058,13 +6058,14 @@ message:
   type: match_only_text
 network.application:
   dashed_name: network-application
-  description: 'A name given to an application level protocol. This can be arbitrarily
-    assigned for things like microservices, but also apply to things like skype, icq,
-    facebook, twitter. This would be used in situations where the vendor or service
-    can be decoded such as from the source/dest IP owners, ports, or wire format.
+  description: 'When a specific application or service is identified from network
+    connection details (source/dest IPs, ports, certificates, or wire format), this
+    field captures the application''s or service''s name.
 
-    The field value must be normalized to lowercase for querying. See the documentation
-    section "Implementing ECS".'
+    For example, the original event identifies the network connection being from a
+    specific web service in a `https` network connection, like `facebook` or `twitter`.
+
+    The field value must be normalized to lowercase for querying.'
   example: aim
   flat_name: network.application
   ignore_above: 1024
@@ -6207,25 +6208,24 @@ network.packets:
   type: long
 network.protocol:
   dashed_name: network-protocol
-  description: 'L7 Network protocol name. ex. http, lumberjack, transport protocol.
+  description: 'In the OSI Model this would be the Application Layer protocol. For
+    example, `http`, `dns`, or `ssh`.
 
-    The field value must be normalized to lowercase for querying. See the documentation
-    section "Implementing ECS".'
+    The field value must be normalized to lowercase for querying.'
   example: http
   flat_name: network.protocol
   ignore_above: 1024
   level: core
   name: protocol
   normalize: []
-  short: L7 Network protocol name.
+  short: Application protocol name.
   type: keyword
 network.transport:
   dashed_name: network-transport
   description: 'Same as network.iana_number, but instead using the Keyword name of
     the transport layer (udp, tcp, ipv6-icmp, etc.)
 
-    The field value must be normalized to lowercase for querying. See the documentation
-    section "Implementing ECS".'
+    The field value must be normalized to lowercase for querying.'
   example: tcp
   flat_name: network.transport
   ignore_above: 1024
@@ -6239,8 +6239,7 @@ network.type:
   description: 'In the OSI Model this would be the Network Layer. ipv4, ipv6, ipsec,
     pim, etc
 
-    The field value must be normalized to lowercase for querying. See the documentation
-    section "Implementing ECS".'
+    The field value must be normalized to lowercase for querying.'
   example: ipv4
   flat_name: network.type
   ignore_above: 1024

diff --git a/experimental/generated/ecs/ecs_nested.yml b/experimental/generated/ecs/ecs_nested.yml
@@ -7346,14 +7346,15 @@ network:
   fields:
     network.application:
       dashed_name: network-application
-      description: 'A name given to an application level protocol. This can be arbitrarily
-        assigned for things like microservices, but also apply to things like skype,
-        icq, facebook, twitter. This would be used in situations where the vendor
-        or service can be decoded such as from the source/dest IP owners, ports, or
-        wire format.
-
-        The field value must be normalized to lowercase for querying. See the documentation
-        section "Implementing ECS".'
+      description: 'When a specific application or service is identified from network
+        connection details (source/dest IPs, ports, certificates, or wire format),
+        this field captures the application''s or service''s name.
+
+        For example, the original event identifies the network connection being from
+        a specific web service in a `https` network connection, like `facebook` or
+        `twitter`.
+
+        The field value must be normalized to lowercase for querying.'
       example: aim
       flat_name: network.application
       ignore_above: 1024
@@ -7499,25 +7500,24 @@ network:
       type: long
     network.protocol:
       dashed_name: network-protocol
-      description: 'L7 Network protocol name. ex. http, lumberjack, transport protocol.
+      description: 'In the OSI Model this would be the Application Layer protocol.
+        For example, `http`, `dns`, or `ssh`.
 
-        The field value must be normalized to lowercase for querying. See the documentation
-        section "Implementing ECS".'
+        The field value must be normalized to lowercase for querying.'
       example: http
       flat_name: network.protocol
       ignore_above: 1024
       level: core
       name: protocol
       normalize: []
-      short: L7 Network protocol name.
+      short: Application protocol name.
       type: keyword
     network.transport:
       dashed_name: network-transport
       description: 'Same as network.iana_number, but instead using the Keyword name
         of the transport layer (udp, tcp, ipv6-icmp, etc.)
 
-        The field value must be normalized to lowercase for querying. See the documentation
-        section "Implementing ECS".'
+        The field value must be normalized to lowercase for querying.'
       example: tcp
       flat_name: network.transport
       ignore_above: 1024
@@ -7531,8 +7531,7 @@ network:
       description: 'In the OSI Model this would be the Network Layer. ipv4, ipv6,
         ipsec, pim, etc
 
-        The field value must be normalized to lowercase for querying. See the documentation
-        section "Implementing ECS".'
+        The field value must be normalized to lowercase for querying.'
       example: ipv4
       flat_name: network.type
       ignore_above: 1024

diff --git a/generated/beats/fields.ecs.yml b/generated/beats/fields.ecs.yml
@@ -3538,14 +3538,15 @@
       level: extended
       type: keyword
       ignore_above: 1024
-      description: 'A name given to an application level protocol. This can be arbitrarily
-        assigned for things like microservices, but also apply to things like skype,
-        icq, facebook, twitter. This would be used in situations where the vendor
-        or service can be decoded such as from the source/dest IP owners, ports, or
-        wire format.
-
-        The field value must be normalized to lowercase for querying. See the documentation
-        section "Implementing ECS".'
+      description: 'When a specific application or service is identified from network
+        connection details (source/dest IPs, ports, certificates, or wire format),
+        this field captures the application''s or service''s name.
+
+        For example, the original event identifies the network connection being from
+        a specific web service in a `https` network connection, like `facebook` or
+        `twitter`.
+
+        The field value must be normalized to lowercase for querying.'
       example: aim
     - name: bytes
       level: core
@@ -3637,10 +3638,10 @@
       level: core
       type: keyword
       ignore_above: 1024
-      description: 'L7 Network protocol name. ex. http, lumberjack, transport protocol.
+      description: 'In the OSI Model this would be the Application Layer protocol.
+        For example, `http`, `dns`, or `ssh`.
 
-        The field value must be normalized to lowercase for querying. See the documentation
-        section "Implementing ECS".'
+        The field value must be normalized to lowercase for querying.'
       example: http
     - name: transport
       level: core
@@ -3649,8 +3650,7 @@
       description: 'Same as network.iana_number, but instead using the Keyword name
         of the transport layer (udp, tcp, ipv6-icmp, etc.)
 
-        The field value must be normalized to lowercase for querying. See the documentation
-        section "Implementing ECS".'
+        The field value must be normalized to lowercase for querying.'
       example: tcp
     - name: type
       level: core
@@ -3659,8 +3659,7 @@
       description: 'In the OSI Model this would be the Network Layer. ipv4, ipv6,
         ipsec, pim, etc
 
-        The field value must be normalized to lowercase for querying. See the documentation
-        section "Implementing ECS".'
+        The field value must be normalized to lowercase for querying.'
       example: ipv4
     - name: vlan.id
       level: extended

diff --git a/generated/csv/fields.csv b/generated/csv/fields.csv
@@ -381,7 +381,7 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Normalization,Example,Description
 8.0.0-dev,true,network,network.inner.vlan.name,keyword,extended,,outside,Optional VLAN name as reported by the observer.
 8.0.0-dev,true,network,network.name,keyword,extended,,Guest Wifi,Name given by operators to sections of their network.
 8.0.0-dev,true,network,network.packets,long,core,,24,Total packets transferred in both directions.
-8.0.0-dev,true,network,network.protocol,keyword,core,,http,L7 Network protocol name.
+8.0.0-dev,true,network,network.protocol,keyword,core,,http,Application protocol name.
 8.0.0-dev,true,network,network.transport,keyword,core,,tcp,Protocol Name corresponding to the field `iana_number`.
 8.0.0-dev,true,network,network.type,keyword,core,,ipv4,"In the OSI Model this would be the Network Layer. ipv4, ipv6, ipsec, pim, etc"
 8.0.0-dev,true,network,network.vlan.id,keyword,extended,,10,VLAN ID as reported by the observer.

diff --git a/generated/ecs/ecs_flat.yml b/generated/ecs/ecs_flat.yml
@@ -5008,13 +5008,14 @@ message:
   type: match_only_text
 network.application:
   dashed_name: network-application
-  description: 'A name given to an application level protocol. This can be arbitrarily
-    assigned for things like microservices, but also apply to things like skype, icq,
-    facebook, twitter. This would be used in situations where the vendor or service
-    can be decoded such as from the source/dest IP owners, ports, or wire format.
+  description: 'When a specific application or service is identified from network
+    connection details (source/dest IPs, ports, certificates, or wire format), this
+    field captures the application''s or service''s name.
 
-    The field value must be normalized to lowercase for querying. See the documentation
-    section "Implementing ECS".'
+    For example, the original event identifies the network connection being from a
+    specific web service in a `https` network connection, like `facebook` or `twitter`.
+
+    The field value must be normalized to lowercase for querying.'
   example: aim
   flat_name: network.application
   ignore_above: 1024
@@ -5157,25 +5158,24 @@ network.packets:
   type: long
 network.protocol:
   dashed_name: network-protocol
-  description: 'L7 Network protocol name. ex. http, lumberjack, transport protocol.
+  description: 'In the OSI Model this would be the Application Layer protocol. For
+    example, `http`, `dns`, or `ssh`.
 
-    The field value must be normalized to lowercase for querying. See the documentation
-    section "Implementing ECS".'
+    The field value must be normalized to lowercase for querying.'
   example: http
   flat_name: network.protocol
   ignore_above: 1024
   level: core
   name: protocol
   normalize: []
-  short: L7 Network protocol name.
+  short: Application protocol name.
   type: keyword
 network.transport:
   dashed_name: network-transport
   description: 'Same as network.iana_number, but instead using the Keyword name of
     the transport layer (udp, tcp, ipv6-icmp, etc.)
 
-    The field value must be normalized to lowercase for querying. See the documentation
-    section "Implementing ECS".'
+    The field value must be normalized to lowercase for querying.'
   example: tcp
   flat_name: network.transport
   ignore_above: 1024
@@ -5189,8 +5189,7 @@ network.type:
   description: 'In the OSI Model this would be the Network Layer. ipv4, ipv6, ipsec,
     pim, etc
 
-    The field value must be normalized to lowercase for querying. See the documentation
-    section "Implementing ECS".'
+    The field value must be normalized to lowercase for querying.'
   example: ipv4
   flat_name: network.type
   ignore_above: 1024