From 0796cc3437dc50e47bca7677825edbe546881b3e Mon Sep 17 00:00:00 2001 From: Mathieu Martin Date: Fri, 2 Oct 2020 15:11:52 -0400 Subject: [PATCH] Try to clarify the meaning of the non-directional 'internal' and 'external' values. Also quoting the values, when they're mentioned in the description. --- code/go/ecs/network.go | 11 +++++++++-- docs/field-details.asciidoc | 6 ++++-- generated/beats/fields.ecs.yml | 11 ++++++++--- generated/ecs/ecs_flat.yml | 12 ++++++++---- generated/ecs/ecs_nested.yml | 11 ++++++++--- schemas/network.yml | 10 ++++++++-- 6 files changed, 45 insertions(+), 16 deletions(-) diff --git a/code/go/ecs/network.go b/code/go/ecs/network.go index 7e80a6b11b..21fd5d5b79 100644 --- a/code/go/ecs/network.go +++ b/code/go/ecs/network.go @@ -70,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, using the values ingress or egress. + // 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, using the values inbound, outbound, internal or external. + // 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 their 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. diff --git a/docs/field-details.asciidoc b/docs/field-details.asciidoc index 65d2223ae3..2ccf97afe8 100644 --- a/docs/field-details.asciidoc +++ b/docs/field-details.asciidoc @@ -3342,9 +3342,11 @@ Recommended values are: -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 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 your 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, 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 their perimeter. This could for example be useful for ISPs or VPN service providers. type: keyword diff --git a/generated/beats/fields.ecs.yml b/generated/beats/fields.ecs.yml index 6a311095e1..fd51cab037 100644 --- a/generated/beats/fields.ecs.yml +++ b/generated/beats/fields.ecs.yml @@ -2596,10 +2596,15 @@ 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.\nWhen mapping events from a network or perimeter-based monitoring\ + \ 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 your network perimeter,\ - \ using the values inbound, outbound, internal or external." + \ 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 their perimeter. This could for example be useful for ISPs or\ + \ VPN service providers." example: inbound - name: forwarded_ip level: core diff --git a/generated/ecs/ecs_flat.yml b/generated/ecs/ecs_flat.yml index 35db7dee8a..929eeecf14 100644 --- a/generated/ecs/ecs_flat.yml +++ b/generated/ecs/ecs_flat.yml @@ -3986,10 +3986,14 @@ network.direction: 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.\nWhen mapping\ - \ events from a network or perimeter-based monitoring context, populate this field\ - \ from the point of view of your network perimeter, using the values inbound,\ - \ outbound, internal or external." + \ 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 your 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 their perimeter.\ + \ This could for example be useful for ISPs or VPN service providers." example: inbound flat_name: network.direction ignore_above: 1024 diff --git a/generated/ecs/ecs_nested.yml b/generated/ecs/ecs_nested.yml index 21c5ca9745..5c4e50dc2b 100644 --- a/generated/ecs/ecs_nested.yml +++ b/generated/ecs/ecs_nested.yml @@ -4734,10 +4734,15 @@ network: 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.\nWhen mapping events from a network or perimeter-based monitoring\ + \ 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 your network perimeter,\ - \ using the values inbound, outbound, internal or external." + \ 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 their perimeter. This could for example be useful for ISPs or\ + \ VPN service providers." example: inbound flat_name: network.direction ignore_above: 1024 diff --git a/schemas/network.yml b/schemas/network.yml index 976e4029dd..d70051ee89 100644 --- a/schemas/network.yml +++ b/schemas/network.yml @@ -94,11 +94,17 @@ * unknown 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. + 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, - using the values inbound, outbound, internal or external. + 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 their perimeter. This could for example be useful for ISPs or + VPN service providers. example: inbound - name: forwarded_ip