Add network directions ingress and egress (elastic#945)

CHANGELOG.next.md

@@ -21,6 +21,7 @@ Thanks, you're awesome :-) -->
 * Added Mime Type fields to HTTP request and response. #944
 * Added `threat.technique.subtechnique` to capture MITRE ATT&CK® subtechniques. #951
 * Added `configuration` as an allowed `event.category`. #963
+* Added network directions ingress and egress. #945
 
 #### Improvements
 

docs/field-details.asciidoc

@@ -3356,6 +3356,10 @@ example: `1:hO+sN4H+MG5MY/8hIrXPqc4ZQz0=`
 
 Recommended values are:
 
+  * ingress
+
+  * egress
+
   * inbound
 
   * outbound
@@ -3368,9 +3372,11 @@ Recommended values are:
 
 
 
-When mapping events from a host-based monitoring context, populate this field from the host's point of view.
+When mapping events from a host-based monitoring context, populate this field from the host's point of view, using the values "ingress" or "egress".
+
+When mapping events from a network or perimeter-based monitoring context, populate this field from the point of view of the network perimeter, using the values "inbound", "outbound", "internal" or "external".
 
-When mapping events from a network or perimeter-based monitoring context, populate this field from the point of view of your network perimeter.
+Note that "internal" is not crossing perimeter boundaries, and is meant to describe communication between two hosts within the perimeter. Note also that "external" is meant to describe traffic between two hosts that are external to the perimeter. This could for example be useful for ISPs or VPN service providers.
 
 type: keyword
 
@@ -3409,7 +3415,7 @@ example: `6`
 // ===============================================================
 
 | network.inner
-| Network.inner fields are added in addition to network.vlan fields to describe  the innermost VLAN when q-in-q VLAN tagging is present. Allowed fields include  vlan.id and vlan.name. Inner vlan fields are typically used when sending traffic with multiple 802.1q encapsulations to a network sensor (e.g. Zeek, Wireshark.)
+| Network.inner fields are added in addition to network.vlan fields to describe the innermost VLAN when q-in-q VLAN tagging is present. Allowed fields include vlan.id and vlan.name. Inner vlan fields are typically used when sending traffic with multiple 802.1q encapsulations to a network sensor (e.g. Zeek, Wireshark.)
 
 type: object
 

generated/beats/fields.ecs.yml

@@ -2622,11 +2622,17 @@
       type: keyword
       ignore_above: 1024
       description: "Direction of the network traffic.\nRecommended values are:\n \
-        \ * inbound\n  * outbound\n  * internal\n  * external\n  * unknown\n\nWhen\
-        \ mapping events from a host-based monitoring context, populate this field\
-        \ from the host's point of view.\nWhen mapping events from a network or perimeter-based\
-        \ monitoring context, populate this field from the point of view of your network\
-        \ perimeter."
+        \ * ingress\n  * egress\n  * inbound\n  * outbound\n  * internal\n  * external\n\
+        \  * unknown\n\nWhen mapping events from a host-based monitoring context,\
+        \ populate this field from the host's point of view, using the values \"ingress\"\
+        \ or \"egress\".\nWhen mapping events from a network or perimeter-based monitoring\
+        \ context, populate this field from the point of view of the network perimeter,\
+        \ using the values \"inbound\", \"outbound\", \"internal\" or \"external\"\
+        .\nNote that \"internal\" is not crossing perimeter boundaries, and is meant\
+        \ to describe communication between two hosts within the perimeter. Note also\
+        \ that \"external\" is meant to describe traffic between two hosts that are\
+        \ external to the perimeter. This could for example be useful for ISPs or\
+        \ VPN service providers."
       example: inbound
     - name: forwarded_ip
       level: core
@@ -2645,8 +2651,8 @@
       level: extended
       type: object
       description: Network.inner fields are added in addition to network.vlan fields
-        to describe  the innermost VLAN when q-in-q VLAN tagging is present. Allowed
-        fields include  vlan.id and vlan.name. Inner vlan fields are typically used
+        to describe the innermost VLAN when q-in-q VLAN tagging is present. Allowed
+        fields include vlan.id and vlan.name. Inner vlan fields are typically used
         when sending traffic with multiple 802.1q encapsulations to a network sensor
         (e.g. Zeek, Wireshark.)
       default_field: false

generated/ecs/ecs_flat.yml

@@ -4019,11 +4019,17 @@ network.community_id:
   type: keyword
 network.direction:
   dashed_name: network-direction
-  description: "Direction of the network traffic.\nRecommended values are:\n  * inbound\n\
-    \  * outbound\n  * internal\n  * external\n  * unknown\n\nWhen mapping events\
-    \ from a host-based monitoring context, populate this field from the host's point\
-    \ of view.\nWhen mapping events from a network or perimeter-based monitoring context,\
-    \ populate this field from the point of view of your network perimeter."
+  description: "Direction of the network traffic.\nRecommended values are:\n  * ingress\n\
+    \  * egress\n  * inbound\n  * outbound\n  * internal\n  * external\n  * unknown\n\
+    \nWhen mapping events from a host-based monitoring context, populate this field\
+    \ from the host's point of view, using the values \"ingress\" or \"egress\".\n\
+    When mapping events from a network or perimeter-based monitoring context, populate\
+    \ this field from the point of view of the network perimeter, using the values\
+    \ \"inbound\", \"outbound\", \"internal\" or \"external\".\nNote that \"internal\"\
+    \ is not crossing perimeter boundaries, and is meant to describe communication\
+    \ between two hosts within the perimeter. Note also that \"external\" is meant\
+    \ to describe traffic between two hosts that are external to the perimeter. This\
+    \ could for example be useful for ISPs or VPN service providers."
   example: inbound
   flat_name: network.direction
   ignore_above: 1024
@@ -4058,8 +4064,8 @@ network.iana_number:
 network.inner:
   dashed_name: network-inner
   description: Network.inner fields are added in addition to network.vlan fields to
-    describe  the innermost VLAN when q-in-q VLAN tagging is present. Allowed fields
-    include  vlan.id and vlan.name. Inner vlan fields are typically used when sending
+    describe the innermost VLAN when q-in-q VLAN tagging is present. Allowed fields
+    include vlan.id and vlan.name. Inner vlan fields are typically used when sending
     traffic with multiple 802.1q encapsulations to a network sensor (e.g. Zeek, Wireshark.)
   flat_name: network.inner
   level: extended

generated/ecs/ecs_nested.yml

@@ -4768,11 +4768,17 @@ network:
     network.direction:
       dashed_name: network-direction
       description: "Direction of the network traffic.\nRecommended values are:\n \
-        \ * inbound\n  * outbound\n  * internal\n  * external\n  * unknown\n\nWhen\
-        \ mapping events from a host-based monitoring context, populate this field\
-        \ from the host's point of view.\nWhen mapping events from a network or perimeter-based\
-        \ monitoring context, populate this field from the point of view of your network\
-        \ perimeter."
+        \ * ingress\n  * egress\n  * inbound\n  * outbound\n  * internal\n  * external\n\
+        \  * unknown\n\nWhen mapping events from a host-based monitoring context,\
+        \ populate this field from the host's point of view, using the values \"ingress\"\
+        \ or \"egress\".\nWhen mapping events from a network or perimeter-based monitoring\
+        \ context, populate this field from the point of view of the network perimeter,\
+        \ using the values \"inbound\", \"outbound\", \"internal\" or \"external\"\
+        .\nNote that \"internal\" is not crossing perimeter boundaries, and is meant\
+        \ to describe communication between two hosts within the perimeter. Note also\
+        \ that \"external\" is meant to describe traffic between two hosts that are\
+        \ external to the perimeter. This could for example be useful for ISPs or\
+        \ VPN service providers."
       example: inbound
       flat_name: network.direction
       ignore_above: 1024
@@ -4807,8 +4813,8 @@ network:
     network.inner:
       dashed_name: network-inner
       description: Network.inner fields are added in addition to network.vlan fields
-        to describe  the innermost VLAN when q-in-q VLAN tagging is present. Allowed
-        fields include  vlan.id and vlan.name. Inner vlan fields are typically used
+        to describe the innermost VLAN when q-in-q VLAN tagging is present. Allowed
+        fields include vlan.id and vlan.name. Inner vlan fields are typically used
         when sending traffic with multiple 802.1q encapsulations to a network sensor
         (e.g. Zeek, Wireshark.)
       flat_name: network.inner

schemas/network.yml

@@ -85,17 +85,26 @@
         Direction of the network traffic.
 
         Recommended values are:
+          * ingress
+          * egress
           * inbound
           * outbound
           * internal
           * external
           * unknown
 
         When mapping events from a host-based monitoring context, populate this
-        field from the host's point of view.
+        field from the host's point of view, using the values "ingress" or "egress".
 
         When mapping events from a network or perimeter-based monitoring context,
-        populate this field from the point of view of your network perimeter.
+        populate this field from the point of view of the network perimeter,
+        using the values "inbound", "outbound", "internal" or "external".
+
+        Note that "internal" is not crossing perimeter boundaries, and is meant
+        to describe communication between two hosts within the perimeter. Note also
+        that "external" is meant to describe traffic between two hosts that are
+        external to the perimeter. This could for example be useful for ISPs or
+        VPN service providers.
       example: inbound
 
     - name: forwarded_ip
@@ -138,14 +147,14 @@
 
         If `source.packets` and `destination.packets` are known, `network.packets` is their sum.
       example: 24
-    
+
     # q-in-q vlan fields for identifying 802.1q nested vlans
     - name: inner
       level: extended
       type: object
       short: Inner VLAN tag information
       description: >
-        Network.inner fields are added in addition to network.vlan fields to describe 
-        the innermost VLAN when q-in-q VLAN tagging is present. Allowed fields include 
+        Network.inner fields are added in addition to network.vlan fields to describe
+        the innermost VLAN when q-in-q VLAN tagging is present. Allowed fields include
         vlan.id and vlan.name. Inner vlan fields are typically used when sending traffic
         with multiple 802.1q encapsulations to a network sensor (e.g. Zeek, Wireshark.)