From e9d87695770b3052455eb25a3621ec296e564a8d Mon Sep 17 00:00:00 2001 From: Mathieu Martin Date: Fri, 2 Oct 2020 16:32:13 -0400 Subject: [PATCH] Add network directions ingress and egress (#945) --- CHANGELOG.next.md | 1 + code/go/ecs/network.go | 23 ++++++++++++++++------- docs/field-details.asciidoc | 12 +++++++++--- generated/beats/fields.ecs.yml | 20 +++++++++++++------- generated/ecs/ecs_flat.yml | 20 +++++++++++++------- generated/ecs/ecs_nested.yml | 20 +++++++++++++------- schemas/network.yml | 19 ++++++++++++++----- 7 files changed, 79 insertions(+), 36 deletions(-) diff --git a/CHANGELOG.next.md b/CHANGELOG.next.md index afd179c547..417377de00 100644 --- a/CHANGELOG.next.md +++ b/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 diff --git a/code/go/ecs/network.go b/code/go/ecs/network.go index e47d15abd2..a696a4e419 100644 --- a/code/go/ecs/network.go +++ b/code/go/ecs/network.go @@ -61,6 +61,8 @@ type Network struct { // Direction of the network traffic. // Recommended values are: + // * ingress + // * egress // * inbound // * outbound // * internal @@ -68,10 +70,17 @@ type Network struct { // * 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. + // context, 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. Direction string `ecs:"direction"` // Host IP address when the source IP address is the proxy. @@ -94,9 +103,9 @@ type Network struct { Packets int64 `ecs:"packets"` // 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.) + // 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.) Inner map[string]interface{} `ecs:"inner"` } diff --git a/docs/field-details.asciidoc b/docs/field-details.asciidoc index b716165642..9bd030d0af 100644 --- a/docs/field-details.asciidoc +++ b/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 diff --git a/generated/beats/fields.ecs.yml b/generated/beats/fields.ecs.yml index 150ee1d911..807ffd2115 100644 --- a/generated/beats/fields.ecs.yml +++ b/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 diff --git a/generated/ecs/ecs_flat.yml b/generated/ecs/ecs_flat.yml index a209023534..08277b4372 100644 --- a/generated/ecs/ecs_flat.yml +++ b/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 diff --git a/generated/ecs/ecs_nested.yml b/generated/ecs/ecs_nested.yml index 2189a64503..b4fecef933 100644 --- a/generated/ecs/ecs_nested.yml +++ b/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 diff --git a/schemas/network.yml b/schemas/network.yml index 4b01088e9a..c6fed904b7 100644 --- a/schemas/network.yml +++ b/schemas/network.yml @@ -85,6 +85,8 @@ Direction of the network traffic. Recommended values are: + * ingress + * egress * inbound * outbound * internal @@ -92,10 +94,17 @@ * 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.)